Hugging Face Datasets 怎样单独保存与载入 FAISS 索引

Hugging Face Datasets 的 FAISS 索引可以单独保存：建好索引后调用 save_faiss_index 写出文件，下次把对应的数据集载入，再用 load_faiss_index 挂回索引。关键是同时保留原数据的行顺序；只拿到一个索引文件，并不能还原全部文本和业务字段。

官方文档：https://huggingface.co/docs/datasets/en/faiss_es

把数据快照与索引文件分开

设想一个本地知识检索任务：文档已经转成向量，进程重启后却找不到原先的检索入口。先分清丢失的是数据、向量列还是已挂载的索引。三者有关联，但不是同一份资源。

先用明确的索引名构建并导出

下面使用手工编写的三维数值演示文件生命周期，不调用模型，也不代表真实语义质量。环境需要安装 Datasets、NumPy 和可用的 FAISS 实现。例子选择 CPU，并显式指定平方欧氏距离，避免把分数理解成概率。

from pathlib import Path
import faiss
from datasets import Dataset

# 三维向量仅用于演示保存过程，不是模型生成的语义表示。
ds = Dataset.from_dict({
    "doc_id": ["a", "b", "c"],
    "text": ["检查订单状态", "修改收货地址", "查询退款进度"],
    "embedding": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
})
root = Path("bundle")
root.mkdir(exist_ok=True)

# 列名是 embedding，检索索引名另取 vectors，两者不要混淆。
ds.add_faiss_index(
    column="embedding",
    index_name="vectors",
    metric_type=faiss.METRIC_L2,
)
ds.save_faiss_index("vectors", str(root / "vectors.faiss"))

# 数据集落盘前移除已挂载索引，索引文件已经单独保存。
ds.drop_index("vectors")
ds.save_to_disk(str(root / "dataset"))

这里把索引名设为 vectors。后面查询和保存时使用这个名字，而不是机械填写向量列名。若没有显式设置名称，默认名称才通常跟随建索引的列。

重新载入数据后挂回索引

新进程不必再次运行建索引操作。读取刚才保存的数据目录，再挂载同包内的索引文件即可。不要把载入索引的调用赋值回数据集变量；它操作现有对象，不用于返回新的 Dataset。

from pathlib import Path
import numpy as np
from datasets import load_from_disk

# 使用同一发布包内的数据与索引，保留建立索引时的行顺序。
root = Path("bundle")
restored = load_from_disk(str(root / "dataset"))
restored.load_faiss_index("vectors", str(root / "vectors.faiss"))

# 查询维度必须与索引一致；这里仍使用演示用三维向量。
query = np.asarray([0.9, 0.1, 0.0], dtype=np.float32)
scores, examples = restored.get_nearest_examples("vectors", query, k=2)
print(examples["doc_id"])
print(scores)

正常完成后，list_indexes() 应能列出挂载名称，查询接口返回分数和对应样本。以上是供读者运行的示例，不附带虚构的本地运行记录。真实项目的查询向量应与文档向量使用相匹配的编码模型、维度及预处理方式。

排查载入后文档错位

索引载入成功不等于业务映射必然正确。当前源码会比较索引向量数量与 Dataset 长度，但相同数量的数据可能已经换了顺序。如果建索引时文档甲在第0行，恢复数据却把文档乙放在第0行，返回的位置就会关联到错误文本。

因此，索引和数据最好作为同一次发布的配套文件。业务上可以记录数据版本、文档ID序列、编码模型标识、向量维度和距离度量。更新文档、删行、重排或改变向量生成方式后，应重新评估并通常重建对应索引，不要沿用名称相同的旧文件。

按症状区分文件问题和索引问题

索引文件是否保存原文？不要依赖它恢复原文，业务字段由 Dataset 快照保存。载入时一定需要向量列吗？已有索引负责向量检索，官方示例也支持将索引挂到对应原始数据上；本例保留向量列是为了后续维护更方便。drop_index 会删除磁盘文件吗？它移除当前数据集挂载的索引，不等于删除此前导出的文件。

API参考：https://huggingface.co/docs/datasets/en/package_reference/main_classes