벡터DB, Qdrant 컬렉션 검색 코드 설명

Qdrant 컬렉션 검색을 위한, 파이썬 코드를 바탕으로 각 부분의 의미와 전체적인 동작 흐름을 상세히 설명합니다.

1. 코드의 의미

이 코드는 Qdrant 벡터 데이터베이스에 연결하여, 미리 정의된 test 컬렉션에서 특정 query_vector와 유사한 상위 2개의 포인트를 검색하고, 그 결과(ID, 벡터, 페이로드, 점수)를 출력하는 기능을 수행합니다.

from qdrant_client import QdrantClient # Qdrant 서버와 통신하기 위한 클라이언트 라이브러리를 가져옵니다.
from qdrant_client.models import Distance, VectorParams, PointStruct # Qdrant 모델 정의를 가져옵니다.
# Distance: 벡터 간 거리 측정 방식 (예: 코사인 유사도)
# VectorParams: 컬렉션 생성 시 벡터의 차원과 거리 방식을 정의
# PointStruct: Qdrant에 저장될 하나의 데이터 단위(ID, 벡터, 페이로드)를 정의

client = QdrantClient(host="localhost", port=6333) # QdrantClient 객체를 생성합니다.
# host="localhost": Qdrant 서버가 현재 이 파이썬 코드를 실행하는 컴퓨터(또는 Docker 컨테이너)에 설치되어 있음을 의미합니다.
# port=6333: Qdrant 서버의 기본 gRPC 통신 포트입니다.

query_vector = [0.5, 0.5] # 검색을 위한 '쿼리 벡터'를 정의합니다.
# 이 벡터는 'test' 컬렉션의 벡터 차원(이 예시에서는 2차원)과 동일해야 합니다.
# 실제 애플리케이션에서는 사용자의 질의(텍스트, 이미지 등)를 임베딩 모델(예: OpenAI의 text-embedding-3-small)을 통해 벡터로 변환하여 이 자리에 사용합니다.

search_response = client.query_points( # Qdrant 클라이언트를 사용하여 컬렉션에서 유사한 포인트를 검색하는 메서드를 호출합니다.
    collection_name = "test", # 검색을 수행할 대상 컬렉션의 이름입니다.
    query = query_vector,     # 검색 기준이 되는 쿼리 벡터입니다. 이 벡터와 가장 유사한 포인트들을 찾습니다.
    limit=2,                  # 검색 결과로 반환할 포인트의 최대 개수를 2개로 제한합니다. (가장 유사한 상위 2개)
    with_payload = True,      # 검색 결과에 각 포인트의 페이로드(메타데이터)를 포함할지 여부를 결정합니다. True로 설정하면 페이로드도 함께 반환됩니다.
)

# 검색 결과는 search_response.points 속성에 PointStruct 객체 리스트 형태로 담겨 있습니다.
for point in search_response.points: # 검색된 각 포인트(PointStruct 객체)를 순회하며 정보를 출력합니다.
    print(f"ID: {point.id}, Vector: {point.vector}, Payload: {point.payload}, Score: {point.score}")
    # point.id: 검색된 포인트의 고유 ID
    # point.vector: 검색된 포인트의 벡터 값
    # point.payload: 검색된 포인트의 페이로드(메타데이터)
    # point.score: 쿼리 벡터와 해당 포인트 벡터 간의 유사도 점수 (0과 1 사이의 값, 1에 가까울수록 유사)

print("\nFull response object:")
print(search_response) # 검색 작업의 전체 응답 객체를 출력합니다.
# 이 객체는 검색된 포인트 리스트 외에 추가적인 정보(예: 시간)를 포함할 수 있습니다.

핵심 개념:

