~/tools / 임베딩과 검색(RAG) / pgvector SQL Builder

pgvector SQL Builder — pgvector SQL 작성: 테이블, HNSW/IVFFlat 인덱스, 최근접 이웃 쿼리

PostgreSQL에서 pgvector로 임베딩을 저장하고 검색하는 SQL을 작성합니다. vector(n) 또는 halfvec(n) 열이 있는 테이블, 거리에 맞는 연산자 클래스를 쓰는 HNSW 또는 IVFFlat 인덱스, 읽기 쉬운 점수를 돌려주는 최근접 이웃 쿼리를 얻을 수 있습니다. pgvector 문서에 나온 한계를 확인하고, 벡터가 차지하는 공간도 추정합니다. 데이터는 브라우저 밖으로 나가지 않습니다.

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (
  id bigserial PRIMARY KEY,
  content text NOT NULL,
  embedding vector(384) NOT NULL
);

CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);

PREPARE search_documents(vector(384)) AS
  SELECT id, content, 1 - (embedding <=> $1) AS cosine_similarity
  FROM documents
  ORDER BY embedding <=> $1
  LIMIT 5;

-- EXECUTE search_documents('[0.0123, -0.0456, ...]');

pgvector는 PostgreSQL에 벡터 유사도 검색을 더해 주는 오픈 소스 확장으로, Ollama로 만든 임베딩을 나머지 데이터와 같은 데이터베이스에 저장할 수 있습니다. 헷갈리기 쉬운 부분이 몇 가지 있습니다. 열의 차원 수는 임베딩 모델의 차원 수와 같아야 합니다. 거리마다 자기 연산자가 있어서, 코사인 거리는 <=>, L2 거리는 <->, 내적에 음수를 취한 값은 <#>, L1 거리는 <+>입니다. 근사 인덱스는 같은 거리의 연산자 클래스(<=>에는 vector_cosine_ops 등)로 만들었고, 쿼리가 연산자 자체를 오름차순으로 정렬하며 LIMIT이 있을 때만 사용됩니다. 이 도구는 한 번의 선택으로 세 부분을 작성합니다. CREATE EXTENSION과 CREATE TABLE, CREATE INDEX, 그리고 읽기 쉬운 점수와 함께 가장 가까운 행을 돌려주는 PREPARE 문입니다(코사인 유사도는 1에서 코사인 거리를 뺀 값이고, 내적은 <#>에 -1을 곱한 값입니다). pgvector 0.8.7의 README와 소스 코드에 있는 한계를 적용합니다. 한 열은 최대 16,000차원, 인덱스는 vector가 2,000차원, halfvec가 4,000차원까지이고, IVFFlat에는 L1 연산자 클래스가 없으며, HNSW의 m은 2에서 100까지, ef_construction은 4에서 1,000까지이면서 2 × m 이상이어야 합니다. HNSW에서는 검색이 돌려주는 행이 최대 hnsw.ef_search개(기본값 40)이므로, LIMIT이 그보다 크면 경고합니다. IVFFlat에서는 README의 시작점인 100만 행까지는 rows / 1000, 그보다 많으면 sqrt(rows), probes에는 sqrt(lists)를 써서 lists와 probes를 채웁니다. 생성된 SQL은 Ollama에서 만든 실제 384차원 벡터로 PostgreSQL 16의 pgvector 0.8.7에서 실행했고, EXPLAIN으로 인덱스가 쓰이는 것을 확인했습니다.

이 도구의 핵심 로직은 MIT 라이선스의 오픈 소스로 공개되어 있습니다. github.com/seigo5555/toolkitbox-lib/src/pgvector-sql.ts