supervc-stack/VectorChord · 上手攻略

• 仓库：supervc-stack/VectorChord
• 链接：https://github.com/supervc-stack/VectorChord
• 分类：database / ai / vector-search
• 作者：spark
• 更新：2026-07-28

是什么

VectorChord（扩展名 vchord）是 PostgreSQL 上一款面向向量检索的扩展，由原 pgvecto.rs 团队（TensorChord）迭代而来。它把向量索引、Rerank 和量化压缩统一塞进 PG 里，目标是把"亿级向量表"和"普通业务表"放在同一套关系型基础设施上跑，不再引入额外的专用向量库。

它有几条主线卖点：

• 兼容 pgvector 的 vector 类型与 <->、<=>、<#> 等距离算子，老应用几乎无痛迁移。
• 内置 RaBitQ 量化压缩，1 美元成本可存放约 40 万条 768 维向量，官方说法是同价位容量比 Pinecone 多 6 倍、比 pgvector/pgvecto.rs 多 26 倍。
• 内置 vchordrq（RaBitQ 量化）、vchordg（图索引）等索引类型，配合层次 K-Means + 磁盘优化的构建流程，单机 1 亿向量索引约 20 分钟。
• 对稀疏/全文向量混用场景，还有同系列的 VectorChord-bm25 配套扩展，可与 pg_tokenizer.rs 一起放进官方 all-in-one 镜像。
• 提供 vector_l2_ops、vector_ip_ops、vector_cosine_ops、vector_maxsim_ops（多向量检索 / ColBERT 风格）这几套 ops，覆盖 ANN 与 MaxSim。

许可上有点特殊：AGPLv3 / Elastic License v2 双协议。闭源商用前要先看 ELv2 的限制条款，或联系官方邮箱谈商业授权。

解决什么问题

当业务体量走到"百万级向量 + 业务元数据混合查询"的阶段，传统选择要么是 Postgres + pgvector（简单但 1 亿级以上吃力），要么是引入 Pinecone / Milvus / Qdrant / Weaviate 这种专用向量库（运维负担陡增、数据双写、JOIN 要绕一圈）。VectorChord 想覆盖中间地带：保留 pgvector 的 SQL 友好性，把"存储 + ANN + rerank + 量化"全部收敛到一个 PG 进程里，重点解决：

1. 中大规模（千万 ~ 十亿级）向量表的索引构建太慢、内存吃紧。
2. 业务字段和向量需要在同一事务里做"过滤 + 排序 + JOIN"，专用向量库做这件事很别扭。
3. 量化压缩带来的召回损失不可控，希望有可解释、可测量的回收机制。
4. 想用 MaxSim / ColBERT 这类多向量检索，又不想再叠一套 Faiss。

快速安装

最省事的路径是用 Docker，跑官方提供的 vchord-postgres 镜像（基于 pgvector 那一套打包）：

docker run \
  --name vectorchord-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d ghcr.io/tensorchord/vchord-postgres:pg18-v1.1.1

psql -h localhost -p 5432 -U postgres

版本号（pg18-v1.1.1）以 https://github.com/tensorchord/VectorChord-images 的 Support Matrix 为准；不同 PG 大版本要选对应 tag，例如需要 bm25 时换 tensorchord/vchord-suite:pg17-latest。

如果已经有现成的 PG（建议 PG 14+），可以用预编译包安装。具体步骤在官方文档 getting-started/installation.html，大致流程是：

# Debian/Ubuntu 示例（以官方文档为准）
sudo apt-get install postgresql-16-vchord
# 或在 PG 安装后加载预编译的 .so
CREATE EXTENSION vchord CASCADE;

对包名（postgresql-XX-vchord）的具体可用性，部署前最好到 docs.vectorchord.ai 的安装页核对一遍，因为发行版不一定都打包最新版。

核心用法

1. 建表 + 写入向量

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

CREATE TABLE items (
  id        bigserial PRIMARY KEY,
  embedding vector(3)
);

INSERT INTO items (embedding)
SELECT ARRAY[random(), random(), random()]::real[]
FROM generate_series(1, 1000);

vector(N) 这条类型声明和 pgvector 保持一致，老迁移项目不需要改 schema。

2. 创建 ANN 索引

-- RaBitQ 量化版（默认推荐）
CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);

-- 图索引版本（适合更大规模 / 更高召回）
CREATE INDEX ON items USING vchordg  (embedding vector_cosine_ops);

vchordrq 走 RaBitQ 量化、构建快；vchordg 走图索引，更接近 HNSW 的体验。两者切换不需重建表。

