~/tools / 嵌入與搜尋（RAG） / pgvector SQL Builder

pgvector SQL Builder — 寫出 pgvector SQL：資料表、HNSW/IVFFlat 索引與最近鄰查詢

寫出用 pgvector 在 PostgreSQL 中儲存與搜尋 embedding 的 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 產生的 embedding 可以和其他資料存放在同一個資料庫中。有幾個細節很容易出錯。欄位的維度數必須和你的 embedding 模型相同。每種距離都有自己的運算子：<=> 是餘弦距離，<-> 是 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 的起點填入 lists 與 probes：100 萬列以內用 rows / 1000，超過則用 sqrt(rows)，probes 則用 sqrt(lists)。產生的 SQL 已用 Ollama 的真實 384 維向量，在 PostgreSQL 16 上的 pgvector 0.8.7 執行，且 EXPLAIN 顯示索引確實被使用。

這個工具的核心邏輯以 MIT 授權開放原始碼。 github.com/seigo5555/toolkitbox-lib/src/pgvector-sql.ts