Python/Python+Database

파이썬으로 벡터 데이터베이스 Weaviate 연동하기: 인공지능 시대의 데이터 검색 비법

코딩 코디네이터 2025. 4. 14. 10:00

파이썬으로 벡터 데이터베이스 Weaviate 연동하기
: 인공지능 시대의 데이터 검색 비법

GPT, 추천 시스템, 검색엔진…
이 모든 것의 뒤에는 벡터 데이터베이스가 있습니다.
그중 Weaviate는 지금 가장 ‘핫’한 선택지라는 거,
알고 계셨나요?

안녕하세요, 여러분!

오늘은 요즘 AI와 검색 분야에서 큰 주목을 받고 있는 벡터 데이터베이스 중 하나인 Weaviate를 파이썬으로 연동하는 방법에 대해 이야기해볼게요.

기존 관계형 데이터베이스와는 다르게, 벡터 기반으로 데이터를 저장하고 검색할 수 있는 이 혁신적인 도구는 특히 AI 모델과 찰떡궁합입니다.

“음… 그게 뭔데?” 하고 고개를 갸웃하셨다면, 지금 이 글을 정독하셔야 할 이유가 충분합니다 😉

단순한 이론 설명이 아닌, 실습 가능한 코드 예제와 함께 직접 동작시켜보는 튜토리얼 형태로 구성했으니, 끝까지 따라오시면 완전 정복하실 수 있어요!

1. Weaviate란 무엇인가요? 🧠 2. 벡터 데이터베이스가 필요한 이유는? 🔍 3. Weaviate 설치 및 기본 설정 방법 ⚙️ 4. 파이썬에서 Weaviate와 연결하기 💻 5. 실전 예제: 문서 벡터화하고 검색하기 🔎 6. 함께 쓰면 좋은 도구들 및 활용 팁 💡

1. Weaviate란 무엇인가요? 🧠

Weaviate는 오픈소스 기반의 벡터 검색 엔진(Vector Search Engine)입니다.

일반적인 데이터베이스처럼 텍스트나 숫자를 저장하는 기능은 물론이고, 이미지·텍스트·음성 등의 비정형 데이터를 벡터 형태로 저장하고 검색할 수 있도록 최적화된 구조를 갖고 있어요.

쉽게 말하면,

자연어 기반의 유사도 검색을 구현할 때 아주 강력한 도구라는 거죠.

GPT, BERT, CLIP, SBERT 등 다양한 AI 임베딩 모델과 연결해서, 어떤 문장이 다른 문장과 얼마나 비슷한지를 빠르게 찾아주는 시스템을 만들 수 있어요.

🔧 Weaviate의 주요 특징

벡터 임베딩 데이터를 저장하고 검색하는 데 최적화된 DB
OpenAI, HuggingFace 등 다양한 임베딩 모델과 자동 연동 가능
REST API와 GraphQL API 모두 지원
Python, JavaScript 등 다양한 클라이언트 라이브러리 제공

📦 저장 방식: 벡터와 함께 저장하는 객체 기반 구조

Weaviate는 데이터를 단순 문자열로 저장하는 게 아니라, Object + Vector 형태로 저장합니다.

즉, 예를 들어 다음처럼 저장할 수 있어요:

Object (Text)	Vector (임베딩)
"강아지는 귀엽다"	[0.12, 0.98, ..., 0.34]
"고양이는 독립적이다"	[0.22, 0.76, ..., 0.18]

이 벡터 값은 AI 임베딩 모델을 통해 자동 생성되며, 저장된 벡터끼리의 코사인 유사도 기반으로 비슷한 데이터를 검색할 수 있게 되는 거죠. 정말 똑똑하죠?

📈 활용 분야는 어디에?

ChatGPT와 같은 검색 기반 챗봇의 벡터 검색 엔진
제품 추천 시스템에서 유사도 기반 상품 검색
이미지·텍스트 검색 엔진

요약하자면,

Weaviate는 지금 시대의 AI 애플리케이션에 꼭 필요한 검색형 데이터베이스예요.

아직 익숙하지 않아도, 한 번 써보면 “아 이래서 다들 벡터DB 쓰는구나” 하실 거예요!

2. 벡터 데이터베이스가 필요한 이유는? 🔍

