【学习笔记】pgvector 入门：用 PostgreSQL 直接实现向量检索-13

如果项目已经使用 PostgreSQL，是否一定要再部署 Milvus？不一定。

pgvector 是 PostgreSQL 的向量相似度搜索扩展，可以把向量直接存进 PostgreSQL 表，并使用 SQL 完成近邻查询。对于中小型知识库、原型项目和希望减少基础设施数量的团队，它是一条很有吸引力的路线。

本文从安装、建表、写入、查询和索引开始，搭建一个最小的文本向量检索示例，并说明它适合什么场景、有哪些边界。

一、pgvector 解决什么问题？

PostgreSQL 原生并不是向量数据库。安装 pgvector 扩展后，可以获得：

• vector等向量数据类型；

• L2、内积、余弦等距离运算符；

• 精确近邻搜索；

• HNSW 和 IVFFlat 等近似索引；

• 向量与普通 SQL 条件、JOIN 和事务结合查询。

pgvector 官方项目将其定位为 PostgreSQL 的开源向量相似度搜索扩展，并强调可以把向量与其他业务数据一起存储。

pgvector 是 PostgreSQL 的扩展，不是一个独立的向量服务。它的查询、索引构建、WAL、备份、连接数和资源消耗都发生在 PostgreSQL 体系内。这是它简化架构的原因，也是它需要和业务 SQL 争抢资源的原因。

二、安装和启用扩展

具体安装方式取决于操作系统、PostgreSQL 版本和发行版。可以使用系统包、Docker、源码或托管服务提供的扩展。

安装完成后，在目标数据库中启用：

CREATE EXTENSION IF NOT EXISTS vector;

扩展是按数据库启用的。即使服务器上已经安装了 pgvector，如果当前数据库没有执行CREATE EXTENSION，仍然不能使用vector类型。

可以检查扩展版本：

SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';

生产环境中要记录 PostgreSQL 和 pgvector 版本，升级前先阅读兼容性说明，并准备回滚和备份方案。

三、创建一个向量表

向量字段需要指定维度。假设 Embedding 模型输出 1536 维：

CREATE TABLE document_chunks ( id BIGSERIAL PRIMARY KEY, document_id UUID NOT NULL, tenant_id UUID NOT NULL, content TEXT NOT NULL, metadata JSONB NOT NULL DEFAULT '{}'::jsonb, embedding VECTOR(1536), created_at TIMESTAMPTZ NOT NULL DEFAULT now() );

这里的VECTOR(1536)必须与 Embedding 模型实际输出维度一致。模型换成 768 维时，不能直接把 768 维向量写进vector(1536)字段。

在 AI 应用中，建议同时保存：

• 原始文本片段；

• 文档 ID；

• 租户 ID；

• 页码、标题和版本等元数据；

• Embedding 模型名称和版本。

不要只保存一个向量，否则检索到结果后无法追溯来源和执行权限过滤。

四、写入向量

向量可以使用字符串形式插入：

INSERT INTO document_chunks ( document_id, tenant_id, content, embedding ) VALUES ( '00000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000010', '员工年休假申请需要通过内部系统提交。', '[0.12, -0.03, 0.44, ...]' );

示例中的省略号只是说明格式，实际写入时必须提供完整的 1536 个数值。

批量建库时，不建议逐条发送 INSERT。可以使用驱动的批量写入或COPY，并在初始数据加载完成后再创建索引，以减少建库时间。

生产批量导入建议记录批次 ID、文档版本、Embedding 模型版本和成功/失败条数。初始大批量导入可以先写入数据、执行ANALYZE、再创建索引；日常增量写入则需要观察索引维护、WAL、锁和查询尾延迟。

五、用 SQL 执行最近邻查询

pgvector 使用不同运算符表示不同距离：

使用余弦距离查询：

SELECT id, document_id, content, 1 - (embedding <=> '[0.12, -0.03, 0.44, ...]') AS cosine_similarity FROM document_chunks WHERE tenant_id = '00000000-0000-0000-0000-000000000010' AND embedding IS NOT NULL ORDER BY embedding <=> '[0.12, -0.03, 0.44, ...]' LIMIT 5;

注意两个细节：

1. <=>返回的是余弦距离，距离越小越相似；

2. 如果要展示余弦相似度，可以使用1 - distance。

pgvector 的<#>返回负内积，这是为了配合 PostgreSQL 只能使用升序索引扫描的行为。不要直接把<#>的负值当成正向内积解释。

六、把普通 SQL 条件和向量检索结合起来

