Qdrant 벡터DB 운영 및 사용 방법 총정리 — 컬렉션 설계부터 RAG 연동까지

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, HnswConfigDiff, OptimizersConfigDiff
from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType

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

client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(
        size=1536,              # OpenAI text-embedding-3-small 차원
        distance=Distance.COSINE,
    ),
    hnsw_config=HnswConfigDiff(
        m=16,                   # 그래프 연결 수
        ef_construct=128,       # 인덱스 빌드 시 탐색 폭
    ),
    optimizers_config=OptimizersConfigDiff(
        indexing_threshold=20000,
    ),
    quantization_config=ScalarQuantization(
        scalar=ScalarQuantizationConfig(type=ScalarType.INT8, quantile=0.99, always_ram=True),
    ),
)

# Scalar Quantization: float32 → int8 (메모리 4배 절감)
# 일반적인 텍스트 검색에 적합, recall 손실 < 1%

# Binary Quantization: float32 → 1-bit (메모리 32배 절감)
# 매우 공격적. 고차원(1536+)에서만 사용. oversampling 필요
from qdrant_client.models import BinaryQuantization, BinaryQuantizationConfig

client.update_collection(
    collection_name="documents",
    quantization_config=BinaryQuantization(
        binary=BinaryQuantizationConfig(
            always_ram=True,
        ),
    ),
)

from qdrant_client.models import PointStruct
import openai

def get_embedding(text: str) -> list[float]:
    resp = openai.embeddings.create(model="text-embedding-3-small", input=text)
    return resp.data[0].embedding

# 단건 upsert
client.upsert(
    collection_name="documents",
    points=[
        PointStruct(
            id=1,
            vector=get_embedding("Qdrant는 Rust로 작성된 벡터DB입니다."),
            payload={"title": "Qdrant 소개", "category": "database", "tenant_id": "team-alpha"},
        ),
    ],
)

# 대량 upsert — 100건씩 배치 처리
BATCH_SIZE = 100
for i in range(0, len(points), BATCH_SIZE):
    client.upsert(collection_name="documents", points=points[i : i + BATCH_SIZE])

from qdrant_client.models import SearchParams

results = client.search(
    collection_name="documents",
    query_vector=get_embedding("벡터 데이터베이스 성능 최적화"),
    limit=10,
    score_threshold=0.7,
    search_params=SearchParams(
        hnsw_ef=128,       # 검색 시 ef 값 (정확도 조절)
        exact=False,       # True면 brute-force (정확하지만 느림)
    ),
    with_payload=True,
    with_vectors=False,    # 벡터 자체는 반환하지 않음 (응답 크기 절감)
)

for result in results:
    print(f"ID: {result.id}, Score: {result.score:.4f}")
    print(f"  Title: {result.payload['title']}")

curl -X POST "http://localhost:6333/collections/documents/points/search" \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, ...],
    "limit": 10,
    "with_payload": true,
    "params": {
      "hnsw_ef": 128
    }
  }'

from qdrant_client.models import PointIdsList, FilterSelector, Filter, FieldCondition, MatchValue

# 페이로드 업데이트
client.set_payload(collection_name="documents", payload={"category": "vector-database"}, points=[1, 2, 3])

# 포인트 삭제 (ID 기반)
client.delete(collection_name="documents", points_selector=PointIdsList(points=[10, 11, 12]))

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

from qdrant_client.models import PayloadSchemaType, TextIndexParams, TokenizerType

# 키워드 인덱스 (정확 매칭)
client.create_payload_index(collection_name="documents", field_name="category", field_schema=PayloadSchemaType.KEYWORD)

# 정수 인덱스 (범위 검색)
client.create_payload_index(collection_name="documents", field_name="page_count", field_schema=PayloadSchemaType.INTEGER)

# 텍스트 인덱스 (전문 검색 — 다국어 토크나이저)
client.create_payload_index(
    collection_name="documents",
    field_name="content",
    field_schema=TextIndexParams(type="text", tokenizer=TokenizerType.MULTILINGUAL, min_token_len=2, max_token_len=20),
)

from qdrant_client.models import Filter, FieldCondition, MatchValue, Range

