ChromaDB 인덱스 설정

ChromaDB 인덱스 설정 (Configure Collections)

컬렉션은 벡터를 어떻게 색인하고 검색할지 정하는 설정(configuration) 을 갖고 있어요. 기본값만으로도 대부분의 사용 사례에서 좋은 성능을 내지만, 데이터 규모나 정확도·성능 요구에 따라 값을 바꿀 수 있어요.

출처: 공식문서 - Configure Collections

HNSW 인덱스 (단일 노드)

단일 노드(Single Node) ChromaDB 컬렉션에서는 근사 최근접 이웃(ANN) 검색을 위해 HNSW(Hierarchical Navigable Small World) 인덱스를 사용해요. HNSW는 계층 구조를 가진 그래프 기반 인덱스로, 차원이 큰 벡터에서도 가까운 벡터를 빠르게 찾아주는 알고리즘이에요.

주요 설정값은 이래요:

  • space — 유사도/거리 계산 방식을 정해요. cosine, l2, ip(내적) 같은 값을 쓸 수 있어요.
  • ef_construction — 인덱스를 만들 때 이웃 후보 목록 크기를 정해요. 값이 클수록 인덱스 품질은 좋아지지만 메모리와 시간이 늘어나고, 작을수록 정확도는 줄어드는 대신 생성이 빨라져요. 기본값은 100이에요.
  • sync_threshold — 인덱스를 영구 저장소와 동기화할 시점을 정해요. 기본값은 1000이고, 생성 후 수정할 수 있어요.
  • resize_factor — 인덱스가 커질 때 얼마나 늘어날지를 정해요. 기본값은 1.2이고, 생성 후 수정할 수 있어요.

예를 들어 space와 ef_construction을 바꿔 컬렉션을 만들면:

collection = client.create_collection(
    name="my-collection",
    embedding_function=OpenAIEmbeddingFunction(model_name="text-embedding-3-small"),
    configuration={
        "hnsw": {
            "space": "cosine",
            "ef_construction": 200
        }
    }
)

SPANN 인덱스 (분산/클라우드)

Distributed Chroma와 Chroma Cloud 컬렉션에서는 ANN 검색을 위해 SPANN(Spacial Approximate Nearest Neighbors) 인덱스를 사용해요. 주요 설정값은:

  • 한 노드당 후보 이웃 수로 기본값이 200인 값, 최대 이웃 수를 정하는 max_neighbors(기본값 64), 그리고 분할 클러스터에서 재할당을 고려할 가장 가까운 클러스터 수를 정하는 reassign_neighbor_count(기본값 64) 같은 파라미터를 다뤄요.

임베딩 함수 구성

컬렉션에 어떤 임베딩 함수를 쓰느냐도 인덱스 구성에 영향을 줘요. 임베딩 함수는 create_collection의 embedding_function 인자로 넘기거나, 컬렉션 configuration 안의 embeddingFunction(타입스크립트) 필드로 지정할 수 있어요.

import os
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction, CohereEmbeddingFunction

# embedding_function 인자 사용
openai_collection = client.create_collection(
    name="my_openai_collection",
    embedding_function=OpenAIEmbeddingFunction(
        model_name="text-embedding-3-small",
    )
)

많은 임베딩 함수는 외부 임베딩 제공자 API와 연동하기 위해 API 키가 필요해요. ChromaDB는 제공자별 표준 환경 변수에서 자동으로 API 키를 찾아서 사용해요. 환경 변수 이름을 바꾸고 싶다면 api_key_env_var로 커스텀 환경 변수를 지정할 수 있어요.

cohere_ef = CohereEmbeddingFunction(
    api_key_env_var="MY_CUSTOM_COHERE_API_KEY",
    model_name="embed-english-light-v2.0",
    truncate="NONE",
)

더 알아보기 (Learn more)