Postgres의 HNSW 인덱스: 벡터 검색을 위한 인덱스 웰

HNSW는 Hierarchical Navigable Small World를 의미합니다. 이는 그래프 인덱스입니다. 각 벡터는 가장 가까운 이웃과 연결된 노드가 되며 여러 개의 겹쳐진 레이어로 구성됩니다. 검색은 그래프 상단의 가장 희박한 레이어에서 시작한 다음 가장 관련성이 높은 이웃으로 레이어별로 내려갑니다. 따라서 검색 시간은 줄 수에 따라 선형이 아닌 거의 대수적으로 변합니다.

pgVector의 또 다른 인덱스인 IVFFlat는 다르게 작동합니다. 즉, 벡터 공간을 기존 샘플의 트레이닝 패스에 의해 결정된 목록으로 나눈 후 인덱스를 생성할 수 있습니다. HNSW에는 이러한 제약 조건이 없습니다. 삽입할 때마다 그래프가 직접 강화되므로 지속적으로 증가하는 테이블에서 작업하기가 더 간단해집니다. 반면에 HNSW 인덱스는 동일한 볼륨의 동등한 IVFFlat보다 더 많은 메모리를 소비하고 빌드하는 데 더 많은 시간이 걸립니다.

pgVector는 버전 0.5.0에서 HNSW 지원을 도입합니다. 이후 버전에서는 이 가이드에 유용한 기능을 추가합니다. 2000차원을 초과하는 색인을 생성하는 halfvec 유형(0.7.0)과 필터링된 쿼리에 대한 재현율을 향상시키는 hnsw.iterative_scan 매개 변수(0.8.0)입니다. 결정하기 전에 pgVector를 전용 벡터 베이스와 비교하는 경우 pgVector와 Pinecone, Weaviate 및 Qdrant 비교에서 장단점을 자세히 설명합니다.

먼저 설치된 pgVector의 버전을 확인하세요. 너무 오래된 확장으로 인해 이 가이드의 일부 기능, 특히 halfvec 및 hnsw.iterative_scan기능이 자동으로 실패합니다.

SELECT extversion FROM pg_extension WHERE extname = 'vector';

HNSW는 pgVector 0.5.0부터 존재했습니다. 2000차원을 초과하는 임베딩을 색인화하는 데 필요한 halfvec유형에는 버전 0.7.0 이상이 필요합니다. hnsw.iterative_scan 매개변수는 버전 0.8.0을 요청합니다.

Aurabase 프로젝트에서는 문제가 발생하지 않습니다. Postgres 이미지는 공유 Postgres 클러스터(docker/Postgres.Dockerfile, pgvector/pgvector:0.8.6-pg16-bookworm에 직접 구축됨)와 프로젝트별 전용 Postgres 16 CNPG 인스턴스(docker/Postgres.CNPG.Dockerfile, 공식 CloudNativePG 이미지에서 pgVector 0.8.6을 상속함) 모두에 pgVector 0.8.6을 포함합니다. 2026년 8월 24일에 두 Dockerfile 모두에서 확인되었습니다.

열 유형은 임베딩을 생성하는 모델뿐만 아니라 임베딩의 크기에 따라 달라집니다. pgVector는 vector유형의 클래식 벡터를 저장하며 저장 공간은 최대 16,000차원입니다. 그러나 이 유형의 HNSW 인덱싱은 2000차원으로 제한됩니다. 그 이상에서는 CREATE INDEX가 실패합니다.

일반적인 임베딩 모델은 종종 이 임계값을 초과합니다. OpenAI의 text-embedding-3-large 또는 Google의 gemini-embedding-2는 기본적으로 최대 3072차원을 생성합니다. HNSW를 사용하여 이러한 벡터를 인덱싱하려면 열을 halfvec(저장 정밀도 절반)로 캐스팅하세요. 그러면 인덱싱 제한이 2000차원을 훨씬 넘어갑니다.

Aurabase RAG 엔진은 프로덕션에서 이러한 절충안을 보여줍니다. 지원되는 세 가지 차원 클래스(768, 1536, 3072)는 동일한 embeddings테이블의 세 가지 개별 열에 저장됩니다. 열 768 및 1536은 vector유형의 HNSW에서 직접 인덱싱됩니다. 열 3072는 ::halfvec(3072)캐스트를 통해 인덱싱되어 정확하게 2000 차원 한도를 우회합니다.

CREATE INDEX idx_embeddings_vec_768 ON embeddings
  USING hnsw (embedding_768 vector_cosine_ops)
  WHERE embedding_768 IS NOT NULL;

CREATE INDEX idx_embeddings_vec_1536 ON embeddings
  USING hnsw (embedding_1536 vector_cosine_ops)
  WHERE embedding_1536 IS NOT NULL;

CREATE INDEX idx_embeddings_vec_3072 ON embeddings
  USING hnsw ((embedding_3072::halfvec(3072)) halfvec_cosine_ops)
  WHERE embedding_3072 IS NOT NULL;

