Python/Python+Database

파이썬으로 벡터 데이터베이스 Qdrant 연동하기: AI 검색의 핵심 기술 이해

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

파이썬으로 벡터 데이터베이스 Qdrant 연동하기
: AI 검색의 핵심 기술 이해

GPT도, 챗봇도 결국 검색 기술이 핵심입니다.
AI 시대에 꼭 알아야 할 벡터 데이터베이스 Qdrant,
파이썬으로 쉽게 연동해보세요!

안녕하세요!

오늘은 인공지능 검색 서비스의 핵심이라고 할 수 있는 Qdrant 벡터 데이터베이스를 파이썬과 함께 활용하는 방법을 소개해 드릴게요.

요즘은 검색도 단순한 키워드 기반을 넘어서 의미 기반 검색(Semantic Search)이 대세잖아요?

그 중심에 바로 벡터 데이터베이스가 있습니다.

특히 Qdrant는 오픈소스이며 성능도 뛰어나서 스타트업이나 연구 프로젝트에서 많이 쓰이고 있죠.

이번 글에서는 Qdrant를 설치하고, 파이썬으로 벡터 데이터를 넣고, 검색까지 직접 구현해보는 실전 예제까지 소개해드릴게요.

1. Qdrant란 무엇인가요? 🧠

AI 모델이 텍스트나 이미지의 의미를 벡터로 표현하고, 이를 비교해서 유사한 항목을 찾는 기술, 바로 벡터 검색입니다.

Qdrant는 이러한 벡터 검색을 빠르고 효율적으로 수행할 수 있도록 설계된 오픈소스 벡터 검색 엔진이에요.

2021년 Rust 언어로 개발된 Qdrant는 고성능을 자랑하며, GPU 없이도 대용량 데이터를 빠르게 처리할 수 있어요.

특히 Docker 기반 배포가 간편하고, REST API 및 gRPC 지원을 통해 파이썬 등 다양한 언어에서 쉽게 연동 가능하다는 장점이 있습니다.

💡 Qdrant는 이런 상황에서 유용해요!

고객 리뷰나 댓글 등 비정형 텍스트 데이터를 의미 기반으로 검색하고 싶을 때
이미지, 오디오 등 다양한 데이터를 벡터로 표현한 뒤 유사 항목을 찾을 때
대화형 AI에서 사용자의 의도에 맞는 응답을 벡터 기반으로 찾고 싶을 때

📊 Qdrant 주요 특징 정리

항목	내용
언어	Rust (백엔드), Python/REST API (클라이언트)
지원 검색	유사 벡터 검색 (k-NN), 필터 기반 조건 검색
배포 방식	Docker, 바이너리, 클라우드 서비스 (Qdrant Cloud)
장점	빠른 속도, 쉬운 연동, 벡터 필터링 지원

정리하자면,

Qdrant는 의미 기반 검색을 실현하고 싶은 모든 사람에게 강력한 도구가 되어줄 수 있어요.

다음 섹션에서는 Qdrant를 직접 설치하고 환경을 준비하는 방법을 알아볼게요!

2. Qdrant 설치 및 환경 설정 ⚙️

Qdrant는 로컬 개발자 환경에 맞춰 간단하게 Docker로 실행할 수 있어요.

별도 설치 없이 명령어 몇 줄이면 끝!

혹시 Docker가 익숙하지 않다면 파이썬 전용 qdrant-client 라이브러리만으로도 접근 가능합니다.

📦 설치 방법 1: Docker로 실행

Docker가 설치되어 있다면 다음 명령어로 바로 Qdrant 서버를 실행할 수 있어요.

docker run -p 6333:6333 qdrant/qdrant

위 명령어를 실행하면 http://localhost:6333 포트로 REST API 서버가 열려요.

기본 포트는 6333번이니, 방화벽 설정이나 충돌을 체크하세요.

🐍 설치 방법 2: Python 환경 구성

Qdrant는 Python에서도 손쉽게 접근할 수 있도록 qdrant-client 패키지를 제공합니다.

아래 명령어로 설치해 주세요.

pip install qdrant-client

설치 후에는 다음과 같이 간단한 코드로 Qdrant 서버에 연결할 수 있어요.

from qdrant_client import QdrantClient

client = QdrantClient(host="localhost", port=6333)

🔍 설치 확인 체크리스트

localhost:6333 포트 접속 시 Qdrant 상태 페이지 확인됨
Python에서 클라이언트 객체 생성 시 오류 없이 성공
Docker 로그에서 "Qdrant started" 메시지 확인됨

이제 Qdrant 설치는 끝났어요!

다음 단계에서는 파이썬 코드로 Qdrant에 벡터 데이터를 넣고, 검색할 수 있는 준비를 해볼게요!

