Qdrant 핵심 개념 자주 묻는 질문

Qdrant 핵심 개념 자주 묻는 질문 (faq-qdrant-fundamentals)

Qdrant를 처음 접하거나 운영하다 보면 "이런 것도 되나?", "왜 이렇게 동작하지?" 싶은 질문이 꼭 나오게 마련이에요. 여기서는 벡터, 검색, 컬렉션, 보안, 클라우드까지 Qdrant의 기초 개념에 대한 질문들을 엮어서 하나씩 풀어볼게요.

출처: Qdrant 공식문서

Vectors (벡터)

Qdrant가 지원하는 벡터 차원의 최댓값은 얼마인가요?

Dense 벡터에서 Qdrant는 최대 65,535차원까지 지원해요.

저장할 수 있는 벡터 메타데이터의 최대 크기는 얼마인가요?

메타데이터 크기에 대한 고정 제한(inherent limitation)은 없어요. 다만 성능과 리소스 사용에 맞게 최적화하는 것이 좋습니다. 사용자가 설정에서 상한을 지정할 수도 있어요.

같은 유사도 검색 쿼리를 다른 머신에서 실행하면 결과가 달라질 수 있나요?

네, 하드웨어 구성과 병렬 처리 방식이 다르기 때문에 결과가 아주 조금 달라질 수 있어요.

이 차이는 데이터의 특성과 구체적인 애플리케이션에 따라 달라집니다. 차원, 도메인 특화 모델, 각 임베딩의 성능 특성 등을 고려해 보세요.

Qdrant는 한 데이터 포인트에 여러 개의 벡터를 기본 지원해서, 서로 다른 제공자의 임베딩이 같은 컬렉션 안에 공존할 수 있어요.

네, Qdrant는 다른 벡터 저장소에서 임베딩을 이전(migration)하는 것도 지원해서, Qdrant로의 전환과 기능 도입이 수월해요.

인덱스된 벡터 수가 컬렉션의 벡터 수와 일치하지 않는 이유는?

Qdrant는 컬렉션의 모든 벡터를 항상 인덱스할 필요는 없어요. 데이터를 세그먼트 단위로 저장하는데, 세그먼트가 충분히 작으면 전체 스캔(full-scan) 검색이 더 효율적이거든요.

컬렉션 상태가 green인지, 그리고 인덱스되지 않은 벡터 수가 인덱싱 임계값보다 작은지 확인하세요.

컬렉션 정보가 포인트 수를 부정확하게 보여주는 이유는?

Qdrant의 컬렉션 정보 API는 컬렉션의 포인트 수를 근사값으로 반환해요. 정확한 수가 필요하면 count API를 사용하면 됩니다.

컬렉션의 벡터가 내가 업로드한 것과 일치하지 않아요.

두 가지 가능한 이유가 있어요.

컬렉션 설정에서 Cosine 거리 메트릭을 사용한 경우. 이때 Qdrant는 더 빠른 거리 계산을 위해 벡터를 사전에 정규화해요. 원본 벡터를 반드시 보존해야 한다면 Dot 거리 메트릭을 고려해 보세요.
uint8 데이터 타입으로 벡터를 저장한 경우. uint8은 입력 값에 특별한 형식을 요구해서 임베딩 모델의 일반적인 출력과 호환되지 않을 수 있어요.

포인트 하나에 벡터를 몇 개나 저장할 수 있나요? 벡터가 아예 없는 포인트도 가능한가요?

포인트 하나에는 dense, sparse, multi 벡터를 얼마든지 담을 수 있어요. 다만 각각 컬렉션의 스키마에 구성되어 있어야 합니다. Qdrant가 강제하는 하드 리밋은 없지만 실질적인 한계는 적용돼요. 벡터가 하나 추가될 때마다 메모리 사용이 늘어나서, 현실적인 상한은 사용 가능한 RAM과 저장 공간에 의해 결정됩니다. 벡터 하나만 붙일 수도 있고, 이름이 다른 여러 벡터를 붙일 수도 있어요(예: 시맨틱 검색용 dense 벡터 옆에 키워드 매칭용 sparse 벡터). 이렇게 하면 한 컬렉션 안에서 같은 데이터의 여러 표현에 대해 하이브리드 쿼리를 실행할 수 있어요. 각 벡터는 반드시 컬렉션의 스키마에 정의되어 있어야 합니다.

