관리

관리 (Administration)

Qdrant는 런타임에 인스턴스의 동작을 수정할 수 있는 관리 도구를 제공해요. 설정 파일을 수동으로 바꾸지 않고도 인스턴스 동작을 바꿀 수 있어요.

복구 모드 (Recovery Mode)

v1.2.0부터 사용 가능해요.

복구 모드는 Qdrant가 반복적으로 시작에 실패하는 상황에서 도움이 돼요. 복구 모드로 시작하면 Qdrant는 메모리 부족(out of memory)을 막기 위해 컬렉션 메타데이터만 로드해요. 이를 통해 예를 들어 컬렉션을 삭제하는 방식으로 메모리 부족 상황을 해결할 수 있어요. 문제를 해결한 뒤 Qdrant를 정상적으로 재시작하면 계속 운영할 수 있어요.

복구 모드에서는 컬렉션 삭제만 가능해요. 복구 중에는 컬렉션 메타데이터만 로드되기 때문이에요.

Qdrant Docker 이미지에서 복구 모드를 활성화하려면 환경 변수 QDRANT_ALLOW_RECOVERY_MODE=true를 설정해야 해요. 컨테이너는 먼저 정상적으로 시작을 시도하고, 메모리 부족 오류로 초기화가 실패하면 복구 모드로 재시작해요. 이 동작은 기본적으로 꺼져 있어요.

Qdrant 바이너리를 쓰는 경우에는, 환경 변수에 복구 메시지를 설정해서 복구 모드를 활성화할 수 있어요. 예를 들어 QDRANT__STORAGE__RECOVERY_MODE="My recovery message"처럼요.

저메모리 모드 (Low Memory Mode)

v1.18.0부터 사용 가능해요.

저메모리 모드는 시작 시 메모리 요구량을 줄여줘요. 메모리가 제한된 호스트에서는 정상 시작 과정이 노드가 접근 가능해지기 전에 메모리를 다 소진해서 크래시 루프가 생길 수 있어요. 저메모리 모드는 노드를 줄어든 메모리 사용량으로 기동시켜서, 메모리 사용을 줄이는 설정 변경을 할 수 있게 해줘요. 노드가 안정되면 원래대로 되돌리면 돼요.

세 가지 모드가 있어요.

모드	설명
disabled	기본값. 모든 컴포넌트를 저장된 그대로 로드해요.
no_resident	양자화된 벡터와 payload 필드 인덱스를, 구성된 티어와 무관하게 cold 메모리 티어로 내려요.
no_populate	no_resident와 같고, 추가로 로드 시 mmap 프리페치를 건너뛰어 벡터와 HNSW 그래프도 cold로 강제해요. 가장 낮은 시작 메모리 사용량이지만, OS 페이지 캐시가 따뜻해질 때까지 첫 쿼리는 더 느려요.

저메모리 모드를 활성화하려면 노드 구성 파일에 storage.low_memory_mode를 설정해요.

storage:
  low_memory_mode: no_populate   # or no_resident

또는 환경 변수를 사용해요.

QDRANT__STORAGE__LOW_MEMORY_MODE=no_populate

저메모리 모드는 다음 재시작 때 적용돼요. 컬렉션에 저장된 메모리 티어 설정을 바꾸는 게 아니라, 그 시작 동안 데이터가 어디에 로드되는지만 덮어쓸 뿐이에요.

스트릭트 모드 (Strict Mode)

v1.13.0부터 사용 가능해요.

스트릭트 모드는 Qdrant 클러스터를 보호하기 위해 컬렉션의 특정 유형의 연산을 제한하는 기능이에요. 시스템에 과부하를 줄 수 있는 비효율적인 사용 패턴을 막는 게 목표예요.

실행되는 쿼리를 통제할 수 없을 때, 스트릭트 모드는 더 예측 가능하고 반응적인 서비스를 보장해요. 한도를 넘으면 서버는 넘어선 한도에 대한 정보와 함께 클라이언트 측 오류를 반환해요.