• query_points 메서드: Qdrant에서 벡터 유사도 검색을 수행하는 최신 권장 메서드입니다. 주어진 query 벡터와 collection_name 내의 모든 벡터들을 비교하여 유사도 점수가 높은 순서대로 결과를 반환합니다.
• query 인자: 검색의 기준이 되는 벡터입니다. 이 벡터와 컬렉션 내의 벡터들 간의 유사도를 계산합니다.
• limit: 반환될 검색 결과의 최대 개수를 제한합니다.
• with_payload: 검색 결과에 벡터뿐만 아니라 해당 벡터에 연결된 메타데이터(페이로드)도 함께 포함할지 여부를 결정합니다. RAG(Retrieval Augmented Generation) 시스템에서는 이 페이로드를 LLM에 전달하여 답변을 생성하는 데 활용합니다.
• score: 검색 결과로 반환되는 각 포인트에는 score 속성이 포함됩니다. 이 점수는 쿼리 벡터와 해당 포인트의 벡터 간의 유사도를 나타내며, 컬렉션 생성 시 정의된 distance (여기서는 COSINE) 방식에 따라 계산됩니다. 점수가 높을수록 더 유사하다는 의미입니다.

2. 실행 방법

이 코드를 실행하려면 다음 전제 조건이 충족되어야 합니다.

전제 조건:

1. Qdrant 서버 실행 중: Qdrant 서버가 localhost:6333에서 실행 중이어야 합니다.
   • docker run -p 6333:6333 -p 6334:6334 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant (AWS EC2에서는 sudo 사용)
2. qdrant-client 라이브러리 설치: Python 환경에 qdrant-client 라이브러리가 설치되어 있어야 합니다.
   • pip install qdrant-client
3. test 컬렉션이 존재하고 데이터가 삽입되어 있어야 함:
   • 이전에 size=2로 생성한 test 컬렉션이 Qdrant에 있어야 합니다.
   • 그리고 client.upsert 코드를 사용하여 이 test 컬렉션에 최소한 두 개의 포인트(id=1, vector=[1,1]과 id=2, vector=[-1,1])가 삽입되어 있어야 합니다.

실행 단계:

1. 위 Python 코드를 search_qdrant_test.py와 같은 이름으로 저장합니다.
2. 터미널 또는 명령 프롬프트를 열고, 해당 파일이 저장된 디렉토리로 이동합니다.
3. 다음 명령어를 입력하여 코드를 실행합니다.
4. python search_qdrant_test.py

3. 올바른 결과 (예상 출력)

코드가 성공적으로 실행되고 test 컬렉션에 예시 포인트들이 삽입되어 있다면, 터미널에는 다음과 유사한 결과가 출력될 것입니다.

ID: 1, Vector: [1.0, 1.0], Payload: {'name': 'Same direction'}, Score: 0.9999999999999999
ID: 2, Vector: [-1.0, 1.0], Payload: {'name': 'Opposite direction'}, Score: 0.0

Full response object:
points {
  id: 1
  payload {
    fields {
      key: "name"
      value {
        string_value: "Same direction"
      }
    }
  }
  vector {
    data: 1.0
    data: 1.0
  }
  score: 0.9999999999999999
}
points {
  id: 2
  payload {
    fields {
      key: "name"
      value {
        string_value: "Opposite direction"
      }
    }
  }
  vector {
    data: -1.0
    data: 1.0
  }
  score: 0.0
}
time_ms: 1 # 또는 다른 작은 숫자

출력 해석:

• query_vector = [0.5, 0.5]와 vector=[1,1]은 같은 방향을 가리키므로 코사인 유사도 점수가 1.0에 매우 가깝게 (0.999...) 나옵니다.
• query_vector = [0.5, 0.5]와 vector=[-1,1]은 서로 직교하는 방향(코사인 유사도 0)이거나, 거의 반대 방향에 가까우므로 점수가 0.0으로 나옵니다.
• limit=2이므로, 가장 유사한 두 개의 포인트가 반환됩니다. 이 예시에서는 두 포인트 모두 반환됩니다.
• with_payload=True이므로 Payload 정보도 함께 출력됩니다.