Qdrant 구성 요소

LLM

Qdrant 구성 요소

LOGFORCE 로그포스 2025. 6. 23. 11:33

개요

Qdrant는 벡터 유사도 검색 엔진 & VectorDB의 역할을 한다.
REST API를 통해 벡터를 저장, 검색 할 수 있으며 페이로드를 통해 벡터를 관리할 수 있다.
벡터 유사도 검사에서 Similarity Metric으로 Cosine, Dot, Euclid 등 선택할 수 있으며,
Collections, Points 등 몇 가지 구성요소를 기반으로 동작한다.

Qdrant 구성 요소

1. Points

Qdrant 기본 Entity다. Vector + Payload + Optional ID로 구성된다.
Vector: 이미지/문서/사운드/비디오 등을 벡터화 한 값
Payload: 벡터에 관한 부가데이터를 JSON형태로 저장한 값.
ID: 벡터의 식별자

point는 이런 형태로 넣게 된다.
ID는 64-bit unsigned integers 또는 UUID 로 넣을 수 있다.

PUT /collections/{collection_name}/points
{
    "points": [
        {
            "id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
            "payload": {"color": "red"},
            "vector": [0.9, 0.1, 0.1]
        }
    ]
}

Langchain으로 저장한 point를 조회해보면 payload로 page_content, metadata 등이 함께 들어갔다.
JSON을 사용하여 표현할 수 있는 어떤 정보든 넣을 수 있다.

{
  "id": "08af50f3-6606-4073-953f-57ae668e7b30",
  "vector": [
    0.009180975, -0.0057382825, ..., 0.003189075
  ],
  "payload": {
    "page_content": "4 \n \nQ3.  다른 국가들에 적용되는 상호관세율은? \nA3. 중국 34%, 유럽연합 20%, 일본 24% 등으로 책정되어 ...",
    "metadata": {
      "producer": "PDFium",
      "creator": "PDFium",
      "creationdate": "",
      "source": "/var/folders/zz/tn93_s4p00gn/T/tmp__eaypdf",
      "total_pages": 11,
      "page": 3,
      "page_label": "4",
      ...
    }
  }
}

이런식으로 덧붙인 Payload는 아래와 같이 Search시 Filtering에 활용할 수 있다.

POST /collections/{collection_name}/points/query
{
    "query": [0.2, 0.1, 0.9, 0.79],
    "filter": {
        "must": [
            {
                "key": "city",
                "match": {
                    "value": "London"
                }
            }
        ]
    },
    "params": {
        "hnsw_ef": 128,
        "exact": false
    },
    "limit": 3
}

2. Distance Metrics

벡터 간의 유사성을 측정하는 데 사용한다. 아래에 설명할 Collections 생성할때 함께 지정해야한다.
어떤 Metrics를 사용할지는 어떤 임베딩 모델을 썼느냐에 따라 달라진다.

3. Collections

Point의 집합을 의미한다.

Collection을 만들때는 vectorParams으로 Vector Dimension과 Distance Metrics을 넣어준다.
즉, 한 Collection 내 Point들은 모두 동일한 Vector Dimension(= 벡터 차원 수 = 임베딩 크기)를 가지고,

단일 Metric으로 비교되는 것이다.

예를 들면 1번 point의 예시에서 vector부분 배열 길이가 Collection의 벡터 차원 수와 동일해야만

그 Collection에 해당 Point를 넣을 수 있으며, Collection 내 Point들은 동일한 Distance Metrics에 의해 비교된다.

(다만 Named Vector는 단일 점에 여러 Vector를 가지고 고유의 차원 수와 메트릭을 쓸 수 있다고 한다)

아래는 Collection 생성 예시이다.

qdrant.create_collection(
    collection_name=collection_name,
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
)

물론 임베딩한 벡터 차원 수가 안 맞으면 DB에 넣을때 당연히 에러가 나는데,

임베딩 시 벡터 차원 수는 임베딩 모델마다 다르다.
가령, text-embedding-3-small(차원 수 1536)을 쓴다면 Qdrant VectorParams의 size도 위 예시처럼 1536으로 맞춰줘야한다.

/collection으로 Collection 목록을 조회해볼 수 있으며,
특정 collection에 값을 저장한 후 collection_name으로 조회해보면 아래와 같다.

{
  "result": {
    "status": "green",  // 컬렉션 상태 정상
    "points_count": 35,  // 현재 저장된 벡터 개수
    "config": {
      "params": {
        "vectors": {
          "size": 1536,         // 벡터 차원 수 (예: OpenAI 임베딩용)
          "distance": "Cosine"  // 유사도 계산 방식 (코사인 거리)
        },
        "on_disk_payload": true  // payload 디스크 저장 여부
      },
      "hnsw_config": {
        "m": 16,
        "ef_construct": 100,
        "on_disk": false  // 인덱스는 메모리에 존재
      },
      "optimizer_config": {
        "flush_interval_sec": 5,  // 디스크로 flush되는 주기 (5초)
        "indexing_threshold": 20000  // 인덱싱 시작 기준 
      }
    }
  },
  "status": "ok"
}

4. Storage

벡터를 저장할 스토리지는 2종류가 제공된다.

Memory 저장 (RAM 저장하니까 액세스 속도가 더 빠른 옵션이다.)
Memmap 저장 (파일로 만들어서 디스크에 저장)

Collection 생성시에 아래와 같이 지정할 수 있다.

client.recreate_collection(
    collection_name="my_collection",
    vectors_config=VectorParams(
        size=1536,
        distance=Distance.COSINE
    ),
    on_disk_payload=True,  # payload를 디스크에 저장
    hnsw_config={
        "on_disk": False       # 인덱스는 메모리에 유지
    }
)

번외) Install

클라우드와의 없이 자체 인프라에서 실행하고자 하는 경우

Qdrant Private Cloud Enterprise Operator를 이용하여 Kubernetes 클러스터에 설치할 것을 권장

테스트 또는 개발 환경에서는 Qdrant를 컨테이너로 실행하거나, 바이너리 실행 파일로 직접 구동할 수 있음.
또한, Kubernetes에 손쉽게 설치할 수 있도록 Helm 차트를 함께 제공함.

Installation Guide

https://qdrant.tech/documentation/guides/installation/

Helm

https://artifacthub.io/packages/helm/qdrant/qdrant](https://artifacthub.io/packages/helm/qdrant/qdrant)

K8s

Helm Install

k create -n qdrant

helm repo add qdrant https://qdrant.github.io/qdrant-helm
helm repo update
helm upgrade -i qdrant -n qdrant qdrant/qdrant #install

k get all -n qdrant

NodePort svc로 변경 (테스트 용도)

helm upgrade -i qdrant qdrant/qdrant \
  --set service.type=NodePort \
  --namespace qdrant

Docker

docker run -p 6333:6333 -d qdrant/qdrant

저작자표시 (새창열림)