포인트는 벡터가 0개일 수도 있어요. 업서트(upsert)할 때 벡터를 제공하지 않으면, Qdrant는 ID와 페이로드만 가진 포인트로 저장합니다. 필터링을 포함한 문서 저장소로 Qdrant를 쓰고 싶거나, 나중에 벡터를 추가할 계획이 있을 때 유용해요. 벡터 없는 포인트는 최근접 이웃 검색 결과에는 나타나지 않지만, scroll과 페이로드 필터링으로는 완전히 접근 가능합니다.

네, Qdrant Cloud를 사용한다면 Qdrant Cloud Inference로 임베딩을 생성할 수 있어요. 한 번의 API 호출로 데이터를 임베딩·저장·인덱싱해서, 별도의 추론 서비스나 임베딩 파이프라인이 필요 없어요.

Cloud Inference는 시맨틱 검색용 dense 모델, 키워드 검색용 sparse 모델, 이미지·텍스트 검색용 멀티모달 모델을 지원합니다. 임베딩이 클러스터 네트워크 안쪽에서 생성되기 때문에 외부 API 오버헤드를 피할 수 있어서, 지연 시간이 낮고 이그레스 비용이 없으며 움직이는 부품(느슨한 연결 고리)이 적어요.

무료로 사용할 수 있는 모델도 여럿 있는데, 모든 클러스터 티어에서(무료 티어 포함) 쓸 수 있어요. Qdrant Cloud Console의 Cluster Detail 페이지에 있는 Inference 탭에서 사용 가능한 모델과 사용량을 확인할 수 있습니다.

Qdrant 오픈소스나 셀프 호스팅을 쓰고 있다면 Cloud Inference는 사용할 수 없어요. 이때는 Qdrant의 가벼운 로컬 추론 라이브러리인 FastEmbed를 쓰거나, 직접 임베딩 모델·서비스를 가져오면 됩니다. 지원되는 모델과 제공자는 임베딩 문서에서 확인하세요.

문서의 각 청크(chunk)를 Qdrant에서 별도의 포인트로 만들어야 하나요?

네, 대부분의 RAG(Retrieval-Augmented Generation) 구성에서 각 청크는 별도의 포인트로 저장돼요. 청크 텍스트(또는 그 참조)는 페이로드에 들어가고, 그 청크의 임베딩이 벡터가 됩니다. 포인트들이 document_id 페이로드 필드를 공유하면 결과를 원본 문서로 추적할 수 있어요.

청크를 어떻게 나누는지가 결과에 큰 영향을 주는데, 도메인에 따라 다릅니다. 시작점으로 보면: 책이나 산문에는 문단 단위 분할이 잘 맞고, 기술 문서나 Q&A 콘텐츠에는 문장 단위 분할이 더 잘 맞는 경향이 있어요. 실험을 계획해 보세요 — 청크 전략은 검색 품질에서 가장 영향을 많이 주는 변수 중 하나입니다.

참고: 텍스트 청크 전략(Text Chunking Strategies)

포인트 삭제는 내부적으로 어떻게 동작하나요? 삭제할 때마다 인덱스를 다시 만들까요?

Qdrant는 삭제를 비트마스크(bitmask)를 이용한 소프트 삭제로 구현해서, 삭제할 때마다 인덱스를 다시 만들지 않아요. 비트마스크는 가벼운 데이터 구조라서, 삭제된 포인트의 데이터에 접근하지 않고도 그 포인트를 연산에서 제외해야 하는지 빠르게 판단할 수 있어요. 물리적 정리는 Vacuum Optimizer가 백그라운드에서 처리합니다.