여러분 혹시 이런 경험 없으세요?

검색창에 뭔가 입력했는데, 딱 원하는 결과가 안 나올 때요.

그런 순간마다 “내가 말한 의도를 컴퓨터가 정확히 이해했으면 좋겠는데…” 라고 생각한 적,

저만 그런 거 아니죠? 😅

바로 그 문제를 해결해주는 게 벡터 검색, 그리고 그 기반이 되는 벡터 데이터베이스입니다.

🧩 기존 키워드 검색의 한계

키워드 기반 검색은 정확한 단어 일치가 있어야 함
문맥이나 의미는 반영되지 않음 (ex. "강아지" vs "멍멍이")
비정형 데이터(이미지, 음성 등)는 검색하기 어렵다

그렇다면 어떻게 하면 문맥까지 반영한 “의미 기반 검색”이 가능할까요?

답은 AI 임베딩 + 벡터 유사도 검색입니다.

🔮 AI 시대의 데이터 검색 방식: 유사도 기반

최근 ChatGPT, 추천 시스템, 검색 기반 챗봇 등의 서비스들은 자연어 처리 모델로부터 생성된 벡터를 활용해 유사한 정보를 찾아냅니다.

이걸 가능하게 해주는 게 바로 벡터 데이터베이스예요.

기존 방식	벡터 방식
“고양이 사진” → 키워드 일치한 결과만 출력	“귀여운 반려동물 이미지”도 유사한 결과로 출력
텍스트 외 데이터 검색 어려움	이미지, 음성도 벡터화해서 검색 가능

🚀 왜 Weaviate인가요?

벡터 검색을 지원하는 데이터베이스는 많지만, Weaviate는 AI 모델을 자동 연동해주는 “Hybrid Search” 기능이 있어 정말 편리해요.

게다가 GraphQL API를 제공해, 구조화된 쿼리도 가능하다는 점에서 타 DB보다 유연하게 활용할 수 있답니다.

OpenAI, Cohere, HuggingFace 등의 임베딩 API와 자동 연동
REST API + GraphQL로 다양한 형태의 검색 가능

결론은 이거예요.

이제는 키워드 기반 검색에서 벗어나, 의미와 문맥을 반영한 스마트한 검색 시스템이 필요한 시대입니다. Weaviate는 그런 변화의 중심에 있는 도구라고 볼 수 있죠.

3. Weaviate 설치 및 기본 설정 방법 ⚙️

이제 본격적으로 시작해볼까요?

Weaviate는 로컬, 클라우드, Docker를 통해 쉽게 실행할 수 있어요.

특히 학습이나 테스트용으로는 Docker로 설치하는 게 가장 간편합니다.

여기선 Docker 기반 설치를 중심으로 설명드릴게요.

🐳 Step 1: Docker 설치

Docker Desktop을 다운로드하고 설치합니다.
설치 후 Docker가 실행되고 있는지 확인하세요.

Docker Desktop: The #1 Containerization Tool for Developers | Docker

Docker Desktop is collaborative containerization software for developers. Get started and download Docker Desktop today on Mac, Windows, or Linux.

www.docker.com

📦 Step 2: Docker Compose 파일 작성

아래와 같은 내용의 docker-compose.yml 파일을 만들어주세요. 최신 버전 정보는 공식 문서에서 확인할 수 있어요.

version: '3.4'
services:
  weaviate:
    image: semitechnologies/weaviate:1.23.3
    ports:
      - "8080:8080"
    restart: on-failure
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: "./data"
      DEFAULT_VECTORIZER_MODULE: text2vec-openai
      ENABLE_MODULES: text2vec-openai
      OPENAI_APIKEY: your-openai-api-key-here

여기서 text2vec-openai는 OpenAI 기반 임베딩을 사용하는 모듈이에요.

물론 HuggingFace, Cohere 같은 다른 모듈도 설정 가능하지만, 가장 간단한 건 OpenAI API 키를 사용하는 거죠.

🚀 Step 3: Weaviate 서버 실행

터미널을 열고 docker-compose.yml이 있는 경로에서 아래 명령어를 실행해보세요.

docker-compose up -d

