Qdrant 벡터 데이터베이스에 새로운 컬렉션(Collection)을 생성하는 예시

아래 Python 코드는 Qdrant 벡터 데이터베이스에 새로운 컬렉션(Collection)을 생성하는 예시입니다. 각 부분의 의미와 실행 방법, 그리고 올바른 결과를 상세히 설명합니다.

1. 코드의 의미

이 코드는 Qdrant 클라이언트를 사용하여 test라는 이름의 새로운 컬렉션을 생성합니다. 이 컬렉션은 2차원(dimension) 벡터를 저장하며, 벡터 간의 유사도를 측정할 때 코사인 유사도(Cosine Distance) 방식을 사용하도록 설정됩니다.

from qdrant_client import QdrantClient # Qdrant 서버와 통신하기 위한 클라이언트 라이브러리를 가져옵니다.
from qdrant_client.models import Distance, VectorParams # Qdrant 모델 정의(벡터 파라미터, 거리 측정 방식)를 가져옵니다.

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

collection_name = "test" # 생성할 컬렉션의 이름을 'test'로 정의합니다.

response = client.create_collection( # Qdrant 클라이언트를 사용하여 새로운 컬렉션을 생성하는 메서드를 호출합니다.
    collection_name = collection_name, # 위에서 정의한 컬렉션 이름을 전달합니다.
    vectors_config = VectorParams(size=2, distance=Distance.COSINE) # 벡터 저장소의 설정을 정의합니다.
    # size=2: 이 컬렉션에 저장될 벡터의 차원(dimension)을 2로 설정합니다. 즉, 각 벡터는 [x, y]와 같은 2개의 숫자로 구성됩니다.
    # distance=Distance.COSINE: 벡터 간의 유사도를 측정하는 방식을 코사인 유사도로 설정합니다. 코사인 유사도는 두 벡터가 가리키는 방향이 얼마나 유사한지를 측정하며, 텍스트 임베딩 등에서 많이 사용됩니다.
)

print(response) # 컬렉션 생성 작업의 결과를 출력합니다.

핵심 개념:

• 컬렉션(Collection): Qdrant에서 벡터와 페이로드(메타데이터)를 저장하는 논리적인 단위입니다. 관계형 데이터베이스의 테이블과 유사하다고 볼 수 있습니다.
• 벡터(Vector): 숫자 배열로 표현된 데이터의 특징입니다. 텍스트, 이미지, 오디오 등을 숫자로 변환한 것입니다.
• 차원(Dimension): 벡터를 구성하는 숫자의 개수입니다. (예: [0.1, 0.5]는 2차원, [0.1, 0.2, 0.3, ... , 0.9]는 10차원)
• 거리 측정 방식(Distance Metric): 벡터 간의 유사성 또는 거리를 계산하는 방법입니다.
  • Distance.COSINE (코사인 유사도): 두 벡터 간의 각도 코사인 값을 측정하여 유사도를 판단합니다. 방향이 중요할 때 사용됩니다.
  • Distance.EUCLID (유클리드 거리): 두 벡터 간의 직선 거리를 측정합니다.
  • Distance.DOT (내적): 두 벡터의 내적 값을 사용하여 유사도를 측정합니다.

2. 실행 방법

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

전제 조건:

1. Qdrant 서버 실행 중: Qdrant 서버가 localhost:6333에서 실행 중이어야 합니다. Docker를 사용한다면 다음 명령어로 실행할 수 있습니다.(AWS EC2 인스턴스에서 실행하는 경우, sudo를 붙이고, Flask 앱에서 host="localhost"로 설정한 것처럼 Qdrant Docker도 같은 인스턴스에서 localhost로 접근 가능해야 합니다.)
2. docker run -p 6333:6333 -p 6334:6334 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant
3. qdrant-client 라이브러리 설치: Python 환경에 qdrant-client 라이브러리가 설치되어 있어야 합니다.
4. pip install qdrant-client

실행 단계:

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

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

코드가 성공적으로 실행되면, Qdrant 서버에 test 컬렉션이 생성되고 터미널에는 다음과 같은 결과가 출력될 것입니다.

True

이는 컬렉션 생성 작업이 성공했음을 나타내는 불리언 값 True입니다.

발생할 수 있는 예외 상황:

• False 또는 에러 메시지 출력:
  • 만약 test라는 이름의 컬렉션이 이미 Qdrant 서버에 존재한다면, client.create_collection() 메서드는 False를 반환하거나 에러를 발생시킬 수 있습니다.
  • 이 경우, 컬렉션을 다시 생성하려면 먼저 기존 컬렉션을 삭제해야 합니다. client.delete_collection(collection_name="test")를 먼저 호출한 후 create_collection을 시도하거나, client.recreate_collection() 메서드를 사용하는 것이 더 안전합니다.
  • # 컬렉션이 이미 존재할 경우 삭제 후 재 생성 client.recreate_collection( collection_name = collection_name, vectors_config = VectorParams(size=2, distance=Distance.COSINE) )
• 연결 오류 (Timeout 등):
  • Qdrant 서버가 실행 중이지 않거나, host 또는 port 설정이 잘못되었거나, 방화벽/보안 그룹 문제로 인해 Qdrant 서버에 연결할 수 없다면 timed out과 같은 연결 오류가 발생할 수 있습니다.