strict_mode_config는 새 컬렉션을 만들 때 활성화할 수 있어요. 사용 가능한 모든 strict_mode_config 매개변수에 대한 정의는 스키마 정의를 참고해요. 이 구성에서 enabled 필드는 스트릭트 모드를 동적으로 켜고 끄는 토글로 동작해요.

구체적인 제한 없이 스트릭트 모드만 켜는 건 효과가 없어요. 시행하고 싶은 제한을 명시적으로 설정해야 해요.

Qdrant Cloud에서는 새 컬렉션에 대해 스트릭트 모드가 기본적으로 활성화되어 있어요. 구체적인 제한은 Qdrant Cloud 클러스터 구성 문서를 참고해요.

기본 한도를 올리거나 스트릭트 모드를 완전히 끌 수도 있어요. 다만 안정적인 클러스터를 보장하기 위해 기본 구성을 사용해 스트릭트 모드를 켜 둘 것을 강력히 권장해요. 기존 컬렉션에서 스트릭트 모드를 끄려면 다음을 사용해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": false
    }
}

인덱스되지 않은 payload로 조회하기 비활성화 (Disable Retrieving via Non Indexed Payload)

unindexed_filtering_retrieve를 false로 설정하면, 인덱스되지 않은 payload 키로 필터링해 포인트를 조회하는 걸 막아요. 이 연산은 매우 느릴 수 있어요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "unindexed_filtering_retrieve": false
    }
}

또는 나중에 기존 컬렉션에서 컬렉션 매개변수 업데이트 API를 통해 다시 켤 수 있어요.

PATCH /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "unindexed_filtering_retrieve": true
    }
}

인덱스되지 않은 payload로 업데이트하기 비활성화 (Disable Updating via Non Indexed Payload)

unindexed_filtering_update를 false로 설정하면, 인덱스되지 않은 payload 키로 필터링해 포인트를 업데이트하는 걸 막아요. 이 연산은 매우 느릴 수 있어요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "unindexed_filtering_update": false
    }
}

최대 payload 인덱스 개수 (Maximum Number of Payload Index Count)

max_payload_index_count는 컬렉션에 존재할 수 있는 payload 인덱스의 최대 개수를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "max_payload_index_count": 10
    }
}

최대 쿼리 limit 매개변수 (Maximum Query limit Parameter)

큰 결과 집합을 조회하는 것은 비용이 커요. max_query_limit는 단일 쿼리에서 조회할 수 있는 포인트의 최대 개수를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "max_query_limit": 10
    }
}

최대 timeout 매개변수 (Maximum timeout Parameter)

오래 실행되는 연산은 종종 더 깊은 문제의 징후예요. max_timeout은 모든 API 연산에서 timeout 매개변수의 최대값(초 단위)을 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "max_timeout": 10
    }
}

정확 검색 비활성화 (Disable Exact Search)

정확 검색(exact search)은 HNSW 인덱스를 우회하고 brute-force 스캔을 수행해서, 큰 컬렉션에서는 매우 느릴 수 있어요. search_allow_exact를 false로 설정하면 클라이언트가 정확 검색을 요청하지 못하게 해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "search_allow_exact": false
    }
}

최대 HNSW ef 매개변수 (Maximum HNSW ef Parameter)

높은 HNSW ef 값은 recall을 높이지만 검색 지연도 늘려요. search_max_hnsw_ef는 검색 매개변수에 허용되는 최대 ef 값을 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "search_max_hnsw_ef": 128
    }
}

최대 검색 오버샘플링 (Maximum Search Oversampling)

높은 오버샘플링(oversampling) 계수는 검색 중 평가되는 후보 수를 늘려서 지연 시간을 크게 증가시킬 수 있어요. search_max_oversampling은 검색 매개변수에 허용되는 최대 오버샘플링 계수를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "search_max_oversampling": 2.0
    }
}

필터링 조건의 최대 크기 (Maximum Size of a Filtering Condition)

큰 필터링 조건은 평가 비용이 커요. condition_max_size는 필터링 조건이 가질 수 있는 요소의 최대 개수를 제한해요. 예를 들어 MatchAny의 요소 수를 말해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "condition_max_size": 10
    }
}