# 카테고리가 "database"이고 페이지 수가 10 이상인 문서 중 유사도 검색
results = client.search(
    collection_name="documents",
    query_vector=get_embedding("벡터 인덱스 최적화"),
    query_filter=Filter(
        must=[
            FieldCondition(
                key="category",
                match=MatchValue(value="database"),
            ),
            FieldCondition(
                key="page_count",
                range=Range(gte=10),
            ),
        ],
        must_not=[
            FieldCondition(
                key="status",
                match=MatchValue(value="archived"),
            ),
        ],
    ),
    limit=5,
)

from qdrant_client.models import SparseVector, SparseVectorParams, Prefetch, FusionQuery, Fusion

# dense + sparse 벡터 설정으로 컬렉션 생성
client.create_collection(
    collection_name="hybrid_docs",
    vectors_config={"dense": VectorParams(size=1536, distance=Distance.COSINE)},
    sparse_vectors_config={"sparse": SparseVectorParams()},
)

# Reciprocal Rank Fusion 기반 하이브리드 검색
results = client.query_points(
    collection_name="hybrid_docs",
    prefetch=[
        Prefetch(query=get_embedding("벡터 검색 성능"), using="dense", limit=20),
        Prefetch(query=SparseVector(indices=[1, 42, 1337], values=[0.9, 0.3, 0.7]), using="sparse", limit=20),
    ],
    query=FusionQuery(fusion=Fusion.RRF),
    limit=10,
)

from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_qdrant import QdrantVectorStore
from langchain.chains import RetrievalQA
from langchain.text_splitter import RecursiveCharacterTextSplitter

# 1. 문서 분할
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50,
    separators=["\n\n", "\n", ". ", " ", ""],
)
chunks = text_splitter.split_documents(documents)

# 2. 벡터 스토어 생성
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

vectorstore = QdrantVectorStore.from_documents(
    documents=chunks,
    embedding=embeddings,
    url="http://localhost:6333",
    collection_name="rag_documents",
    force_recreate=True,
)

# 3. RAG 체인 구성
retriever = vectorstore.as_retriever(
    search_type="similarity_score_threshold",
    search_kwargs={
        "k": 5,
        "score_threshold": 0.7,
    },
)

llm = ChatOpenAI(model="gpt-4o", temperature=0)

qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=retriever,
    return_source_documents=True,
)

# 4. 질문 응답
response = qa_chain.invoke({"query": "Qdrant의 HNSW 인덱스 파라미터를 어떻게 튜닝하나요?"})
print(response["result"])

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.vector_stores.qdrant import QdrantVectorStore
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
import qdrant_client

# 1. Qdrant 클라이언트 & 벡터 스토어
qclient = qdrant_client.QdrantClient(host="localhost", port=6333)

vector_store = QdrantVectorStore(
    client=qclient,
    collection_name="llamaindex_docs",
)

# 2. 설정
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.llm = OpenAI(model="gpt-4o", temperature=0)
Settings.chunk_size = 512
Settings.chunk_overlap = 50

# 3. 문서 로드 및 인덱싱
documents = SimpleDirectoryReader("./data").load_data()

index = VectorStoreIndex.from_documents(
    documents,
    vector_store=vector_store,
)

# 4. 쿼리 엔진
query_engine = index.as_query_engine(
    similarity_top_k=5,
)

response = query_engine.query("Qdrant에서 필터링과 벡터 검색을 동시에 하는 방법은?")
print(response)

# 메트릭 확인
curl http://localhost:6333/metrics

# 주요 메트릭
# qdrant_grpc_responses_total        — gRPC 요청 수
# qdrant_rest_responses_total        — REST 요청 수
# qdrant_collection_points_total     — 컬렉션별 포인트 수
# qdrant_collection_search_latency   — 검색 지연 시간

# 스냅샷 생성 및 목록 조회
client.create_snapshot(collection_name="documents")
snapshots = client.list_snapshots(collection_name="documents")
for snap in snapshots:
    print(f"Name: {snap.name}, Size: {snap.size}")

# REST API로 스냅샷 다운로드
curl -o snapshot.tar "http://localhost:6333/collections/documents/snapshots/snapshot-2026-03-09.snapshot"

# 전체 스토리지 스냅샷 (모든 컬렉션 포함)
curl -X POST "http://localhost:6333/snapshots"

# gRPC 사용 권장
client = QdrantClient(
    host="localhost",
    port=6333,
    grpc_port=6334,
    prefer_grpc=True,
)