这是 pgvector 对业务应用很有吸引力的地方：可以在同一条 SQL 中完成租户、状态、版本和时间过滤。

SELECT id, content, metadata, 1 - (embedding <=> $1::vector) AS similarity FROM document_chunks WHERE tenant_id = $2 AND metadata ->> 'status' = 'published' AND metadata ->> 'language' = 'zh-CN' ORDER BY embedding <=> $1::vector LIMIT $3;

这类查询非常适合小型企业知识库。权限和业务过滤可以和向量检索放在同一个关系查询中，减少应用层拼接多个系统结果的复杂度。

但要通过EXPLAIN (ANALYZE, BUFFERS)检查实际执行计划。过滤条件和近似索引之间的组合可能影响召回数量和执行效率。

如果过滤条件很严格，近似索引可能先访问有限候选，导致最终有效结果不足。pgvector 新版本提供了迭代扫描等能力，但是否适用取决于 PostgreSQL 和 pgvector 版本，不能把某个版本的参数直接复制到所有环境。遇到空结果或召回不足时，应同时比较精确搜索基线、近似搜索计划和过滤后候选数量。

七、精确搜索与近似搜索

默认情况下，pgvector 可以执行精确近邻搜索：对候选向量计算距离，再返回最准确的结果。

7.1优点：

• 召回结果准确；

• 便于建立评测基线；

• 小数据量下实现简单。

7.2 缺点：

• 数据量增大后查询成本上升；

• 高并发下 CPU 压力增大。

当数据规模和查询压力上升，可以建立近似索引。近似搜索通常以少量召回率损失换取更低延迟。

八、HNSW 索引

使用余弦距离时，可以创建：

CREATE INDEX document_chunks_embedding_hnsw ON document_chunks USING hnsw (embedding vector_cosine_ops);

HNSW 通过多层图结构寻找近邻，通常具有较好的速度—召回率平衡。可以调整构建参数：

CREATE INDEX document_chunks_embedding_hnsw_tuned ON document_chunks USING hnsw (embedding vector_cosine_ops) WITH ( m = 16, ef_construction = 64 );

参数越激进，可能提高召回率，但会增加建索引时间、内存和写入成本。具体参数需要压测，不建议直接复制到生产环境。

如果使用 L2 或内积，需要使用对应的 operator class：

-- L2 CREATE INDEX ON document_chunks USING hnsw (embedding vector_l2_ops); -- Inner Product CREATE INDEX ON document_chunks USING hnsw (embedding vector_ip_ops);

同一个查询指标和索引 operator class 必须匹配。

九、IVFFlat 索引

IVFFlat 先把向量划分到若干列表，再只搜索部分列表：

CREATE INDEX document_chunks_embedding_ivfflat ON document_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

查询时可以调整探测列表数量：

BEGIN; SET LOCAL ivfflat.probes = 10; SELECT id, content FROM document_chunks ORDER BY embedding <=> $1::vector LIMIT 5; COMMIT;

probes越大，通常召回率越高，但查询成本也会上升。

IVFFlat 的列表数和数据量有关。数据量很小时，过早创建过大的 IVFFlat 索引可能导致效果不理想。可以先用精确搜索建立基线，再决定是否需要近似索引。

十、批量导入时的建议顺序

创建表 ↓ 批量导入文本和向量 ↓ 检查行数、维度和空值 ↓ 创建向量索引 ↓ 执行 ANALYZE ↓ 用真实问题压测

示意：

SELECT COUNT(*) FROM document_chunks; SELECT COUNT(*) FROM document_chunks WHERE embedding IS NULL; ANALYZE document_chunks;

初始数据加载完成后再建索引，通常比边写入边构建更高效。生产环境创建大索引时，还要考虑是否使用并发创建以减少对写入的影响。

十一、pgvector 的 Python 查询示例

下面使用伪代码表示应用层流程，真实项目需要根据使用的 PostgreSQL 驱动选择参数绑定方式：

query_vector = embedding_model.embed_query(user_query) sql = """ SELECT id, document_id, content, 1 - (embedding <=> %s::vector) AS similarity FROM document_chunks WHERE tenant_id = %s ORDER BY embedding <=> %s::vector LIMIT %s """ rows = connection.execute( sql, (query_vector, tenant_id, query_vector, top_k), ).fetchall()

连接层同样重要：使用连接池限制在线查询和批量导入的并发，设置 statement timeout，避免一个慢向量查询长期占用连接。大索引创建和重建应安排在可控时段，并评估是否需要CREATE INDEX CONCURRENTLY。

应用层要确保：

