설정

설정 (Configuration) (ops-configuration-configuration)

Qdrant는 처음부터 대부분의 사용 사례에 잘 맞는 합리적인 기본값을 제공해요. 그런데 상황에 따라 이 설정을 바꿔야 할 때가 있어요. 이 페이지에서는 설정 파일과 환경 변수를 활용해 Qdrant를 원하는 대로 구성하는 방법을 살펴볼게요.

출처: Qdrant 공식문서

Qdrant는 대부분의 사용 사례에 적합한 컬렉션·네트워크 설정의 합리적인 기본값을 갖고 출시돼요. 이 기본값들은 Qdrant 소스 코드에서 볼 수 있어요. 설정을 커스터마이즈하고 싶다면 설정 파일과 환경 변수를 사용하면 돼요.

설정 파일 (Configuration Files)

Qdrant를 커스터마이즈하려면 다음 위치 중 한 곳에 설정 파일을 마운트할 수 있어요. 이 가이드에서는 .yaml 파일을 사용하지만, Qdrant는 .toml, .json, .ini 같은 다른 형식도 지원해요.

  1. 메인 설정: qdrant/config/config.yaml

커스텀 config.yaml 파일을 마운트해서 기본 설정을 덮어써요.

 docker run -p 6333:6333 \ -v $( pwd ) /config.yaml:/qdrant/config/config.yaml \ qdrant/qdrant
  1. 환경별 설정: config/{RUN_MODE}.yaml

Qdrant는 RUN_MODE 변수에 따라 환경별 설정 파일을 찾아요. 기본적으로 공식 Docker 이미지는 RUN_MODE=production을 사용하므로 config/production.yaml을 찾게 돼요.

RUN_MODE를 다른 값(예: dev)으로 바꾸고 해당 파일을 제공하면 이 설정을 덮어쓸 수 있어요.

 docker run -p 6333:6333 \ -v $( pwd ) /dev.yaml:/qdrant/config/dev.yaml \ -e RUN_MODE = dev \ qdrant/qdrant
  1. 로컬 설정: config/local.yaml

local.yaml 파일은 주로 버전 관리에 포함되지 않는 머신별 설정에 사용해요.

 docker run -p 6333:6333 \ -v $( pwd ) /local.yaml:/qdrant/config/local.yaml \ qdrant/qdrant
  1. --config-path로 커스텀 설정

--config-path 인자로 커스텀 설정 파일 경로를 지정할 수 있어요. 이 설정은 다른 설정 파일을 덮어써요.

 docker run -p 6333:6333 \ -v $( pwd ) /config.yaml:/path/to/config.yaml \ qdrant/qdrant \ ./qdrant --config-path /path/to/config.yaml

이 설정들이 어떻게 로드되고 병합되는지에 대한 자세한 내용은 아래의 로딩 순서와 우선순위를 참고하세요. 사용 가능한 전체 설정 옵션 목록은 아래에서 볼 수 있어요.

환경 변수 (Environment Variables)

환경 변수로도 Qdrant를 설정할 수 있는데, 환경 변수는 항상 최고 우선순위를 가지며 파일 기반 설정을 덮어써요.

환경 변수 형식은 다음과 같아요. QDRANT__ 프리픽스로 시작해야 하고, 중첩 속성은 이중 밑줄(__)로 구분해요. 예를 들어:

 docker run -p 6333:6333 \ -e QDRANT__LOG_LEVEL = INFO \ -e QDRANT__SERVICE__API_KEY = <MY_SECRET_KEY> \ -e QDRANT__SERVICE__ENABLE_TLS = true \ -e QDRANT__TLS__CERT = ./tls/cert.pem \ qdrant/qdrant

이렇게 하면 다음 설정이 적용돼요.

 log_level : INFO service : enable_tls : true api_key : <MY_SECRET_KEY> tls : cert : ./tls/cert.pem

로딩 순서와 우선순위 (Loading Order and Priority)

시작할 때 Qdrant는 여러 설정 소스를 하나의 유효한 설정으로 병합해요. 로딩 순서는 다음과 같아요 (중요도가 낮은 것부터 높은 것 순).

  1. 내장 기본 설정 (Embedded default configuration)
  2. config/config.yaml
  3. config/{RUN_MODE}.yaml
  4. config/local.yaml
  5. 커스텀 설정 파일
  6. 환경 변수

덮어쓰기 동작 (Overriding Behavior)

목록에서 나중에 오는 소스의 설정이 앞선 소스의 설정을 덮어써요.

  • config/{RUN_MODE}.yaml(3)의 설정은 config/config.yaml(2)의 설정을 덮어써요.
  • --config-path로 제공한 커스텀 설정 파일(5)은 다른 모든 파일 기반 설정을 덮어써요.
  • 환경 변수(6)는 최고 우선순위이며 파일의 어떤 설정보다도 덮어써요.

설정 검증 (Configuration Validation)

