Qdrant: Rust 기반 벡터 데이터베이스로 100만+ 벡터를 10ms 지연으로 처리 — 2026년 자체 호스팅 배포 가이드

{
  "id": "doc_4821",
  "vector": [0.01, -0.23, 0.89, ...],
  "payload": {
    "file_name": "contract_v2.pdf",
    "department": "legal",
    "created_at": 1704067200,
    "tags": ["confidential", "draft"],
    "file_size_mb": 4.2
  }
}

docker pull qdrant/qdrant:v1.13.0
docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage:z \
  qdrant/qdrant:v1.13.0

# 확인 — {"title":"qdrant","version":"1.13.0"} 반환해야 함
curl http://localhost:6333

# docker-compose.yml
version: "3.8"
services:
  qdrant:
    image: qdrant/qdrant:v1.13.0
    ports:
      - "6333:6333"   # REST API
      - "6334:6334"   # gRPC API
    volumes:
      - qdrant_data:/qdrant/storage
    environment:
      - QDRANT__SERVICE__GRPC_PORT=6334
      - QDRANT__STORAGE__SNAPSHOT_PATH=/qdrant/snapshots
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    restart: unless-stopped

volumes:
  qdrant_data:

docker-compose up -d
curl http://localhost:6333/collections  # 컬렉션 목록 (초기에는 비어 있음)

# 사전 빌드된 바이너리 다운로드 (Linux x86_64)
wget https://github.com/qdrant/qdrant/releases/download/v1.13.0/qdrant-x86_64-unknown-linux-gnu.tar.gz
tar -xzf qdrant-x86_64-unknown-linux-gnu.tar.gz
./qdrant

# 또는 Homebrew로 설치 (macOS)
brew install qdrant/tap/qdrant

# production.yaml
storage:
  storage_path: /qdrant/storage
  snapshots_path: /qdrant/snapshots
  performance:
    max_search_threads: 8
    max_optimization_threads: 4

service:
  http_port: 6333
  grpc_port: 6334
  max_request_size_mb: 32

cluster:
  enabled: false  # 분산 모드에서는 true로 설정
  p2p:
    port: 6335

# 1536 차원의 컬렉션 생성 (OpenAI 임베딩)
curl -X PUT http://localhost:6333/collections/documents \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 1536,
      "distance": "Cosine",
      "hnsw_config": {
        "m": 16,
        "ef_construct": 100,
        "full_scan_threshold": 10000
      }
    },
    "optimizers_config": {
      "default_segment_number": 2,
      "indexing_threshold": 20000
    }
  }'

# upsert_vectors.py
from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct, VectorParams, Distance

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

# 컬렉션 생성
client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
)

# 포인트 업서트 (페이로드가 있는 벡터)
points = [
    PointStruct(
        id=1,
        vector=[0.01, -0.23, 0.89] + [0.0] * 1533,  # 1536차원 플레이스홀더
        payload={"title": "API Reference", "category": "docs", "version": 2}
    ),
    PointStruct(
        id=2,
        vector=[-0.15, 0.42, 0.71] + [0.0] * 1533,
        payload={"title": "User Guide", "category": "docs", "version": 1}
    ),
]

client.upsert(collection_name="documents", points=points)
print(f"{len(points)}개 벡터를 업서트했습니다")

# search_filtered.py
from qdrant_client.models import Filter, FieldCondition, MatchValue

results = client.search(
    collection_name="documents",
    query_vector=[0.02, -0.25, 0.88] + [0.0] * 1533,
    query_filter=Filter(
        must=[
            FieldCondition(
                key="category",
                match=MatchValue(value="docs")
            ),
            FieldCondition(
                key="version",
                range=Range(gte=2)
            ),
        ]
    ),
    limit=5,
    with_payload=True,
)

for point in results:
    print(f"ID: {point.id}, 점수: {point.score:.4f}, 페이로드: {point.payload}")