3. ANN 查询

-- 5 条最近邻，L2 距离
SELECT id, embedding <-> '[3,1,2]' AS dist
FROM items
ORDER BY embedding <-> '[3,1,2]'
LIMIT 5;

Cosine / 内积换 vector_cosine_ops / vector_ip_ops 即可。

4. 多向量检索（MaxSim / ColBERT 风格）

CREATE INDEX ON items USING vchordrq (embedding vector_maxsim_ops);

SELECT id FROM items
ORDER BY embedding <#> '[0.1,0.2,0.3,0.4]'::maxsim
LIMIT 10;

这一套对 RAG 中 ColBERT 风格的 late interaction 很有用，不需要再叠 Faiss。

5. 配合业务字段过滤

SELECT id, name
FROM items
WHERE category = 'books'
ORDER BY embedding <=> $1::vector
LIMIT 10;

ANN 索引在前面 WHERE 过滤之后再做精确排序，是 pgvector 一脉的常见用法；VectorChord 在 docs 里还专门有 prefilter / prefetch / prewarm 几篇调优文档，处理"过滤性很强 / 几乎全表扫"的场景。

6. 量化与召回测量

VectorChord 提供原生的 vector(4) / vector(8) 等低比特向量类型，对应 RaBitQ4 / RaBitQ8。官方给出的数字是 RaBitQ8 的召回损失 < 1%。要量化之前最好用 measure-recall 流程拿真实数据验一下。

-- 例：把向量降到 4-bit 存储
ALTER TABLE items ALTER COLUMN embedding TYPE vector(4);

具体语法随版本可能有差异，请以 docs.vectorchord.ai/vectorchord/usage/quantization-types.html 为准。

典型适用场景

• RAG + 业务元数据强过滤：在 PG 一侧就能完成"商品类目/标签/价格区间 + 向量相似度"联合排序，避免双写两套库。
• 亿级向量 + 单实例：不想引入专用向量库，又希望避开 pgvector 的内存压力。
• ColBERT / 多向量检索：原本要 Faiss 兜底，现在 vector_maxsim_ops 一步到位。
• 混合检索：和 VectorChord-bm25 + pg_tokenizer.rs 拼成"BM25 + 向量"统一接口。
• 成本敏感的中小团队：自建 PG、保留关系型数据库的全部能力（事务、备份、监控、副本），量化 + 磁盘友好索引把单位成本压到 Pinecone 那种 SaaS 的几分之一。

不太适合的：

• 千亿级向量、单实例压不住的体量，应该直接上专用向量库 / 分布式方案。
• 需要 GPU 加速的 ANN；VectorChord 是 CPU 路线。

坑与注意

1. 许可证是双协议 AGPLv3 + Elastic v2，闭源商用要单独评估；公司内部工具、对外交付 SaaS 都受影响。
2. 版本对应关系：镜像 tag、vchord 与 vchord-bm25 必须对得上 PG 大版本号，否则 CREATE EXTENSION 会直接失败。部署前先翻 Support Matrix。
3. 不要裸用默认参数：第一次上生产前，至少要走一遍 performance-tuning、partitioning-tuning、measure-recall 三篇文档，尤其是大规模数据集的 sampling 与 prewarm。
4. 索引构建吃 IO：vchordrq 用 RaBitQ + K-Means 会读全表；亿级数据时建议在低峰期建索引，或直接走 External Index Precomputation。
5. 距离算子和索引必须配对：用 vector_l2_ops 索引就别拿 <=>（cosine）去查，否则会扫全表。
6. 图索引 vchordg 的内存占用：和 HNSW 类似，预算要先按 N × M（N 是向量数，M 决定图稀疏度）粗算一下。
7. 从 pgvector 迁过来：schema 不用动，但要重新建索引（USING vchordrq），且不要同时保留两套索引在同一列上。
8. 配套生态还在长：vchord-bm25、pg_tokenizer.rs 等周边扩展的版本节奏和主扩展不完全同步，全套引入时建议锁版本。

与同类对比

如果团队已经在 PG 生态里、向量规模在千万到十亿、又不希望引入额外集群，VectorChord 是当前性价比最高的选项之一；如果体量在百万级以下，pgvector 其实就够用，不必为量化收益换掉它；如果要 GPU 或百亿级，再去评估 Milvus / Qdrant。

一句话推荐结论

PG 生态里做"中等以上规模 + 关系过滤"向量检索的首选扩展，比 pgvector 更扛数据量，比专用向量库更省运维——前提是你能接受 AGPLv3 / ELv2 的双协议。