pgvector 是什麼、怎麼安裝和使用：在 PostgreSQL 裏存向量、查最近鄰、建索引

本文根據 pgvector 官方倉庫 README 整理，資料核對於 2026-10-11。文中命令和 SQL 取自官方 README，沒有在本機運行驗證。

適用於誰

• 搜「pgvector 是什麼」「pgvector 安裝」「pgvector 教學」「pgvector docker」的人；
• 業務數據已經在 PostgreSQL 裏，做 RAG 或語義搜尋時不想再多維護一個向量數據庫的人；
• 用上了 pgvector，但數據一多查詢就變慢，不知道索引該怎麼建的人。

結論先說

1. pgvector 是 PostgreSQL 的一個開源擴展，給它加上向量相似度搜索，向量可以和其他業務數據存在同一個庫、同一張表裏。
2. 支持 PostgreSQL 13 及以上。
3. 用法就是 SQL：CREATE EXTENSION vector; 之後，多了一個 vector 列類型和幾個距離運算符。
4. 不建索引時是精確搜尋，結果完全準確但數據多了會慢；建了近似索引會更快，代價是召回率略降。
5. 索引首選 HNSW。官方的評價是它在速度和召回率之間的平衡更好，代價是建索引更慢、更佔內存。
6. vector 類型最多能給 2,000 維建索引。維度更高的嵌入要用半精度或二值量化。

一、它提供了什麼

• 精確和近似的最近鄰搜尋；
• 四種向量類型：單精度 vector、半精度 halfvec、二值 bit、稀疏 sparsevec；
• 六種距離：L2、內積、餘弦、L1、漢明、傑卡德。

因為它就在 PostgreSQL 裏，事務、備份、權限、關聯查詢這些能力照常可用。比如「只在當前用戶有權限看的文檔裏做語義搜尋」，就是一條帶 WHERE 的普通 SQL。

二、安裝

Linux 和 Mac（從源碼編譯）

sh
cd /tmp
git clone --branch v0.8.7 https://github.com/pgvector/pgvector.git
cd pgvector
make
make install # may need sudo

Docker

sh
docker pull pgvector/pgvector:pg18-trixie

鏡像裏是已經裝好 pgvector 的 PostgreSQL，本地試用最省事。

Windows：官方的做法是在 Visual Studio 裏安裝 C++ 支持，以管理員身份打開「x64 Native Tools Command Prompt for VS」，設定 PGROOT 為 PostgreSQL 的安裝路徑，克隆同一個版本標籤後用 nmake /F Makefile.win 編譯並安裝。完整命令見 README。

其他方式：README 還列了 Homebrew、PGXN、APT、Yum、conda-forge 等包管理器；許多託管的 PostgreSQL 服務也已經提供這個擴展，用雲數據庫的先查一下廠商文檔，往往不需要自己安裝。

三、四條 SQL 上手

sql
CREATE EXTENSION vector;
CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));
INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

1. 在當前數據庫裏啟用擴展（每個要用它的數據庫執行一次）；
2. 建一張帶向量列的表，vector(3) 表示 3 維。實際使用時括號裏是嵌入模型的輸出維度；
3. 插入向量，寫法是方括號包住、逗號分隔的字符串；
4. 按 L2 距離找出離 [3,1,2] 最近的 5 條。

實際的表通常還有原文、來源等列，向量列只是其中一列。

四、六個距離運算符

兩點說明：

• <#> 返回的是負內積，所以同樣是 ORDER BY ... LIMIT 取最小值，得到的是內積最大的；
• 用哪種距離，看嵌入模型的文檔建議。文本嵌入最常用的是餘弦距離。建索引時選的運算符類要和查詢時用的距離一致，否則索引用不上。

五、建索引：HNSW 還是 IVFFlat

HNSW

sql
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

• 官方評價：速度與召回率的平衡更好，但建索引更慢、佔用內存更多；
• 建索引時的兩個參數：m（預設 16）和 ef_construction（預設 64），寫法是 WITH (m = 16, ef_construction = 64)；
• 查詢時的參數 hnsw.ef_search 預設 40，調大可以提高召回率，代價是變慢。

IVFFlat

sql
CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100);

• 官方評價：建索引更快、佔內存更少，但查詢性能較低；
• 要在表裏有了數據之後再建；
• lists 的取值建議：100 萬行以內用「行數 / 1000」，超過 100 萬行用「行數的平方根」；
• 查詢時的 ivfflat.probes 從「lists 的平方根」起步，調大提高召回率、降低速度。

怎麼選：

示例裏的 vector_l2_ops 對應 L2 距離。用餘弦距離查詢時，建索引要換成對應餘弦的運算符類，名稱見 README 的索引一節。

六、維度上限

嵌入模型的輸出超過 2,000 維時，README 給的辦法：

• 用半精度向量或半精度索引，可以到 4,000 維；
• 用二值量化，可以到 64,000 維；
• 或者對子向量建索引、做降維。

有的嵌入模型支持指定較低的輸出維度，在調用時直接取一個 2,000 以內的維度也是常見做法，以所用模型的文檔為準。

七、混合搜尋

README 說明 pgvector 可以和 PostgreSQL 自帶的全文搜尋配合使用，兩路結果可以用 Reciprocal Rank Fusion（倒數排名融合）或交叉編碼器合併。

用戶的問題裏有型號、編號、專有名詞這類必須精確匹配的詞時，只靠向量搜尋容易漏，加上全文搜尋會穩很多。

常見問題

Q：一張表能存多少向量？

README 的回答：非分區表預設最大 32 TB；分區表可以有成千上萬個這樣的分區。

Q：建了索引，結果變少或者和之前不一樣？

近似索引本來就是用少量召回率換速度。調大 hnsw.ef_search 或 ivfflat.probes 可以提高召回率。

Q：CREATE EXTENSION vector 報錯說找不到擴展？

說明擴展文件沒有裝到這個 PostgreSQL 實例上。自建的檢查編譯安裝是否裝到了正確的 PostgreSQL 版本；雲數據庫看廠商是否支持、是否要先在控制台開啟。

Q：和專門的向量數據庫怎麼選？

已經在用 PostgreSQL、向量規模在單機能承受的範圍內，pgvector 少一個系統、數據一致性也好處理。只是做原型看《ChromaDB 是什麼》；規模很大看《Milvus Lite 使用教學》裏對 Milvus 各形態的說明。

參考資料

• pgvector/pgvector（官方倉庫與 README）：https://github.com/pgvector/pgvector