Qdrant는 시작할 때 설정을 검증해요. 문제가 발견되면 서버가 오류 정보와 함께 즉시 종료돼요. 예를 들어:

 Error: invalid type: 64-bit integer `-1`, expected an unsigned 64-bit or smaller integer for key `storage.hnsw_index.max_indexing_threads` in config/production.yaml

이 덕분에 잘못된 설정이 일찍 잡혀서, Qdrant가 잘못된 설정으로 실행되는 것을 방지해요.

설정 옵션 (Configuration Options)

다음 YAML 예시는 사용 가능한 설정 옵션을 설명해요.

아래 보이는 memory 옵션에 대한 자세한 내용은 메모리 계층(Memory Tiers)을 참고하세요.

 log_level : INFO # Logging configuration # Qdrant logs to stdout. You may configure to also write logs to a file on disk. # Be aware that this file may grow indefinitely. # logger: # # Logging format, supports `text` and `json` # format: text # on_disk: # enabled: true # log_file: path/to/log/file.log # log_level: INFO # # Logging format, supports `text` and `json` # format: text # buffer_size_bytes: 1024 storage : # Where to store all the data storage_path : ./storage # Where to store snapshots snapshots_path : ./snapshots snapshots_config : # "local" or "s3" - where to store snapshots snapshots_storage : local # s3_config: # bucket: "" # region: "" # access_key: "" # secret_key: "" # Where to store temporary files # If null, temporary snapshots are stored in: storage/snapshots_temp/ temp_path : null # Deprecated: use `payload.memory` instead. # If true - point payloads will not be stored in memory. # It will be read from the disk every time it is requested. # This setting saves RAM by (slightly) increasing the response time. # Note: those payload values that are involved in filtering and are indexed - remain in RAM. # # Default: true on_disk_payload : true # Default payload storage configuration for newly created collections. # Overrides the deprecated `on_disk_payload` flag if both are set. # payload: # # Memory placement of the payload storage: cold or cached. # memory: cold # Maximum number of concurrent updates to shard replicas # If `null` - maximum concurrency is used. update_concurrency : null # Write-ahead-log related configuration wal : # Size of a single WAL segment wal_capacity_mb : 32 # Number of WAL segments to create ahead of actual data requirement wal_segments_ahead : 0 # Normal node - receives all updates and answers all queries node_type : "Normal" # Listener node - receives all updates, but does not answer search/read queries # Useful for setting up a dedicated backup node # node_type: "Listener" performance : # Number of parallel threads used for search operations. If 0 - auto selection. max_search_threads : 0 # CPU budget, how many CPUs (threads) to allocate for an optimization job. # If 0 - auto selection, keep 1 or more CPUs unallocated depending on CPU size # If negative - subtract this number of CPUs from the available CPUs. # If positive - use this exact number of CPUs. optimizer_cpu_budget : 0 # Prevent DDoS of too many concurrent updates in distributed mode. # One external update usually triggers multiple internal updates, which breaks internal # timings. For example, the health check timing and consensus timing. # If null - auto selection. update_rate_limit : null # Limit for number of incoming automatic shard transfers per collection on this node, does not affect user-requested transfers. # The same value should be used on all nodes in a cluster. # Default is to allow 1 transfer. # If null - allow unlimited transfers. #incoming_shard_transfers_limit: 1 # Limit for number of outgoing automatic shard transfers per collection on this node, does not affect user-requested transfers. # The same value should be used on all nodes in a cluster. # Default is to allow 1 transfer. # If null - allow unlimited transfers. #outgoing_shard_transfers_limit: 1 # Enable async scorer which uses io_uring when rescoring. # Only supported on Linux, must be enabled in your kernel. # See: <https://qdrant.tech/articles/io_uring/#and-what-about-qdrant> #async_scorer: false # Whether components readable through either a memory mapping or io_uring should use # io_uring. Only has an effect on Linux. # # - unset (default): the immutable vector storages follow `async_scorer`, nothing else # uses io_uring. # - "disabled": no component uses io_uring. # - "auto": use io_uring for components with a `cold` memory placement, where reads hit # the disk. Components meant to sit in RAM keep using mmap, which is faster there. #io_uring: disabled # Maximum number of collections to load concurrently. #max_concurrent_collection_loads: 1 # Maximum number of local shards to load concurrently when loading a collection. #max_concurrent_shard_loads: 1 # Maximum number of segments to load concurrently when loading a local shard. #max_concurrent_segment_loads: 8 optimizers : # The minimal fraction of deleted vectors in a segment, required to perform segment optimization deleted_threshold : 0.2 # The minimal number of vectors in a segment, required to perform segment optimization vacuum_min_vector_number : 1000 # Target amount of segments optimizer will try to keep. # Real amount of segments may vary depending on multiple parameters: # - Amount of stored points # - Current write RPS # # It is recommended to select default number of segments as a factor of the number of search threads, # so that each segment would be handled evenly by one of the threads. # If `default_segment_number = 0`, will be automatically selected by the number of available CPUs default_segment_number : 0 # Do not create segments larger this size (in KiloBytes). # Large segments might require disproportionately long indexation times, # therefore it makes sense to limit the size of segments. # # If indexation speed have more priority for your - make this parameter lower. # If search speed is more important - make this parameter higher. # Note: 1Kb = 1 vector of size 256 # If not set, will be automatically selected considering the number of available CPUs. max_segment_size_kb : null # Maximum size (in KiloBytes) of vectors allowed for plain index. # Default value based on experiments and observations. # Note: 1Kb = 1 vector of size 256 # To explicitly disable vector indexing, set to `0`. # If not set, the default value will be used. indexing_threshold_kb : 10000 # Interval between forced flushes. flush_interval_sec : 5 # Max number of threads (jobs) for running optimizations per shard. # Note: each optimization job will also use `max_indexing_threads` threads by itself for index building. # If null - have no limit and choose dynamically to saturate CPU. # If 0 - no optimization threads, optimizations will be disabled. max_optimization_threads : null # This section has the same options as 'optimizers' above. All values specified here will overwrite the collections # optimizers configs regardless of the config above and the options specified at collection creation. #optimizers_overwrite: # deleted_threshold: 0.2 # vacuum_min_vector_number: 1000 # default_segment_number: 0 # max_segment_size_kb: null # indexing_threshold_kb: 10000 # flush_interval_sec: 5 # max_optimization_threads: null # Default parameters of HNSW Index. Could be overridden for each collection or named vector individually hnsw_index : # Number of edges per node in the index graph. Larger the value - more accurate the search, more space required. m : 16 # Number of neighbours to consider during the index building. Larger the value - more accurate the search, more time required