삭제 연산 후에는 API로 그 포인트에 즉시 접근할 수 없어요. 소프트 삭제 메커니즘은 내부 구현 세부 사항입니다.

변경 사항이 없는 포인트를 업서트해도 삭제 후 재삽입이 일어나나요?

네. Qdrant는 업서트 전에 유사도 검사를 하지 않아요. 이미 존재하는 포인트를 동일한 데이터로 업서트해도, 여전히 이전 버전을 삭제 표시하고 새 복사본을 삽입합니다.

포인트의 `version` 필드는 무엇을 나타내나요?

Query API 응답의 version 필드는 그 포인트에 대한 마지막 수정의 내부 샤드 레벨 연산 번호를 나타내요. 내부 프로세스에 의해 증가하기 때문에, 애플리케이션 레벨 쓰기 횟수의 신뢰할 만한 지표가 아니고 복제본 간 비교도 불가능합니다. 애플리케이션 레벨 쓰기 추적이 필요하면 직접 관리하는 페이로드 카운터를 사용하세요.

Search (검색)

Qdrant는 실시간 데이터 업데이트와 검색을 어떻게 처리하나요?

Qdrant는 벡터 데이터의 라이브 업데이트를 지원해서, 새로 삽입·업데이트·삭제된 벡터가 즉시 검색에 반영돼요. 백그라운드 인덱스 업데이트 중에는 인덱스되지 않은 세그먼트에 대해 전체 스캔 검색을 사용합니다.

검색 결과에 null 값을 가진 벡터가 있어요. 왜죠?

기본적으로 Qdrant는 네트워크 트래픽을 최소화하려고 검색 결과에 벡터를 반환하지 않아요. Search/Scroll의 with_vector 파라미터를 true로 설정하면 강제로 반환하게 만들 수 있습니다.

그런데도 결과에 "vector": null이 보인다면, 전달하는 벡터의 형식이 올바르지 않거나 upsert 메서드를 호출하는 방식에 문제가 있을 수 있어요.

벡터 없이 검색하려면 어떻게 하나요?

아마 scroll 메서드를 찾고 계신 것 같아요. 필터 기반으로 레코드를 가져오거나 컬렉션의 모든 레코드를 순회할 수 있습니다.

필터된 벡터 검색이 느려요. 무엇을 먼저 확인해야 하나요?

필터링하는 모든 필드에 페이로드 인덱스를 추가하세요. 페이로드 인덱싱은 HNSW 파라미터 변경 같은 다른 최적화보다 필터된 쿼리에서 훨씬 큰 속도 향상을 만들어 주는 경우가 많아요.

최상의 결과를 얻으려면 데이터를 업로드하기 전에 페이로드 인덱스를 만드세요. 나중에 데이터를 업로드할 때는 m이나 ef_construct를 최소 변경(예: 100에서 101로)해서 HNSW 인덱스를 다시 만듭니다. 새 인덱스가 완성될 때까지 쿼리는 기존 인덱스로 계속 서비스되므로 다운타임이 없어요. ef_construct 값을 바로 원래 값으로 되돌리지 말고, 새 값으로 유지하세요.

페이로드 인덱스가 없는 필드로 클라이언트가 필터링하지 못하게 하려면 strict mode를 켜고 unindexed_filtering_retrieve를 false로 설정하면 됩니다.

참고: 인덱싱, 저지연 검색, 느린 요청 로그

Qdrant는 전문 검색(full-text search)이나 하이브리드 검색을 지원하나요?

Qdrant는 우선 벡터 검색 엔진이에요. 그래서 전문 검색 지원도 벡터 검색 사용 사례를 해치지 않는 범위에서만 구현합니다. 인터페이스와 성능 모두 해당돼요.

Qdrant가 할 수 있는 것:

전문 검색 필터로 검색
벡터 검색에 전문 필터 적용(즉, 특정 단어·구문이 있는 레코드 사이에서 벡터 검색 수행)
접두사 검색과 시맨틱 search-as-you-type
SPLADE나 유사 모델에서 쓰는 sparse 벡터
Multi-vectors, 예: ColBERT 같은 late-interaction 모델
여러 검색의 조합

Qdrant가 지원할 계획이 없는 것:

비벡터 기반 검색·랭킹 함수
내장 온톨로지 또는 지식 그래프
쿼리 분석기 같은 NLP 도구

물론 Qdrant를 필요로 하는 어떤 특수 도구(전문 검색 엔진 포함)와도 결합할 수 있어요. 하이브리드 검색에 대한 우리의 접근 방식을 더 읽어보세요.

하이브리드 검색에서 RRF(Reciprocal Rank Fusion)와 DBSF(Distribution-Based Score Fusion)는 언제 써야 하나요?

두 방법 모두 여러 검색 레그(예: dense와 sparse)의 점수를 합치지만, 작동 방식이 달라요.

RRF (Reciprocal Rank Fusion) 는 점수 크기가 아니라 순위(position)를 기준으로 랭크 목록을 합칩니다. 서로 다른 검색 방법의 점수가 호환되지 않는 스케일일 때(dense vs. sparse에서 흔함) 잘 동작해요. 기본적으로 여기서 시작하세요. 필요에 따라 가중치와 k를 조정합니다.
DBSF (Distribution-Based Score Fusion) 는 합치기 전에 prefetch별 점수 분포를 기준으로 점수를 정규화해요. 점수 분포가 잘 정돈되어 있고 절대 점수 값이 최종 랭킹에 영향을 주길 원할 때 더 좋은 결과를 낼 수 있어요.

커스텀 퓨전을 위해서는 Formula Query를 사용하세요. 예를 들어 감쇠(decay) 함수로 두 점수를 0-1 범위로 정규화한 뒤 합칠 수 있어요. 이 방식은 감쇠 함수 파라미터를 동적으로 설정할 수 없으므로 각 코퍼스의 대략적 점수 분포를 파악해야 합니다. Formula Query는 prefetch 순위에 접근할 수 없고 원시 점수만 접근할 수 있어서, 커스텀 순위 기반 퓨전은 지원하지 않아요.

어느 방법이 내 사례에 더 좋은지 평가하려면 작은 golden 쿼리 집합을 만들고 각 방법에서 검색 품질 메트릭(예: NDCG@10)을 비교해 보세요.

참고: 하이브리드 쿼리 레퍼런스의 퓨전 방법 선택 결정 표, 그리고 퓨전 방법 선택 노트북(BEIR/SciFact에서 RRF vs 가중 RRF vs DBSF를 재사용 가능한 가중치 튜닝 헬퍼와 함께 실행).

하이브리드 검색 결과가 관련성이 없어요. 어디서부터 디버깅해야 하나요?

다음 순서로 진행하세요.

sparse 전처리를 확인하세요. sparse 결과가 나쁘면 흔히 토큰화 문제예요. 비영어 텍스트라면 텍스트 검색 설정에서 언어별 형태소 분석(stemming)과 불용어 목록을 구성하세요.
레그를 분리하세요. dense-only와 sparse-only 쿼리를 각각 실행해 보세요. 한 레그가 단독으로 나쁜 결과를 낸다면 퓨전을 튜닝하기 전에 그걸 먼저 고치세요.
퓨전 가중치를 튜닝하세요. 두 레그가 개별적으로는 괜찮은데 퓨전이 품질을 떨어뜨린다면, RRF 구성에서 prefetch별 가중치를 조정해 보세요. 보편적인 기본값은 없어요. 작은 라벨링된 쿼리 집합으로 평가합니다.
리랭킹 단계를 추가하세요. 정밀도가 지연 시간보다 중요하다면 리랭킹을 마지막 단계로 두면 불완전한 검색을 회복할 수 있어요.