3. 파이썬에서 Qdrant 연동하기 🐍

Qdrant는 REST API도 지원하지만, Python에서는 qdrant-client 라이브러리를 사용하는 게 훨씬 간단하고 직관적이에요.

이 섹션에서는 파이썬을 이용해 Qdrant와 통신하고 데이터를 다루는 기본적인 흐름을 살펴볼게요.

🔌 클라이언트 연결 기본 예제

from qdrant_client import QdrantClient

# 기본 로컬 환경 (Docker로 실행 중일 때)
client = QdrantClient(host="localhost", port=6333)

위와 같이 객체를 생성하면, 이제 Qdrant의 API를 직접 호출하지 않고도 파이썬 코드만으로 거의 모든 작업을 수행할 수 있어요.

📁 기본적인 컬렉션 확인

# 현재 존재하는 모든 컬렉션 목록 확인
collections = client.get_collections()
print(collections)

Qdrant에서 벡터 데이터를 저장하려면 반드시 컬렉션(collection)을 먼저 만들어야 해요.

이건 RDB로 치면 하나의 테이블처럼 생각하면 편해요.

🔨 예제: 새로운 컬렉션 만들기

client.recreate_collection(
    collection_name="test_vectors",
    vectors_config={"size": 4, "distance": "Cosine"}
)

size: 벡터의 차원 수 (예: 4차원 벡터)
distance: 거리 계산 방식 (Cosine, Euclid 등 가능)

지금까지 Qdrant와 파이썬을 연결하고, 컬렉션을 확인하고 생성하는 과정을 해봤습니다.

다음 단계에서는 실제로 벡터 데이터를 삽입해보고, 저장된 데이터를 어떻게 검색하는지 다뤄볼게요!

4. 벡터 데이터 삽입과 컬렉션 관리 📦

이제 본격적으로 Qdrant에 데이터를 넣어볼 차례입니다!

텍스트를 임베딩해서 만든 벡터를 Qdrant에 저장하면, 나중에 의미 기반 검색이 가능해집니다.

Qdrant에서는 각 벡터를 하나의 포인트(Point)로 다루며, 고유한 ID를 부여할 수 있어요.

🔢 벡터 데이터 삽입 예제

client.upsert(
    collection_name="test_vectors",
    points=[
        {
            "id": 1,
            "vector": [0.1, 0.2, 0.3, 0.4],
            "payload": {"category": "news", "title": "AI Trends 2024"}
        },
        {
            "id": 2,
            "vector": [0.2, 0.1, 0.5, 0.3],
            "payload": {"category": "tech", "title": "Qdrant 소개"}
        }
    ]
)

여기서 중요한 포인트는 payload예요.

Qdrant는 단순 벡터뿐 아니라 메타 정보도 함께 저장할 수 있어서, 필터링 검색에 아주 유용하죠!

📋 컬렉션 설정 조회

info = client.get_collection(collection_name="test_vectors")
print(info)

이 명령어로 현재 컬렉션의 벡터 사이즈, 거리 알고리즘, 샤드 수, 저장된 포인트 수 등 구조 정보를 한눈에 확인할 수 있어요.

🚨 데이터 관리 꿀팁

업데이트는 같은 ID로 다시 upsert하면 됩니다.
삭제는 delete 메서드를 사용해 ID 기반으로 삭제 가능해요.

client.delete(collection_name="test_vectors", points_selector={"points": [2]})

이제 Qdrant에 데이터를 잘 넣는 방법을 배웠어요.

다음 단계에서는 벡터를 기준으로 가장 비슷한 데이터를 찾는 의미 기반 검색을 실습해보겠습니다!

5. 의미 기반 검색 쿼리 실습 🔍

이제 Qdrant의 진짜 강점인 의미 기반 벡터 검색을 해볼 시간입니다!

사용자가 특정 문장을 입력했을 때, 그 의미와 가장 비슷한 문서를 찾는 게 핵심이에요.

단어 그대로 검색하지 않고, 의미를 벡터화해서 유사도를 계산해주는 것이죠.

🎯 벡터 검색 기본 예제

search_result = client.search(
    collection_name="test_vectors",
    query_vector=[0.15, 0.25, 0.35, 0.45],
    limit=2
)

for item in search_result:
    print(item)

위 예제는 입력 벡터와 가장 가까운 2개의 포인트를 검색합니다.

벡터 간 유사도는 우리가 컬렉션 생성할 때 설정한 Cosine 방식으로 계산됩니다.

🧠 의미 기반 검색을 위한 임베딩

보통은 텍스트 문장을 검색할 때, Sentence-BERT, Cohere, OpenAI 등의 모델을 이용해 벡터로 변환합니다.

