pgvector怎麼用 PostgreSQL向量擴充套件教程

pgvector是PostgreSQL的向量檢索擴充套件，裝好之後就能在熟悉的PostgreSQL裡存向量、做相似度搜尋，不用額外搭資料庫。它適合語義檢索、推薦和RAG等場景：先用嵌入模型把文字轉成數字向量，再讓資料庫按距離找出最相近的內容。本文用餘弦距離演示從安裝到查詢的基本流程。

第一步：安裝和啟用pgvector

先確認PostgreSQL版本和部署方式，再安裝與資料庫版本匹配的pgvector。使用託管資料庫時，先檢視服務是否已提供該擴充套件；自建環境則按系統包管理器或專案說明安裝。安裝擴充套件程式只是準備工作，後面還要在每個需要存向量的資料庫裡啟用它，不能只在伺服器上裝完就直接建立vector列。

連線目標資料庫後執行 CREATE EXTENSION IF NOT EXISTS vector;。注意副檔名是vector，不是pgvector；重複執行也不會因為已安裝而報錯。可用 SELECT extname, extversion FROM pg_extension WHERE extname = ‘vector’; 檢查是否啟用並檢視版本。如果提示找不到擴充套件，通常需要先在伺服器安裝對應元件，或確認當前託管服務支援它。

第二步：建向量表和索引

向量維度必須和生成嵌入時的模型輸出一致。下面用1536維舉例，實際使用時請替換為模型的真實維度；文件正文和向量放在同一行，便於檢索結果直接返回原文。執行建表語句後，可先插入少量測試資料，再檢查欄位型別與資料是否符合預期。

例如建立一張文件表：CREATE TABLE documents (id bigserial PRIMARY KEY, content text NOT NULL, embedding vector(1536));。其中content存文字，embedding存向量。若模型輸出不是1536維，就把括號中的數字改成實際維數。向量不是隨手編寫的文字特徵，通常由嵌入模型生成；入庫時要確保每條向量長度一致，並與列定義匹配。

選擇距離型別和索引方式

先確定業務要用哪種距離。餘弦距離常用於語義嵌入，查詢運算子是 <=>，對應索引操作類 vector_cosine_ops；L2歐氏距離用 <->，內積用 <#>。索引操作類要和查詢距離匹配，否則索引可能無法用於預期的檢索。

資料量較大時可建HNSW近似索引：CREATE INDEX documents_embedding_hnsw ON documents USING hnsw (embedding vector_cosine_ops);。它通常查詢較快，但會用更多記憶體，建索引也可能更慢。IVFFlat則適合希望控制記憶體、且已有一定資料量的場景；它需要先有資料再建索引，列表數和查詢探測數還要結合資料規模調節。

• HNSW：不要求先訓練聚類，可在空表建索引；常作為優先測試的近似檢索方案，但要留意記憶體和建索引成本。
• IVFFlat：建索引快、佔用記憶體較少，通常先寫入資料再建；增加探測列表數有助於提高召回，但可能降低速度。
• 如果資料量還不大，先直接查詢並觀察效能；pgvector預設可執行精確最近鄰搜尋，結果召回完整，未必一開始就需要近似索引。

第三步：寫入向量並查詢

將內容和對應嵌入一併寫入。比如：INSERT INTO documents (content, embedding) VALUES (‘介紹資料庫向量檢索’, ‘[0.12, -0.08, 0.31]’);。這裡的短向量只是展示格式，不能直接插入前面定義的1536維列；真實示例中的陣列必須有1536個數。應用程式通常先呼叫嵌入模型，再用引數化SQL把文字和向量寫入資料庫。

查詢時，用同一嵌入模型把使用者問題轉為向量，再按餘弦距離排序：SELECT id, content, embedding <=> ‘[…]’ AS distance FROM documents ORDER BY embedding <=> ‘[…]’ LIMIT 5;。把兩處省略號替換為實際查詢向量。距離越小，向量越接近。為了讓近似索引有機會生效，排序應直接使用距離運算子並配合LIMIT；不要把距離改寫成相似度表示式再排序。

落地時建議先用小批資料驗證維度、距離選擇和返回內容，再用真實規模測試查詢耗時與召回質量。若檢索還需要關鍵詞、分類或權限條件，可在SQL中結合常規欄位過濾；上線前檢查執行計劃，確認索引是否被採用。面向國內使用者構建AI應用時，也可瞭解碼上飛這一替代方案；官網地址：codeflying.cgref.cn。本文由潤滅整理。