管理训练任务

训练进行中，您可以查看进度、保留需要的记录，并根据运行状态决定下一步。中断后继续原任务、增加训练轮数、修改配置重新试验，使用的操作不同：

当前情况	应执行什么
正在训练，想查看进度和指标	查看日志与 TensorBoard
任务中断，原定训练尚未完成	从完整训练检查点恢复
已完成训练，希望增加轮数	确认算法满足条件后使用轮数扩展
修改数据、算法或超参数	使用新的 run ID 重新训练
需要重新执行已有同名记录	明确需要覆盖的内容后使用 --force

查看训练进度

先根据启动命令中的 --log-dir 与 --run-id 找到运行目录。以下命令在任务目录执行，repro 替换为实际运行名称：

tail -f logs/repro/venv/venv/train.log

上例查看名为 venv 的世界模型阶段；策略日志通常位于 policy/<阶段名>/train.log。在相应日志中查看轮次、验证结果和报错位置。启用 output.tensorboard: true 时，可以打开曲线：

tensorboard --logdir logs/repro

在终端提示的地址查看训练与验证指标。训练损失下降时，也要结合验证误差或控制回报判断效果。完整报告读法见分析训练结果。

同一任务可能包含多个阶段，各阶段分别保留记录。运行级 models/ 保存当前选中的模型，具体保存规则见设置训练流程。

恢复中断训练

在线用户恢复同一任务时保留原 access key、配置、数据路径、运行 ID 和日志目录，复用该任务已有的授权申请。 使用离线许可证时，确认文件在当前环境仍可读取且有效。授权问题见故障排查。

保持原配置、数据、运行名称及日志目录一致，然后执行：

revive train \
  --config config.yaml \
  --run-id repro \
  --log-dir logs \
  --resume best

如果存在多个阶段、需要明确恢复某一条记录，可以填写检查点路径：

revive train \
  --config config.yaml \
  --run-id repro \
  --log-dir logs \
  --resume logs/repro/venv/venv/checkpoints/best_train_state.pt

选择能够恢复训练的文件

默认 output.checkpoint_policy: best_only 保存最优轮次的完整训练状态。恢复从这个轮次完成后继续，之后尚未保存的训练会重新执行。例如中断时已到第 100 轮、最优状态在第 80 轮，就从第 80 轮之后恢复。

文件	用途
checkpoints/best_train_state.pt	恢复模型、优化器、随机状态及训练进度
checkpoints/best.pt	选中模型的权重
models/env.pt、models/policy.pt	模型推理与部署

显式采用 checkpoint_policy: legacy 的运行还可使用 --resume latest。默认 best_only 不保存独立的 latest 文件。支持的记录选择方式还包括 run/record 和 run/domain/record；存在多个匹配时需指定完整路径。

保持数据与配置一致

恢复同一次训练需要原来的软件与依赖、数据、图结构、生效配置、验证设置和上游模型。修改学习率、数据划分或选模规则后，应作为新的试验运行。

遇到 identity mismatch 时，按报错指出的项目检查原记录与当前输入。以下十二项用于定位差异：

检查对象	错误信息中的字段
运行、记录和阶段	run_id、record_id、stage_index、stage_name、domain、algorithm_key
图与数据	graph_signature、data_fingerprint
参数与默认资源	config_fingerprint、defaults_fingerprint
选模与上游依赖	selection_signature、dependency

算法内部训练状态版本也需匹配。使用门控正则的 Hybrid BC 时，检查点还需要匹配的 bc_auxiliary_version；恢复时保留原软件环境和训练目标。具体处理见续训故障排查。

延长训练轮数

原定训练已经完成，希望增加轮数时，可以从已选中的检查点创建一个新运行，保留原实验。当前入口适用于无训练 phases、固定学习率的单阶段 venv.bc，学习率调度需为 optimizer.scheduler: none。

追加训练轮数目前需要离线许可证。普通中断续训仍按上面的恢复流程执行。

revive train \
  --config original.yaml \
  --extend-from logs/parent/venv/venv/checkpoints/best_train_state.pt \
  --additional-epochs 20 \
  --run-id extended-001 \
  --log-dir logs

original.yaml 使用父实验未修改的配置，数据和种子沿用原实验，新的 run ID 必须未被使用。新增轮数从所选检查点的下一轮开始计算，模型、优化器、随机状态与选模进度一起继承；父实验的最佳模型仍参与候选选择。

条件	使用要求
父实验	已完成预定轮数
算法和结构	单阶段 BC、无 phases、固定学习率
数据与其他参数	与父实验一致
运行方式	与 --resume、--force 互斥；不适用于策略、搜索或 profile 运行
连续扩展	当前不支持对扩展后的运行再次扩展

