📑 本页目录(点开跳转)
07 · 向量检索落地
⏱ 42 分钟 | ⭐ 先别急着上专用向量库
🎯 一句话
如果向量和业务数据需要一起查、一起更新,可以先用同一个 Postgres 建立基线。是否拆开,取决于自己的查询、索引和运维实测。
⚠️ 这一章不讲 RAG 该怎么切分、怎么重排(那是《大模型全景导论》08), 也不讲 HNSW 和 IVF 的原理(那是《推荐算法》10)。 ⭐ 本章只讲一件事:怎么把它真的存进库里、和业务数据一起查。
🤔 一、先回答那个所有人都跳过的问题
搜「向量数据库」,出来的全是专用产品的对比评测。几乎没人先问一句:你需要多一个数据库吗?
多一个数据库,你就多了:
| 多出来的 | 具体是什么 |
|---|---|
| 一套备份和恢复 | 而且要和主库恢复到同一个时间点,否则数据对不上 |
| 一套监控告警 | 又一个会半夜挂掉的东西 |
| 一套连接管理 | 连接池、超时、重试,全部再来一遍 |
| ⭐ 一致性问题 | 这条最贵,下面单独说 |
⭐ 决定性的那个问题:向量和业务数据要不要保持一致
假设用户删了一份文档。你要:
操作步骤
- 从 documents 表删掉这条记录
- 从向量库删掉它的所有向量
这两步不在一个事务里。 于是:
- ① 成功 ② 失败 → 💀 文档已删除,但用户提问时还能检索到它的内容(数据泄露)
- ① 失败 ② 成功 → 文档还在列表里,但问不出任何内容(用户困惑)
⚠️ 这不是理论风险,是必然会发生的 —— 网络抖动、进程重启、部署时机,任何一个都能制造它。 要解决就得引入对账任务、软删除、事件溯源……一整套本来不需要的复杂度。
⭐ 如果向量和文档在同一个 PostgreSQL 数据库,可把这两步纳入同一个事务。下面在外键上配置
ON DELETE CASCADE,删除父文档时一并删除它的片段。外部缓存或另存的索引仍需单独更新。
🐘 二、pgvector:把向量当成一个字段
pgvector 是 Postgres 的一个扩展。装上之后,向量就是一种列类型,和 int、text 平级。
🗓️ 本章的 SQL 全部未实跑 —— 需要 PostgreSQL + pgvector 扩展,本地没有环境就跑不了。 而且运算符、索引参数、支持的向量类型都随 pgvector 版本变,动手前查你那一版的文档。
-- 🗓️ 未实跑,需要 PostgreSQL + pgvector
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE documents ( -- ⭐ 业务侧的文档表,chunks 挂在它下面
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL,
title TEXT NOT NULL,
archived BOOLEAN NOT NULL DEFAULT false, -- ⭐ 第四节要拿它过滤
created_at TIMESTAMPTZ DEFAULT now()
);
CREATE TABLE chunks (
id BIGSERIAL PRIMARY KEY,
document_id BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
user_id BIGINT NOT NULL, -- ⭐ 多租户过滤要用,见第四节
content TEXT NOT NULL,
embedding VECTOR(1536), -- ⭐ 维度写死,和你的 embedding 模型对应
created_at TIMESTAMPTZ DEFAULT now()
);
⭐ 注意 ON DELETE CASCADE —— 上一节那个一致性问题,在这里就是一行 DDL 解决的。
删文档,它的所有 chunk 和向量跟着走,在同一个事务里。
先在仅有演示数据的本地表里看距离排序。$1 绑定查询向量,业务查询还要加第四节的可见范围条件。
-- 🗓️ 未实跑,需要 PostgreSQL + pgvector
SELECT content, embedding <=> $1 AS distance
FROM chunks
ORDER BY embedding <=> $1
LIMIT 5;
三个距离运算符,⚠️ 必须和你的 embedding 模型匹配:
| 运算符 | 距离 | 什么时候用 |
|---|---|---|
<=> |
余弦距离 | 模型文档建议按向量方向比较时 |
<-> |
L2(欧氏) | 模型文档明确说用 L2 时 |
<#> |
负内积 | 模型建议用内积时。负号让更大的内积在升序排序里靠前 |
同一组向量改用另一种度量,SQL 仍可能成功,但排名可能变。先核对模型推荐的度量,建索引时选对应的运算符类。pgvector 运算符文档。
把一次文档提问变成可核对的排序
用户问「退款什么时候到账?」手里有几段说明文字。逐字找「到账」会漏掉写着「款项原路退回」的片段。嵌入(Embedding)模型把文本编码成一串数字,称为向量(Vector)。如果模型把相关文字映射到相近方向,就能先取回值得阅读的片段。
为什么这里比较方向? 如果两个向量都指向同一方向,仅长度不同,余弦相似度(Cosine Similarity)把它们视为同样接近。做法是先把两个向量各自除以长度,再把对应坐标相乘相加,得到两个方向的点积。下例向量只有两个坐标,长度用勾股定理算。查询向量 q 和片段向量 v 必须处于同一向量空间,长度必须非零。
用假设的二维向量来手算,数字是为了演示,实际向量的坐标通常没有这样简单的含义。设 q = (1, 0),片段 C11 的 v = (3, 4)。两向量长度分别为 √(1² + 0²) = 1 和 √(3² + 4²) = 5。归一化后相乘相加:1 × (3/5) + 0 × (4/5) = 0.6。pgvector 的 <=> 返回余弦距离(Cosine Distance),即 1 − 余弦相似度,所以 C11 的距离为 1 − 0.6 = 0.4。
再算当前用户的 C12,v = (0, 2),长度为 2,余弦相似度为 1 × (0/2) + 0 × (2/2) = 0,距离为 1。允许使用的只有 C11 和 C12,取 Top‑2 得到 C11 → C12。数据库按距离升序排。距离 0.4 无单位,也不表示答案有 40% 的概率正确。下游仍须看片段是否包含到账时间,才能决定是否引用。
📇 三、索引:⚠️ 别建太早
精确搜索逐个计算合格候选的距离。没有向量索引时,Postgres 仍可能先通过普通索引缩小范围,不一定全表扫描。先量自己的候选数、延迟和吞吐,再决定是否上近似索引。
pgvector 有两种索引:
| IVFFlat | HNSW | |
|---|---|---|
| 建索引速度 | 快 | ⚠️ 慢很多 |
| 占用空间 | 小 | 大 |
| 查询速度 | 好 | ⭐ 更好 |
| 召回率 | 依赖参数调优 | ⭐ 通常更高 |
| ⚠️ 致命点 | 先载入代表性数据再建(需要聚类) | 可以在空表上建 |
IVFFlat 需要足够的代表性数据来划分候选列表。如果过早建了索引,结果条数或召回可能不达标。先补足数据,再考虑重建并与精确结果对照。
⭐ 实践建议: 先用精确搜索做正确性对照。合格范围小且延迟达标时可以继续用它。需要提速时,在同一批查询上比较 HNSW、IVFFlat 的延迟、召回和资源开销。
近似最近邻搜索(Approximate Nearest Neighbor Search,ANN)用有限的扫描预算找可能接近的向量。当查询实际走近似索引时,结果可能与精确搜索不同。效果变差时,先核对实际计划、数据和过滤范围,再试调 HNSW 的 ef_search 或 IVFFlat 的 probes。
🔒 四、⭐ 过滤 + 向量检索:差别到底在哪(⚠️ 最容易被讲错的一节)
真实需求几乎从来不是「在全部向量里搜最相似的」,而是:
「在当前用户有权读、没被归档的文档里,搜最相似的 5 条」
这个私有文档示例由服务端认证后取出当前用户 ID,绑定到 $2,$1 绑定查询向量。若是租户内共享文档,要用实际成员、角色和资源授权限定范围。查询参数里的用户号或单个所有者过滤都不能代替业务授权。
-- 🗓️ 未实跑,需要 PostgreSQL + pgvector
SELECT c.id AS chunk_id, c.document_id, c.content, c.embedding <=> $1 AS distance
FROM chunks c
JOIN documents d ON d.id = c.document_id
WHERE c.user_id = $2 -- 私有文档:片段所有者
AND d.user_id = $2 -- 文档所有者也必须匹配
AND c.embedding IS NOT NULL -- 向量尚未生成时不可参与排序
AND d.archived = false -- ⭐ 注意:这个条件在另一张表上
ORDER BY c.embedding <=> $1
LIMIT 5;
chunk_id 与 document_id 用于追溯来源。archived 在 documents 上,查询通过 JOIN 把文档状态与片段关联,
这一点下面还会回来说。
在专用向量库里,这件事叫「带元数据过滤的检索」,是一个需要专门支持的特性, 各家实现差异很大,通常就两种做法,各有各的问题:
| 做法 | 问题 |
|---|---|
| 先过滤再搜(pre-filter) | 先缩小候选范围。合格数据很少时,精确计算也可能足够快 |
| 先搜再过滤(post-filter) | ⚠️ 取回 top 100 过滤完只剩 3 条,甚至一条不剩 —— 你要的 5 条拿不到 |
⚠️⚠️ 别搞错:这个困境 pgvector 也有
很多「pgvector vs 专用向量库」的对比文章会把这个困境说成专用库独有。这是错的。
当执行计划实际选择了 HNSW 或 IVFFlat,pgvector 会在近似索引扫描后应用过滤,可能得到不足 K 条的结果。若规划器先按业务条件缩小范围再精确排序,就没有这个近似候选预算。SQL 中 WHERE 写在 ORDER BY 前面,并不能决定实际执行计划。
pgvector 从 0.8.0 起可启用迭代索引扫描。过滤后不足时,索引可以继续扫描,直到取够或达到预算。继续扫也可能凑不够,所以仍要测自己的查询。pgvector 迭代扫描说明。
pgvector 的价值在于与业务 SQL、事务和查询规划器的结合,不能把专用向量库说成“不支持精确搜索”。例如 Qdrant 的 SearchParams(exact=True) 就能提供精确对照。官方 ANN 召回实验。
| 比较项 | pgvector 的特点 | 对照时须核实 |
|---|---|---|
| 精确与近似 | 不建近似索引时可精确扫描;也可建 HNSW/IVFFlat | 专用库也可能支持精确模式;按具体版本、过滤与数据规模测试 |
| 过滤与规划 | B-tree、SQL 条件与向量查询可组合 | 规划器不保证总选最优;用 EXPLAIN 与实测观察,不能只看 SQL 写法 |
| 事务和关联 | 与业务数据在同一个 PostgreSQL 事务中更新,可 JOIN | 独立向量库与业务库之间通常需要同步;更新/删除/撤权必须量延迟并对账 |
小数据量先用精确搜索建立基线;大数据量再测近似索引的召回—延迟取舍。存储选型要比较自己的过滤分布、成本和运维条件。检索实验将这种对照接到 RAG。
候选必须经过可信的业务授权。这个私有文档示例用服务端认证得到的所有者范围。生产服务如何把访问范围落实到应用和数据层,见第 08 章。
用相同四条片段,分清少返回和漏掉近邻
把刚才的例子加到四条。C13 已归档,C21 不在当前用户的可见范围内。两条的向量 (2, 0)、(1, 0) 都和查询 (1, 0) 同方向,余弦相似度都为 1,距离都为 0。这里把近似索引的扫描上限简化为「只看到三个候选」,便于手算。
C11(0.4)→ C12(1),两条都能交给下游。
看到 C13(0)→ C21(0)→ C11(0.4)。过滤后只剩 C11。C12 在允许范围内,却未进入这次扫描的候选。两条同分的候选在教学代码中按编号排。
这是一次有两个合格近邻却只交付一个的例子。如果精确基线也只有一个合格候选,返回一条就是正常结果。反过来,近似查询即使返回了 K 条,也可能用较远的候选填满名额。要查漏了谁,比较结果编号。这里的索引召回率以精确结果为参照,用「两组共同的编号数 ÷ 精确结果条数」计算。本例 K = 2,精确组是 C11、C12,共同的只有 C11,所以 1 ÷ 2 = 50%。如果精确组为空,分母为 0,应单独记录空结果。这项指标衡量近似搜索复现精确结果的程度,文档是否真的有用还需另做相关性评测。
下面的 Python 3 示例只用标准库。把四个演示向量直接作为输入,比较同一过滤条件下的精确结果和候选受限结果。它只模拟固定的候选范围,不实现 HNSW 或 IVFFlat。
from math import hypot
query = (1, 0)
current_user = 7
k = 2
rows = [
("C11", 7, False, (3, 4)),
("C12", 7, False, (0, 2)),
("C13", 7, True, (2, 0)),
("C21", 9, False, (1, 0)),
]
def distance(vector):
x, y = vector
qx, qy = query
return 1 - (qx * x + qy * y) / (hypot(qx, qy) * hypot(x, y))
def eligible(row):
_, owner, archived, _ = row
return owner == current_user and not archived
ranked = sorted(rows, key=lambda row: (distance(row[3]), row[0]))
exact_ranked = sorted(filter(eligible, rows), key=lambda row: (distance(row[3]), row[0]))
exact = [row[0] for row in exact_ranked[:k]]
limited = [row[0] for row in ranked[:3] if eligible(row)][:k]
print("exact:", exact)
print("limited:", limited)
print("index recall:", f"{len(set(exact) & set(limited)) / len(exact):.0%}")
运行后依次得到 exact: ['C11', 'C12']、limited: ['C11']、index recall: 50%。exact 先筛选可用的片段,再按距离排序。limited 模拟只看到前三条候选,再从中筛选。分母在这组演示里固定非零。
在线诊断时,保持数据快照、模型版本、距离、授权条件和 K 一致。先在可控环境跑出精确对照,再用 EXPLAIN 确认近似索引是否真的被选中。遇到并列距离时,精确对照和比较程序需要采用一致的并列处理约定。对比短结果比例、索引召回率和延迟,重点覆盖只匹配少量记录的过滤条件。可试着调大扫描预算,或对很小的合格范围用精确搜索。无论扫描多少,只有通过授权的片段才能进入模型上下文。
🧮 五、embedding 在哪算、什么时候算
文档片段在写入阶段提前算向量,每次查询只计算问题的向量。
因果链
查询和文档向量必须来自兼容的同一个向量空间。通常使用同一个模型版本,并各自采用模型文档要求的查询侧和文档侧输入约定。有的模型要求两侧用不同前缀。同样长的向量也可能来自互不兼容的空间,数据库的维度检查只能拦住长度不符。
⭐ 换 embedding 模型 = 全部重算。 这件事的代价要提前知道:
- 一百万个 chunk,按常见的 embedding 定价,重算一次是一笔真金白银
- 维度不同时要用兼容的存储结构。即使维度相同,也要分版本隔离搜索范围和索引
- 可建新表或新版本的检索路径,回填、核对覆盖率和检索质量后,再同时切换查询编码与目标索引
⭐ 实践建议:记录模型和版本,例如在表里加
embedding_model、embedding_version,再结合文档版本判断哪些片段需要重算。上文 SQL 的演示表只放单一版本。写入与查询时都要校验维度,使用余弦距离时还要拦截零向量。
🚦 六、什么时候真该上专用向量库
前面全在劝你别上。但确实存在该上的时候 —— 判断信号:
| 信号 | 说明 |
|---|---|
| ⭐ 向量数超过千万级 | pgvector 的索引构建和内存占用开始成为运维负担 |
| QPS 很高且延迟敏感 | 专用库在纯向量检索这一件事上做了更多优化 |
| 需要 Postgres 没有的检索能力 | 比如 GPU 加速检索、放不进内存的磁盘索引。🗓️ ⚠️ 量化压缩不在此列 —— pgvector 已经支持标量量化(halfvec)和二值量化,别拿一个不成立的理由去多养一个数据库(版本相关,用前查文档) |
| 向量和业务数据本来就分离 | ⭐ 比如向量来自离线批处理,和在线库没有一致性要求 —— 这时第一节那个理由不成立了 |
| 团队已经在运维那个库了 | 边际成本为零,那就用 |
⚠️ 注意上面没有一条是「因为它是专门做这个的」。 ⭐ 技术选型的成本不在「学会用」,在「长期运维」 —— 多一个有状态的组件,就多一个会在凌晨出问题的东西。
🔄 七、换个栈怎么对应
| Python(本章主栈) | Node | Go | |
|---|---|---|---|
| 驱动 | psycopg / asyncpg |
pg / postgres.js |
pgx |
| 向量类型 | pgvector 官方客户端 🗓️ | 同 | 同 |
| ORM 集成 | SQLAlchemy + pgvector | Drizzle / Prisma(⚠️ 向量支持较新,先查) | sqlc / GORM |
⭐ 核心概念三家完全一致 —— 建表、<=> 运算符、索引、过滤,都是 SQL 层的事。
⭐ 这一章的内容几乎全部是 SQL 和数据建模,换语言不影响 ——
这也是选 pgvector 的一个附带好处:你的知识不绑定在某个 SDK 上。
(🗓️ 上表的包名和各家 ORM 的向量支持程度都在变,用前先查。
⚠️ 官方客户端的仓库名带语言后缀(pgvector-python / -node / -go),但包管理器里的安装名不一定带 ——
以 PyPI / npm / Go module 上的实际名字为准,别照着仓库名去装。)
🔗 这一章连到哪里
| 去哪 | 为什么 |
|---|---|
| 06 · 关系数据库 | ⭐ 本章的表就建在那一章那个库里。连接池、迁移、事务边界那几条在这里同样适用 |
| 08 · 认证、会话与多租户 | 第四节按私有文档所有者筛选。那一章讲如何用可信身份和业务授权限定可见范围 |
| 11 · 长任务与队列 | 算 embedding 是几十秒的活,HTTP 请求等不了 —— 必须走队列 |
| 大模型全景导论 08 · RAG 深水区 | ⭐ 分工:那一章讲 RAG 策略(怎么切分、要不要重排、怎么评估检索质量),本章讲怎么真的存进库里。两章合起来才完整 |
| ⭐ 07b · 文件上传与对象存储 | ⚠️ 本章第五节那张流程图的第一步就是「上传文档」 —— 而这一步本章一个字没讲。那一章补上入口:为什么不能让文件流过你的后端、413 是怎么来的、预签名直传的形状、传完之后怎么触发切分 |
| 推荐算法 10 · 向量检索 ANN | HNSW 和 IVF 为什么快、怎么工作在那一章。本章只讲该选哪个、什么时候建 |
| 数据这一关 17 · 版本与血缘 | 「换 embedding 模型要全部重算」是一个典型的血缘问题 —— 那一章讲怎么系统地记录「这份数据是怎么来的」 |
✅ 检查点
- 多一个专用向量库,会多出哪四样东西?哪一样最贵?
- 用户删除文档时,向量和业务数据分开存会出什么问题?pgvector 怎么绕开它?
- pgvector 的三个距离运算符分别是什么?选错了会怎样?
- IVFFlat 有一个新手必栽的坑,是什么?为什么特别难发现?
- 数据量只有几万条时,索引该怎么建?
- ⭐ 「带元数据过滤的检索」有哪两种做法、各有什么问题?⚠️ 建了 HNSW 之后 pgvector 还有这个问题吗?那它的优势到底是哪三条?
- embedding 该在写入时算还是查询时算?为什么?
- 换 embedding 模型的代价是什么?该提前存哪一列来降低这个代价?
- 什么时候真该上专用向量库?列三条信号。
- 先预测再看答案。候选预算从 3 改为 2,仍按示例距离和编号排序。过滤后还剩几条?与精确 Top‑2 的索引召回率是多少?
👀 答案
- 一套备份恢复(还要和主库恢复到同一时间点)、一套监控告警、一套连接管理、一致性问题(最贵)。
- 删除要做两步(删业务记录、删向量),这两步不在一个事务里:①成功②失败 → 💀 文档已删除但仍能被检索到(数据泄露);①失败②成功 → 文档还在但问不出内容。⚠️ 网络抖动、进程重启、部署时机都会触发。pgvector 里一行
ON DELETE CASCADE就解决了 —— 同一个事务。 <=>为余弦距离,<->为 L2 欧氏距离,<#>为负内积。按模型推荐的度量选运算符。用错可能改变排序。- IVFFlat 需要代表性数据来划分候选列表。数据过少就建索引,结果条数和召回可能不达标。先补数据,再重建并核对。
- 先按业务过滤后的候选规模实测精确搜索。延迟达标时可以不建近似索引。延迟不达标时,比较索引的召回、延迟和资源开销。
- 两种做法:pre-filter(先过滤再搜——候选集变小,向量索引可能失效退化成暴力扫)、post-filter(先搜再过滤——⚠️ 取回 top 100 过滤完只剩 3 条甚至 0 条,要的 5 条拿不到)。⚠️⚠️ pgvector 一样有这个问题:实际使用 HNSW / IVFFlat 的查询可能遇到过滤后不足 K,应检查执行计划与迭代扫描配置,换个存储不会让近似索引变精确(🗓️ 较新版本有
hnsw.iterative_scan这类开关,专门给它兜底——这恰恰说明问题真实存在)。它真正的优势是三条:① 小数据量可以干脆不建索引,精确扫描过滤得一条不差——专用库也可能提供精确模式,需按具体引擎验证;② 过滤条件能走普通 B-tree,「先过滤再精扫」还是「走向量索引」由查询规划器自己挑,不用你二选一;③ 过滤条件和向量在同一份数据、同一个事务里,archived在另一张表上也能 JOIN,不必把元数据同步一份过去(同步就会漂)。 - 文档片段提前算,查询侧每次为问题算。两边要遵守同一向量空间的编码约定,同维不能证明兼容。
- 迁移时要为仍需检索的片段重算,按版本隔离候选与索引。提前记录
embedding_model和embedding_version,便于确定回填范围。 - 任选三条:向量数超千万级、QPS 高且延迟敏感、需要 Postgres 没有的检索能力(GPU 加速、放不进内存的磁盘索引;⚠️ 量化压缩不算 —— pgvector 已经有
halfvec和二值量化,拿它当理由是不成立的)、向量和业务数据本来就分离(来自离线批处理、无一致性要求 —— 这时第一节的理由不成立)、团队已经在运维那个库。⚠️ 注意没有一条是「因为它是专门做这个的」 —— 技术选型的成本不在「学会用」,在「长期运维」。 - 先看到的是距离都为 0 的 C13 和 C21,前者已归档,后者不在当前用户可见范围。结果为空,共同编号数为 0,索引召回率为 0 ÷ 2 = 0%。精确对照仍能找出 C11 和 C12。
本节回顾
⚡ 走神救援
⭐ 这一章的立场:向量需要和业务数据一起查、一起更新时,可以先放在同一个数据库里建立基线。
⭐ 多一个专用库就多四样东西:一套备份恢复、一套监控、一套连接管理,以及最贵的那个——一致性。删文档要删业务记录和删向量两步,⚠️ 它们不在一个事务里。💀 一半成功就是「文档已删除却仍能被检索到」,那是数据泄露;反过来是文档还在但问不出内容。⭐ 而放在一起时,这一切就是一行级联删除。
先测精确搜索。只有查询确实需要提速时,才测近似索引的召回和延迟。IVFFlat 先载入代表性数据再建索引。
⭐⭐ 最关键的一节是「带元数据过滤的检索」:真实需求几乎从不是「在全部向量里搜」,而是「在这个用户的、这个文件夹里的、没归档的文档里搜」。实际走近似索引时,候选扫描可能先受预算限制,再由授权条件过滤。用同一授权范围的精确 Top‑K 对照,才能判断少了谁。
它真正的优势是三条:小数据量可以干脆不建索引(专用库也可能支持精确模式)、过滤条件走普通索引由查询规划器自己挑、过滤和向量在同一份数据同一个事务里。⭐ 所以理由是「你多了几个选项而且不用自己选」,不是「问题不存在」。
换向量模型需要为仍要检索的片段重算。记录模型版本,隔离新旧搜索范围,回填并验证后再切换。
⚠️ 真该上专用库的信号里没有一条是「因为它是专门做这个的」——⭐ 技术选型的成本不在学会用,在长期运维:多一个有状态组件,就多一个会在凌晨出问题的东西。
下一节 👉 07b-文件上传与对象存储.md