Qdrant에서 필터링하는 세 가지 접근 방식은 무엇이고, 각각 언제 써야 하나요?

세 가지 전략이 있어요.

페이로드 인덱스만 사용 — 필터링을 통한 순수 논리적 분리. 어떤 카디널리티에서도 동작합니다.
is_tenant=true를 가진 페이로드 인덱스 — 논리적 분리 + 공유 샤드 위의 물리적 공동 배치(co-location)와 테넌트별 하위 인덱스. 여전히 어떤 카디널리티에서도 동작하며, 컬렉션당 한 필드만 이 설정을 쓸 수 있어요.
커스텀 샤딩(shard_key_selector) — 서로 다른 샤드로 나누는 하드한 물리적 경계. 노이지-네이버(noisy-neighbor) 문제를 없애줘요. 낮은 카디널리티(< 약 1,000개 고유 값)에서, 그리고 항상 그 필드로 필터링할 때만 권장합니다.

같은 쿼리를 `limit=20`와 `limit=100`으로 실행하면, 처음 20개 결과가 일치한다고 보장되나요?

결과는 일반적으로 겹치는 구간에서 일관적일 것으로 기대돼요. 그러나 HNSW는 근사 알고리즘이에요. limit가 클수록 검색 범위가 넓어져서 더 작은 limit에서 반환된 것보다 더 좋은 매치를 찾을 수 있어요. limit=100이 더 좋은 매치를 찾으면 처음 20개 포인트를 재정렬할 수 있습니다.

Query API 응답의 `time` 필드는 무엇을 나타내나요? 네트워크 지연을 포함하나요?

time 값은 초 단위이며 Qdrant 서버가 요청을 처리하는 데 쓴 총 시간을 나타내요. 클라이언트와 서버 사이의 네트워크 왕복 시간은 포함하지 않습니다.

검색 결과를 페이지네이션할 때 중복 결과가 나오는 이유는?

HNSW가 근사 알고리즘이기 때문에 요청 사이에 결과의 랭킹이 살짝 바뀔 수 있어요. 그래서 offset으로 페이지네이션하면 같은 포인트가 여러 페이지에 나오거나 포인트가 통째로 건너뛸 수 있습니다. 이건 버그가 아니라 예상된 동작이에요.

이를 우회하는 세 가지 방법이 있어요.

클라이언트 사이드 페이지네이션 — 한 번의 요청으로 큰 배치(예: 상위 100개)를 가져와 클라이언트에서 페이지네이션합니다. 왕복을 줄이고 중복을 없애지만, 사용자가 한 번에 보는 것보다 많은 데이터를 반환하는 대가가 있어요.
정확 검색(exact search) — HNSW를 우회해 모든 벡터를 스캔해서 안정적이고 결정적인 순서로 결과를 반환해요. 이러면 offset 기반 페이지네이션이 올바르게 동작합니다. 지연 시간이 높아서 작은 컬렉션에서만 실용적이에요.
본 ID 제외 — 이후 페이지마다 이전 페이지의 모든 포인트 ID를 담은 must_not: has_id 필터를 전달합니다. 제외 목록은 페이지마다 limit 개수만큼 커져서, 순차적·정방향 페이지네이션에는 잘 맞지만 임의 페이지로 점프하기에는 실용적이지 않아요.

참고: 안정적 정렬(Stable Ordering)

`limit`이 `hnsw_ef`보다 크면 Qdrant가 자동으로 `hnsw_ef`를 조정하나요?

네. Qdrant는 내부적으로 ef = max(ef, limit)로 설정해서 후보 목록이 요청한 결과 수 이상이 되도록 해요.

검색 중 `hnsw_ef`의 기본값은 무엇인가요?

기본적으로 hnsw_ef는 ef_construct(기본값: 100)와 같아요. ef_construct는 그래프 구성 중 고려하는 이웃 수를 제어하는 컬렉션 레벨 구성이고, hnsw_ef는 검색 중 동적 후보 목록 크기를 제어하는 쿼리별 파라미터입니다.

