벡터 인덱스 선택·구성하기

벡터 인덱스 선택·구성하기 (Flat/Dynamic/HFresh)

컬렉션의 각 네임드 벡터(named vector)는 자체 인덱스 설정을 가질 수 있어요. 멀티테넌트 컬렉션이면 각 테넌트가 컬렉션의 인덱스 설정을 물려받습니다. 기본값만으로도 훌륭하지만, 파라미터를 이해하면 검색 속도·정확도·메모리 사용을 더 잘 최적화할 수 있어요. 이 페이지에서는 HNSW·Flat·Dynamic·HFresh 네 인덱스 타입의 구성법을 다룹니다.

출처: 공식문서 - Select & configure vector indexes

상황부터 — 네 가지 벡터 인덱스를 언제 쓸까

HNSW(기본) — 대규모 데이터셋에서 빠르고 정확한 유사도 검색. 다층 그래프로 근사 최근접 이웃을 효율적으로 찾아요.
Flat — 완전 탐색(brute-force)으로 정확도를 보장. 소규모 인덱스(약 10,000~20,000 객체 미만)나 테넌트별로 작은 격리 인덱스가 있는 멀티테넌시에 탁월.
Dynamic — 객체 수 변동이 심한 유스케이스. Flat으로 시작해 객체 수가 임계값(기본 10,000)을 넘으면 HNSW로 자동 전환.
HFresh — 대규모 데이터셋에서 낮은 메모리로 근사 검색. 벡터를 여러 posting list에 넣어 병렬 검색.

Flat 인덱스 구성

Flat 인덱스는 인덱스의 모든 벡터와 쿼리 벡터를 하나씩 비교합니다. 복잡한 그래프 구조를 저장하지 않아 메모리 오버헤드가 극히 낮은 게 큰 장점이에요. 양자화를 켜서 brute-force 검색을 더 빠르게 만들 수 있어요.

from weaviate.classes.config import Configure, VectorDistances

client.collections.create(
    name=collection_name,
    # ... other parameters
    vector_config=Configure.Vectors.text2vec_weaviate(
        vector_index_config=Configure.VectorIndex.flat(
            distance_metric=VectorDistances.COSINE,                     # Distance metric
            quantizer=Configure.VectorIndex.Quantizer.bq(cache=True),   # Quantizer configuration
            vector_cache_max_objects=1000000,                           # Maximum number of objects in the cache
        )
    ),
)

Dynamic 인덱스 구성

Dynamic 인덱스는 멀티테넌트 환경에서 특히 유용해요. 작은 테넌트는 메모리 효율적인 Flat을, 큰 테넌트는 성능 좋은 HNSW를 자동으로 얻습니다.

⚠️ 비동기 인덱싱 필수 — Dynamic 인덱스는 Weaviate 인스턴스에 비동기 인덱싱(async indexing)이 활성화돼야 합니다.

기본 설정으로 만들기:

from weaviate.classes.config import Configure

client.collections.create(
    name=collection_name,
    # ... other parameters
    vector_config=Configure.Vectors.text2vec_weaviate(
        vector_index_config=Configure.VectorIndex.dynamic()
    ),
    multi_tenancy_config=Configure.multi_tenancy(enabled=True), # Dynamic index works well with multi-tenancy set-ups
)

HNSW와 Flat 설정, 그리고 전환 임계값도 커스터마이즈할 수 있어요.

from weaviate.classes.config import Configure, VectorDistances

client.collections.create(
    name=collection_name,
    # ... other parameters
    vector_config=Configure.Vectors.text2vec_weaviate(
        vector_index_config=Configure.VectorIndex.dynamic(
            distance_metric=VectorDistances.COSINE,                     # Distance metric
            threshold=25000,                                            # Threshold for switching to dynamic index
            hnsw=Configure.VectorIndex.hnsw(
                # Your preferred HNSW configuration
            ),
            flat=Configure.VectorIndex.flat(
                # Your preferred flat configuration
            ),
        )
    ),
    multi_tenancy_config=Configure.multi_tenancy(   # Dynamic index works well with multi-tenancy set-ups
        enabled=True,
        auto_tenant_creation=True,
        auto_tenant_activation=True,
    ),
)

HFresh 인덱스 구성

HFresh는 SPFresh 계열의 클러스터 기반 인덱스로, 중심(centroid) 인덱스에 HNSW를 쓰며 데이터 대부분을 디스크에 유지해 메모리 효율이 좋아요. 기본 설정은 Configure.VectorIndex.hfresh()만 넘기면 돼요.

기본값: distance_metric=cosine, replicas=4(벡터당 posting list 수), search_probe=256(검색할 posting list 수), max_posting_size_kb=48.

search_probe 기본값 256은 v1.36.20, v1.37.10, v1.38.2 이후 릴리스에서 적용. 그 이전 릴리스는 64가 기본.

from weaviate.classes.config import Configure, VectorDistances

client.collections.create(
    name=collection_name,
    # ... other parameters
    vector_config=Configure.Vectors.text2vec_weaviate(
        vector_index_config=Configure.VectorIndex.hfresh(
            distance_metric=VectorDistances.COSINE,     # Distance metric
            max_posting_size_kb=1024,                    # Max posting list size in KB
            replicas=4,                                  # Number of posting lists per vector
            search_probe=64,                             # Number of posting lists to search
        )
    ),
)

튜닝 포인트:

max_posting_size_kb — posting list 최대 크기(KB). 기본 48.
replicas — 벡터를 저장할 posting list 수. 높이면 recall↑, 저장↑.
search_probe — 쿼리 시 검색할 posting list 수. 높이면 recall↑, 검색 느려짐. 위 예시는 64로 기본값보다 낮춰 속도를 우선한 경우.

벡터 인덱스 선택·구성하기