• 查询向量和文档向量使用同一个 Embedding 体系；

• 参数使用驱动绑定，避免 SQL 注入；

• tenant_id和权限过滤不会被遗漏；

• 空向量、维度错误和数据库超时有明确处理；

• 结果保留文档来源和版本信息。

十二、pgvector 的优点

1. 架构简单

业务数据和向量可以在同一个 PostgreSQL 集群中管理，减少服务数量。

2. 事务和 JOIN 方便

文档状态、权限和向量记录可以使用关系查询组织起来。

3. 运维体系成熟

可以复用 PostgreSQL 的备份、复制、监控和权限体系。

4. 适合快速验证

不必一开始部署独立向量数据库，就可以完成语义检索和 RAG 原型。

十三、pgvector 的边界

13.1 数据规模和并发

向量数量、查询并发和延迟要求达到一定规模后，需要评估 PostgreSQL 是否会被向量检索拖累。

13.2 资源竞争

业务 SQL、事务写入、全文检索和向量搜索共享数据库资源，可能互相影响。

13.3 向量索引调优

HNSW、IVFFlat、过滤条件和 PostgreSQL 查询计划需要一起调优。

13.4 扩展方式

如果系统需要独立扩展向量查询节点和业务数据库，拆分成 PostgreSQL + Milvus 可能更合适。

13.5 备份与恢复

pgvector 的向量和索引属于 PostgreSQL 数据库的一部分，不能只备份业务表结构而忽略扩展版本、向量数据和索引重建时间。恢复演练至少要验证：

恢复 PostgreSQL 实例 ↓ 确认 vector 扩展和版本 ↓ 检查向量行数、维度和 NULL 比例 ↓ 确认索引可用或执行重建 ↓ 用固定问题集验证 Recall@K 和延迟

十四、上线前检查清单

• 已在目标数据库启用vector扩展；

• 向量维度与 Embedding 模型一致；

• 查询指标和 operator class 匹配；

• 知道<=>是余弦距离而不是相似度；

• 精确搜索和近似搜索有对比基线；

• HNSW/IVFFlat 参数经过真实数据压测；

• 过滤条件包含租户和权限边界；

• 批量导入和建索引顺序合理；

• 使用EXPLAIN (ANALYZE, BUFFERS)分析慢查询；

• 已规划备份、升级和索引重建。

• 使用连接池、查询超时和并发限制；

• 已验证过滤条件下的精确搜索与近似搜索差异；

• 已进行包含 pgvector 扩展和索引恢复的演练；

PostgreSQL 加 pgvector，还是 PostgreSQL 加 Milvus？

这是 RAG 项目非常常见的架构选择题。很多团队一开始想要“最专业”的向量数据库，直接部署 Milvus；也有团队为了减少组件，试图把所有向量检索都放进 PostgreSQL。

更稳妥的答案不是固定选其中一个，而是先判断：

向量检索是业务数据库中的一个功能，还是已经成为需要独立扩展的核心基础设施？

还要问三个运行问题：谁负责数据事实，谁负责向量索引，谁负责故障恢复？

pgvector 把业务数据和向量放在同一个 PostgreSQL 体系中；Milvus 则把向量检索拆成独立基础设施，通常还需要单独考虑 Standalone/Distributed、元数据、对象存储和索引服务。拆分后能力更强，但组件和同步链路也更多。

十五、两种架构先看懂

15.1 方案 A：PostgreSQL + pgvector

应用服务 ↓ PostgreSQL ├── 用户、权限、文档和任务 ├── 会话、审计和业务数据 └── pgvector 向量检索

向量和业务数据在同一个数据库中，应用通过 SQL 完成过滤、关联和检索。

15.2 方案 B：PostgreSQL + Milvus

应用服务 ├── PostgreSQL：业务事实 └── Milvus：大规模向量检索

PostgreSQL 负责用户、权限、文档和任务；Milvus 负责向量存储、索引和相似度搜索。两者通过document_id、chunk_id和元数据关联。

十六、优先使用 pgvector 的场景

16.1. 项目处于原型和验证阶段

如果还在验证用户是否真的需要知识库，使用 PostgreSQL + pgvector 可以减少部署和运维成本：

FastAPI + PostgreSQL + pgvector + 一个 Embedding 模型

先把“上传、切分、向量化、检索、回答”跑通，再根据数据和并发决定是否拆分。

16.2. 向量数据规模中小

向量数量较少、查询并发有限、延迟要求可接受时，pgvector 往往足够。具体上限不能只看一个数字，需要结合：

• 向量维度；

• 索引类型；

