Qdrant Cloud 클러스터 구성하기

Qdrant Cloud 클러스터 구성하기 (cloud-configure-cluster)

Qdrant Cloud는 특정 요구 사항에 맞게 클러스터를 최적화할 수 있는 몇 가지 고급 구성 옵션을 제공해요. 이러한 옵션은 Qdrant Cloud 콘솔의 클러스터 상세(Cluster Details) 페이지에서 접근할 수 있어요.

클라우드 플랫폼은 Qdrant에서 사용 가능한 모든 구성 옵션을 노출하지는 않아요. 여기서는 관련된 옵션만 선별해서 아래에 자세히 설명해 드릴게요.

또한 클라우드 플랫폼은 최적의 성능과 안정성을 보장하기 위해 다음 설정을 클러스터에 자동으로 구성해요:

  • 클러스터의 최대 컬렉션 수는 1000으로 설정돼요. 컬렉션 수가 많아지면 성능이 저하될 수 있어요. 자세한 내용은 멀티테넌시(Multitenancy)를 참고해 주세요.
  • 성능과 안정성을 개선하기 위해 새 컬렉션에는 기본적으로 엄격 모드(strict mode)가 활성화되며, 다음과 같은 제한 사항이 적용돼요:
    • 인덱스되지 않은 페이로드 키를 필터링해 포인트를 조회하는 것은 허용되지 않아요 (unindexed_filtering_retrieve가 false로 설정됨).
    • 인덱스되지 않은 페이로드 키를 필터링해 포인트를 업데이트하는 것은 허용되지 않아요 (unindexed_filtering_update가 false로 설정됨).
    • 컬렉션당 최대 페이로드 인덱스 수는 100으로 설정돼요 (max_payload_index_count가 100으로 설정됨).
  • 분산 배포와 수평 확장을 지원하기 위해 클러스터 모드가 자동으로 활성화돼요.
  • 컬렉션당 최대 페이로드 인덱스 수는 100으로 설정돼요. 페이로드 인덱스 수가 많아지면 성능이 저하될 수 있어요 (Qdrant v1.16.0부터).

Cluster node endpoints

컬렉션 기본값 (Collection Defaults)

클러스터의 새 컬렉션에 대한 구성의 기본값을 설정할 수 있어요. 이 기본값은 컬렉션 생성 요청에서 재정의하지 않는 한 새 컬렉션을 만들 때 사용돼요.

기본 복제 팩터(Replication Factor), 기본 쓰기 일관성 팩터(Write Consistency Factor), 그리고 벡터를 RAM에 캐시하지 않고 디스크에만 저장할지 여부를 구성할 수 있어요.

자세한 내용은 Qdrant 구성을 참고해 주세요.

고급 최적화 (Advanced Optimizations)

이러한 고급 설정을 구성하면 성능과 안정성에 영향을 미칠 수 있어요. 사용 사례에 정말 필요한지 확신하지 않는 한 기본값을 사용할 것을 권장해요.

옵티마이저 CPU 예산 (Optimizer CPU Budget)

최적화 및 인덱싱 작업에 할당할 CPU(스레드) 수를 구성해요:

  • 0 또는 비어 있으면(기본값) - Qdrant는 사용 가능한 CPU 수, 최적화 작업 수, 트래픽 부하에 따라 최적화 작업에 할당하지 않고 하나 이상의 CPU 코어를 남겨 둬요.
  • 음수이면 - Qdrant는 사용 가능한 CPU에서 이 수만큼 빼서 최적화에 사용해요.
  • 양수이면 - Qdrant는 정확히 이 수만큼의 CPU를 최적화에 사용해요.

비동기 스코어러 (Async Scorer)

리스코어링(rescoring) 시 io_uring을 사용하는 비동기 스코어러를 활성화해요. 자세한 내용은 Qdrant 내부 살펴보기: io_uring와 대규모 검색(Large Scale Search)를 참고해 주세요.

클라이언트 IP 제한 (Client IP Restrictions)

구성하면 선택한 IP 범위만 클러스터에 접근할 수 있어요. 이는 클러스터를 보호하고 신뢰할 수 있는 네트워크에서 오는 클라이언트만 연결할 수 있게 하려고 할 때 유용해요.

Cluster node endpoints

재시작 모드 (Restart Mode)

클라우드 플랫폼은 버전 업그레이드 또는 유지보수 중에 클러스터에 가장 적합한 재시작 모드를 자동으로 선택해요. 멀티 노드 클러스터에 복제 팩터가 2 이상인 컬렉션이 하나 이상 있으면 클라우드 플랫폼은 롤링 재시작(rolling restart) 모드를 사용해요. 이는 클러스터의 노드를 한 번에 하나씩 재시작하므로 재시작 과정에서도 클러스터가 계속 사용 가능한 상태를 유지한다는 뜻이에요.

멀티 노드 클러스터이지만 모든 컬렉션의 복제 팩터가 1이면 클라우드 플랫폼은 병렬 재시작(parallel restart) 모드를 사용해요. 이는 클러스터의 노드를 동시에 재시작한다는 뜻으로, 짧은 다운타임이 발생하지만 롤링 재시작보다 빠를 거예요.

