索引构建与存储

沿用第 1 章的多租户文档块表 doc_chunks（embedding vector(1536)）。第 1 章建索引时只写了 opclass、没碰参数；这一章把 WITH (...) 里的每个数字摊开，看它们如何决定构建时间、索引体积和召回率。

2.1HNSW 与 IVFFlat：两种 PG 访问方法

HNSW 和 IVFFlat 都是 Postgres 的索引访问方法（access method），同一条 CREATE INDEX 语法、不同的 USING 和参数；它们的本质区别是能不能建在空表上。

两者的 DDL 形状一致，差别在 USING 后面的方法名和 WITH 里的构建参数：

-- HNSW：可以建在空表上，之后每次 INSERT 增量把节点接进图
CREATE INDEX ON doc_chunks
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 64);     -- m 默认 16，ef_construction 默认 64

-- IVFFlat：必须先灌数据再建，lists 个质心来自对已有行做 k-means
CREATE INDEX ON doc_chunks
    USING ivfflat (embedding vector_cosine_ops)
    WITH (lists = 100);                       -- lists 默认 100

底层机制（比文档深一层）：这条"建之前要不要有数据"的差别，根子在两种索引的结构怎么来。HNSW 是一张增量可生长的图——空图也是合法的图，每来一行就把它的节点连进去，所以建在空表上、再慢慢 INSERT 完全成立。IVFFlat 不是图，它先把向量空间切成 lists 个单元（cell），每个单元一个质心（centroid），而质心是对当前表里已有的行跑 k-means 算出来的。表是空的，就没有行可聚类，质心退化成随机点，整个倒排结构形同虚设。所以 IVFFlat 的铁律是：先把数据灌进去，再建索引；数据分布大改之后还得重建。算法层面 HNSW 的贪婪搜索、IVF 的聚类怎么工作，见隔壁 vector-database 教程 02；这一章只把它们当 Postgres 对象看。

参数怎么取，有经验公式。IVFFlat 的 lists 和 query 端的 probes 都随行数走：

2.2图在索引页里怎么躺

HNSW 的图被拆成两种 tuple、散落在多张 8KB 页上；检索靠 TID 指针在页之间跳，所以它是随机 I/O 密集型——图装不进内存，延迟就崩。

底层机制（比文档深一层）：HNSW 在索引里存两种 tuple。element tuple（HnswElementTuple）装一个节点：向量原值、一个 heaptids[] 数组（最多约 10 个堆表 TID，指向这个向量对应的实际数据行）、节点所在的层级（level），以及一个指向独立的 neighbor tuple 的指针。neighbor tuple 单独存这个节点的邻居列表，大小约 (level+2) × m 个邻居槽。这两种 tuple 都按普通堆页规则塞进一张张 8KB 页里，谁和谁同页是不确定的。索引的 0 号元数据页（metadata page）记着图的入口点（entry point）——它的 block 号和页内 offset，每次检索都从这里出发。

把机制推到后果：检索沿图遍历，每一跳都要解引用一个落在任意页上的邻居 TID。当整张图能装进 shared_buffers / 操作系统页缓存时，这些跳大多命中内存，延迟是毫秒级。一旦图的体积超过可用内存，落在未缓存页上的那些跳就各自触发一次缺页（page fault），要从磁盘把那张页读上来——一次 ANN 检索动辄几十上百跳，延迟随之从毫秒塌到几十甚至上百毫秒。这就是为什么"索引能不能装进内存"是 HNSW 性能的头号杠杆，压倒一切参数微调。

2.3构建悬崖：maintenance_work_mem

HNSW 构建在内存里跑，直到 maintenance_work_mem 装满；越过这道坎，构建掉进逐元组落盘的慢路径，同样的数据、同一个阈值，构建时间炸开 10–50 倍。

底层机制（比文档深一层）：HNSW 构建时，pgvector 先尝试把整张正在生长的图放进 maintenance_work_mem 里建——这条内存路径快。一旦图的体积超过这个上限，pgvector 在日志里打出一行：

NOTICE:  hnsw graph no longer fits into maintenance_work_mem after 524288 tuples
HINT:  Building will take significantly more time.

这行 NOTICE 一出，构建就从"整图在内存"切到逐元组落盘（on-disk, one tuple at a time）的路径：每接一个新节点都要在磁盘上的图结构里读写，慢 10–50 倍。同一批数据，只因为跨过 maintenance_work_mem 这一个阈值，构建时间就从线性增长变成断崖式爆炸。这就是构建悬崖。

