训练模型

当您准备好数据和配置文件，并通过第 2 步的预检之后，就可以开始世界模型训练。 需要进一步训练策略时，还需定义奖励函数。REVIVE 支持按顺序完成这两个阶段； 如果任务只需要预测或仿真，也可以单独训练世界模型。

本节继续使用倒立摆示例，介绍运行检查、模型训练和结果查看。世界模型在旧版 REVIVE 文档中 称为“虚拟环境模型”，用于学习系统在当前状态和动作下的变化。

以下命令均在 examples/pendulum/ 目录下执行，训练结果保存在该目录的 logs/ 中， 与下一节的模型加载路径对应。仅使用 CPU 时，请先将 config.min.yaml 中的 training.device 设为 cpu：

cd examples/pendulum

配置中 reward.py 等相对路径以配置文件所在目录为基准。如果从仓库根目录执行训练命令， 请相应调整 --config 和 --train-data 的路径。

训练前的运行检查

运行前请完成授权配置：在线用户配置 access key， 离线用户安装有效许可证或设置 REVIVE_LICENSE。在线授权由训练命令申请；首次申请前， revive license status 提示缺少许可证不代表 access key 无效。 在线模式下，本页的短训练与正式训练使用不同的运行 ID，分别作为训练任务申请授权。

正式训练前，建议使用 --profile smoke 进行快速运行检查。该模式会减少训练轮数和采样数量， 用于检查数据读取、模型训练和导出是否正常：

revive train \
  --config config.min.yaml \
  --train-data data/pendulum.npz \
  --run-id pendulum-smoke \
  --log-dir logs \
  --profile smoke

运行检查沿用当前配置中的算法、节点、列名、动作范围、损失、奖励和优化器。 运行开始时会显示 smoke 提示，保存的配置中也会记录该模式。

运行检查的用途

smoke 生成的模型仅用于流程检查和推理验证，不用于模型效果评估或生产控制。 较少的训练轮数和采样数量会影响学习及模型选择，完整训练的稳定性和效果需要单独验证。

选择训练目标

世界模型训练

世界模型用于预测系统状态，也可以对给定的动作序列进行多步推演。仅需要这些功能时， 可以将 config.min.yaml 复制为 config.world-model.yaml，保留决策流图和变量定义， 将 training.stages 改为以下单阶段配置。CPU 环境同时保留 training.device: cpu。

以下是 training 内的配置片段：

stages:
  - {name: venv, algorithm: venv.bc}

修改完成后，从当前任务目录执行：

revive train --config config.world-model.yaml --train-data data/pendulum.npz --run-id world-model-demo --log-dir logs

训练完成后，世界模型保存在 logs/world-model-demo/models/env.pt。 用户可以在报告中查看单步和多步预测误差、模型选择记录，以及 ONNX 数值一致性验证结果。 该配置只训练世界模型，因此无需生成 policy.pt。

使用世界模型评估操作方案时，动作输入由历史数据、现有控制器或指定的操作方案提供。 如果还需要学习新的控制策略，可以使用下面的两阶段训练配置。

策略训练

策略模型根据当前状态生成动作，并通过奖励函数学习如何改善任务表现。开始策略训练前， 需要确认世界模型的适用范围，并定义奖励函数、动作物理边界和评估指标。

配套的 config.min.yaml 已配置好世界模型与策略的阶段依赖。执行下面的命令后，REVIVE 会先完成世界模型训练，再使用该模型训练策略。策略的业务效果还需要根据收益和约束指标 单独评估。

两阶段正式训练

revive train \
  --config config.min.yaml \
  --train-data data/pendulum.npz \
  --run-id pendulum-quickstart \
  --log-dir logs \
  --seed 42

该最小配置使用默认训练参数，世界模型与策略各训练 100 轮。实际耗时取决于设备和运行环境。 完成后，终端会显示各阶段的结果，例如：

--- 训练完成 ---
  venv: best_metric=0.2470, final_epoch=99
  policy: best_metric=-2.5732, final_epoch=99

--run-id 用于命名本次训练任务，全部训练结果保存在 logs/<run-id>/ 目录下。 同一任务的多个阶段共用该目录，并根据阶段依赖加载相应模型。下一节将从这里加载模型进行推理。

训练设备、训练轮数、批次大小和学习率通过 YAML 配置文件设置，训练命令不提供这些参数的 命令行覆盖选项。修改后可通过 config.resolved.yaml 查看实际生效的配置。

示例配置说明

最小配置使用默认超参数，适合作为首次训练的起点。源码案例中的 config.yaml 则采用 针对倒立摆调整过的 REVIVE-P 世界模型与 PPO 策略配置，各训练 1000 轮。 完整配置位于源码的 examples/pendulum/config.yaml，历史结果见倒立摆。 完成首次训练后，可以结合任务需要参考详细配置调整参数。

训练阶段配置

图：世界模型可以单独使用；策略阶段加载选中的世界模型，在模型中训练并验证策略。

