如何重建本地 AI 搜索索引并验证来源版本

直接回答

本地搜索索引应被当作派生数据迁移来重建，并绑定到一组明确的源快照和转换配置。数据库行数本身不能证明每条源记录都有对应索引、索引使用了当前解析器或分块器，也不能证明结果指回正确来源。开始之前定义索引清单：源集合版本、解析或抽取器版本、文本规范化规则、分块规则、若使用向量则记录 embedding 模型及版本、词项或向量引擎、schema 版本和构建完成状态。任何会改变索引文本或向量的输入，都应形成可独立验证的候选索引身份。 本文讨论索引生命周期，不讲如何搜索 PDF 或生成问答。词面精确索引和向量索引的查询行为与一致性检查不同，不能因为重建后结果看起来相似就视为可互换。RAG-01 将本地检索流程拆成导入、分块、embedding、索引、检索、prompt 和生成，可帮助定位索引所处阶段。PRIVACY-01 也设定边界：本地检索不代表应用不存在其他网络请求。本文不声称 Cove 已上线 RAG、embedding 或索引重建能力。 先清点权威源数据及其派生项。为每条本地文档或记录分配稳定来源 ID 和版本。只有产品实现了变更队列或变更表时，才把删除、更新和解析失败事件写入其中。重建应读取一致的源快照或使用版本化游标，否则构建过程中发生的更新可能漏掉或被重复索引。为无法解析的记录、空文档、已删除源和文件授权被撤销的情况定义结果。不能把无权读取的内容当成成功的空记录，因为“没有可检索文本”和“读取失败”是不同状态。 重建方案应匹配已安装的索引实现。小索引且有事务边界时，可以考虑原位刷新；若需要保证旧索引仍可用，单独生成候选更容易检查。数据库含多个 schema 版本时，使用已记录的迁移路径，并用导出的旧 schema 测试。Room 支持 FTS 虚拟表；SQLite FTS5 文档说明外部内容同步和 rebuild 命令，但这些命令和语义不会自动适用于 Room FTS4、向量存储或其他库。使用厂商特定 SQL 修复前，先确认准确的引擎和版本。对于外部内容表，基础内容表必须与全文索引保持同步；仅重建索引不能修复错误的来源映射。 可行时在隔离的候选空间中构建。记录预期来源数、接受数、跳过数和分类失败数，以及分块/向量数、源版本、完整性结果和完成标记。绝不能把未完成候选设为当前索引。构建后运行该引擎实际支持的完整性检查，再将代表性来源 ID、版本、页码或记录位置和规范化文本与权威记录比对。使用固定查询检查缺失词、删除后仍存在的旧词、重复分块、语言筛选错误和向量版本混用。一个看起来合理的结果不证明所有来源都已建索引。 切换索引需要明确的回滚边界。重建前记录当前活动索引 ID。只有通过完整性、覆盖、来源追溯和查询检查后，才能激活候选。如果候选失败，就保留旧索引，或明确显示搜索正在恢复；不要为了追求表面覆盖而混入不同版本的数据。如果解析器或 embedding 模型变更，要么重建所有受影响记录，要么显式保留每条记录版本，并设计能够安全处理版本差异的检索规则。若源记录在构建期间发生变化，应重放有限的变更集，或对新快照重新开始。 删除和隐私也是索引正确性的一部分。来源删除时，要确保关联分块、向量、摘要片段、缓存、排队任务和索引行不会因后台 worker 延迟或后续重建而重新出现。若索引使用无内容或外部内容模式，应明确哪一层保留可读文本、哪项操作真正删除内容。不能把搜索不到某条记录说成取证级擦除。用唯一合成 canary 验证删除后它不会出现在查询和应用控制的诊断中；若备份或用户导出在范围内，还要分别描述。 最终记录应写明应用构建、源版本、转换配置、引擎、schema、清单计数、拒绝输入、完整性结果、查询夹具、切换前后的活动索引和回滚结果。只报告实际观察到的内容。一次成功重建只验证了特定索引和源快照，不能证明检索相关性、问答质量、语言覆盖或所有功能均可离线运行。