다른 양자화 방법들의 기본 `rescore` 값은 무엇인가요?

기본적으로 rescoring은 네 가지 양자화 방법에서만 켜집니다: binary quantization, TurboQuant 1 Bit, TurboQuant 1.5 Bit, TurboQuant 2 Bit. 다른 양자화 방법은 기본적으로 rescore하지 않아요. 기본 동작은 쿼리 타임의 rescore 파라미터로 덮어쓸 수 있습니다.

양자화 검색 파라미터에서 `ignore=true`는 무엇을 하나요?

ignore가 true면 Qdrant는 여전히 양자화된 벡터로 만든 HNSW 그래프를 탐색하지만, 후보를 점수 매길 때 양자화 거리 대신 정확한(전체 정밀도) 거리를 사용해요. 완전히 양자화된 검색과 비교해 다른 이웃이 선택될 수 있어서 일부 비용이 들지만 리콜을 개선할 수 있어요.

Collections (컬렉션)

컬렉션을 몇 개나 만들 수 있나요?

원하는 만큼 만들 수 있지만, 각 컬렉션은 추가 리소스가 필요하다는 걸 알아두세요. 작은 컬렉션을 많이 만드는 것은 상당한 리소스 소비 오버헤드를 만들기 때문에 강력히 권장하지 않아요.

사용자/대화/문서마다 컬렉션을 만드는 것은 안티패턴으로 간주합니다.

컬렉션, 격리, 다중 사용자에 대해 더 자세히는 멀티테넌시(Multitenancy) 문서를 읽어보세요.

임베딩하는 데이터가 같은 페이로드 구조를 공유하고, 한 요청에서 여러 벡터 공간을 가로질러 쿼리하고 싶을 때(예: 같은 제품에 대해 dense 텍스트 벡터와 CLIP 이미지 벡터 결합)는 named vectors를 사용하세요. 페이로드 스키마가 크게 다르거나, 독립적인 스케일링이 필요하거나, 포인트에 구성된 벡터 중 하나만 설정·조회하거나, 새 임베딩을 테스트하거나, 특정 벡터 집합이 훨씬 자주 단독으로 쿼리될 때는 별도의 컬렉션을 사용하세요.

일반 지침: named vectors는 하나의 포인트(와 그 페이로드)를 공유해요. 서로 다른 임베딩이 근본적으로 다른 개체(entity)를 나타낸다면 다른 컬렉션에 넣어야 합니다.

참고: Named Vectors

네, named vectors를 사용한다면 가능합니다.

새 모델용 named vector를 추가하고
백그라운드에서 포인트를 재임베딩한 다음
준비가 되면 기존 named vector를 제거합니다.

named vectors를 쓰지 않는다면 새 컬렉션을 만들어야 해요. 별칭(alias) 기반 스왑으로 다운타임 없는 마이그레이션을 할 수 있습니다.

새 컬렉션을 만들고 새 모델로 재임베딩한 데이터를 넣습니다.
인덱싱이 끝나면 컬렉션 별칭을 원자적으로 업데이트해 새 컬렉션을 가리키게 합니다.
마이그레이션이 안정적이라고 확신될 때 기존 컬렉션을 삭제합니다.

참고: 새 임베딩 모델로 마이그레이션

컬렉션이 "grey" 상태인 이유는?

grey 상태의 컬렉션은 옵티마이저가 멈췄다는 뜻이에요. 최적화가 진행 중일 때 Qdrant 인스턴스가 재시작되면 이런 일이 생길 수 있습니다. 이 상태 동안 인덱스되지 않은 데이터의 양이 늘어날 수 있어요. Qdrant는 인덱스되지 않은 세그먼트에 대해 전체 스캔 검색으로 폴백하기 때문에 쿼리 지연 시간이 나빠집니다. indexed_only나 prevent_unoptimized를 활성화하면 Qdrant가 인덱스되지 않은 데이터를 반환하지 않아 검색 결과가 불완전할 수 있어요.

