minAlphaFold2 检查点与断点续训指南:掌握 resume 机制与随机状态保存,让训练实验完整可复现

原创2026-11-09 09:58:381,934 阅读

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 生成器状态

minAlphaFold2 项目概览图,展示 AlphaFold2 纯 PyTorch 重实现的架构与检查点续训背景

检查点安全写入

保存流程是"先写临时文件 → flush → fsync → 原子替换"(trainer.py 原子写入),即使训练中途断电,也不会留下半截损坏的 .pt 文件。写入前还会调用 require_finite_state 检查所有张量数值有限,防止 NaN/Inf 污染后续训练。

恢复逻辑:从哪个位置继续?

加载由 load_checkpoint_for_resume 完成,恢复点固定为最后一个完整 epoch 的边界:epoch 计数 +1 后从下一个 epoch 开始。如果中断发生在 epoch 中间,该 epoch 会整体重跑。这个"宁可重跑、不可错位"的设计,换来的是数据采样序列与样本数学习率调度的完全对齐。

2️⃣ 断点续训:如何一条命令接着跑

AlphaFold2 模型结构示意图,展示 minAlphaFold2 检查点续训所服务的 Evoformer 与 Structure Module 全流程

最快上手:三步完成续训

第一步:正常启动训练(新运行拒绝非空的输出目录,防止覆盖历史结果):

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️⃣ 随机状态保存:实验可复现性的底层保障

可复现性来自三个环环相扣的机制:

  1. 初始种子:set_seed 用 --seed(默认 0)同时设定 Python、NumPy、Torch CPU/CUDA 的种子,控制模型初始权重与 DataLoader 的 shuffle 顺序。
  2. 过程状态落盘:每个 epoch 结束时,_rng_state 捕获当前全部随机状态写入检查点,恢复时由 _restore_rng 精确还原。注意它连两个 DataLoader 的 Generator 状态一起保存——这意味着续训后的数据打乱顺序与原始运行逐位一致,样本数学习率调度(如 6.4M 样本处的一次性 ×0.95 衰减)才能精确对齐。
  3. 合约校验兜底: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。

登录后查看全文
minAlphaFold2