🏠 总目录📚 本教程 07 · 向量检索落地 ← →

AI全栈 / 07

向量已经算出来,检索该落在哪一层?

先核对存储、过滤与召回需求,再决定索引和独立向量库是否必要。

能说明过滤条件、向量版本和检索结果之间的约束。

核对过滤与检索

📑 本页目录(点开跳转)

07 · 向量检索落地

⏱ 42 分钟 | ⭐ 先别急着上专用向量库


🎯 一句话

如果向量和业务数据需要一起查、一起更新,可以先用同一个 Postgres 建立基线。是否拆开,取决于自己的查询、索引和运维实测。

⚠️ 这一章不讲 RAG 该怎么切分、怎么重排(那是《大模型全景导论》08), 也不讲 HNSW 和 IVF 的原理(那是《推荐算法》10)。 ⭐ 本章只讲一件事:怎么把它真的存进库里、和业务数据一起查。


🤔 一、先回答那个所有人都跳过的问题

搜「向量数据库」,出来的全是专用产品的对比评测。几乎没人先问一句:你需要多一个数据库吗?

多一个数据库,你就多了:

多出来的 具体是什么
一套备份和恢复 而且要和主库恢复到同一个时间点,否则数据对不上
一套监控告警 又一个会半夜挂掉的东西
一套连接管理 连接池、超时、重试,全部再来一遍
⭐ 一致性问题 这条最贵,下面单独说

⭐ 决定性的那个问题:向量和业务数据要不要保持一致

假设用户删了一份文档。你要:

操作步骤

  1. 从 documents 表删掉这条记录
  2. 从向量库删掉它的所有向量

这两步不在一个事务里。 于是:

⚠️ 这不是理论风险,是必然会发生的 —— 网络抖动、进程重启、部署时机,任何一个都能制造它。 要解决就得引入对账任务、软删除、事件溯源……一整套本来不需要的复杂度。

⭐ 如果向量和文档在同一个 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)。如果模型把相关文字映射到相近方向,就能先取回值得阅读的片段。

① 问题 → 向量按查询侧约定编码问题,得到查询向量。
② 确定可搜范围本例只允许当前用户尚未归档且已有可用向量的片段。
③ 由近到远取前 K 个精确搜索比较范围内所有合格向量。K 是最多取回的片段数。
④ 交付片段和来源下游收到片段文字和来源编号,再核对这些文字能否回答问题。