필터 내 최대 조건 개수 (Maximum Number of Conditions in a Filter)

필터링 조건이 많으면 평가 비용이 커요. filter_max_conditions는 필터가 가질 수 있는 최대 조건 개수를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "filter_max_conditions": 10
    }
}

벡터 삽입 시 최대 배치 크기 (Maximum Batch Size When Inserting Vectors)

매우 큰 배치 업서트를 보내면 내부 혼잡이 생길 수 있어요. upsert_max_batchsize는 벡터 업서트 중 배치의 최대 크기(바이트)를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "upsert_max_batchsize": 1000
    }
}

검색 시 최대 배치 크기 (Maximum Batch Size When Searching)

매우 큰 검색 배치를 보내면 내부 혼잡이 생길 수 있어요. search_max_batchsize는 단일 배치 요청에서 허용되는 최대 검색 수를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "search_max_batchsize": 1000
    }
}

최대 컬렉션 저장 크기 (Maximum Collection Storage Size)

컬렉션의 최대 크기를 벡터 및/또는 payload 저장 크기 기준으로 설정할 수 있어요. max_collection_vector_size_bytes 및/또는 max_collection_payload_size_bytes는 컬렉션의 최대 바이트 크기를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "max_collection_vector_size_bytes": 1000000,
        "max_collection_payload_size_bytes": 1000000
    }
}

최대 상주 메모리 사용량 (Maximum Resident Memory Usage)

v1.19.0부터 더 이상 사용되지 않음(Deprecated). 메모리를 제한하려면 리소스 쿼터(resource quotas)를 사용해요.

노드가 메모리 압박을 받을 때 새로운 쓰기 연산은 클러스터를 불안정하게 만들 수 있어요. max_resident_memory_percent는 프로세스 상주 메모리가 시스템 전체 메모리에서 주어진 비율을 초과하면, 메모리를 많이 쓰는 쓰기 연산(업서트, set payload 등)을 거부해요. 삭제 연산은 영향을 받지 않아요. 값 범위는 1~100이에요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "max_resident_memory_percent": 90
    }
}

최대 포인트 개수 (Maximum Points Count)

max_points_count는 컬렉션의 최대 포인트 개수를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "max_points_count": 1000
    }
}

속도 제한 (Rate Limiting)

매우 높은 수신 요청 비율은 지연 시간에 부정적인 영향을 줄 수 있어요. read_rate_limit 및/또는 write_rate_limit는 레플리카당 분당 최대 연산 수를 제한해요.

최대 연산 수를 초과하면 클라이언트는 재시도 전 대기 시간을 제안하는 HTTP 429 오류 코드를 받아요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "read_rate_limit": 1000,
        "write_rate_limit": 100,
    }
}

멀티벡터당 최대 벡터 개수 (Maximum Vectors per Multivector)

포인트당 벡터가 많은 멀티벡터는 저장, 인덱싱, 쿼리에 비용이 커요. multivector_config는 각 이름 있는(named) 벡터에 대해 멀티벡터당 최대 벡터 개수를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "multivector_config": {
            "{vector_name}": {
                "max_vectors": 10
            }
        }
    }
}

최대 스파스 벡터 길이 (Maximum Sparse Vector Length)

긴 스파스 벡터는 메모리 사용량을 늘리고 필터링을 느리게 해요. sparse_config는 각 이름 있는 벡터에 대해 스파스 벡터의 최대 길이를 제한해요.

PUT /collections/{collection_name}
{
    "strict_mode_config": {
        "enabled": true,
        "sparse_config": {
            "{vector_name}": {
                "max_length": 1000
            }
        }
    }
}

이처럼 스트릭트 모드는 운영 중인 클러스터를 예측 가능하게 유지하는 강력한 도구예요. 한 번에 많은 제한을 거는 대신, 실제 상황에서 필요해지는 제한부터 하나씩 걸어보는 걸 권장해요.

출처: Qdrant 공식문서

더 알아보기 (Learn more)

• 운영 구성(Operational Configuration) 개요
• 메모리 티어
• 리소스 쿼터