编写配置

完成数据和任务定义之后，您可以通过 revive init 生成初始配置，再按业务要求完善变量、 动作范围和奖励函数。本节介绍配置生成、默认参数和训练前检查。

以下命令从 SDK 根目录执行；reward.py 等配置内的相对路径以配置文件所在目录为基准。

执行预检前请完成安装与授权。首次在线用户尚未取得许可证时， 先按首次运行启动配套示例；训练命令也会执行配置和数据预检。

生成初始配置

若不确定数据中包含哪些变量，先不指定 --state / --action 执行一次，命令将列出全部变量 后退出：

revive init --data examples/pendulum/data/pendulum.npz

  actions              dim=1    范围=[-2, 2]
  index                dim=1    范围=[200, 2e+04] （轨迹切分标记）
  states               dim=3    范围=[-8, 8]

  init 不猜测哪个变量是状态、哪个是动作——猜错不会报错，只会让模型静默地学到错误的映射。

  这份数据只有两个建模变量，按维度看可能是：--state states --action actions

状态与动作需要由用户根据业务含义指定。确认变量后，补充 --state 和 --action 参数并重新执行：

revive init \
  --data examples/pendulum/data/pendulum.npz \
  --state states \
  --action actions \
  --out gen/config.yaml

命令会在 gen/ 目录生成 config.yaml 和奖励函数模板 reward.py，目录不存在时自动创建。 同名文件已存在时会停止写入；需要覆盖时可使用 --force，并事先保留需要的旧文件。 生成的配置与前面介绍的决策流图对应：

graph:
  nodes:
    actions: {inputs: [states]}
    delta_states: {inputs: [states, actions]}
    next_states: {inputs: [states, delta_states], function: builtin.delta_add}
  columns:
    states: [states_0, states_1, states_2]
    actions:
    - {name: actions_0, min: -2.999993, max: 2.999966}

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

完善任务配置

生成配置中的以下内容需要根据实际任务确认和修改：

位置	生成的内容	倒立摆应改为
列名	states_0、actions_0 等占位名	cos_theta、sin_theta、theta_dot、torque
动作边界	依据数据分布估计（中心 ± 观测半幅 × 1.5），此处约为 ±3.0	执行器真实上限 ±2.0
reward.py	占位函数（惩罚状态与动作的平方和）	第 1 步写出的真实奖励

动作范围的确认方法见物理边界说明。 本例的数据估计值 ±3.0 比设备实际范围宽 50%，应改为 ±2.0。范围过宽可能产生无法执行的动作， 范围过窄则会限制可用操作，因此需要依据设备规格填写。

改完这三处，得到的就是仓库中的 examples/pendulum/config.min.yaml：

graph:
  nodes:
    actions: {inputs: [states]}
    delta_states: {inputs: [states, actions]}
    next_states: {inputs: [states, delta_states], function: builtin.delta_add}
  columns:
    states: [cos_theta, sin_theta, theta_dot]
    actions: [{name: torque, min: -2.0, max: 2.0}]

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

该配置可以用于世界模型与 PPO 策略训练。后续教程使用配套的 config.min.yaml； 如果使用自行编辑的配置，请相应替换命令中的配置和数据路径。

配置检查与业务确认

预检验证配置和函数能否执行。合法的列名、数值范围或奖励函数仍可能不符合实际业务目标， 因此用户需要单独确认变量含义、设备边界和奖励设计。

默认参数与生效配置

训练时通过 --config 指定配置文件，未填写的通用参数使用默认值或根据任务推导。 算法默认值随安装包分发。完整生效配置还包括运行路径、设备和数据等信息， 用于复核本次训练的具体设置。

通常需要填写以下两类内容：

1. 任务定义：决策流图、变量列和动作物理边界等。
2. 需要调整的参数：与默认值不同的网络、训练或验证设置。

通过以下命令查看字段的生效值及来源：

revive validate \
  --config examples/pendulum/config.min.yaml \
  --train-data examples/pendulum/data/pendulum.npz \
  --show-defaults

它会列出每个字段的生效值及其来源（用户 YAML / 算法默认 / 数据推断）。训练时系统补全后的 完整配置也会保存至运行目录（config.resolved.yaml），可随时对照。两份配置的关系见 查看生效参数。

执行预检

revive validate \
  --config examples/pendulum/config.min.yaml \
  --train-data examples/pendulum/data/pendulum.npz

提供数据后，预检会读取轨迹、校验状态转移、检查数据划分和统计、构建各阶段的图， 并检查自定义函数、奖励函数、验证方案及 ONNX 导出要求：

--- 数据、Graph 与可执行组件深验证 ---
  训练集: 80 条轨迹 / 15920 个样本
  验证集: 20 条轨迹 / 3980 个样本
  可执行检查: static_config, validation_plans, real_data_batch, resolve, source_contract,
  input, execute, output, trace, onnx_export, onnx_checker, onnx_runtime, graphs, load,
  signature, onnx_action_bounds, custom_callables, algorithm_capabilities

============================================================
  配置验证: 通过
============================================================

输出中，100 段运行记录被划分为 80 段训练轨迹和 20 段验证轨迹，每段 200 步产生 199 个 转移样本。用户可以据此核对数据划分和样本数量。只有命令行和配置 data.path 均未提供训练数据时， 才仅执行静态检查（字段名、算法键、依赖关系），无法发现实际数据的维度不匹配、奖励函数不可执行等问题。

validate 不创建训练结果目录，也不覆盖已有训练记录。 可反复执行；ONNX 预检使用的临时文件在检查后清理。

常见报错

报错信息	含义	处理方式
配置里有未知字段: graph.nodez（是不是想写 'nodes'？）	字段名拼写错误或位置不当	按提示修正；解析遇到未知字段时立即报错
phase=onnx_action_bounds ... missing=[...]	动作列未声明 min/max	在 columns 中补充，采用设备真实上下限
shape mismatch	数组最后一维与 columns 声明的列数不一致	通过 revive info --data 确认实际维度
reward cannot be loaded	奖励文件不存在或函数名错误	路径以配置文件所在目录为基准
ONNX trace 失败	自定义函数中使用了 NumPy、.item()、文件读取或依赖数据的分支	改写为纯张量运算
转移 ... 必须提供节点 'delta_states'	图采用默认 raw_delta 约定，却缺少增量节点	推荐补齐增量组合；直接预测可设置 transition_contract: direct_next，并选择支持该约定的算法

完整的报错索引见故障排查。

接入自己的业务

接入业务数据时，还需要结合任务完成以下配置：

• --state / --action 各指定一个数据变量名，该变量的数组可以包含多个维度；多节点任务及外部条件在生成后继续编辑图和列定义；
• 除三类占位值外还需审查业务定义：图依赖、外生输入、历史窗口、采样周期与数据覆盖；
• 修改配置后重新执行 validate，在开始训练前检查维度、函数和阶段依赖。

配置中还有大量本页没有涉及的字段（数据划分、验证设置、导出策略、各算法超参）。 可以根据任务需要查阅：配置与调优。

---

下一步：训练模型。

逐块理解配置文件的结构，见 YAML 配置； 查看完整的真实配置，见完整示例。