운영 환경에서의 Qdrant: 퀵스타트 가이드가 알려주지 않는 10가지 주의사항

Qdrant 퀵스타트는 정말 훌륭합니다. 5분 만에 벡터를 업서트(upserting)하고 검색 결과를 얻을 수 있으니까요. 하지만 "데모가 작동한다"와 "이것이 나를 당황하게 하지 않고 운영 환경(production)에서 돌아간다" 사이에는 간극이 존재하며, 그 간극에 존재하는 대부분의 내용은 단일 문서 페이지에 들어있지 않습니다. 그것들은 레퍼런스 섹션, GitHub 이슈, 그리고 새벽 2시에 이 문제와 맞닥뜨린 사람들의 경험담 속에 흩어져 있습니다.

저는 Qdrant를 익히는 과정에서 문서를 처음부터 끝까지 읽고, 데모를 구축하고, 간극을 감사(auditing)하며 이 내용들을 수집했습니다. 다음은 여러분을 괴롭힐 시점에 따라 대략적으로 분류한, 중요한 10가지 사항입니다: 첫 일주일, 첫 한 달, 그리고 첫 장애 발생 시점 순입니다.

모든 코드는 현재의 Python 클라이언트 API(search가 아닌 query_points)를 사용합니다.

첫 일주일

1. 페이로드 인덱싱(Payload indexing)은 자동으로 이루어지지 않습니다

이것이 가장 큰 문제입니다. Qdrant는 기본적으로 어떤 페이로드(payload) 필드에서도 필터링을 할 수 있게 해주며, 데모 규모에서는 매우 빠릅니다. 그래서 필터링이 "그냥 잘 작동한다"고 가정하기 쉽습니다. 실제로 작동은 합니다. 다만 후보 페이로드에 대해 **전체 스캔(full scan)**을 수행하는 방식이며, 이는 컬렉션(collection)이 커짐에 따라 성능이 급격히 떨어집니다.

필터링하려는 모든 필드에는 명시적인 인덱스가 필요합니다:

client.create_payload_index(
    collection_name="my_docs",
    field_name="category",
...

인덱싱되지 않은 필드로 필터링을 한다고 해서 경고가 뜨지는 않습니다. 증상은 그저 "수십만 개의 포인트(points)를 넘어가는 어느 시점부터 필터링된 쿼리가 느려졌다"는 것입니다. 페이로드 인덱스를 사후 처리가 아닌, 컬렉션 생성 스크립트의 일부로 만드세요.

2. 코사인 유사도(Cosine) vs 내적(dot product): 정규화가 결정합니다

만약 임베딩(embeddings)이 L2 정규화(L2-normalized)되어 있다면 — OpenAI와 Cohere의 임베딩이 그러합니다 — 코사인 유사도(cosine similarity)와 내적(dot product)은 **동일한 순위(identical rankings)**를 제공합니다. 하지만 내적은 정규화 단계를 건너뛰므로 더 빠른 선택지입니다:

vectors_config=VectorParams(size=1536, distance=Distance.DOT)

함정은 반대 방향으로도 작동합니다. 정규화되지 않은 (un-normalized) 임베딩에 DOT를 사용하면, 결과가 크기가 더 큰 벡터 쪽으로 조용히 편향됩니다. 에러는 발생하지 않지만, 미묘하게 잘못된 순위가 매겨집니다. 이는 최악의 종류의 버그입니다.

경험 법칙(Rule of thumb): OpenAI/Cohere → DOT. 그 외의 경우나 확실하지 않다면, 자동으로 정규화를 수행해 주는 COSINE을 사용하세요.

3. 컬렉션 설정(Collection config)은 영구적입니다

벡터 차원(dimensions)과 거리 측정 방식(distance metric)은 create_collection 이후에는 변경할 수 없습니다 (immutable). 마이그레이션 경로는 존재하지 않으며, 임베딩 모델을 교체한다는 것은 새로운 컬렉션을 만들고 모든 데이터를 처음부터 다시 인입(re-ingest)해야 함을 의미합니다.

이는 단순히 기본값을 선택할 것이 아니라, 사전에 신중하게 결정해야 할 문제입니다. 만약 모델을 교체할 가능성이 있다면(반드시 교체하게 될 것입니다), 첫날부터 **네임드 벡터 (named vectors)**를 사용하세요. 그러면 전체 시스템을 재구축하는 대신, 새 모델을 위한 새로운 네임드 벡터를 추가하고 데이터를 백필(backfill)할 수 있습니다:

vectors_config={
    "openai-small": VectorParams(size=1536, distance=Distance.DOT),
    # 나중에 새로운 컬렉션 없이 "openai-large"를 추가할 수 있는 여유 공간
...

첫 한 달

4. upsert는 포인트(point) 전체를 교체합니다

Qdrant에는 세 가지 업데이트 작업이 있으며, 잘못된 작업을 사용하면 데이터가 조용히 유실됩니다:

• upsert — 포인트 전체를 교체합니다: 벡터 및 모든 페이로드(payload) 필드
• set_payload — 전달한 페이로드 필드만 업데이트합니다
• update_vectors — 벡터만 업데이트합니다

전형적인 실수는 "필드 하나를 업데이트"하기 위해 upsert를 사용하는 것입니다. 다시 포함하지 않은 모든 페이로드 필드는 사라집니다. 에러도, 경고도 없습니다. 메타데이터를 패치(patching)하려는 것이라면 set_payload를 사용해야 합니다.

5. 매우 선택적인 필터는 알고리즘을 조용히 변경합니다

Qdrant의 필터링된 검색(filtered search)은 스마트합니다. 쿼리 플래너(query planner)는 필터에 일치하는 포인트가 얼마나 될지 추정하며, 만약 일치하는 집합이 매우 작다면(컬렉션의 약 1% 미만이라고 가정), HNSW 인덱스를 완전히 건너뛰고 일치하는 포인트들에 대해 정밀 스캔(exact scan)을 수행합니다. 해당 선택도(selectivity)에서는 그 방식이 실제로 더 빠르기 때문입니다.

이는 올바른 동작이지만, 사용자가 어떤 필터(filter)를 선택하느냐에 따라 "검색이 평소에는 빠르다가 가끔 느려지는" 혼란스러운 증상을 유발합니다. 만약 특정 차원(dimension)이 항상 매우 높은 선택도(selectivity)를 가진다면 — 테넌트별(per-tenant) 데이터가 전형적인 사례입니다 — 하나의 거대한 컬렉션을 필터링하는 대신, 별도의 컬렉션으로 분리하거나 Qdrant의 멀티테넌시(multitenancy) 패턴을 사용하는 것을 고려하십시오.

6. score_threshold를 설정하십시오. 그렇지 않으면 RAG 파이프라인이 정중하게 환각(hallucinate)을 일으킬 것입니다

기본적으로 검색은 결과가 얼마나 멀리 떨어져 있든 상관없이 limit에 해당하는 가장 가까운 결과들을 반환합니다. 컬렉션이 전혀 알지 못하는 것에 대해 질문하더라도, 여전히 상위 5개의 "가장 가까운" 청크(chunk)를 반환하며 — 이는 쓰레기 데이터입니다 — 그러면 LLM은 이를 바탕으로 자신 있게 답변을 합성할 것입니다.

해결책은 하나의 파라미터와 하나의 정직한 코드 경로를 추가하는 것입니다:

results = client.query_points(
    collection_name="my_docs",
    query=query_vector,
...

OpenAI 임베딩(embeddings)의 경우 0.7 정도의 임계값(threshold)이 합리적인 시작점이지만, 모델마다 점수 분포가 크게 다르므로 모델별로 조정하십시오. 결과가 비어 있는 경우(empty-results)를 처리하는 분기(branch)는 예외적인 상황이 아니라, 반드시 구현해야 할 기능입니다.

당신의 첫 번째 장애

7. HNSW 튜닝: 어떤 노브(knob)를 먼저 돌려야 하는지 알 것

세 가지 파라미터가 재현율(recall)/속도/메모리 간의 트레이드오프(trade-off)를 제어합니다:

• ef (검색 시간) — 검색 중의 빔 폭(beam width). 이것을 가장 먼저 튜닝하십시오. 인덱스 재구축(rebuild)이 필요 없으며, 종종 이것만으로도 충분합니다.
• ef_construct (기본값 100) — 인덱스 구축 중의 빔 폭. 값이 높을수록 그래프 품질은 좋아지지만, 데이터 삽입(ingest) 속도는 3~5배 느려집니다. 재구축이 필요합니다.
• m (기본값 16) — 노드당 에지(edge) 수. 값이 높을수록 재현율은 좋아지지만 메모리 사용량은 영구적으로 증가합니다. 재구축이 필요합니다.

따라서 재현율이 너무 낮을 때의 디버깅 순서는 다음과 같습니다: ef를 높입니다 $\rightarrow$ 그것으로 충분하지 않다면 ef_construct를 높이고 재구축합니다 $\rightarrow$ 그 후에야 m을 건드립니다. 블로그 포스트에서 봤다는 이유만으로 바로 m=64로 설정하는 것은 메모리를 영구적으로 낭비하는 결과를 초래합니다.

8. 스냅샷(Snapshots)은 당신의 백업 기본 단위입니다 — 그리고 스스로 스케줄링되지 않습니다

Self-hosted Qdrant에는 자동 백업 기능이 없습니다. 기본 단위는 스냅샷(Snapshot)입니다:

client.create_snapshot(collection_name="my_docs")

사고가 터진 후가 아니라, 터지기 전에 반드시 숙지해야 할 세 가지가 있습니다:

1. 스냅샷을 자동으로 실행해 주는 것은 아무것도 없습니다. Cron 등을 사용하여 직접 스케줄링하지 않으면 실행되지 않습니다.
2. 데이터와 동일한 디스크에 있는 스냅샷은 아무런 보호 수단이 되지 못합니다. 반드시 노드 외부(off-node)로 전송하십시오.
3. 복제(Replication)는 백업이 아닙. 분산 모드에서의 replication_factor > 1은 고가용성(High Availability)을 제공하지만, 잘못된 배포로 인한 삭제 작업까지 즐겁게 복제해 버립니다.

(Qdrant Cloud는 백업을 대신 처리해 주지만, 이 사항은 명백히 셀프 호스팅(Self-hosting) 시 주의해야 할 점입니다.)

미리 알아두면 다행인 두 가지

9. 희소 벡터(Sparse vectors)는 다른 유형이며, 하이브리드 검색(Hybrid search)은 쿼리 형태입니다

희소 벡터(Sparse vectors, BM25 방식의 키워드 매칭용)는 단순히 "플래그만 다른 밀집 벡터(Dense vectors)"가 아닙니다. 이들은 별도로 설정되며(SparseVectorParams를 사용하는 sparse_vectors_config), 고유한 값 유형(SparseVector(indices=[...], values=[...]))을 사용합니다.

또한 하이브리드 검색은 마법 같은 hybrid=True 파라미터가 아니라, 하나의 쿼리 형태(Query shape)입니다. 즉, 두 개의 prefetch 서브 쿼리(하나는 밀집 벡터, 하나는 희소 벡터)를 Reciprocal Rank Fusion(RRF)으로 결합하는 방식입니다:

client.query_points(
    collection_name="my_docs",
    prefetch=[
...

이를 설정(Configuration)이 아닌 구성(Composition)의 관점으로 바라보게 되면, Query API 전체가 훨씬 더 이해하기 쉬워질 것입니다.

10. 하나의 포인트(Point)는 여러 개의 벡터를 가질 수 있습니다

제가 마침내 깨달은 모델은 다음과 같습니다: Qdrant의 포인트(Point)는 "메타데이터가 포함된 하나의 벡터"가 아닙니다. 그것은 여러 개의 이름이 지정된 밀집 벡터(Dense vectors)와 희소 벡터(Sparse vectors)를 동시에 가질 수 있는 **엔티티(Entity)**입니다:

vector={
    "text": text_embedding,
    "image": image_embedding,
...

이것은 하나의 컬렉션(Collection) 내에서 동일한 객체에 대해 텍스트 검색, 이미지 검색, 키워드 검색을 수행하는 것을 의미합니다. 세 개의 저장소를 동기화할 필요도 없고, 페이로드(Payload)를 중복해서 가질 필요도 없습니다. 멀티모달(Multimodal) 또는 하이브리드 시스템을 설계하고 있다면, 처음부터 이 기능을 중심으로 설계해야 합니다(주의사항 #3을 참조하세요: 나중에 데이터를 다시 인제스트(Re-ingest)하지 않고는 이 기능을 나중에 덧붙일 수 없습니다).

근저에 깔린 패턴

이 목록에 있는 거의 모든 항목은 서로 다른 옷을 입고 있는 동일한 교훈입니다:
Qdrant의 기본 설정(defaults)은 데모용으로 튜닝되어 있으며, 운영 환경(production)은 명시적인 결정들의 집합입니다 — 필터 필드(filter fields)를 인덱싱하고, 목적에 맞는 거리 측정 지표(distance metric)를 선택하며, 적절한 업데이트 연산(update operation)을 고르고, 자체적인 스냅샷(snapshots)을 스케줄링하며, 자체적인 점수 임계값(threshold)을 설정해야 합니다.

이 중 어느 것도 결함이 아닙니다. 그것들은 당신을 신뢰하는 도구의 구성 인터페이스(configuration surface)일 뿐입니다. 하지만 퀵스타트 가이드는 당신을 대신해 이러한 결정들을 내려줄 수 없으며, 여기서 발생하는 최악의 실패는 소리 없이 찾아오는 실패들입니다. 장애 대응 채널(incident channel)에서 마주하기보다는 블로그 포스트에서 미리 마주하는 것이 더 낫습니다.