设置训练流程
训练流程决定先学习什么、后优化什么，以及如何复用前一阶段的模型。只有预测需求时，训练世界模型即可；需要改进控制动作时，在世界模型之后增加策略或控制器阶段。温控任务还可以先学习基础动态，再延长推演时间，检查模型能否描述持续升温与冷却过程。
选择训练流程
下面的 training 块接在任务图与数据配置之后，先训练倒立摆世界模型，再训练 PPO 策略：
training:
device: auto
seed: 42
log_dir: logs
stages:
- name: venv
algorithm: venv.bc
hyperparameters:
epochs: 200
optimizer: {lr: 0.0003}
- name: policy
algorithm: policy.ppo
inherit_from: venv
hyperparameters:
policy_nodes: [actions]
epochs: 300
rollout_horizon: 20
reward: {path: reward.py, function: get_reward}| 您希望得到什么 | 如何安排阶段 |
|---|---|
| 预测设备响应或模拟状态变化 | 一个 venv.* 阶段 |
| 根据业务奖励优化动作 | 世界模型之后增加 policy.ppo 或 policy.sac |
| 模仿历史操作 | 世界模型之后增加 policy.bc |
| 使用可解释的控制律或在线规划 | 世界模型之后增加 controller.* |
| 逐步学习更长时间的动态 | 多个世界模型阶段依次继承，再训练策略 |
stages 按声明顺序执行。阶段的 name 用于依赖引用与结果目录命名，algorithm 必须填写完整算法键。算法适用场景见选择建模与控制算法。
设置参数与计算资源
确定优化目标
| 需要改善什么 | 配置入口 | 怎样结合业务设置 |
|---|---|---|
| 哪些状态需要准确预测 | BC 的 venv_target_nodes | 选择需要监督的环境节点，增量图中区分 delta 与 next |
| 关键节点不能被其他量掩盖 | node_weights、aggregation_mode | 根据节点重要性和维度聚合方式设置有限非负权重 |
| 点预测误差 | BC 的 loss: mse 或 mae | MSE 更强调大残差；同时核对原始单位误差 |
| 概率预测 | 支持分布输出的 BC loss: nll | 检查分布与尺度，并用预测误差验证实际用途 |
| 持续多步预测 | BC 的 sequence_train | 按业务响应时间设置长度，检查闭环误差 |
| 跟踪目标、节省能耗或平滑动作 | 策略与控制器的 reward | 用实际可获得的状态和动作定义业务收益 |
训练目标与 validation.selection 可以不同：前者决定如何更新模型，后者决定保留哪个模型。比如用 NLL 训练温度分布，同时按多步温度 MAE 选模。
调整轮数、学习率与批量
hyperparameters 只填写需要调整的参数，通常从 epochs、optimizer.lr 和 batch_size 开始。其他参数由算法默认值补齐，未知字段会报错。REVIVE-P 的监督参数位于 hyperparameters.bc，对抗参数位于 hyperparameters.adversarial，其 epochs 位于 hyperparameters 下。
revive validate --config config.yaml --train-data train.npz --show-defaults用生效配置确认修改的位置。不同算法支持不同的损失和参数，不能直接把 BC 的 loss 写到 PPO 或 SAC 中；当前不提供任意 callable 节点损失或通用专家约束配置。具体字段见算法参数说明。
选择设备与随机种子
training.device | 使用方式 |
|---|---|
auto（默认） | 按 NPU、CUDA、CPU 顺序选择可用设备 |
cpu | 使用 CPU |
cuda / cuda:N | 使用指定 CUDA 设备；不可用时报错 |
npu / npu:N | 使用指定 Ascend NPU 设备；不可用时报错 |
固定 training.seed 可以比较相同随机条件下的参数改动；数据划分由 data.split_seed 单独控制。默认启用严格确定性，重复性条件见评估与选择模型。CPU 线程数可通过 training.cpu_threads 设置。
双环境训练还需要按分支安排资源，training.device 仍是主设备。单卡可以依次执行两套模型，多卡与分支资源设置见双环境训练。
让预测起点符合部署条件
有些水处理任务在训练数据中有物理状态标签，但部署时只能获取估计状态。BC 的 sequence_train.initial_state_override 可在直接序列监督中设置 {state: plant_state, source: rollout_initial_state}，在预测起点使用估计状态，监督标签保持原样，rollout 验证采用同一初态。
该功能要求序列训练开启、train_mode: rollout、direct_sequence_supervision: true，监督节点对应 builtin.delta_add 的增量，并设置 objective.displacement.dt: 1；不能同时开启 state_noise。初态误差会纳入累计状态损失。
source 必须由当前或历史可见遥测产生，并保留估计器及数据划分来源；不能借助 observed_keys 持续注入未来估计值。具体业务配置见源码中的 examples/chlorination/control_ready/README.md。能够直接获得部署初态的任务可保持默认 null。
连接阶段与复用模型
继承前一阶段的选中模型
inherit_from 填写前置阶段名称。世界模型接续训练时继承权重，并按当前阶段设置创建优化器与训练状态；策略与控制器阶段则使用已选中的世界模型，其环境参数保持冻结。前置模型需要通过验证、选模和导出，后续阶段才能使用。
同一运行已经完成环境训练时，可以用 env_record_id 引用 <log_dir>/<run_id>/venv/<record>/model/env.pt。它与 inherit_from 二选一，不能用它任意导入其他 run 的权重。
复用时保持原 run_id、log_dir、图和数据身份。修改已有配置快照或覆盖记录涉及显式覆盖；日常参数对比应新建运行。阶段选择、覆盖与恢复的区别见管理训练任务。
逐步延长训练推演
以下 stages 放在 training 下，展示从单步到 4 步、16 步的课程：
stages:
- name: h1
algorithm: venv.bc
hyperparameters:
batch_size: 256
sequence_train: {enabled: false}
- name: h4
algorithm: venv.bc
inherit_from: h1
hyperparameters:
batch_size: 128
sequence_train: {enabled: true, train_mode: rollout, horizon: 4}
- name: h16
algorithm: venv.bc
inherit_from: h4
hyperparameters:
batch_size: 64
sequence_train: {enabled: true, train_mode: rollout, horizon: 16}较长训练展开通常需要更多内存，可以同时降低批量。每个阶段有独立的模型记录与选模结果；比较课程效果时，保持验证推演长度一致。运行级 models/env.pt 由选模与提升规则决定，不保证是最后一个阶段。完整任务见无人机建模。
在不同图之间继承
训练图只需要读取历史动作，控制图则可能需要增加动作网络。这类任务可以在顶层用 graphs 定义命名图，再由阶段的 graph 选择。跨图继承必须声明 migration 并通过兼容性预检。
examples/thermal_workflows/heterogeneous.yaml 将环境图和控制图分别命名为 environment、control。后者新增 heater 策略节点，通过 inherit_from: venv 和 migration: {norm: strict, mode: by_reference} 复用环境。运行后查看 migration_report.json：env_reference 表示引用上游环境执行，新增动作节点需要初始化；failed 非空时不能继续采用该迁移结果。
保留部分节点，只更新其余节点
例如温控模型中的加热器响应已经足够准确，希望继续训练温度动态时，可设置 hyperparameters.frozen_nodes: [heat]。源码的 examples/thermal_workflows/freeze.yaml 先训练 venv，再在同一设备 A 的数据上继承并冻结有权重的 heat 子网。
冻结节点不会加入优化器，相关缓冲状态也保持冻结；应核对冻结节点参数不变、其余目标节点可以更新。固定公式没有可训练参数，无需用冻结功能处理。
冻结并不会使两台设备的数据和归一化自动兼容。阶段继承仍需核对单位、输入布局、归一化和模型结构；当前训练数据源为 run 级，不能在同一运行中为每个阶段另配设备数据。
保存模型与日志
output:
checkpoint_policy: best_only
tensorboard: true
metrics_backend: final
plotting:
enabled: true
trend: true
interval: 10
external_inputs: false
onnx:
enabled: true
required: true
opset: 17
io_space: raw
validate: parity
export_dtype: keep
atol: 1.0e-5
rtol: 1.0e-4找到选中模型和恢复状态
training.log_dir 是运行输出根目录，run_id 区分每次运行。默认 checkpoint_policy: best_only 为各阶段和分支保存最优模型及同轮次的完整续训状态。
| 文件或目录 | 用途 |
|---|---|
config.source.yaml、config.resolved.yaml | 用户配置与实际生效配置 |
阶段 checkpoints/best.pt | 选中轮次的模型权重 |
阶段 checkpoints/best_train_state.pt | 包含优化器、随机状态与训练进度的恢复文件 |
运行级 models/env.pt、models/policy.pt | 默认推理入口，以实际完成的阶段为准 |
默认不额外保存最后一轮。中断后用 --resume best 恢复到最优轮次，该轮之后未保存的训练需要重新执行。需要周期恢复点时，查看训练任务的保存设置。
metrics_backend: final 在阶段结束时导出 CSV/JSON；snapshots 每轮重写指标文件；tensorboard 追加事件并保存紧凑摘要，需要启用并安装 TensorBoard。关闭 plotting.enabled 可减少绘图开销，保留指标与模型保存；只关闭中间趋势图可设置 plotting.trend: false。
准备部署文件
标准训练需要导出并验证 ONNX，enabled、required 保持 true。io_space: raw 使部署方直接使用物理量；选择 processed 时，调用方必须复用对应归一化规则和统计量。
validate: parity 检查 ONNX 与 PyTorch 数值一致性，runtime 检查能否在 ONNX Runtime 中执行。MPC 的候选筛选可能因微小数值差异改变动作，使用 runtime 并在部署环境检验控制效果。导出失败的记录不能成为运行级模型，完整部署步骤见使用与部署模型。
启动训练
从任务目录执行：
revive validate --config config.yaml --train-data train.npz --show-defaults
revive train --config config.yaml --train-data train.npz --run-id experiment-001 --log-dir logs先检查阶段名称、依赖、生效参数和数据范围，再启动正式训练。每次参数对比使用新的 run_id；命令行的运行参数优先级见查看生效参数。
首次接入可以添加 --profile smoke 缩短流程检查时间。smoke 会缩减训练规模，用于确认数据、训练、验证与导出能够连接完成；模型效果使用正式配置评估。