training.stages 定义训练阶段及其执行顺序。下面的配置片段包含世界模型训练和策略训练， 其中策略阶段通过 inherit_from 指定要使用的世界模型：

training:
  stages:
  - {name: venv, algorithm: venv.bc}
  - name: policy
    algorithm: policy.ppo
    inherit_from: venv
    hyperparameters:
      reward: {path: reward.py, function: get_reward}

本例需要填写 inherit_from: venv，使策略阶段加载 venv 阶段按验证指标选中的模型。 选中模型可能来自任意一轮训练。阶段依赖和 hyperparameters 覆盖规则的详细说明， 见阶段依赖与课程训练。

用户可以在阶段配置中进一步设置算法、训练轮数、模型选择指标和多步推演参数。 例如，源码案例中的 config.yaml 使用以下世界模型阶段配置：

  - name: venv
    algorithm: venv.revive_p
    hyperparameters:
      epochs: 1000
    validation:
      selection:
        metric: val/one_step/mae
      one_step:
        force_final: true
      rollout:
        enabled: true
        horizon: 50
        interval: 10
        num_trajectories: 10

该示例使用 val/one_step/mae 选择模型，并通过 force_final: true 确保最后一轮也计算 这一指标。如果配置无法满足所选指标的计算要求，解析阶段会给出提示。

首次接入新数据时，建议先使用 venv.bc 与 policy.ppo 完成数据、决策流图、验证和导出检查， 再根据结果选择其他算法。支持的算法及其适用场景见选择建模与控制算法， 默认参数见算法参数参考。

查看训练报告

训练结束后，REVIVE 会在任务目录中生成 report.md。报告汇总各阶段的训练结果， 适合用于了解模型表现和检查训练是否完成。需要重新生成报告时，可以执行：

revive report --run logs/pendulum-quickstart

报告汇总了训练记录、指标、模型说明文件和生效配置，主要包含以下信息：

• 各阶段的指标数值；
• 模型选择依据，包括指标名称、优化方向和选中轮次；
• ONNX 与 PyTorch 的数值一致性验证结果；
• 数据标识，用于核对本次训练使用的数据。

阅读 best_metric 时，需要同时确认指标的定义及优化方向。例如，下面是该示例已有运行 记录中的“各阶段”内容，具体数值会随训练条件变化：

### venv · `venv.bc`

- 状态：**completed**
- 训练到第 99 个 epoch
- 选优指标：`val/rollout/mae`（取最小）
- 选中：第 99 个 epoch，值 0.247003

### policy · `policy.ppo`

- 状态：**completed**
- 训练到第 99 个 epoch
- 选优指标：`val/rollout/reward_mean`（取最大）
- 选中：第 4 个 epoch，值 -2.57321

在这次运行中，策略共训练 100 轮，最终导出的 policy.pt 使用指标记录中 epoch 为 4 的 检查点，因为它的验证指标最好。世界模型选中了最后一轮的检查点。是否需要增加训练轮数， 还应结合验证曲线的变化判断。

报告还列出 ONNX 验证结果和输出文件，便于查看本次训练的产物。

世界模型评估

