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

pgvector是PostgreSQL的向量檢索擴充套件，裝好之後就能在熟悉的PostgreSQL裡存向量、做相似度搜尋，不用額外搭資料庫。向量通常由文字、圖片等內容經過嵌入模型生成；pgvector負責儲存它們，並按距離找出最接近的結果。下面從安裝、建表到查詢走一遍，示例使用餘弦距離，維度請按你所用模型的輸出調整。

第一步：安裝和啟用pgvector

先確認資料庫版本和安裝方式。自建資料庫可按作業系統及PostgreSQL版本安裝對應的pgvector軟體包，也可以從專案原始碼編譯；託管資料庫則先檢視擴充套件是否已提供。安裝軟體包只是讓伺服器具備擴充套件檔案，真正使用前還要在目標資料庫中啟用它。不同發行版的包名和安裝命令可能不同，照著當前環境的說明操作更穩妥。

連線到要使用的資料庫，執行：CREATE EXTENSION IF NOT EXISTS vector;。這裡副檔名稱是vector，不是pgvector。通常需要資料庫管理員或具備相應權限的帳號來建立擴充套件。執行後可用：SELECT extname FROM pg_extension WHERE extname = ‘vector’; 檢查是否啟用成功。若提示找不到控制檔案或擴充套件檔案，說明伺服器端尚未正確安裝，單純在SQL裡執行命令解決不了。

第二步：建向量表和索引

先準備內容欄位和向量欄位。假設嵌入模型輸出1536維，可以這樣建表：CREATE TABLE documents (id bigserial PRIMARY KEY, content text NOT NULL, embedding vector(1536));。vector(1536)會約束每條向量的維度；如果模型輸出不是1536維，就把數字改成實際值。儲存文字和向量在同一行，後續可以直接把檢索結果與原文一起取出。

接下來建索引。初學或資料量不大時，先不建索引也能查詢，資料庫會逐行計算距離，結果是精確近鄰，但資料變多後可能變慢。需要加速時，可先試HNSW：CREATE INDEX documents_embedding_hnsw ON documents USING hnsw (embedding vector_cosine_ops);。索引使用的運算子類別必須和查詢距離匹配；餘弦距離用vector_cosine_ops。

選擇距離型別和索引方式

常見運算子包括<->（歐氏距離）、<=>（餘弦距離）和<#>（負內積）。距離越小通常表示越相近；內積運算子返回負值，升序排列可取較大的內積結果。文字嵌入常用餘弦距離，但應以模型的建議和業務評估為準。HNSW通常便於直接上手，查詢速度與召回效果的權衡較好，但構建較慢、佔用記憶體較多。

另一種是IVFFlat：CREATE INDEX documents_embedding_ivf ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);。它通常建得較快、記憶體佔用較少，但應先寫入一批資料再建索引，並根據資料量調lists與查詢時的probes。兩種索引不必一開始都建；先用真實資料測試延遲和召回，再決定選擇與引數。建立索引後也可用EXPLAIN檢查查詢計劃。

第三步：寫入向量並查詢

寫入時，向量必須來自模型生成，元素數量要和列維度一致。示例：INSERT INTO documents (content, embedding) VALUES (‘介紹向量搜尋’, ‘[0.12, -0.08, 0.31]’::vector);。這組示例只有三個數，因此只適用於vector(3)列；若表定義為1536維，就要傳入1536個數。實際專案中建議使用資料庫驅動的引數化查詢，不要拼接使用者輸入的SQL。

查詢時，把待檢索內容先送入同一個嵌入模型，得到與表中維度一致的查詢向量，再執行：SELECT id, content, embedding <=> ‘[0.10, -0.05, 0.28]’::vector AS distance FROM documents ORDER BY embedding <=> ‘[0.10, -0.05, 0.28]’::vector LIMIT 5;。這裡向量僅為三維演示，真實查詢要換成模型輸出。ORDER BY使用距離運算子、再配合LIMIT，是向量索引發揮作用的常見寫法。

如果結果不夠相關，可檢查模型、維度、距離型別是否一致，並調整索引搜尋引數；用HNSW時可嘗試提高hnsw.ef_search，通常能改善召回但可能增加耗時。也別忘了過濾條件：先按業務欄位限制候選資料，再檢查執行計劃和實際效果。開發階段可以不建近似索引，和索引查詢結果對照，評估速度與召回之間的取捨。

如果想先用現成工具搭建應用，再接入自己的資料流程，也可以瞭解碼上飛：codeflying.cgref.cn。實踐時建議先用少量資料完成端到端驗證，再逐步增加資料並觀察查詢表現；潤滅也可作為查閱開發實踐內容的入口