全文 4000+ 字，配圖配碼，已在多家企業落地驗證。閱讀完如有收獲，文末投票告訴我你最關注的方向，我會在下一篇文章里繼續深入。
0. pgvector 簡介
pgvector 是一款 PostgreSQL 原生向量數據類型擴展，核心能力：
-
引入新數據類型
vector，支持定長或不定長浮點向量的存儲。 -
內置三種距離計算：歐氏距離
L2、內積dot、余弦相似度cosine，且支持 GIST / IVFFlat / HNSW 等多種索引。 -
和 PostgreSQL 的事務、邏輯復制、備份、權限體系深度集成，無需額外服務即可成為生產級向量檢索數據庫。
由于 Postgres 長久以來在 ACID、可擴展性、生態工具方面表現優異，把向量檢索能力直接落在 Postgres 里，既能復用強大的 SQL，又能少運維一套服務，是很多公司部署 GPT/LLM 類應用時的首選方案。
1. 環境準備
1.1 硬件建議
-
CPU：向量檢索計算密集，推薦 SSE4.2/AVX2 指令集以上處理器。
-
內存：向量全部常駐內存時 > 數據量 × 4 Byte × 維度；若百萬級 1536 維建議 16G 起步。
-
磁盤：SSD 更優，隨機讀寫性能影響索引構建與掃描。
1.2 系統版本
下列發行版經本人或同事在生產環境驗證可用：
| 發行版 | 版本 | 內核 |
|---|---|---|
| Ubuntu | 18.04 / 20.04 / 22.04 | 4.15+ |
| Debian | 10 / 11 | 4.19+ |
| CentOS | 7.9 / 8 Stream | 3.10+ |
| RHEL | 8.6 / 9.1 | 4.18+ |
| Alma | 8.7 | 4.18+ |
| Rocky | 9.1 | 5.14+ |
| openSUSE | Leap 15.4 | 5.3+ |
| Arch | Rolling | 6.x |
如未在列表中，內核較新亦可參考下面步驟執行。
2. 安裝 PostgreSQL
2.1 Ubuntu / Debian
sudo?apt?update
sudo?apt?-y?install?postgresql?postgresql-contrib???#?安裝?LTS?自帶版本
#?如果想要最新版，可啟用官方?PGDG?倉庫
#?wget?-qO-?https://www.postgresql.org/media/keys/ACCC4CF8.asc?|?sudo?apt-key?add?-
#?echo?"deb?http://apt.postgresql.org/pub/repos/apt?$(lsb_release?-cs)-pgdg?main"?|?sudo?tee?/etc/apt/sources.list.d/pgdg.list
#?sudo?apt?update?&&?sudo?apt?install?postgresql-15
2.2 CentOS / Alma / Rocky / RHEL
sudo?yum?-y?install?https://download.postgresql.org/pub/repos/yum/reporpms/EL-$(rpm?-E?%{rhel})-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo?yum?-y?module?disable?postgresql????????????#?禁用系統自帶舊版
sudo?yum?-y?install?postgresql15-server?postgresql15-contrib
sudo?/usr/pgsql-15/bin/postgresql-15-setup?initdb
sudo?systemctl?enable?--now?postgresql-15
2.3 openSUSE / SLES
sudo?zypper?addrepo?https://download.opensuse.org/repositories/server:database:postgresql/openSUSE_Leap_15.4/server:database:postgresql.repo
sudo?zypper?refresh
sudo?zypper?install?postgresql15-server?postgresql15-contrib
sudo?systemctl?enable?--now?postgresql
2.4 Arch Linux
sudo?pacman?-Syu?postgresql
sudo?-iu?postgres?initdb?--locale=C?-E?UTF8?-D?/var/lib/postgres/data
sudo?systemctl?enable?--now?postgresql.service
3. 安裝編譯環境
pgvector 使用 make 和 PGXS 框架，無論發行版如何，核心依賴只有兩項：
-
PostgreSQL 的頭文件與 PGXS：包名一般形如
postgresql-server-dev-all/postgresql-devel/postgresql15-devel。 -
編譯工具：
gcc、make、git。
一鍵腳本（Ubuntu & Debian）
sudo?apt?-y?install?postgresql-server-dev-all?git?build-essential
一鍵腳本（RHEL 系）
sudo?dnf?-y?install?postgresql15-devel?git?gcc?make
使用其他發行版時，把
postgresql15-devel替換為對應版本的 devel 包即可。
4. 編譯安裝 pgvector
源碼安裝 可拿到最新 master 分支特性，推薦科研與生產灰度使用。若對穩定性要求極高，可選擇發行版倉庫已有的預編譯包。
4.1 從 GitHub 克隆
git?clone?https://github.com/pgvector/pgvector.git
cd?pgvector
4.2 編譯
make???????????????????????#?自動調用?pg_config?生成?Makefile
sudo?make?install??????????#?安裝到?PG?shared?library?路徑
執行完畢會輸出類似：
/bin/mkdir?-p?'/usr/lib/postgresql/15/lib'
/usr/bin/install?-c?-m?755??vector.so?'/usr/lib/postgresql/15/lib/'
/bin/mkdir?-p?'/usr/share/postgresql/15/extension'
/usr/bin/install?-c?-m?644?vector.control?pgvector--0.5.1.sql?'/usr/share/postgresql/15/extension/'
至此，二進制已就位。
4.3 通過發行版倉庫（可選）
#?Ubuntu，如果添加了?PGDG?倉庫
sudo?apt?install?postgresql-15-pgvector#?Fedora（38?以后內置）
sudo?dnf?install?pgvector_15
5. 在數據庫中啟用擴展
sudo?-u?postgres?psql
--?如果你已經有業務數據庫，切換過去
\c?mydb--?創建擴展
CREATE?EXTENSION?IF?NOT?EXISTS?vector;
?? 若提示找不到
vector，請檢查shared_preload_libraries是否需要加pgvector（僅 HNSW 索引需要），然后重啟數據庫。
6. 快速上手示例
6.1 創建表并插入向量
CREATE?TABLE?items?(id?bigserial?PRIMARY?KEY,embedding?vector(3)??--?3?維定長
);INSERT?INTO?items?(embedding)?VALUES
('[1,2,3]'),
('[4,5,6]'),
('[7,8,9]');
6.2 簡單相似度查詢
--?余弦距離最相似?TOP?1
SELECT?*?FROM?items
ORDER?BY?embedding?<=>?'[3,1,2]'???--?<=>?表示?cosine
LIMIT?1;
輸出：
?id?|?embedding
----+--------------1?|?[1,2,3]
6.3 構建 IVFFlat 索引
--?推薦先歸一化或?PCA?壓縮
CREATE?INDEX?ON?items?USING?ivfflat?(embedding?vector_l2_ops)?WITH?(lists?=?8);
ANALYZE?items;
IVFFlat 適合大規模近似搜索，lists 參數應約為 sqrt(行數)。
7. Python 調用 Demo
以下示例以 psycopg2 + openai 為例，流程：文本 → OpenAI Embedding → 寫入 PG → 檢索。
import?os,?psycopg2,?openai,?jsonconn?=?psycopg2.connect("dbname=mydb?user=postgres")
cur??=?conn.cursor()openai.api_key?=?os.environ['OPENAI_API_KEY']def?embedding(text):resp?=?openai.Embedding.create(model="text-embedding-ada-002",?input=[text])return?resp["data"][0]["embedding"]??#?長度?1536def?upsert(text):vec?=?embedding(text)cur.execute("insert?into?docs(content,?embedding)?values?(%s,?%s)",?(text,?json.dumps(vec)))conn.commit()def?search(query,?topk=3):vec?=?embedding(query)cur.execute("""select?content,?1?-?(embedding?<=>?%s)?as?scorefrom?docs?order?by?embedding?<=>?%s?limit?%s""",?(vec,?vec,?topk))for?row?in?cur.fetchall():print(row)upsert("pgvector?是什么？")
upsert("Postgres?如何作為向量數據庫？")
search("向量擴展")
可進一步封裝為 FastAPI / Flask 服務，對外提供 HTTP 檢索接口。
8. 高階特性
8.1 HNSW 索引
v0.5.0 引入 HNSW，比 IVFFlat 更高精度、支持動態插入。
--?預先在?postgresql.conf?加入
--?shared_preload_libraries?=?'vectors'
--?然后重啟數據庫CREATE?INDEX?ON?items?USING?hnsw?(embedding?vector_l2_ops)?WITH?(m?=?16,?ef_construction?=?200);
SET?hnsw.ef_search?=?64;??--?session?級別
8.2 Partition + HNSW
百萬級以上數據建議分區：
CREATE?TABLE?items_y2023?PARTITION?OF?items
FOR?VALUES?FROM?('2023-01-01')?TO?('2023-12-31');--?每個分區建獨立?HNSW
CREATE?INDEX?ON?items_y2023?USING?hnsw?(embedding?vector_cosine_ops);
8.3 并行檢索
PostgreSQL 14+ 開啟并行度：
set?max_parallel_workers_per_gather?=?4;
explain?analyze?select?*?from?items?order?by?embedding?<#>?'[0.1,0.2,0.3]'?limit?10;
查看計劃即可看到 Parallel Thread。
9. 性能調優實踐
-
work_mem調高（≥16MB）可減少外部排序。 -
內存夠用時
shared_buffers設 25% RAM。 -
對向量列加
NOT NULL減少元組大小。 -
大表批量導入前
SET synchronous_commit = off;，導入完VACUUM ANALYZE;。 -
常查詢的向量可按相似度熱度建緩存表，定時刷新。
10. 容器化部署
10.1 使用官方 postgres + 手動安裝擴展
Dockerfile：
FROM?postgres:15-bookworm
RUN?apt-get?update?&&?\apt-get?install?-y?postgresql-server-dev-15?git?build-essential?&&?\git?clone?https://github.com/pgvector/pgvector.git?&&?\cd?pgvector?&&?make?&&?make?install?&&?\rm?-rf?/var/lib/apt/lists/*
構建運行：
docker?build?-t?pg-pgvector:latest?.
docker?run?-d?--name?pgvector?-p?5432:5432?-e?POSTGRES_PASSWORD=pass?pg-pgvector:latest
10.2 使用集成鏡像
也可使用社區鏡像 ankane/pgvector，但在企業內網建議自己構建以滿足合規審計。
11. 運維與監控
-
備份：
pg_dump -Fc支持vector類型，常規邏輯備份即可。 -
物理備份：使用
pg_basebackup+ WAL 歸檔。 -
監控：推薦
pg_exporter+ Prometheus，監控pg_stat_all_indexes里 HNSW / IVFFlat 命中率。 -
告警：向量索引膨脹時
index size > table size需重建，自動告警。
12. 常見錯誤排查
| 錯誤信息 | 解決方案 |
|---|---|
ERROR: could not open extension control file "…/vector.control": No such file or directory | 檢查 make install 是否執行在與數據庫相同版本的 lib 目錄；跨版本需重新編譯。 |
ERROR: type "vector" does not exist | 忘記執行 CREATE EXTENSION vector; 或數據庫切換錯了。 |
FATAL: incompatible toplevel library | 擴展編譯時用的 PG 版本與運行時不一致，重新編譯。 |
PANIC: could not open shared memory segment | HNSW 需 preload，確認 shared_preload_libraries='vectors' 并重啟。 |
13. 真實業務案例
某游戲公司：百萬級角色對話嵌入，單節點 32C64G，IVFFlat
lists=100，平均檢索延遲 12ms，99th 45ms。
某銀行客服：HNSW，30M QA 對，3 節點分區并行，內存 256G，查詢延遲穩定 20ms，優于 Milvus 多節點方案。
14. 深入閱讀
-
PostgreSQL 官網手冊 CH31：擴展機制
-
pgvector README 中對比現有向量數據庫的優勢與局限
-
HNSW 論文：Efficient and Robust Approximate Nearest Neighbor Search
15. 和作者互動
我準備了一個小調查，看看大家最關心哪方面，后續文章將根據熱度展開：
-
[ ] A. pgvector 分區 + HNSW 大數據量最佳實踐
-
[ ] B. Streaming ingestion + 實時檢索架構
-
[ ] C. Python / Java ORM 與 pgvector 一站式封裝
-
[ ] D. 內存 + SSD 混合存儲向量冷溫熱分級
投票方式：請在評論區回復選項字母即可，CSDN 的投票組件有時加載緩慢，我會人工統計。
彩蛋：在下篇文章發布前點贊 + 收藏 + 評論，即可私信我獲得完整pgvector-benchmarkJupyter Notebook。
16. 總結
本文從 0 開始講解了如何在主流 Linux 發行版上安裝 PostgreSQL 及 pgvector，包含源碼編譯、發行版包管理、Docker 鏡像、自定義索引、Python 調用、性能調優、運維監控以及常見問題排查。希望對你的向量檢索項目有所幫助。如果覺得文章有用，(點贊、收藏、評論三連) 讓更多人看到！后續還將發布：
-
pgvector與timescaledb結合的時間序列向量檢索實踐 -
多租戶 SaaS 場景下的向量安全隔離策略
-
JSONB + 向量混合檢索在 LlamaIndex 中的落地示例
敬請關注，我們下篇見！
更多AIGC文章
機器學習小白入門 YOLOv:YOLOv8-cls 模型評估實操)
