Qdrant 컬렉션에 포인트(Vector & Payload) 삽입 코드 설명

Python 코드는 Qdrant 컬렉션에 실제 데이터인 **포인트(Point)**를 삽입(Upsert)하는 예시입니다. 각 부분의 의미와 실행 방법, 그리고 올바른 결과를 상세히 설명합니다.

1. 코드의 의미

이 코드는 test라는 이름의 Qdrant 컬렉션에 두 개의 포인트(벡터와 페이로드)를 삽입하거나 업데이트합니다. upsert는 "Update"와 "Insert"의 합성어로, 해당 id를 가진 포인트가 이미 존재하면 업데이트하고, 없으면 새로 삽입합니다.

from qdrant_client import QdrantClient # Qdrant 서버와 통신하기 위한 클라이언트 라이브러리를 가져옵니다.
from qdrant_client.models import Distance, VectorParams, PointStruct # Qdrant 모델 정의(거리 측정 방식, 벡터 파라미터, 포인트 구조)를 가져옵니다.
# PointStruct: Qdrant에 저장될 하나의 데이터 단위(ID, 벡터, 페이로드)를 정의하는 데 사용됩니다.

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

points= [ # Qdrant 컬렉션에 삽입할 포인트들의 리스트를 정의합니다. 각 포인트는 PointStruct 객체입니다.
    PointStruct( # 첫 번째 포인트 정의
        id=1, # 포인트의 고유 ID입니다. 정수 또는 문자열이 될 수 있습니다.
        vector=[1,1], # 이 포인트의 벡터입니다. 이전에 'test' 컬렉션을 2차원으로 생성했으므로, 2개의 숫자로 구성됩니다.
        payload={"name": "Same direction"}, # 이 포인트와 관련된 메타데이터(추가 정보)입니다. JSON 객체 형태로 저장됩니다.
    ),
    PointStruct( # 두 번째 포인트 정의
        id=2, # 두 번째 포인트의 고유 ID입니다.
        vector=[-1,1], # 두 번째 포인트의 벡터입니다.
        payload={"name": "Opposite direction"}, # 두 번째 포인트의 메타데이터입니다.
    ),
]

response = client.upsert( # Qdrant 클라이언트를 사용하여 정의된 포인트들을 컬렉션에 삽입/업데이트하는 메서드를 호출합니다.
    collection_name ="test", # 포인트를 삽입할 컬렉션의 이름을 지정합니다. 이전에 생성한 'test' 컬렉션입니다.
    points= points, # 위에서 정의한 포인트 리스트를 전달합니다.
)

print(response) # upsert 작업의 결과를 출력합니다.

핵심 개념:

• 포인트(Point): Qdrant에 저장되는 가장 기본적인 데이터 단위입니다. 각 포인트는 다음 세 가지 주요 구성 요소를 가집니다.
  • id: 포인트의 고유 식별자입니다. (정수 또는 문자열)
  • vector: 검색에 사용될 벡터 임베딩입니다. 이 예시에서는 2차원 벡터를 사용합니다.
  • payload: 벡터와 관련된 추가적인 메타데이터입니다. JSON 형식의 데이터를 저장할 수 있으며, 필터링이나 검색 결과에 표시될 정보로 활용됩니다.
• upsert: update와 insert의 합성어입니다.
  • 만약 지정된 id를 가진 포인트가 컬렉션에 이미 존재하면, 해당 포인트의 벡터와 페이로드를 업데이트합니다.
  • 만약 지정된 id를 가진 포인트가 컬렉션에 존재하지 않으면, 새로운 포인트를 **삽입(생성)**합니다.
• collection_name: 포인트를 삽입할 대상 컬렉션을 명시합니다. 이 컬렉션은 미리 생성되어 있어야 합니다.

2. 실행 방법

이 코드를 실행하려면 몇 가지 전제 조건이 필요합니다.

전제 조건:

1. Qdrant 서버 실행 중: Qdrant 서버가 localhost:6333에서 실행 중이어야 합니다.
   • docker run -p 6333:6333 -p 6334:6334 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant
2. qdrant-client 라이브러리 설치: Python 환경에 qdrant-client 라이브러리가 설치되어 있어야 합니다.
   • pip install qdrant-client
3. test 컬렉션이 이미 생성되어 있어야 함: 이 코드를 실행하기 전에, size=2로 설정된 test 컬렉션이 Qdrant에 존재해야 합니다. ( client.create_collection 또는 client.recreate_collection 코드를 먼저 실행하여 test 컬렉션을 생성해야 합니다.)

실행 단계:

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

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

코드가 성공적으로 실행되면, Qdrant 서버의 test 컬렉션에 두 개의 포인트가 삽입/업데이트되고 터미널에는 다음과 유사한 결과가 출력될 것입니다.

status {
  ok: true
}
result {
  operation_id: 0
  status: Completed
}

• status { ok: true }: upsert 작업이 성공적으로 완료되었음을 나타냅니다.
• result { operation_id: 0 status: Completed }: 작업이 성공적으로 완료되었고, 해당 작업의 ID를 보여줍니다.