# update_delete.py
# 페이로드 업데이트
client.set_payload(
    collection_name="documents",
    payload={"status": "reviewed", "reviewed_at": 1715000000},
    points=[1],
)

# 필터로 삭제
client.delete(
    collection_name="documents",
    points_selector=FilterSelector(
        filter=Filter(
            must=[
                FieldCondition(key="category", match=MatchValue(value="deprecated"))
            ]
        )
    ),
)

pip install qdrant-client==1.13.0

# python_client.py
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

client = QdrantClient(url="http://localhost:6333")

# 전체 워크플로우: 생성 → 업서트 → 검색
collections = client.get_collections()
print(f"기존 컬렉션: {[c.name for c in collections.collections]}")

# 모든 포인트 스크롤 (배치 검색)
scroll_results = client.scroll(
    collection_name="documents",
    limit=100,
    with_payload=True,
)
print(f"{len(scroll_results[0])}개 포인트를 검색했습니다")

npm install @qdrant/js-client-rest@1.13.0

// ts_client.ts
import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

// 검색
const results = await client.search("documents", {
  vector: [0.02, -0.25, 0.88, /* ... 1536 차원 */],
  limit: 10,
  filter: {
    must: [{ key: "category", match: { value: "docs" } }],
  },
  with_payload: true,
});

console.log(`${results.length}개의 일치를 찾았습니다`);

go get github.com/qdrant/go-client@v1.13.0

// go_client.go
package main

import (
    "context"
    "fmt"
    "log"

    pb "github.com/qdrant/go-client/qdrant"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    conn, err := grpc.Dial("localhost:6334",
        grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil { log.Fatal(err) }
    defer conn.Close()

    collectionsClient := pb.NewCollectionsClient(conn)
    resp, err := collectionsClient.List(context.Background(), &pb.ListCollectionsRequest{})
    if err != nil { log.Fatal(err) }

    for _, c := range resp.GetCollections() {
        fmt.Printf("컬렉션: %s\n", c.GetName())
    }
}

# langchain_qdrant.py
from langchain_qdrant import QdrantVectorStore
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

vector_store = QdrantVectorStore.from_existing_collection(
    embedding=embeddings,
    collection_name="documents",
    url="http://localhost:6333",
)

# 문서 추가
docs = [Document(page_content="Hello world", metadata={"source": "test"})]
vector_store.add_documents(docs)

# 유사도 검색
results = vector_store.similarity_search("hello", k=5)
print(f"{len(results)}개의 유사한 문서를 찾았습니다")

# llamaindex_qdrant.py
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.vector_stores.qdrant import QdrantVectorStore

vector_store = QdrantVectorStore(
    collection_name="documents",
    host="localhost",
    port=6333,
    dimension=1536,
)

storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

# 자주 필터링되는 필드에 대한 페이로드 인덱스 생성
curl -X PUT http://localhost:6333/collections/documents/index \
  -H "Content-Type: application/json" \
  -d '{
    "field_name": "category",
    "field_schema": "keyword"
  }'

# docker-compose.cluster.yml
version: "3.8"
services:
  qdrant-node1:
    image: qdrant/qdrant:v1.13.0
    ports:
      - "6333:6333"
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
      - QDRANT__CLUSTER__CONSENSUS__MAX_MESSAGE_QUEUE_SIZE=1000
    command: ./qdrant --uri http://qdrant-node1:6335

  qdrant-node2:
    image: qdrant/qdrant:v1.13.0
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
    command: ./qdrant --bootstrap http://qdrant-node1:6335 --uri http://qdrant-node2:6335

  qdrant-node3:
    image: qdrant/qdrant:v1.13.0
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
    command: ./qdrant --bootstrap http://qdrant-node1:6335 --uri http://qdrant-node3:6335

# cluster_client.py
from qdrant_client import QdrantClient

# 클러스터에 연결 (자동 장애 조치 처리)
client = QdrantClient(
    host="qdrant-node1",
    port=6333,
    # 프로덕션에서는 로드 밸런서 또는 여러 호스트 사용
)