For details of ingestion (chunking, call to the embedding provider, insertion), see the RAG pipeline tutorial on pgvector.

첫 번째 인덱스에는 최소 구문으로 충분하며 기본값은 pgVector입니다.

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops);

그런 다음 pgVector는 m = 16 및 ef_construction = 64을 적용합니다. 이러한 값을 명시적으로 조정하려면 WITH 절을 사용하세요.

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 24, ef_construction = 100);

매개변수 m은 무엇을 변경합니까?

m는 그래프의 각 노드가 레이어별로 유지하는 최대 연결 수를 설정합니다. 값이 높을수록 그래프가 조밀해집니다. 즉, 재현율이 증가하지만 소비되는 메모리와 구성 시간도 대략 선형적으로 증가합니다. 기본값(16)은 대부분의 경우에 적합합니다. 24 또는 32까지 올라가는 것은 특히 가까운 이웃과 먼 이웃 간의 구별이 더 세밀해지는 대규모 임베딩에서 정당화됩니다.

ef_construction은 무엇을 변경합니까?

ef_construction는 삽입된 각 노드에 대해 인덱스 생성 중에 탐색된 후보 목록의 크기를 설정합니다. 값이 높을수록 최종 그래프의 품질이 향상되므로 구성 시간이 길어지지만 잠재적인 재현율이 향상됩니다. m와 달리 이 매개변수는 쿼리 시 비용이 들지 않습니다. 일회성 투자이며 인덱스가 생성될 때 한 번만 지불됩니다.

동일한 테이블에 있는 여러 차원 클래스에 대한 부분 인덱스

테이블이 여러 벡터 열(Aurabase처럼 차원 클래스당 하나)을 저장하는 경우 WHERE colonne IS NOT NULL절을 사용하여 각 열을 개별적으로 인덱싱합니다. 이 부분 인덱스는 주어진 라인에서 사용되지 않는 클래스에 대한 빈 라인의 인덱싱을 방지하여 인덱스 크기를 줄이고 리콜 비용을 들이지 않고 구성 속도를 높입니다.

연산자 클래스(vector_cosine_ops, vector_l2_ops 또는 vector_ip_ops) 선택은 임베딩 모델이 훈련된 측정항목과 일치해야 합니다. 가장 최근의 텍스트 임베딩 모델은 코사인 유사성을 위해 학습되었습니다. 따라서 vector_cosine_ops(또는 캐스트 열의 halfvec_cosine_ops)가 가장 안전한 기본 선택입니다.

ef_search는 인덱스가 구축될 때가 아니라 각 쿼리에 설정됩니다. 검색 중에 탐색되는 후보 목록의 크기를 설정합니다. 숫자가 높을수록 대기 시간은 길어지지만 재현율은 높아집니다. pgVector는 기본값을 40으로 설정합니다.

SET LOCAL hnsw.ef_search = 100;

SELECT id, content
FROM embeddings
ORDER BY embedding <=> '[...]'::vector
LIMIT 10;

쿼리가 인덱스(네임스페이스, 테넌트 또는 기타 메타데이터 기준)를 스캔한 후 적용된 WHERE 필터와 벡터 검색을 결합하자마자 40만으로는 충분하지 않습니다. HNSW 스캔은 ef_search 원시 후보를 가져온 다음 필터가 이들 중 일부를 삭제합니다. 살아남은 후보자가 너무 적다면 최종 LIMIT는 언더필 상태가 됩니다.

따라서 Aurabase RAG 엔진은 고정 값 40: ef = max(top_k × 4, 64)을 유지하는 대신 요청된 top_k에 따라 ef_search을 동적으로 확장합니다. 가장 가까운 5개의 결과를 검색하려면 ef_search = 64를 사용합니다. 상위 50위 검색에는 ef_search = 200가 사용됩니다. 이 공식은 또 다른 회수/대기 시간 균형이 필요한 배포에 대해 환경 변수별로 조정 가능한 상태로 유지됩니다.

pgVector 0.8은 동일한 문제에 대한 두 번째 레버인 hnsw.iterative_scan를 추가합니다. strict_order 또는 relaxed_order모드에서는 고정된 후보 목록에서 중지하는 대신 필터링 후 충분한 결과를 수집할 때까지 검색이 점차적으로 검색 범위를 확장합니다. Aurabase는 strict_order에서 기본적으로 이를 활성화하지만 저장점에서 호출을 보호합니다. 이 매개변수가 존재하지 않는 0.8 이전 버전의 pgVector에서는 쿼리가 실패하지 않고 성능 저하 모드에서 계속됩니다.

이 HNSW 인덱스는 전체 RAG 파이프라인(청킹, 임베딩 생성, 수집, 검색)의 한 부분일 뿐입니다. 단계별 튜토리얼는 첫 번째 삽입부터 유사성 쿼리까지 pgVector에서 엔드투엔드 파이프라인을 구축합니다. 기술 문서에는 Postgres에 구축된 Aurabase의 기본 AI 기능이 모두 자세히 설명되어 있습니다.