新运行中断后，使用子记录中的 config.source.yaml 和完整训练检查点执行普通恢复。恢复训练时还需保持原加速器的可见设备设置，以便还原随机状态。

温控模型的操作示例

以下命令从 SDK 根目录执行。先生成示例数据并完成一次温控 BC 训练：

python examples/thermal_workflows/prepare_data.py
revive train --config examples/thermal_workflows/config.yaml --run-id thermal_model

保持配置和数据不变，增加一轮训练：

revive train --config examples/thermal_workflows/config.yaml \
  --extend-from examples/thermal_workflows/logs/thermal_model/venv/venv/checkpoints/best_train_state.pt \
  --additional-epochs 1 --run-id thermal_extended --log-dir examples/thermal_workflows/logs

thermal_extended 需要使用新的名称。比较前后选中模型的误差，检查增加训练是否带来实际收益。

调整配置重新训练

修改数据、学习率或模型结构后，为新方案使用独立的运行名称：

revive validate --config candidate.yaml --train-data train.npz --show-defaults
revive train --config candidate.yaml --train-data train.npz --run-id candidate-001 --log-dir logs

保留原结果用于对照，固定评价条件后比较选中模型，方法见比较实验结果。需要接续世界模型权重或逐步增加训练长度时，可使用阶段继承与课程训练。

只有确定要覆盖已有同名记录时才添加 --force。它会处理本次冲突记录，并重建受影响的运行级模型入口和报告；与 --resume 互斥。运行锁会阻止覆盖正在使用的记录。覆盖前先保存需要部署、恢复或比较的文件。

管理模型与日志

按后续用途保存文件

后续用途	需要保留什么
使用模型	完整 models/ 目录、需要的自定义组件与依赖环境
恢复训练	完整运行目录、训练检查点、配置、原数据及软件环境
比较实验	选中模型、报告、指标、配置和评价数据来源

复制 ONNX 时应包含 .onnx_generations/ 等隐藏目录，它们记录实际模型文件。具体目录结构见使用与部署模型。清理运行记录前，先确认以上文件已保存到可用位置。

设置保存频率

通常使用默认的 best_only 保留最优模型与同轮次恢复状态。长时间训练需要周期恢复点时，可以显式选择 legacy：

output:
  checkpoint_policy: legacy
  checkpoint_interval: 10
  checkpoint_seconds: 60
  archive_interval: 0
  checkpoint_mirrors: final
  tensorboard: true
  metrics_backend: tensorboard
  tensorboard_queue: 256
  tensorboard_flush_secs: 10

轮数或时间条件满足时保存 latest，时间条件在 epoch 边界检查；最佳模型改善及阶段结束也会提交。保存间隔越长，中断后可能需要重做的训练越多。checkpoint_mirrors: final 在阶段结束时生成固定名称副本，运行中通过记录清单读取已提交文件。

metrics_backend 可以选择阶段结束时导出（final）、逐轮写入（snapshots）或 TensorBoard。缓冲日志在异常退出时可能缺少尾部，以完整检查点确定可恢复的轮次。指标后端与保存方式可分别设置。

研究快照与已有记录的恢复

需要分析历史判别器时，设置 output.allow_research_snapshots: true，并为每个启用的 d_snapshots 声明正整数 max_snapshots。达到上限后停止写入；这一开关不启用固定轮次模型归档，模型与续训状态仍按 best_only 保存。

恢复已有记录时沿用其冻结的验证与输出配置。旧 resolved 配置缺少 checkpoint_policy 时按 legacy 保存规则解释，升级软件不会自动改变原记录的保存方式。精确续训以 epoch 边界为恢复点。

下表用于核对记录格式，实际恢复还需要上文的数据、配置和依赖一致：

格式字段	当前值
continuation_schema_version	2
默认资源清单的 defaults_version	1

默认资源清单的版本与各算法的默认参数版本分别记录；核对时以运行保存的完整默认资源身份为准。

设置日志语言

报错、日志和命令行帮助默认使用中文。单次使用英文可以把 --lang 放在子命令之前：

revive --lang en train --config config.yaml --train-data train.npz

整个进程使用英文时设置 REVIVE_LANG=en。Python 可调用 revive.set_language("en")，用 revive.set_language(None) 清除显式选择；优先级为显式设置、环境变量、默认中文。支持 en_US.UTF-8 等 locale 写法，非法值会提示并回到中文。

报告与初始化模板按生成时的语言保存，后续切换语言不会改写已有文件。需要查看训练结果时进入分析训练结果，模型使用见使用与部署模型。