# 복제 인자가 있는 컬렉션 생성
collection_info = client.create_collection(
    collection_name="clustered_docs",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
    replication_factor=2,  # 각 샤드가 2개 노드에
)

# REST API를 통한 스냅샷 생성
curl -X POST http://localhost:6333/collections/documents/snapshots

# 응답: {"result":{"name":"documents-2026-05-19-10-30-00.snapshot"}}

# 스냅샷 목록
curl http://localhost:6333/collections/documents/snapshots

# 스냅샷에서 복원
curl -X PUT http://localhost:6333/collections/documents_from_backup/snapshots/recover \
  -H "Content-Type: application/json" \
  -d '{"location": "/qdrant/snapshots/documents-2026-05-19-10-30-00.snapshot"}'

# Python으로 자동화된 스냅샷
from datetime import datetime
import requests

def create_snapshot(collection: str) -> str:
    url = f"http://localhost:6333/collections/{collection}/snapshots"
    resp = requests.post(url)
    result = resp.json()["result"]
    print(f"스냅샷 생성됨: {result['name']}")
    return result["name"]

# 일일 스냅샷 (cron을 통해 실행)
snapshot_name = create_snapshot("documents")

# config/production.yaml
service:
  api_key: "your-secret-api-key-32-chars-long!!"
  enable_cors: false
  verify_https: true

# authenticated_client.py
from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://qdrant.your-domain.com",
    api_key="your-secret-api-key-32-chars-long!!",
    https=True,
    port=443,
)

# 이제 모든 요청에 X-API-Key 헤더가 포함됩니다

# multi_tenant.py
from qdrant_client.models import Filter, FieldCondition, MatchValue

# 단일 컬렉션, 페이로드 필터를 통한 테넌트 격리
def search_for_tenant(query_vector, tenant_id: str, limit: int = 10):
    return client.search(
        collection_name="documents",
        query_vector=query_vector,
        query_filter=Filter(
            must=[
                FieldCondition(
                    key="tenant_id",
                    match=MatchValue(value=tenant_id),
                )
            ]
        ),
        limit=limit,
    )

# 특정 테넌트 내에서만 검색
results = search_for_tenant(query_vector, tenant_id="acme_corp")

# 메트릭 스크래핑
curl http://localhost:6333/metrics

# 감시해야 할 핵심 메트릭:
# qdrant_collection_vectors — 컬렉션당 총 벡터 수
# qdrant_search_latency_ms — 검색 지연 히스토그램
# qdrant_optimizers_segment_count — 세그먼트 수
# qdrant_storage_size_bytes — 저장소 크기

# prometheus.yml 스크래이프 구성
scrape_configs:
  - job_name: "qdrant"
    static_configs:
      - targets: ["qdrant:6333"]
    metrics_path: "/metrics"
    scrape_interval: 15s

# 환경 변수를 통해 설정
docker run -p 6333:6333 \
  -e QDRANT__STORAGE__ON_DISK_PAYLOAD=true \
  -e QDRANT__STORAGE__PERFORMANCE__IN_MEMORY_INDEX_MAP_THRESHOLD_KB=20000 \
  -v qdrant_data:/qdrant/storage \
  qdrant/qdrant:v1.13.0

pip install qdrant-client
qdrant-migrate \
  --source pinecone \
  --pinecone-api-key "YOUR_KEY" \
  --pinecone-index "my-index" \
  --target http://localhost:6333 \
  --target-collection "migrated_docs"

from qdrant_client.models import SparseVector

client.search(
    collection_name="documents",
    query_vector=models.NamedVector(
        name="dense",
        vector=[0.1, 0.2, ...],
    ),
    query_sparse_vector=SparseVector(
        indices=[10, 20, 30],
        values=[0.5, 0.3, 0.8],
    ),
    fusion=models.Fusion.RRF,  # 역순위 퓨전
)