예를 들어 HuggingFace의 transformers를 사용하면 아래와 같이 변환할 수 있어요.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")
query = "AI 관련 최신 기술"
query_vector = model.encode(query).tolist()

그렇게 생성된 벡터를 Qdrant에 넘기면, 의미적으로 유사한 문장을 찾아주는 거죠.

이걸 활용하면 FAQ 검색, 추천 시스템, 챗봇 응답 생성 등 다양한 곳에 쓸 수 있어요.

🔍 필터 기반 검색 추가

search_result = client.search(
    collection_name="test_vectors",
    query_vector=query_vector,
    limit=3,
    query_filter={
        "must": [
            {"key": "category", "match": {"value": "tech"}}
        ]
    }
)

단순히 비슷한 벡터만 찾는 게 아니라 필터 조건도 붙일 수 있어요.

예를 들어

카테고리가 "tech"인 문서 중에서 가장 비슷한 걸 찾을 수 있죠.

🚀 검색 결과 구조

필드	설명
id	벡터에 부여된 고유 식별자
score	입력 벡터와의 유사도 점수
payload	추가 메타데이터 (title, category 등)

Qdrant의 의미 기반 검색 기능은 매우 강력합니다.

검색 정확도를 높이기 위해 벡터 전처리와 필터링을 잘 활용해 보세요!

이제 마지막 단계에서는 실제 텍스트 임베딩과 Qdrant 연동 실습을 해볼 거예요!

6. 예제: 문장 임베딩과 Qdrant 활용 💡

이제 Qdrant와 의미 기반 검색의 전체 흐름을 하나의 예제로 정리해볼게요.

이번 실습에서는 문장을 벡터로 변환하고, Qdrant에 저장한 뒤, 의미적으로 비슷한 문장을 검색하는 전체 파이프라인을 다룹니다.

🧪 예제: 뉴스 문장 검색기

from qdrant_client import QdrantClient
from sentence_transformers import SentenceTransformer

# 1. Qdrant 연결
client = QdrantClient(host="localhost", port=6333)

# 2. 임베딩 모델 로딩
model = SentenceTransformer("all-MiniLM-L6-v2")

# 3. 예제 문장 리스트
documents = [
    {"id": 1, "text": "인공지능 기술이 빠르게 발전하고 있다", "category": "ai"},
    {"id": 2, "text": "Qdrant는 벡터 검색 엔진이다", "category": "tech"},
    {"id": 3, "text": "한국의 경제 성장률이 하락했다", "category": "economy"}
]

# 4. 벡터화 및 저장
vectors = [model.encode(doc["text"]).tolist() for doc in documents]

client.recreate_collection(
    collection_name="demo_news",
    vectors_config={"size": len(vectors[0]), "distance": "Cosine"}
)

client.upsert(
    collection_name="demo_news",
    points=[
        {
            "id": doc["id"],
            "vector": vectors[i],
            "payload": {"category": doc["category"], "text": doc["text"]}
        }
        for i, doc in enumerate(documents)
    ]
)

# 5. 검색 쿼리
query = "AI 기술 발전 방향"
query_vector = model.encode(query).tolist()

result = client.search(
    collection_name="demo_news",
    query_vector=query_vector,
    limit=1
)

print(result[0].payload["text"])

🔍 기대 결과

위 코드를 실행하면 "AI 기술 발전 방향"이라는 문장에 가장 유사한 뉴스 문장을 찾아서 출력합니다.

결과는 높은 확률로 "인공지능 기술이 빠르게 발전하고 있다"가 될 거예요.

✅ 실습 정리

문장을 임베딩하여 벡터로 변환
Qdrant에 벡터와 메타 정보를 함께 저장
의미 기반 검색으로 가장 유사한 문장 탐색

여기까지 따라오셨다면 이제 Qdrant의 전체 사용 흐름을 이해하신 거예요.

로컬에서 AI 기반 검색 서비스를 구현하고 싶은 분께 강력히 추천드립니다!

Qdrant, AI 검색을 위한 강력한 도구

지금까지 Qdrant 벡터 데이터베이스의 개념부터 설치, 파이썬 연동, 벡터 데이터 삽입, 검색까지 전 과정을 함께 살펴봤습니다.

어렵게 느껴질 수 있었던 의미 기반 검색도 직접 실습해보니 생각보다 간단하고 강력하다는 걸 느끼셨을 거예요.

AI 서비스, 챗봇, 추천 시스템, 검색엔진을 만든다면 Qdrant는 정말 든든한 도구입니다.

특히 로컬 환경에서 AI 모델과 함께 통합해서 쓸 수 있다는 점이 큰 장점이죠.

지금 배운 예제 코드를 기반으로 자신만의 프로젝트에 응용해보세요.

생각보다 많은 가능성이 열릴 거예요!

티스토리