위 YAML의 나머지 부분(양자화, 서비스, 클러스터, TLS 섹션 등)은 소스 코드의 config.yaml에서 전체 옵션 주석을 확인할 수 있어요. 서비스·클러스터 관련 설정의 핵심 구조는 다음과 같아요.

 _https_client_certificate : false # Set an api-key. # If set, all requests must include a header with the api-key. # example header: `api-key: <API-KEY>` # # If you enable this you should also enable TLS. # (Either above or via an external service like nginx.) # Sending an api-key over an unencrypted channel is insecure. # # Uncomment to enable. # api_key: your_secret_api_key_here # Set an api-key for read-only operations. # If set, all requests must include a header with the api-key. # example header: `api-key: <API-KEY>` # # If you enable this you should also enable TLS. # (Either above or via an external service like nginx.) # Sending an api-key over an unencrypted channel is insecure. # # Uncomment to enable. # read_only_api_key: your_secret_read_only_api_key_here # Uncomment to enable JWT Role Based Access Control (RBAC). # If enabled, you can generate JWT tokens with fine-grained rules for access control. # Use generated token instead of API key. # # jwt_rbac: true # Hardware reporting adds information to the API responses with a # hint on how many resources were used to execute the request. # # Warning: experimental, this feature is still under development and is not supported yet. # # Uncomment to enable. # hardware_reporting: true # # Uncomment to enable. # Prefix for the names of metrics in the /metrics API. # metrics_prefix: qdrant_ cluster : # Use `enabled: true` to run Qdrant in distributed deployment mode enabled : false # Configuration of the inter-cluster communication p2p : # Port for internal communication between peers port : 6335 # Use TLS for communication between peers enable_tls : false # Configuration related to distributed consensus algorithm consensus : # How frequently peers should ping each other. # Setting this parameter to lower value will allow consensus # to detect disconnected nodes earlier, but too frequent # tick period may create significant network and CPU overhead. # We encourage you NOT to change this parameter unless you know what you are doing. tick_period_ms : 100 # Compact consensus operations once we have this amount of applied # operations. Allows peers to join quickly with a consensus snapshot without # replaying a huge amount of operations. # If 0 - disable compaction compact_wal_entries : 128 # Set to true to prevent service from sending usage statistics to the developers. # Read more: https://qdrant.tech/documentation/ops-configuration/usage-statistics telemetry_disabled : false # TLS configuration. # Required if either service.enable_tls or cluster.p2p.enable_tls is true. tls : # Server certificate chain file cert : ./tls/cert.pem # Server private key file key : ./tls/key.pem # Certificate authority certificate file. # This certificate will be used to validate the certificates # presented by other nodes during inter-cluster communication. # # If verify_https_client_certificate is true, it will verify # HTTPS client certificate # # Required if cluster.p2p.enable_tls is true. ca_cert : ./tls/cacert.pem # TTL in seconds to reload certificate from disk, useful for certificate rotations. # Only works for HTTPS endpoints. Does not support gRPC (and intra-cluster communication). # If `null` - TTL is disabled. cert_ttl : 3600 # Audit logging configuration. # When enabled, Qdrant writes structured JSON audit log entries for every # access-checked API request. # # audit: # enabled: false # dir: ./storage/audit # rotation: daily # max_log_files: 7 # # If true, use X-Forwarded-For header to determine client IP in audit logs. # # Only enable this when running behind a trusted reverse proxy or load balancer. # # WARNING: Enabling this without a trusted proxy allows clients to spoof their IP. # # Default: false # trust_forwarded_headers: false

더 알아보기 (Learn more)