FAISS 检索结果怎么映射回原始文档 ID

FAISS 检索结果要映射回原始文档 ID，关键是不要把结果矩阵里的列号当成业务主键。对 IndexFlatL2 这类不直接支持 add_with_ids 的索引，用 faiss.IndexIDMap 包一层；添加向量时传入 int64 类型的文档 ID，之后 search() 返回的 I 就是这些 ID。拿到 ID 后，再用字典、数据库或 KV 存储回查文档即可。

最小可靠做法：向量、业务 ID、文档元数据使用同一批次写入；检索时把 I 转成 Python 整数后回表，并对 -1 等无效结果做保护。不要重新用返回位置拼接文档主键。

先分清 Faiss 的内部位置和业务文档 ID

一次 search(query, k) 通常返回 D 和 I 两个矩阵：D 表示距离，I 表示命中的向量 ID。若直接对基础索引调用 add()，这个 ID 往往从 0 开始连续增长，看起来像文档列表下标，但它只是 Faiss 侧的编号。

一旦文档被删除、重建、分片或异步写入，内部编号与业务文档主键就可能不再一致。正确的边界是：Faiss 只负责“哪个向量更近”，文档存储负责“这个 ID 对应哪条原文”。

用 IndexIDMap 保存原始文档 ID

IndexFlatL2 提供精确的 L2 距离搜索，但不能直接处理 add_with_ids。把它交给 IndexIDMap 后，外层索引维护向量与自定义 ID 的映射，底层仍然保存向量。

import faiss
import numpy as np

# 每个向量对应一个稳定的业务文档 ID，必须使用 int64
documents = {
    10001: {"title": "向量索引入门", "chunk": "doc-1-0"},
    10002: {"title": "距离函数选择", "chunk": "doc-2-0"},
    10003: {"title": "检索结果回表", "chunk": "doc-3-0"},
}
vectors = np.asarray([
    [0.10, 0.20, 0.30, 0.40],
    [0.12, 0.19, 0.31, 0.39],
    [0.80, 0.70, 0.60, 0.50],
], dtype="float32")
doc_ids = np.asarray(list(documents), dtype="int64")

# IndexFlatL2 不接收 add_with_ids，用 IndexIDMap 增加 ID 映射层
base = faiss.IndexFlatL2(vectors.shape[1])
index = faiss.IndexIDMap(base)
index.add_with_ids(vectors, doc_ids)

# 查询向量的维度必须与索引维度一致
query = np.asarray([[0.11, 0.20, 0.30, 0.41]], dtype="float32")
distances, result_ids = index.search(query, 2)

doc_ids 的顺序必须和 vectors 的行顺序一一对应；这里的对应关系只负责写入映射，并不要求业务 ID 连续。生产环境应让这个 ID 在文档重建后仍可稳定定位，避免同一文档的多个分片共用无法区分的键。

把搜索返回值直接回表

真正返回给应用层时，同时读取距离和 ID，而不是只保留距离。搜索结果可能包含未填满的槽位，尤其是索引规模小于 k 或使用过滤条件时，应先跳过负数 ID，再执行回表。

# 用 ID 回查元数据，不用结果位置访问 documents.values()
hits = []
for distance, raw_id in zip(distances[0], result_ids[0]):
    document_id = int(raw_id)
    if document_id 

如果文档元数据放在数据库，hits 中的 ID 可以组成一次批量查询，并按 Faiss 返回的顺序重新排序。不要用数据库自然返回顺序覆盖相似度顺序，也不要把距离直接当成相似度；L2 距离越小通常越近，但最终排序含义仍由所用度量和业务阈值决定。

IndexIDMap 与 IndexIVF 怎么选

数据量较小、需要精确扫描或正在验证回表逻辑时，IndexIDMap(IndexFlatL2(...)) 直观易懂。若使用 IndexIVFFlat 等 IVF 子类，官方资料说明 IVF 索引本身就存储向量 ID，并原生提供 add_with_ids，额外套 IndexIDMap 反而会重复维护映射。

# IVF 索引原生支持 add_with_ids；写入前先训练量化器
nlist = 4
quantizer = faiss.IndexFlatL2(vectors.shape[1])
ivf = faiss.IndexIVFFlat(quantizer, vectors.shape[1], nlist, faiss.METRIC_L2)
ivf.train(vectors)  # 真实项目要用足够且分布合理的训练样本
ivf.add_with_ids(vectors, doc_ids)

无论选哪种索引，都把“向量写入成功”和“文档元数据可回查”作为同一个发布批次处理。索引重载、分片合并和删除时，优先保留业务 ID 的稳定性；若只重排向量数组而没有同步 ID，检索质量正常也可能回出错误文档。

常见问题：为什么回表结果会错

把 I[0][0] 当成文档数组下标怎么办？ 只有在你从未自定义 ID、且文档数组永久保持同一顺序时才可能碰巧成立。使用 IndexIDMap 后，直接把它当业务 ID 查元数据。

为什么 add_with_ids 报错？ 先确认底层索引是否实现该接口；IndexFlatL2 需要用 IndexIDMap 包装，IVF 子类通常可以直接调用。

重启后如何保持映射？ 保存索引文件的同时保存文档元数据，并把业务 ID 作为长期契约；恢复后先用一条已知 ID 的向量做小样本回表检查，再接入线上流量。