数据与恢复¶
数据目录是什么¶
这个项目把一次运行的所有核心结果都收进同一个 run 目录：
data/runs/<run_id>/
这不是为了目录好看，而是为了让训练、恢复、回放和统计分析共享同一组输入。
为什么一定要集中存放¶
如果 checkpoint、棋谱和 metrics 分散在不同地方，会有三个直接问题：
- 无法确定某个模型权重对应哪批训练数据。
- 恢复时很难准确找到最近一次完整状态。
- 工具渲染和离线分析容易读错文件。
run 目录里通常会有什么¶
如果你是第一次看这个目录，可以先把它理解成“一次运行的总档案袋”。和这次运行有关的核心东西，都应该能在里面找到。
checkpoint¶
它是什么： 训练状态快照，至少包含模型参数以及恢复训练所需的关键状态。
为什么需要： 长期运行不可能假设进程永远不掉。checkpoint 是恢复训练的基础输入。
输入输出是什么：
- 输入：当前模型参数、优化器状态、scheduler 状态、训练步数、随机种子状态。
- 输出：可读回的
latest.pt、previous.pt、best.pt。
怎样判断结果是否正常：
- 新 checkpoint 写入后可以重新加载。
- 三槽轮转关系清楚，不会无限增长。
如果你只想先抓住最重要的一点：checkpoint 不是普通备份，它是“让训练从这里继续”的恢复入口。
棋谱与索引¶
它是什么： 自博弈对局记录和定位这些记录的索引。
为什么需要： 训练需要原始对局数据，回放和抽查也需要能定位到具体某一盘。
输入输出是什么：
- 输入：每步行动、分数、提子、终局原因、配置关联信息。
- 输出：压缩棋谱分片和
games.index.sqlite。
怎样判断结果是否正常：
- 索引能定位回对应分片和行号。
- 压缩记录可以被读取，而不是只写进去不能用。
这里的“索引”可以先理解成一本目录。它不保存整盘棋的全部内容，而是告诉你“第几盘棋具体存在哪个文件、哪一行”。
metrics¶
它是什么： 训练和运行过程中的统计指标。
为什么需要： 没有 metrics，后面只能靠猜测判断训练是否健康。
输入输出是什么：
- 输入：训练 step、loss、worker 数量、硬件策略、吞吐量等运行指标。
- 输出：可分析的结构化指标文件。
怎样判断结果是否正常：
- 指标持续写出，而不是只在程序退出时一次性吐出来。
- 指标字段和配置、checkpoint、运行状态能对上。
如果你只看到一个最终总结，没有过程中的连续指标，后面就很难查出训练是在什么时候开始出问题的。
恢复流程在本项目里意味着什么¶
恢复不是单纯“把模型文件再读回来”。它应该至少恢复：
- 模型权重
- 优化器和调度器状态
- 当前训练步数
- 已生成的游戏计数
- 对应 run 的配置快照引用
如果这些信息缺一大块，恢复后的训练就可能在表面上继续，实际上已经偏离原运行上下文。
读者怎么判断恢复链路正常¶
可以用下面的判断方式：
- 进程中断后能从最近 checkpoint 接着跑。
- 恢复后生成的 metrics 和 step 编号是连续的。
- 恢复流程不会偷偷换模型路线或改配置语义。
一个很实际的判断方法是：
- 先让训练跑一段时间，确认已经写出 checkpoint 和 metrics。
- 人为中断进程。
- 再次启动后，看 step 是否继续增长，而不是从 0 或很早的数字重新开始。