흔한 복구 단계:

Qdrant Web UI의 Trigger Optimizers 버튼을 사용하세요. 컬렉션 정보 페이지에서 grey 상태 옆에 표시됩니다.
업데이트 컬렉션 연산을 보내 최적화를 다시 트리거하세요.

참고: Grey 컬렉션 상태

왜 내 쓰기가 HTTP 507로 거부되나요?

write_consistency_factor개의 복제본이 쓰기를 수용하면 쓰기가 성공해요. 노드에 리소스 쿼터가 설정되어 있으면 쓰기를 받아줄 복제본을 가진 노드가 남지 않을 수 있어요. 507은 write_consistency_factor에 도달할 복제본이 너무 적게 남았다는 뜻입니다. 기본 factor가 1이라면, 샤드의 어떤 복제본에도 공간이 없었다는 뜻이에요.

GET /quotas를 사용해 어느 피어가 가득 찼는지 확인하세요. 노드는 사용량이 떨어지자마자 쓰기를 재개하지 않는다는 점에 주의하세요. 걸린 한도는 사용량이 해제 마진(기본 5퍼센트포인트) 아래로 내려가야 풀립니다.

컬렉션에 많은 수의 벡터를 업로드하려면 어떻게 해야 하나요?

Bulk Upload 가이드에서 권장 사항을 읽어보세요.

벡터 업로드에 권장되는 배치 크기는?

보편적인 권장 배치 크기는 없어요. 최적값은 벡터 차원, 페이로드 크기, 클러스터 구성, 사용 가능한 메모리에 따라 달라집니다. 자신의 환경에 맞는 배치 크기를 벤치마크해 보세요.

좋은 시작점은 배치당 64~256 포인트예요. 다만 배치 안의 연산이 본질적으로 비싼 경우(많은 포인트에 영향을 주는 업데이트나 필터 기반 업데이트 등)에는 개별 요청을 보내는 것이 더 효율적입니다.

참고: Bulk Upload

양자화된 벡터만 저장하고 전체 정밀도 벡터는 버려도 되나요?

아니요. Qdrant는 리인덱싱, 리스코어링 등 여러 연산에서 전체 정밀도 벡터가 필요해요.

양자화를 켠 후 원본 전체 정밀도 벡터를 삭제해도 되나요?

아니요. Qdrant는 Vacuum Optimizer가 세그먼트를 다시 만들 때 양자화 표현을 다시 계산하려면 원본 전체 정밀도 벡터가 필요해요. Qdrant는 각 세그먼트의 전체 정밀도 벡터에서 양자화 통계(offset과 alpha)를 유도하므로, 이걸 없애면 리인덱싱이 불가능해집니다.

Compatibility (호환성)

벡터 계산에서 Qdrant는 CPU나 GPU와 호환되나요?

Qdrant는 주로 확장성과 효율성을 위해 CPU 가속에 의존해요. 그러나 주요 벤더 모두에서 GPU 가속 인덱싱도 지원합니다.

버전 간 호환성을 보장하나요?

버전이 더 오래된 경우, 우리는 인접한 두 마이너 버전 사이에서만 호환성을 보장해요. 클라이언트 버전에도 동일하게 적용됩니다. 클라이언트 버전이 클러스터 버전과 한 마이너 버전 이상 떨어지지 않도록 하세요. 우리 제품 특유의 문제·오류에 대한 break/fix 트러블슈팅 지원은 하겠지만, 커스텀 코드를 검토·작성(또는 재작성)·디버깅하는 것은 Qdrant의 책임이 아닙니다.

다운그레이드를 지원하나요?

모든 제품에서 클러스터 다운그레이드는 지원하지 않아요. 더 새로운 버전의 Qdrant를 배포하면 데이터가 새로운 저장 형식으로 자동 마이그레이션됩니다. 이 마이그레이션은 되돌릴 수 없어요.