클러스터 상세 페이지의 고급 구성 섹션에서 클러스터의 기본 재시작 모드를 재정의할 수 있어요.

Cluster node endpoints

Qdrant Cloud는 클러스터 노드 전반의 샤드 분포를 지속적으로 모니터링하고, 데이터가 고르게 분포되도록 백그라운드에서 샤드를 리밸런싱해요. 이는 클러스터를 수평으로 확장할 때도 일어나요. 리밸런싱 목표는 컬렉션별이 아니라 모든 컬렉션을 합친 노드당 총 샤드 수 및/또는 크기이므로, 클러스터 전체가 그 기준으로 균형 잡혀 있어도 단일 컬렉션은 고르지 않게 배치된 것처럼 보일 수 있어요.

Qdrant Cloud는 샤드 리밸런싱을 위해 세 가지 전략을 제공해요:

  • by_count_and_size (기본값): 이 전략은 샤드 수와 크기를 기준으로 샤드를 리밸런싱해요. 모든 노드가 동일한 수의 샤드를 갖고 샤드 크기가 노드 간에 고르게 분포되도록 보장해요.
  • by_count: 이 전략은 샤드 수만을 기준으로 리밸런싱해요. 모든 노드가 동일한 수의 샤드를 갖도록 보장하지만, 샤드 크기는 노드 간에 고르지 않을 수 있어요.
  • by_size: 이 전략은 크기만을 기준으로 샤드를 리밸런싱해요. 샤드가 노드 간에 크기별로 고르게 분포되도록 보장하지만, 모든 노드의 샤드 수는 동일하지 않을 수 있어요.

자동 리밸런싱이 활성화된 상태에서 샤드를 수동으로 옮기면(샤드 이동(Moving Shards) 참조), 그 이동으로 인해 노드의 샤드 수나 크기가 목표 범위를 벗어나면 자동 리밸런싱이 이를 바로잡기 위해 샤드를 다시 옮길 수 있어요. 노드 간 샤드 분포를 수동으로 제어하려면 샤드 리밸런스 전략(Shard Rebalance Strategy) 옵션에서 비활성화(Disabled) 를 선택해 자동 샤드 리밸런싱을 꺼 주세요.

Cluster node endpoints

클러스터 이름 바꾸기 (Rename a Cluster)

클러스터 상세 페이지에서 Qdrant 클러스터의 이름을 바꿀 수 있어요.

Cluster Actions

클러스터 이름을 바꿔도 기능이나 구성에는 영향을 미치지 않아요. 클러스터의 고유 ID와 클러스터 URL은 동일하게 유지돼요.

Rename Cluster Dialog

클러스터에 레이블 추가하기 (Adding Labels to a Cluster)

클러스터 상세 페이지에서 Qdrant 클러스터에 레이블을 추가할 수 있어요. 레이블은 키-값 쌍으로, 클러스터를 구성하고 관리하는 데 도움을 줘요.

Cluster Labels

감사 로깅 (Audit Logging)

클러스터 상세 페이지의 클러스터 구성 탭에서 클러스터에 대한 감사 로그를 활성화할 수 있어요. 감사 로그는 클러스터에 이루어진 모든 API 호출의 기록을 제공해요. 이는 보안 및 규정 준수 목적에 유용해요.

감사 로그는 Qdrant v1.17.0부터 모든 유료 클러스터에서 사용할 수 있으며, 로그 다운로드 엔드포인트는 Qdrant v1.17.1부터 사용할 수 있어요.

다음 정보가 추적돼요:

  • 수행된 동작 (예: list_collections, create_collection, upsert_points 등)
  • 동작의 타임스탬프
  • 동작을 수행하는 데 사용된 API 키 ID, 또는 Web UI를 통해 수행된 경우 사용자 ID
  • 동작 결과 (성공 또는 실패)
  • 동작이 수행된 IP 주소

로그 파일의 회전 주기(일별/시간별)와 보존 기간(유지할 로그 파일 수)을 구성할 수 있어요.

감사 로그 파일은 클러스터의 암호화된 스토리지 디스크에 저장돼요. 충분한 스토리지 용량이 있는지 확인해야 해요. 스토리지 용량과 사용량은 클러스터 메트릭에서 확인할 수 있어요.

Qdrant API를 통해 클러스터에서 감사 로그를 다운로드할 수 있어요:

curl -X POST 'https://node-N-YOUR-CLUSTER-URL:6333/audit/logs' \
  -H 'api-key: QDRANT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "limit": 50,
    "time_from": "2026-03-26T00:00:00Z",
    "time_to": "2026-03-27T00:00:00Z",
    "filters": {
      "result": "denied",
      "collection": "my_collection"
    }
  }'

필터 없이 호출할 수도 있어요:

curl -X POST 'https://node-N-YOUR-CLUSTER-URL:6333/audit/logs' \
  -H 'api-key: QDRANT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

더 알아보기 (Learn more)

출처: Qdrant 공식문서 - Configure Clusters