解析器升级后，有些离线文档不再出现在搜索中

离线助手保存了本地源记录和词项索引。解析器升级后，一部分记录产生了新的规范化文本，但旧索引仍含上一版条目；同时用户已删除一个文档，而后台索引任务仍在队列中。

决策

按新解析器和源快照构建候选索引，先处理删除事件，候选通过检查前保留旧活动索引。

预期结果

搜索要么切换到一个完整版本，要么明确报告恢复中；不会混用解析器版本，也不会让已删除来源重新出现。

需要收集的证据

只有将以下证据与同一模型文件和测试运行关联起来，结论才可复核：

• RAG-01：本地检索增强流程可分为导入、分块、embedding、本地索引、检索、prompt 构造和生成，各阶段要分别验证。
• PRIVACY-01：本地推理减少了对远程推理服务的内容传输需求，但不证明应用没有其他网络请求。

任务质量需要有版本记录的语料和验收规则；流畅的单条样例不等于准确度结果。

实施流程

Record and compare the index manifest, rebuild fixtures, and query and deletion verification results, treating them as a connected set of artifacts. The note recommends capturing each item in a comparable form so reviewers can evaluate consistency across the rebuild evidence without inferring additional relationships.

1. 冻结来源和转换身份. 记录权威来源 ID、版本、解析器、规范化、分块、embedding 模型（如使用）、索引引擎、schema 和构建 ID，并定义构建期间如何保持源快照一致。
2. 建立索引前分类失败. 区分不可读或授权撤销、抽取结果为空、格式不支持、删除事件和转换错误。将每种结果写入清单，不能统一记为成功的空记录。
3. 构建版本化候选. 按所选引擎支持的隔离索引或事务策略写入。追踪预期、已索引、跳过和失败来源，并且未完成时不标成活动版本。
4. 核查完整性、覆盖和来源. 只使用准确引擎及版本文档支持的检查或修复方法。将来源 ID、版本、位置、词项或向量夹具、删除 canary 和代表性查询与权威记录比较。
5. 明确激活或回滚. 所有门禁通过后再切换活动索引。失败时保留旧的兼容索引或显示不可用状态；重放变化或基于新快照重建，不拼接不兼容版本。
6. 测试删除与隐私路径. 索引任务排队时删除合成来源，等待任务结束并按需再重建，确认相关分块、向量、片段、日志和搜索结果都不会回来。

验收标准

• 每次索引构建都绑定源快照以及显式的转换、引擎和 schema 版本。
• 部分、失败或混合版本的候选不会被报告为活动或完成。
• 删除来源后，排队任务和后续重建不会恢复应用拥有的派生内容，也不会让唯一 canary 再次可检索。

决策对照表

需要避免的失败模式

• 仅比较索引行数，不检查来源 ID、文档版本、分块版本和位置映射。
• 把 SQLite FTS5 的 repair 命令直接套用到 Room FTS4、向量存储或其他数据库。

When rebuilding, avoid mixing embedding revisions within one index and do not serve partial rebuilds as complete. The note restricts release language to what is captured in the recorded artifacts and bounds discussion to the RAG-01 and PRIVACY-01 fact cards.

最小复现记录

发布检查表

• ☐ 主要搜索问题已回答，且没有未经支持的数字。
• ☐ 所有模型文件和运行时版本均已固定。
• ☐ 代表性任务和失败处理策略均有说明。
• ☐ 生命周期、取消、清理和回退均已测试。
• ☐ 用户内容与网络边界均有说明。
• ☐ 结论只适用于被记录的配置。
• ☐ 新增测试结果时链接到原始方法或证据。

来源与相关证据

• Android Developers：用 Room 实体定义数据并支持 FTS
• SQLite：FTS5 外部内容、一致性与 rebuild 命令
• Android Developers：迁移 Room 数据库版本

中文部署与排错专题见。奇连 AI 端侧专题。

常见问题