최신 버전으로 업데이트할 때 문제를 피하려면 어떻게 해야 하나요?

인접한 버전 사이에서 업데이트할 때만 호환성을 보장해요. 버전을 한 번에 하나씩 올려야 합니다: 1.1 -> 1.2, 그리고 1.2 -> 1.3, 그다음 1.3 -> 1.4.

페이로드 인덱스는 업로드 전후 중 언제 만들어야 하나요?

인덱스 재구축을 피하려면 업로드 전에 페이로드 인덱스를 만드세요. 다만 업로드 후 인덱스를 정의해도 괜찮은 시나리오가 있어요. 예를 들어 출시 후 새 필터 로직을 구성할 수 있습니다.

필터를 미리 안다면 항상 먼저 인덱스해야 해요. 나중에 다른 페이로드를 인덱스해야 한다면 여전히 할 수 있지만, 성능 비용을 알아두세요.

HNSW 인덱스가 이미 만들어진 뒤 페이로드 인덱스를 추가해야 한다면, 전체 리인덱스를 어떻게 트리거하나요?

m이나 ef_construct를 바꾸면 자동으로 전체 백그라운드 HNSW 재구축이 트리거돼요. 페이로드 인덱스만 추가하는 경우에는 ef_construct를 최소 변경(예: 100에서 101로)하세요. 새 인덱스가 완성될 때까지 쿼리는 기존 인덱스로 계속 서비스되므로 다운타임이 없어요. ef_construct 값을 바로 원래 값으로 되돌리지 말고 새 값으로 유지하세요.

사용자마다 Qdrant 컬렉션을 하나씩 만들어야 하나요?

아니요. 사용자마다 컬렉션을 만드는 것은 리소스가 더 많이 듭니다.

각 사용자에 별도 컬렉션을 만드는 대신, 단일 컬렉션을 만들고 페이로드로 접근을 분리하는 것을 권장해요. 각 Qdrant 포인트는 메타데이터로 페이로드를 가질 수 있습니다. 멀티테넌시에는 각 포인트에 user_id나 tenant_id를 넣으면 돼요. 저장 공간을 더 최적화하려면 페이로드 필드에 테넌트 인덱싱을 활성화할 수 있습니다.

Security (보안)

내 Qdrant 클러스터는 기본적으로 안전한가요?

배포 방식에 따라 달라요. Qdrant Cloud 클러스터는 항상 기본적으로 안전합니다. 셀프 호스팅 배포는 그렇지 않아요. 모든 네트워크 인터페이스에 열려 있고, 직접 설정하기 전까지는 인증이 구성되어 있지 않습니다. 전체 구성 가이드는 보안(Security)을 참고하세요.

Qdrant는 읽기 전용 접근을 지원하나요?

네. 쿼리는 허용하지만 모든 쓰기 연산은 차단하는 읽기 전용 API 키를 구성할 수 있어요. 두 키를 동시에 활성화할 수 있으므로, 기본 키를 회전하지 않고 소비자에게 읽기 전용 키를 발급할 수 있습니다. 읽기 전용 API 키를 참고하세요.

특정 컬렉션에만 접근을 제한할 수 있나요?

네. Qdrant는 JWT 기반 접근 제어를 지원해서 개별 컬렉션 범위로 읽기·쓰기 권한을 가진 서명된 토큰을 발급할 수 있어요. 각 사용자나 서비스가 자기 데이터에만 접근해야 하는 멀티테넌트 배포에 유용합니다. Granular Access API Keys를 참고하세요.

Cloud (클라우드)

Qdrant Cloud 클러스터를 스케일 다운할 수 있나요?

네, Qdrant Cloud 클러스터는 수직·수평 모두 스케일 다운이 가능해요. 단, 수직 스케일 다운 중에는 디스크 크기를 줄일 수 없다는 점에 유의하세요.

Qdrant 핵심 개념 자주 묻는 질문