브라우저에서 http://localhost:8080/v1/.well-known/ready 로 접속하면 서버 상태를 확인할 수 있어요. “OK”라는 응답이 나오면 성공적으로 Weaviate 인스턴스가 실행된 거예요!

🧪 테스트를 위한 준비 완료!

여기까지 완료되면 이제 파이썬에서 Weaviate에 접속해서 데이터를 주고받을 준비가 된 거예요.

다음 단계에서는 실제로 파이썬 코드로 Weaviate와 연결해보면서 본격적인 실습을 진행해볼게요!

4. 파이썬에서 Weaviate와 연결하기 💻

이제 Weaviate 서버가 정상 실행되고 있다는 전제 하에, 파이썬 코드로 Weaviate와 연결해보겠습니다. Python에서는 공식 라이브러리인 weaviate-client를 사용하면 손쉽게 데이터를 전송하거나 검색할 수 있어요.

📦 Step 1: weaviate-client 설치

pip install weaviate-client

최신 버전이 잘 설치되었는지 아래 명령어로 확인해보세요.

pip show weaviate-client

🔗 Step 2: 클라이언트 연결

import weaviate

# 클라이언트 인스턴스 생성
client = weaviate.Client(
    url="http://localhost:8080",  # 로컬호스트로 실행 중일 경우
    additional_headers={
        "X-OpenAI-Api-Key": "your-openai-api-key-here"  # text2vec-openai 모듈을 위한 키
    }
)

# 연결 확인
if client.is_ready():
    print("✅ Weaviate 연결 성공!")
else:
    print("❌ 연결 실패")

이 코드에서 client.is_ready()는 실제로 서버가 정상 작동 중인지 확인하는 용도로 사용됩니다.

연결에 성공했다면 이제 데이터를 클래스 형태로 정의하고 벡터 저장을 시작할 수 있어요.

🧱 Step 3: 데이터 스키마(Class) 정의

# 기존 스키마 삭제 (테스트용)
client.schema.delete_all()

# 새 스키마 정의
class_obj = {
    "class": "Document",
    "description": "A collection of text documents",
    "vectorizer": "text2vec-openai",
    "properties": [
        {
            "name": "content",
            "dataType": ["text"],
            "description": "The content of the document"
        }
    ]
}

client.schema.create_class(class_obj)

이제 "Document"라는 이름의 클래스에 데이터를 저장할 준비가 완료된 상태예요.

이름, 설명, 속성(property), 그리고 어떤 벡터화 방식(text2vec-openai)을 사용할지를 명시했죠.

📌 다음 단계는?

여기까지 따라오셨다면, 이제 본격적으로 데이터를 벡터로 저장하고 검색하는 실습을 진행해볼 차례예요!

다음 단계에서는 여러 문장을 벡터로 저장하고, 유사도 검색하는 코드를 함께 작성해볼게요 🔍

놓치지 말고 꼭 따라와주세요!

5. 실전 예제: 문서 벡터화하고 검색하기 🔎

이제 진짜 재미있는 단계예요 😎

이전 단계에서 정의한 Document 클래스에 데이터를 저장하고, AI 임베딩을 기반으로 유사한 문서를 검색해보는 예제를 직접 실행해볼게요.

📥 Step 1: 문서 데이터 삽입

documents = [
    {"content": "강아지는 충성스럽고 귀엽다."},
    {"content": "고양이는 독립적인 성격을 가지고 있다."},
    {"content": "사람은 다양한 감정을 가진 존재다."},
    {"content": "AI는 인간의 지능을 모방하려는 기술이다."},
    {"content": "햄스터는 작고 귀여운 반려동물이다."}
]

for doc in documents:
    client.data_object.create(data_object=doc, class_name="Document")

이 코드는 각 문장을 하나의 오브젝트로 Document 클래스에 저장하는 예제예요.

저장하는 동시에 OpenAI 임베딩 API를 통해 자동으로 벡터화되죠.

🔎 Step 2: 유사도 기반 검색 실행

예를 들어, “귀여운 동물”이라는 문장과 가장 유사한 내용을 찾고 싶다면 다음과 같이 검색할 수 있어요.

response = client.query.get("Document", ["content"]) \
    .with_near_text({"concepts": ["귀여운 동물"]}) \
    .with_limit(2) \
    .do()

print(response)