• 过滤条件；

• 查询并发；

• PostgreSQL 机器资源；

• 业务 SQL 的负载。

16.3. 业务过滤和 JOIN 很重要

如果每次检索都需要结合复杂业务条件：

用户可访问的部门 + 文档当前版本 + 租户条件 + 发布状态 + 业务对象关联

pgvector 可以直接与 PostgreSQL 的 WHERE、JOIN、事务和权限模型结合，开发体验通常更简单。

16.4. 团队希望减少基础设施数量

少一个独立服务，就少一套部署、监控、备份、升级和故障处理流程。对于小团队，这是实际的工程收益。

十七、考虑单独部署 Milvus 的场景

17.1. 向量检索已经成为核心负载

如果系统主要工作就是高并发向量搜索，且向量数据持续增长，把检索工作从业务数据库中分离出来，有利于独立扩展查询资源。

17.2. 业务数据库和向量查询互相影响

当向量索引占用大量内存和 CPU，业务 SQL、事务写入和用户请求可能受到影响。将 Milvus 独立出来，可以降低资源竞争。

17.3. 需要面向大规模向量的专用能力

Milvus 提供多种向量索引、近似搜索、过滤、混合检索和多种部署形态。它的 Standalone 和 Distributed 模式适合不同数据规模与可用性要求。

17.4. 需要独立扩展和隔离

查询节点、数据节点和索引任务需要按照不同负载扩展时，专用向量数据库更容易进行针对性设计。

17.5. 多模态和多向量场景增加

文字、图片、音频和稀疏向量同时进入检索系统后，数据模型和索引策略更加复杂。应结合 Milvus 的具体能力、版本和部署成本评估。

十八、不要只用“向量条数”决定选型

“超过多少条就必须用 Milvus”通常是过度简化。真正影响选型的是多个变量的组合：

向量数量 × 向量维度 × 查询并发 × 延迟目标 × 过滤复杂度 × 写入更新频率 × 业务数据库负载 × 可接受运维复杂度

100 万条低并发向量，可能在 PostgreSQL 中运行良好；10 万条高并发且严格低延迟的向量，也可能需要独立检索服务。

十九、两种方案的对比

没有一列可以永久判定优劣，关键是看你的业务约束。

还要比较资源和故障域

Milvus 不是“把 pgvector 换成另一个连接字符串”。生产部署还要明确 Standalone 或 Distributed 形态、对象存储、元数据和备份恢复方式。只有当这些额外能力真正解决了当前瓶颈，拆分才有价值。

二十、从 pgvector 迁移到 Milvus 要提前设计什么？

不要把迁移理解成“把向量复制到另一个数据库”。还要迁移和验证：

• 文档和 Chunk 的唯一 ID；

• Embedding 模型与维度；

• 距离指标；

• 租户、权限和版本元数据；

• 删除和更新策略；

• 索引参数；

• Top K 与阈值；

• 评测集和结果基线。

推荐采用双索引灰度方式：

PostgreSQL + pgvector（旧链路） ↓ 同步或重建 ↓ Milvus（新链路） ↓ 同一批评测问题比较召回率、延迟和成本 ↓ 逐步切换查询流量

在切换期间保留旧链路，出现检索质量或稳定性问题时可以回滚。

迁移时建议使用稳定的chunk_id作为幂等键，并为每个目标批次保存迁移状态：

pending → embedding_ready → milvus_inserted → verified → serving

验证不能只比较向量数量，还要抽样比较 ID、租户、文档版本、删除状态、过滤结果和 Top K 排名。切换前保留旧索引和回滚开关，切换后再按保留周期清理。

二十一、两种架构都需要解决一致性

无论使用 pgvector 还是 Milvus，以下事件都需要同步处理：

• 文档新增；

• 文档内容更新；

• 文档版本发布；

• 文档撤回；

• 权限变化；

• 租户删除；

• Embedding 模型升级。

pgvector 的优势是数据可以在同一 PostgreSQL 中一起提交，但如果向量更新由异步 Worker 完成，仍然需要状态管理。

推荐把 PostgreSQL 作为业务事实源，把向量系统作为可重建的检索索引。文档发布、撤回、删除和权限变化先在 PostgreSQL 中形成明确状态，再由 Outbox/队列驱动 Worker 更新向量索引。这样即使 Milvus 或 pgvector 暂时不可用，也能通过任务状态重试，而不是靠人工猜测哪些向量已经更新。

Milvus 方案则需要更明确的事件驱动或补偿机制：

