建立索引
并测试召回

先理解今天的原理

索引把片段转换成可搜索表示。用户问题经过同样处理后，系统按相似度或关键词找出候选片段。候选片段错误，模型很难生成可靠答案。

召回测试需要提前标出每个问题的正确来源。观察前 K 个结果、排名、过滤条件和缺失原因，才能判断应该修资料、切分、查询还是索引配置。

为什么今天要做这件事

1. 先测召回可以定位知识库最基础的证据链。
2. 固定测试集让每次修改能够比较。
3. 正确来源标签可以避免只凭结果“看起来相关”判断。

开始前检查

这是第 04 天。先完成下面的检查，再开始操作。缺少关键材料时，先补材料，不要让 Agent 猜。

1. 片段目录和元数据已经完成。
2. 准备十个真实问题并标注正确 source_id 与 chunk_id。
3. 选择符合资料隐私要求的检索工具。

一步一步完成

第 1 步：创建索引并记录工具、模型、参数和时间

这一步会生成后续课程继续使用的材料。文件名、保存位置和内容边界需要写清楚，让第二天重新打开项目时仍然知道它的用途。

1. 创建索引并记录工具、模型、参数和时间。
2. 打开新材料逐项检查，删除示例占位内容，补上本次真实信息。
3. 记录保存路径，并确认关闭页面或重新打开项目后仍能找到。
4. 对照今天的目标检查这一项，发现偏差时先处理偏差，再进入第 2 步。

完成这一步后，你应该看到：创建索引并记录工具、模型、参数和时间，产物内容完整并且可以重新找到。

第 2 步：逐题检索前五个候选片段

先把这一项单独完成，再继续后面的动作。操作过程要留下可以检查的材料，方便发现偏差时回到当前步骤。

1. 逐题检索前五个候选片段。
2. 记录输入、实际动作和得到的结果。
3. 对照今日目标检查；结果不一致时，先保存证据并处理当前问题。
4. 对照今天的目标检查这一项，发现偏差时先处理偏差，再进入第 3 步。

完成这一步后，你应该看到：逐题检索前五个候选片段，过程与结果均有可复查证据。

第 3 步：记录正确片段是否出现及所在排名

这一步会生成后续课程继续使用的材料。文件名、保存位置和内容边界需要写清楚，让第二天重新打开项目时仍然知道它的用途。

1. 记录正确片段是否出现及所在排名。
2. 打开新材料逐项检查，删除示例占位内容，补上本次真实信息。
3. 记录保存路径，并确认关闭页面或重新打开项目后仍能找到。
4. 对照今天的目标检查这一项，发现偏差时先处理偏差，再进入第 4 步。

完成这一步后，你应该看到：记录正确片段是否出现及所在排名，产物内容完整并且可以重新找到。

第 4 步：分析失败属于资料缺失、切分、查询或过滤问题

先把这一项单独完成，再继续后面的动作。操作过程要留下可以检查的材料，方便发现偏差时回到当前步骤。

1. 分析失败属于资料缺失、切分、查询或过滤问题。
2. 记录输入、实际动作和得到的结果。
3. 对照今日目标检查；结果不一致时，先保存证据并处理当前问题。
4. 对照今天的目标检查这一项，发现偏差时先处理偏差，再进入第 5 步。

完成这一步后，你应该看到：分析失败属于资料缺失、切分、查询或过滤问题，过程与结果均有可复查证据。

第 5 步：一次只调整一个因素，再运行同一测试集

这一步会让环境或项目发生变化。开始前先保存当前状态，执行时记录真实入口、参数和输出，出现异常就停在当前步骤排查。

1. 一次只调整一个因素，再运行同一测试集。
2. 保存执行命令、输入参数、开始前状态和结束后的输出。
3. 重新运行一次最小检查，确认结果可以稳定复现。
4. 对照今天的目标完成最后检查，确认所有证据已经保存。

完成这一步后，你应该看到：一次只调整一个因素，再运行同一测试集，执行过程与可复现结果已经记录。

question_id,question,expected_chunk,top_k,found,rank,notes
Q01,如何启动本地项目,DOC-001-C03,5,yes,1,
Q02,启动失败先检查什么,DOC-001-C04,5,no,,检查切分与查询词

索引记录：
工具=<名称与版本>
表示模型=<名称与版本>
参数=<top_k、过滤条件>
创建时间=2026-08-19

# 第 04 天操作记录

## 今天使用的入口与版本

## 实际完成的步骤
- [ ] 1. 创建索引并记录工具、模型、参数和时间。
- [ ] 2. 逐题检索前五个候选片段。
- [ ] 3. 记录正确片段是否出现及所在排名。
- [ ] 4. 分析失败属于资料缺失、切分、查询或过滤问题。
- [ ] 5. 一次只调整一个因素，再运行同一测试集。

## 保存的证据
- 文件：
- 截图：
- 命令或测试结果：

## 与文章不同的地方

## 下一步

这次真实操作得到了什么

1. Harness 发布状态与人工批准问题都命中正确原件，分数为 5；低于 2 分时拒答。

本次实际结果：中文检索不再使用容易造成误命中的单个汉字。

正确结果长什么样

完成操作后，用结果来判断今天是否学会。页面能打开或命令能运行，只能说明流程启动了；下面这些证据同时出现，今天才算完成。

1. 十个问题都有预期片段和实际前五结果。
2. 能区分资料、切分、查询和过滤造成的失败。
3. 索引工具、模型、参数和创建时间有记录。
4. 调整后使用同一测试集重新运行并保留对比。

常见错误与恢复

留给明天的材料

结束前把今天的关键结果保存到项目目录。下一天会直接使用这些材料，保存清楚可以减少重复说明和错误猜测。

1. 可用索引。
2. 十题召回测试集与结果。
3. 索引配置和失败分类记录。