并行构建：又一个被 maintenance_work_mem 掐住的开关

pgvector 0.6.0（2024-01）给 HNSW 加了并行构建。它的做法是把正在生长的图放进一段共享内存（内部叫 hnswarea），多个 worker 同时往里接节点。两个工程细节决定了它的边界：

• 用相对偏移指针：共享内存段在每个 worker 进程里映射到的虚拟地址不同，所以图内的指针不能存绝对地址，必须存相对段起点的偏移，每个 worker 解引用时各自加上自己的基址——这样大家看到的是同一张图。
• 段不能扩容、按元素加 LWLock：每个 element 用一把轻量锁（LWLock）保护并发修改；但这段共享内存一旦分配就不能再长大。它的大小同样由 maintenance_work_mem 决定。

把两节的机制叠起来，就看出 maintenance_work_mem 偏小是双重惩罚：它既让共享内存段装不下图、提前关掉并行（worker 无段可用），又触发 §2.3 的逐元组落盘慢路径。一个参数没给够，并行和快路径一起没了。控制并行度的是 max_parallel_maintenance_workers，默认 2（外加 leader 进程本身）。

-- 为这次构建临时放大内存与并行度（按图体积，百万行级常配多个 GB）
SET maintenance_work_mem = '8GB';
SET max_parallel_maintenance_workers = 7;   -- 默认 2；加上 leader 共 8 路

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

-- 建完核对索引真实体积，确认它能被内存覆盖
SELECT pg_size_pretty(pg_relation_size('doc_chunks_embedding_idx'));

2.4参数与"怎么真正量召回"

build 参数定下索引的"上限"，query 参数定下每次查询花多少力气；默认 ef_search = 40 / probes = 1 给的召回率很普通，而没有任何东西会警告你——召回率必须自己量。

先把四个参数归位。它们分成 build 和 query 两端，调高都换来更高召回、更慢速度：

分工要分清：build 参数（m / ef_construction / lists）在建索引时一次性定下结构质量的上限，建完不可调，要变只能重建；query 参数（ef_search / probes）每条查询都能用 SET 调，控制这一次"搜得多狠"。一条硬规则：ef_search 必须 ≥ 你要取的 k——要取 top-10 却把 ef_search 设成 5，索引连 10 个候选都凑不齐。

底层机制（比文档深一层）：默认 ef_search = 40 意味着 HNSW 遍历时维护一个大小 40 的候选集，probes = 1 意味着 IVFFlat 只探查 1 个单元。这两个默认值偏向速度，给出的召回率在很多数据集上只有八九成、甚至更低，取决于数据分布。pgvector 没有内置的召回率监控——索引照常返回 k 条、查询照常很快，召回率低这件事完全不可见。唯一的办法是拿精确暴力检索的结果当 ground truth，去比对索引返回的结果。

怎么逼 Postgres 跑一次精确暴力检索？在一个事务里关掉索引扫描，让 planner 退化成顺序扫描 + 精确排序，同一条 ORDER BY ... LIMIT k 就成了 ground truth：

-- 1) ground truth：关掉索引扫描，强制精确暴力 top-10
BEGIN;
SET LOCAL enable_indexscan = off;
SET LOCAL enable_indexonlyscan = off;
SELECT id FROM doc_chunks ORDER BY embedding <=> $1 LIMIT 10;   -- 真值
COMMIT;

-- 2) 索引结果：正常走 HNSW，先定 ef_search
SET hnsw.ef_search = 40;                                        -- 默认值
SELECT id FROM doc_chunks ORDER BY embedding <=> $1 LIMIT 10;   -- 近似

-- 3) recall@10 = 两个 id 集合的交集大小 / 10
--    多取一批查询向量求平均，才是这套参数的真实召回率
-- 4) 召回不达标就抬高 ef_search（48 → 64 → 100 ...）重测，直到达标

流程固定：关索引取真值 → 走索引取近似 → 算 overlap@k / k → 不达标就抬 ef_search / probes 重测，直到召回率压过你的目标（比如 0.95）。单条查询不算数，要在一批有代表性的查询向量上取平均。这是验收一个向量索引唯一可信的方式——延迟能用秒表测，召回率只能这么算出来。