minAlphaFold2 检查点与断点续训指南:掌握 resume 机制与随机状态保存,让训练实验完整可复现
minAlphaFold2 检查点与断点续训指南:掌握 resume 机制与随机状态保存,让训练实验完整可复现
minAlphaFold2 是一个用约 3000 行纯 PyTorch 重实现 AlphaFold2 的教学项目,内置完整的检查点与断点续训(resume)能力:训练每完成一个 epoch 就自动落盘模型权重、优化器与 EMA 状态,训练中断后一条命令即可从断点继续,随机状态完整保存确保实验可复现。本文带你吃透 minAlphaFold2 的检查点机制、续训方法与可复现性设计。
1️⃣ 检查点机制:一个 .pt 文件里存了什么
minAlphaFold2 的每个检查点都是"全量状态",远不止模型权重。对照 trainer.py 中的 save_checkpoint:
| 内容 | 作用 |
|---|---|
run_id |
运行唯一标识,续训时校验是否属于同一次实验 |
epoch / global_step / global_samples |
训练计数器,保证样本级学习率调度接得上 |
model_state_dict |
当前模型权重 |
optimizer_state_dict |
Adam 优化器动量状态,避免续训"重新热身" |
ema_state_dict |
EMA 影子参数(§1.11.7),用于验证与选点 |
best_val_loss + history |
最佳验证损失与各 epoch 指标历史 |
| 配置快照 | 模型、数据、训练三份配置 |
resume_contract |
代码/配置/数据合约指纹(见下文) |
rng_state |
Python / NumPy / Torch / CUDA / 两个 DataLoader 生成器状态 |
检查点安全写入
保存流程是"先写临时文件 → flush → fsync → 原子替换"(trainer.py 原子写入),即使训练中途断电,也不会留下半截损坏的 .pt 文件。写入前还会调用 require_finite_state 检查所有张量数值有限,防止 NaN/Inf 污染后续训练。
恢复逻辑:从哪个位置继续?
加载由 load_checkpoint_for_resume 完成,恢复点固定为最后一个完整 epoch 的边界:epoch 计数 +1 后从下一个 epoch 开始。如果中断发生在 epoch 中间,该 epoch 会整体重跑。这个"宁可重跑、不可错位"的设计,换来的是数据采样序列与样本数学习率调度的完全对齐。
2️⃣ 断点续训:如何一条命令接着跑
最快上手:三步完成续训
第一步:正常启动训练(新运行拒绝非空的输出目录,防止覆盖历史结果):
python scripts/train_af2.py --stage initial \
--model-config tiny \
--checkpoint-dir checkpoints/run-01
第二步:训练中断后,加 --resume 指向最新检查点:
python scripts/train_af2.py --stage initial \
--model-config tiny \
--checkpoint-dir checkpoints/run-01 \
--resume checkpoints/run-01/initial_latest.pt
第三步:验证输出——fit 函数 会打印恢复信息:
[resume] epoch=12 global_step=960 global_samples=11520
看到 epoch / global_step / global_samples 与中断前一致,说明状态已完整恢复。
云端自动续训:同一命令反复执行
在 Modal GPU 上,modal_train_af2.py 提供了 auto-resume 钩子:每次容器启动时自动检查 <checkpoint-dir>/<stage>_latest.pt 是否存在,存在则追加 --resume,不存在则全新开始。于是一整天 24 小时的容器超时被切断后,只需反复执行同一条命令即可:
modal run scripts/modal_train_af2.py --stage initial
首次运行从零开始,之后每次都从共享 Volume 上的最新检查点无缝接管。
续训前的合约校验
--resume 不是"加载权重就能跑"。fit 函数 会先把当前环境的"合约"与检查点内保存的 resume_contract(_resume_contract 生成)逐一对比,任何一项不符都会报错并建议改用 --init-from 开新实验。合约覆盖五类内容:
| 校验对象 | 内容 |
|---|---|
| 模型配置 | ModelConfig 全部字段 |
| 数据配置 | 裁剪尺寸、MSA 深度等 + manifest 文件 SHA-256 |
| 训练配置 | 学习率、batch、EMA 等超参 |
| 数据缓存 | 训练/验证集中每条链 NPZ 文件的 SHA-256 |
| 代码版本 | minalphafold/ 目录下所有 .py 源文件哈希 |
这个设计的目的非常直接:防止你在改过代码或数据后,"以为在续训"其实已在跑一个不同的实验。
3️⃣ 别混淆:--resume 与 --init-from 是两回事
minAlphaFold2 把"继续"和"继承"严格分开(train_af2.py 参数解析):
--resume |
--init-from |
|
|---|---|---|
| 用途 | 同阶段断点续训 | 跨阶段微调(如 initial → finetune) |
| 恢复内容 | 模型 + 优化器 + EMA + 计数器 + RNG | 仅模型权重 |
| 优化器 / 计数器 | 原样恢复 | 全新(fresh optimizer / counters) |
| 合约校验 | 必须完全匹配 | 无 |
论文的两阶段训练正是用 --init-from 衔接的:finetune 阶段从 initial 阶段检查点加载权重,但学习率减半、裁剪尺寸从 256 提升到 384、打开结构违规损失(详见 training_alphafold2.toml):
python scripts/train_af2.py --stage finetune \
--checkpoint-dir checkpoints/af2 \
--init-from checkpoints/af2/initial_latest.pt
两者互斥,同时指定会直接报错(validate_training_config)。一句话记忆:同一个实验断了用 --resume;换超参/进下一阶段用 --init-from 开新目录。
4️⃣ 随机状态保存:实验可复现性的底层保障
可复现性来自三个环环相扣的机制:
- 初始种子:set_seed 用
--seed(默认 0)同时设定 Python、NumPy、Torch CPU/CUDA 的种子,控制模型初始权重与 DataLoader 的 shuffle 顺序。 - 过程状态落盘:每个 epoch 结束时,_rng_state 捕获当前全部随机状态写入检查点,恢复时由 _restore_rng 精确还原。注意它连两个 DataLoader 的
Generator状态一起保存——这意味着续训后的数据打乱顺序与原始运行逐位一致,样本数学习率调度(如 6.4M 样本处的一次性 ×0.95 衰减)才能精确对齐。 - 合约校验兜底:RNG 状态保证"过程"可复现,合约校验保证"代码与数据没变",两者缺一不可。
三者叠加的效果是:一次中断的训练,续训后能逐位复现原始训练的轨迹,而不会因为随机状态漂移而"偷偷"跑成另一个实验。
5️⃣ 常见问题排查
| 报错 | 原因与处理 |
|---|---|
FileExistsError: Checkpoint output already exists |
新运行拒绝非空输出目录。要么 --resume 续训,要么换新的 --checkpoint-dir(见 fit 函数检查) |
ValueError: Resume checkpoint does not match ... |
代码、配置或数据与检查点不一致。这是"实验已变",应使用 --init-from 以新实验方式继续 |
--init-from is required when --stage=finetune ... |
微调阶段未指定权重来源,补上 --init-from <initial_latest.pt> |
| 恢复后进度看起来"回退"了 | 正常现象:恢复点永远是上一个完整 epoch 边界,中断的 epoch 会重跑 |
总结
- 检查点 = 模型 + 优化器 + EMA + 计数器 + 配置 + 合约 + RNG 状态,共 10 类信息,缺一不可;
- 续训命令只需加
--resume <xxx_latest.pt>,恢复点固定为最后一个完整 epoch 边界; --resume(精确续训)与--init-from(跨阶段微调)职责不同且互斥;- 合约校验失败 ≠ 故障,它是在提醒你"这已经是一个新实验";
- RNG 状态 + 合约校验的组合,是 minAlphaFold2 实验可复现性的双保险。
想亲手验证这些行为,可以看测试用例 test_fit_resumes_global_step_and_samples(覆盖续训计数器与 RNG 恢复);完整实现集中在 minalphafold/trainer.py,训练入口为 scripts/train_af2.py。

