HNSW 인덱스 파라미터

HNSW(Hierarchical Navigable Small World)는 Weaviate의 기본 벡터 인덱스로, 대부분의 유스케이스에 권장됩니다. vectorIndexConfig로 인덱스 타입과 속성을 설정하며, 컬렉션 생성 시 정의합니다. 인덱스 타입은 hnsw, flat, dynamic, hfresh 중 선택해요. flat은 인덱스당 객체 수가 적은 멀티테넌시 같은 경우에, dynamic은 객체 수가 임계값을 넘으면 flat에서 hnsw로 자동 전환되는 방식에 어울립니다.

출처: 공식문서 - Vector index

상황부터 — 파라미터가 왜 중요한가

HNSW는 검색 속도·정확도(recall)·임포트 속도 사이의 트레이드오프를 조정하는 파라미터 묶음으로 이뤄져요. 일부 HNSW 파라미터는 변경 가능(mutable) 하지만, 일부는 컬렉션 생성 후에는 수정할 수 없어요. 그래서 컬렉션을 만들 때부터 신중히 정해야 합니다.

주요 HNSW 파라미터

파라미터	타입	기본값	변경	설명
`cleanupIntervalSeconds`	integer	300	Yes	정리(cleanup) 빈도. 높을수록 덜 자주·더 많이 정리. 보통 조정 불필요.
`distance`	string	`cosine`	No	거리 메트릭(cosine, dot 등).
`ef`	integer	-1	Yes	검색 중 HNSW가 쓰는 동적 리스트 크기. 높을수록 정확하지만 느림. 512 초과는 recall 개선이 미미. `-1`이면 Weaviate가 dynamic `ef`로 자동 조정.
`efConstruction`	integer	128	No	인덱스 구축 중 사용하는 동적 리스트 크기. 높으면 그래프가 정확해져 검색 성능 좋아지지만 임포트는 느림. 0보다 커야 함.
`HNSWGeoIndexEF`	integer	800	Yes	geo 기반 쿼리의 검색 깊이.
`maxConnections`	integer	32	No	요소당 최대 연결 수. 0번 레이어 위 레이어의 연결 제한. 0번 레이어는 (2×`maxConnections`) 연결 가능. 0보다 커야 함.
`dynamicEfMin`	integer	100	Yes	dynamic `ef`의 하한. `ef`가 -1일 때만 사용.
`dynamicEfMax`	integer	500	Yes	dynamic `ef`의 상한. `dynamicEfMax`가 limit보다 높으면 무시되고 `ef`가 한계가 됨.
`dynamicEfFactor`	integer	8	Yes	dynamic `ef`의 배수(리스트 잠재 길이). `ef`가 -1일 때만 사용.
`filterStrategy`	string	`acorn`	Yes	필터 전략. `acorn`(v1.34부터 기본) 또는 `sweeping`.
`flatSearchCutoff`	integer	40000	Yes	flat-search cutoff 임계값. 벡터 인덱스 검색을 강제하려면 0으로 설정.
`skip`	boolean	false	No	true면 컬렉션을 인덱싱하지 않음. 벡터 생성도 막으려면 `vectorizer: none`과 함께.
`vectorCacheMaxObjects`	integer	1e12	Yes	메모리 캐시 최대 객체 수. 기본 1조(1e12).
`rq`/`pq`/`bq`/`sq`	object	--	Yes	양자화 압축 설정(각각 RQ/PQ/BQ/SQ).

PQ는 일부 데이터가 로드돼 있어야 하므로, 샤드당 10,000~100,000개 벡터가 로드된 뒤 활성화하는 것을 권장합니다.

파라미터 선택 요령 (ef/efConstruction/maxConnections)

쿼리 수·임포트/업데이트량·요구 recall 조합에 따라 설정이 달라져요.

쿼리 적고 임포트 없음, recall 낮음 — 이상적인 조합. ef와 efConstruction 둘 다 낮게 유지.
쿼리 적고 임포트 없음, recall 높음 — ef와 efConstruction을 recall이 만족할 때까지 높이면 약 100%까지 도달 가능.
쿼리 많고 임포트 없음, recall 낮음 — 쿼리/초(QPS)가 많으므로 ef는 낮게, efConstruction은 크게 높임.
쿼리 많고 임포트 많고 recall 높음 — efConstruction을 임포트 시간 한계까지 올린 뒤 ef로 QPS↔recall 균형을 맞춤.

대부분 유스케이스의 좋은 출발점(팁):

파라미터	값
`ef`	64
`efConstruction`	128
`maxConnections`	32

데이터베이스 수준 파라미터

PERSISTENCE_HNSW_MAX_LOG_SIZE — HNSW write-ahead-log 최대 크기. 기본 500MiB. compaction 효율을 높이려면 HNSW 그래프 크기에 가깝게 설정 권장(메모리 증가).
DEFAULT_QUANTIZATION — 새 컬렉션에 기본 적용할 양자화 기법 결정. 초기화하지 않으면 압축 미적용.

툼스톤(tombstone) 정리

툼스톤은 삭제된 객체를 표시하는 레코드예요. HNSW 인덱스에서 cleanupIntervalSeconds에 따라 주기적으로 정리됩니다. 인덱스가 커지면 정리도 오래 걸리고 리소스를 많이 써서, 사이클당 삭제 수를 제어하는 환경변수가 있습니다.

TOMBSTONE_DELETION_MIN_PER_CYCLE — 불필요한 정리 사이클 방지
TOMBSTONE_DELETION_MAX_PER_CYCLE — 정리가 너무 오래 걸리고 리소스를 많이 쓰는 것 방지
TOMBSTONE_DELETION_CONCURRENCY — 정리 스레드 수(기본: CPU 코어 절반)

예) 샤드당 3억 객체 클러스터라면 MIN=1000000(100만), MAX=10000000(1000만)이 좋은 출발점일 수 있어요.

요약

HNSW는 검색 속도·recall·빌드 시간의 트레이드오프 중심에 서 있는 기본 인덱스.
ef(검색), efConstruction(구축), maxConnections(연결 수) 세 축을 워크로드에 맞춰 튜닝.
생성 후 수정 불가능한 파라미터(efConstruction, maxConnections, distance)는 컬렉션 생성 시점에 결정.
대규모 삭제가 잦은 컬렉션은 툼스톤 정리 환경변수로 부하를 통제.

HNSW 인덱스 파라미터