• 单步误差（val/one_step/*）：衡量下一时刻的预测准确性。
• 多步推演误差（val/rollout/*）：衡量连续推演多个时间步后的偏差。

这两类指标需要结合查看。模型可能具有较小的单步误差，但在连续推演时逐步累积偏差， 进而影响策略训练的可靠性。

在本例的默认输出配置下，每轮指标保存在 logs/pendulum-quickstart/venv/venv/metrics/ 中， metrics.csv 每行对应一轮训练，曲线保存在同级的 plots/ 目录。查看曲线时，建议关注 误差随推演步数的变化、各关键变量的误差，以及验证误差是否仍在下降。

可接受的误差范围需要结合业务要求确定。作为初步参照，可以使用当前状态作为下一时刻的预测值， 计算这一基准的误差。如果世界模型未明显优于该基准，应先检查其是否学到了任务所需的动态变化， 再决定是否进入策略训练。用户还可以通过以下命令，根据多步预测误差获取推演步数建议：

revive suggest-rollout \
  --config config.min.yaml \
  --data data/pendulum.npz \
  --model logs/pendulum-quickstart/models/env.pt

策略模型评估

策略评估需要关注奖励、动作是否长期保持在上下限，以及状态和动作是否超出历史数据的覆盖范围。 奖励值应结合其定义，并在相同条件下与基准策略比较。例如，可以使用 policy.bc 学习历史操作， 作为 PPO 或 SAC 的对照。算法之间的适用差异见选择建模与控制算法。

上文倒立摆结果中的 -2.5732 是单步平均奖励，对应代价函数 θ² + 0.1·θ̇² + 0.001·u² 的负值，越接近 0 越好。 倒立摆提供了同一数据上详细配置的历史结果，比较时还需核对 训练参数和评估条件。

模型内评估与业务评估

世界模型的偏差可能使某些操作获得偏高的预测奖励。因此，模型内的奖励比较需要结合 世界模型的多步误差分析；策略是否改善实际业务表现，还需要独立评估。

训练结果文件

logs/pendulum-quickstart/
├── report.md                   训练报告
├── run_info.json               任务信息：run_id、git commit、各阶段记录
├── config.source.yaml          用户提供的源配置
├── config.resolved.yaml        补全默认值后的生效配置
├── metrics_summary.json        各阶段最终指标汇总
├── models/                     部署模型及说明文件
│   ├── env.pt                  世界模型
│   ├── policy.pt               策略模型
│   ├── env.onnx.json           ONNX 说明文件（模型位于 .onnx_generations/ 中）
│   └── policy.onnx.json
├── venv/venv/                  世界模型训练记录
│   ├── checkpoints/best_train_state.pt   最优轮次的完整续训状态
│   ├── metrics/  plots/  tensorboard/  train.log
│   └── record_info.json        阶段状态与模型选择结果
└── policy/policy/              策略训练记录，结构相同

models/ 目录中的模型文件用于推理和部署，checkpoints/best_train_state.pt 用于恢复训练。 两类文件保存的信息不同，不能互相替代，详细说明见部署模型与训练检查点。

确认训练完成时，应检查 record_info.json 中的状态是否为 completed， 以及 models/ 目录中是否包含所需模型文件。训练过程中保存的中间检查点可用于恢复， 其存在本身不表示整个阶段已完成。

保留结果、重新训练与强制覆盖

REVIVE 默认保留已有训练记录。如果同一 run-id 下本次需要创建的训练记录已经存在， 命令会提示冲突并退出。用户可以使用新的 run-id 保存另一组训练结果， 也可以通过 --force 覆盖需要重新训练的记录：

revive train --config config.min.yaml --train-data data/pendulum.npz --run-id pendulum-quickstart --log-dir logs --force

覆盖已有训练结果

--force 会在预检通过后删除需要覆盖的旧记录，删除后无法恢复。该选项不能与 --resume 同时使用；后者用于从检查点恢复训练。配置或预检失败时，旧结果仍会保留。 正在被其他训练进程使用的目录不允许强制覆盖。

Python 接口采用相同规则：revive.run("config.yaml", force=True)。 重新执行完整的两阶段训练时，会清理该训练任务的旧结果；仅重新执行一个阶段时，会清理 该阶段的冲突记录，并保留上游阶段的模型。任务目录中的默认部署模型和旧报告也会撤下， 在新结果通过验证后重新生成。向已有任务添加新的阶段记录无需强制覆盖，但仍需满足阶段依赖要求。

运行检查使用独立的 pendulum-smoke 名称，与正式训练区分。无论检查成功或失败， 已生成的日志、检查点和 ONNX 文件都会保留，供后续排查。再次检查时，可以更换任务名称， 或使用 --force 覆盖旧记录。

训练中断后的恢复

例如，世界模型已完成、策略阶段中断，且策略阶段已保存最佳训练检查点时，明确指定策略检查点：

revive train --config config.min.yaml --run-id pendulum-quickstart --log-dir logs \
  --resume logs/pendulum-quickstart/policy/policy/checkpoints/best_train_state.pt

若中断的是世界模型阶段，将路径中的 policy/policy 改为 venv/venv。 两阶段各有检查点时，--resume best 无法唯一定位记录，会报告歧义。

新训练默认只保留最佳检查点。该命令恢复最优轮次的模型、优化器、算法状态、随机数状态和模型选择记录， 从该轮次完成后继续；中断前已经执行但未保存的后续训练需要重做。 配置、数据及依赖必须与检查点一致。显式采用 checkpoint_policy: legacy 的运行仍可用 --resume latest。 部署模型文件不能用于恢复完整训练状态，具体要求见精确续训。 已完成的运行增加轮数属于另一项操作，适用范围见追加训练轮数。

接入自己的业务

将上述流程用于自己的业务数据时，建议配置以下内容：

• 验证数据：按完整运行段划分独立验证集，并通过 --val-data 指定。
• 训练设备：在配置中明确设置 training.device，例如 cuda:0。自动选择设备时， 请在训练开始前确认实际使用的设备是否符合预期。
• 任务名称：分阶段执行世界模型与策略训练时，使用同一个 --run-id， 使后续阶段能够按依赖找到已有模型。
• 运行检查：正式训练前使用 --profile smoke，确认数据、配置、训练和导出流程。

---

下一步：使用模型。

报告各项指标的含义和适用范围见分析训练结果。

训练效果排查

训练效果不理想时，可以先检查数据、决策流图和任务目标，再结合结果调整训练参数。 以下是几类常见现象及建议检查的内容：

现象	建议检查内容
单步误差持续较大	第 1 步中的数据列对齐、单位和异常数据段
单步准确，但多步推演偏差较大	历史窗口、中间过程变量及模型结构；也可评估 venv.revive_p 的适用性
策略动作长期保持在上下限	动作范围是否符合设备规格，奖励函数中各项权重是否合理

其他问题的检查方法见改善预测与控制效果。