PostgreSQL 更新业务状态 ↓ 发布索引更新事件 ↓ Worker 更新 Milvus ↓ 成功 / 失败回写 PostgreSQL ↓ 失败重试或人工处理

二十二、如何做真实压测？

选型前至少准备三类数据：

22.1 业务数据

不同文档长度、不同权限和不同更新频率的真实样本。

22.2 查询数据

真实用户问题、长问题、无答案问题、关键词问题和权限边界问题。

22.3 负载数据

不同并发数、Top K、过滤条件、批量写入和更新操作。

至少比较：

• P50、P95、P99 查询延迟；

• Recall@K；

• 过滤后的有效结果数量；

• 索引构建时间；

• 内存和 CPU；

• 写入吞吐；

• 故障恢复时间；

• 运维与备份成本。

不要只测试一次查询，也不要只测“没有过滤条件”的理想情况。

二十三、一个实用的分阶段路线

23.1 阶段一：先用 pgvector 验证闭环

PostgreSQL + pgvector ↓ 验证解析、切分、Embedding 和回答质量

23.2 阶段二：优化检索和数据模型

评估全文检索、混合检索、Reranker、过滤和索引参数

23.3 阶段三：确认瓶颈

如果业务 SQL、事务和向量搜索资源竞争明显 或延迟、并发、规模达到独立扩展需求 ↓ 考虑迁移 Milvus

23.4 阶段四：独立向量服务

PostgreSQL：业务事实 Milvus：向量检索 消息队列：索引同步 监控：跨系统链路追踪

二十四、常见错误决策

24.1 错误一：因为 Milvus 专业，所以项目一开始就部署

专业能力需要用数据证明是否必要。复杂部署不等于更好的检索效果。

24.2 错误二：因为 pgvector 简单，所以永远不拆分

当向量检索明显影响业务数据库时，继续把所有负载绑在一起也不是好的架构。

24.3 错误三：迁移时只复制向量，不复制版本和权限

这样可能导致检索到旧文档、越权文档或无法显示引用来源。

24.4 错误四：只看平均延迟

企业系统更应该关注 P95、P99、故障恢复和高峰期资源竞争。

二十五、选型决策表

二十六、上线前检查清单

• 不以向量条数单独决定选型；

• 已评估查询并发、延迟和过滤条件；

• 已比较 pgvector 精确与近似检索；

• 已评估业务 SQL 与向量搜索的资源竞争；

• 已定义文档、Chunk、版本和租户 ID；

• 已设计新增、更新、删除和权限变更同步；

• 迁移时保留旧索引和回滚方案；

• 使用同一评测集比较召回率和最终答案质量；

• 计算了部署、备份、监控和运维成本；

• 明确何种指标触发从 pgvector 拆分到 Milvus。

• 如果使用 Milvus，已明确 Standalone/Distributed、对象存储和元数据依赖；

• 如果使用 pgvector，已验证业务 SQL 与向量检索的资源隔离；

• 迁移具备稳定 ID、双写/灰度、校验和回滚方案；

二十七、结语：

27.1 pgvector 是 PostgreSQL 的自然延伸，但不是所有规模的终点

pgvector 让 PostgreSQL 可以直接保存向量并执行相似度搜索。对于中小型 RAG、原型和关系查询占主导的应用，它能以较低的系统复杂度完成完整闭环。

但当向量规模、并发、隔离和扩展需求不断增长时，仍然要用真实数据评估它的边界。

27.2 先用简单方案验证，再用数据决定拆分

pgvector 和 Milvus 不是“入门方案”和“高级方案”的简单关系。

pgvector 的核心优势是把向量检索与 PostgreSQL 的业务数据、SQL、事务和权限结合起来；Milvus 的核心优势是为专用向量检索提供更强的规模、索引和独立扩展能力。

最稳妥的路线通常是：先使用能快速验证业务闭环的方案，持续收集召回率、延迟、资源和运维数据，等瓶颈真实出现后再拆分。

至此，第三篇章“PostgreSQL 与业务数据”全部完成。下一篇章将进入 Milvus 与向量数据库，从《Milvus 是什么？为什么 RAG 系统经常使用它？》开始。

参考资料

1. pgvector 官方项目

2. Milvus Documentation：What is Milvus

3. Milvus Documentation：Basic Vector Search

4. Milvus Documentation：Architecture Overview

5. Milvus Documentation：Run Milvus with Docker Compose

6. PostgreSQL Documentation：Indexes

7. PostgreSQL Documentation：Concurrency Control

8. PostgreSQL Documentation：EXPLAIN

14.什么时候用 pgvector，什么时候单独部署 Milvus？