이렇게 하면 벡터 간의 유사도를 기준으로 가장 비슷한 문장을 찾아주는 거죠.

정말 신기하고도 똑똑한 검색 방식이에요 🤯

📌 검색 결과 예시

순위	문장 내용
1위	“강아지는 충성스럽고 귀엽다.”
2위	“햄스터는 작고 귀여운 반려동물이다.”

이 결과를 보면 확실히 “귀여운 동물”이라는 키워드와 가장 의미상 가까운 문장을 골라내고 있어요.

이게 바로 기존 키워드 검색으로는 불가능한 의미 기반 검색의 힘이죠!

🙋‍♀️ 활용 아이디어

FAQ 자동 응답 시스템 (비슷한 질문 자동 매칭)
뉴스 기사 유사도 분석
추천 시스템의 콘텐츠 기반 필터링

이제 여러분도 직접 데이터를 저장하고, AI처럼 똑똑한 검색을 구현할 수 있게 된 거예요!

간단한 코드 몇 줄로 강력한 검색 시스템을 만들 수 있다니, 이건 꼭 써봐야죠 🤖

6. 함께 쓰면 좋은 도구들 및 활용 팁 💡

Weaviate를 혼자 쓰는 것도 물론 훌륭하지만, 다양한 도구들과 결합하면 훨씬 더 막강한 성능과 편의성을 누릴 수 있어요.

특히 AI 기반 검색 시스템을 구축하거나 RAG, 챗봇, 추천 시스템 등을 만들고 싶다면,

아래와 같은 툴들과 궁합이 정말 좋습니다!

🤖 1. 임베딩 모델 API: OpenAI, Cohere, HuggingFace

text2vec-openai: ChatGPT 계열 OpenAI 임베딩 사용 가능
text2vec-cohere: 빠르고 저렴한 Cohere 벡터화 지원
text2vec-transformers: HuggingFace 모델 직접 연동 가능

🧰 2. 프론트엔드 연결: Streamlit, Gradio, FastAPI

Streamlit: 실시간 검색 인터페이스 구축에 딱! 초보자도 쉽게 사용 가능
Gradio: 이미지 + 텍스트를 처리하는 UI가 필요할 때 유용
FastAPI: RESTful API와 검색 서비스 서버 구축에 최적

📈 3. 대규모 데이터 관리: Elasticsearch, Milvus, Qdrant과 비교

DB	특징
Weaviate	AI 벡터 자동 연동 + GraphQL 지원
Milvus	대규모 처리에 강점, 고성능 검색에 특화
Qdrant	Rust 기반, 빠른 속도와 유연한 API
Elasticsearch	전통적 검색엔진 + 플러그인으로 벡터 검색 확장

🎯 활용 팁 정리

작은 테스트부터 시작하세요: 5~10개 데이터로 먼저 실험해보면 이해가 쏙쏙!
임베딩 모델에 따라 결과가 완전히 달라져요: 다양한 모델을 시도해 보세요.
Streamlit 대시보드로 실시간 검색 앱 만들기 추천!

Weaviate는 단독으로도 훌륭하지만, 연결할수록 무한히 확장 가능한 데이터 AI 인프라가 됩니다.

직접 이 조합들을 활용해보면서 나만의 “지식 검색 플랫폼”을 구축해보세요 🚀

파이썬과 Weaviate, AI 검색의 시작점

지금까지 함께 살펴본 Weaviate는 단순한 데이터 저장소가 아닙니다.

의미 기반 검색, 유사도 기반 추천, 인공지능 챗봇의 핵심이 되는 중요한 도구입니다.

파이썬으로 간단하게 설치하고 연결해, 복잡한 벡터 연산 없이도 고급 검색 기능을 구현할 수 있다는 점은 정말 큰 장점이죠.

이제는 키워드 검색을 넘어서야 할 때입니다.

AI 서비스에 꼭 필요한 벡터 DB 기술, 여러분도 이제 첫발을 내디뎠습니다.

오늘 배운 내용으로 여러분의 프로젝트에 더 스마트한 기능을 넣어보세요!

궁금한 점이 있다면 댓글로 남겨주시고, 더 알고 싶은 주제가 있다면 언제든지 요청해주세요. 😉

놓치지 않도록 구독과 북마크는 필수!

티스토리