为什么这里比较方向? 如果两个向量都指向同一方向,仅长度不同,余弦相似度(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】→连同文本一起入库
↑ 慢,几十秒起步,所以走队列(第 11 章)
用户提问→【算 query 的 embedding】→查询
↑ 快,一次一条,可以同步做

查询和文档向量必须来自兼容的同一个向量空间。通常使用同一个模型版本,并各自采用模型文档要求的查询侧和文档侧输入约定。有的模型要求两侧用不同前缀。同样长的向量也可能来自互不兼容的空间,数据库的维度检查只能拦住长度不符。

⭐ 换 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 模型要全部重算」是一个典型的血缘问题 —— 那一章讲怎么系统地记录「这份数据是怎么来的」

✅ 检查点

  1. 多一个专用向量库,会多出哪四样东西?哪一样最贵?
  2. 用户删除文档时,向量和业务数据分开存会出什么问题?pgvector 怎么绕开它?
  3. pgvector 的三个距离运算符分别是什么?选错了会怎样?
  4. IVFFlat 有一个新手必栽的坑,是什么?为什么特别难发现?
  5. 数据量只有几万条时,索引该怎么建?
  6. ⭐ 「带元数据过滤的检索」有哪两种做法、各有什么问题?⚠️ 建了 HNSW 之后 pgvector 还有这个问题吗?那它的优势到底是哪三条?
  7. embedding 该在写入时算还是查询时算?为什么?
  8. 换 embedding 模型的代价是什么?该提前存哪一列来降低这个代价?
  9. 什么时候真该上专用向量库?列三条信号。
  10. 先预测再看答案。候选预算从 3 改为 2,仍按示例距离和编号排序。过滤后还剩几条?与精确 Top‑2 的索引召回率是多少?
👀 答案
  1. 一套备份恢复(还要和主库恢复到同一时间点)、一套监控告警、一套连接管理、一致性问题(最贵)。
  2. 删除要做两步(删业务记录、删向量),这两步不在一个事务里:①成功②失败 → 💀 文档已删除但仍能被检索到(数据泄露);①失败②成功 → 文档还在但问不出内容。⚠️ 网络抖动、进程重启、部署时机都会触发。pgvector 里一行 ON DELETE CASCADE 就解决了 —— 同一个事务。
  3. <=> 为余弦距离,<-> 为 L2 欧氏距离,<#> 为负内积。按模型推荐的度量选运算符。用错可能改变排序。
  4. IVFFlat 需要代表性数据来划分候选列表。数据过少就建索引,结果条数和召回可能不达标。先补数据,再重建并核对。
  5. 先按业务过滤后的候选规模实测精确搜索。延迟达标时可以不建近似索引。延迟不达标时,比较索引的召回、延迟和资源开销。
  6. 两种做法:pre-filter(先过滤再搜——候选集变小,向量索引可能失效退化成暴力扫)、post-filter(先搜再过滤——⚠️ 取回 top 100 过滤完只剩 3 条甚至 0 条,要的 5 条拿不到)。⚠️⚠️ pgvector 一样有这个问题:实际使用 HNSW / IVFFlat 的查询可能遇到过滤后不足 K,应检查执行计划与迭代扫描配置,换个存储不会让近似索引变精确(🗓️ 较新版本有 hnsw.iterative_scan 这类开关,专门给它兜底——这恰恰说明问题真实存在)。它真正的优势是三条:① 小数据量可以干脆不建索引,精确扫描过滤得一条不差——专用库也可能提供精确模式,需按具体引擎验证;② 过滤条件能走普通 B-tree,「先过滤再精扫」还是「走向量索引」由查询规划器自己挑,不用你二选一;③ 过滤条件和向量在同一份数据、同一个事务里,archived 在另一张表上也能 JOIN,不必把元数据同步一份过去(同步就会漂)。
  7. 文档片段提前算,查询侧每次为问题算。两边要遵守同一向量空间的编码约定,同维不能证明兼容。
  8. 迁移时要为仍需检索的片段重算,按版本隔离候选与索引。提前记录 embedding_model 和 embedding_version,便于确定回填范围。
  9. 任选三条:向量数超千万级、QPS 高且延迟敏感、需要 Postgres 没有的检索能力(GPU 加速、放不进内存的磁盘索引;⚠️ 量化压缩不算 —— pgvector 已经有 halfvec 和二值量化,拿它当理由是不成立的)、向量和业务数据本来就分离(来自离线批处理、无一致性要求 —— 这时第一节的理由不成立)、团队已经在运维那个库。⚠️ 注意没有一条是「因为它是专门做这个的」 —— 技术选型的成本不在「学会用」,在「长期运维」。
  10. 先看到的是距离都为 0 的 C13 和 C21,前者已归档,后者不在当前用户可见范围。结果为空,共同编号数为 0,索引召回率为 0 ÷ 2 = 0%。精确对照仍能找出 C11 和 C12。

本节回顾

⚡ 走神救援

⭐ 这一章的立场:向量需要和业务数据一起查、一起更新时,可以先放在同一个数据库里建立基线。

⭐ 多一个专用库就多四样东西:一套备份恢复、一套监控、一套连接管理,以及最贵的那个——一致性。删文档要删业务记录和删向量两步,⚠️ 它们不在一个事务里。💀 一半成功就是「文档已删除却仍能被检索到」,那是数据泄露;反过来是文档还在但问不出内容。⭐ 而放在一起时,这一切就是一行级联删除。

先测精确搜索。只有查询确实需要提速时,才测近似索引的召回和延迟。IVFFlat 先载入代表性数据再建索引。

⭐⭐ 最关键的一节是「带元数据过滤的检索」:真实需求几乎从不是「在全部向量里搜」,而是「在这个用户的、这个文件夹里的、没归档的文档里搜」。实际走近似索引时,候选扫描可能先受预算限制,再由授权条件过滤。用同一授权范围的精确 Top‑K 对照,才能判断少了谁。

它真正的优势是三条:小数据量可以干脆不建索引(专用库也可能支持精确模式)、过滤条件走普通索引由查询规划器自己挑、过滤和向量在同一份数据同一个事务里。⭐ 所以理由是「你多了几个选项而且不用自己选」,不是「问题不存在」。

换向量模型需要为仍要检索的片段重算。记录模型版本,隔离新旧搜索范围,回填并验证后再切换。

⚠️ 真该上专用库的信号里没有一条是「因为它是专门做这个的」——⭐ 技术选型的成本不在学会用,在长期运维:多一个有状态组件,就多一个会在凌晨出问题的东西。

下一节 👉 07b-文件上传与对象存储.md

打卡记录保存在你的浏览器里,首页能看到总进度