配置填写与调整顺序

首次配置任务时，先明确业务变量、预测关系和训练目标。能够完成训练后，再根据验证结果调整学习速度、模型规模和推演长度。本页帮助您选择当前需要关注的配置项；已知字段名时，可直接查配置项说明。

当前需要	优先阅读	命令行查询
建立一个可训练的任务	先完成任务定义	revive info --tier basic
改善已有模型的效果	按效果调整常用参数	revive info --tier advanced
使用历史、多步优化等复杂功能	按需设置专项功能	revive info --tier expert

这些分类用于安排阅读顺序。是否必须填写，取决于节点类型、算法与任务：函数节点需要函数引用，策略优化需要奖励，类别列需要明确允许的取值。可由数据推导或已有默认值的设置通常可以省略。

先完成任务定义

明确观测、动作与预测关系

以冰箱温控为例，先确定温度观测、制冷动作与门状态，再定义这些变量如何影响下一时刻温度。将变量及列顺序写入 graph.columns，将依赖关系写入 graph.nodes。动作边界应来自设备能力，数据中的最大值和最小值用于描述已覆盖的工况。

数据列的名称与类型、节点的输入和函数引用通常需要先检查。NodeConfig.name 这类名称会出现在查询结果中；实际 YAML 使用 graph.nodes.<节点名>，无需在节点内重复填写名称。

确定训练目标与阶段依赖

只学习设备响应时，先设置世界模型阶段。需要优化控制动作时，再配置策略或控制器阶段，明确动作节点、奖励函数和依赖的世界模型。奖励应对应业务目标，例如温度偏差与能耗，而不是仅以训练损失作为控制目标。

完整 YAML 可从编写任务配置或对应任务案例开始修改。

查看任务定义配置项（23 项，对应 basic）

配置项	所在配置	说明
max	数据列与物理边界	物理上界，要求同 min。应根据执行器或工艺允许范围设置；观测数据的最大值仅表示样本覆盖范围。
min	数据列与物理边界	物理下界，需按执行器或工艺允许范围设置。直接策略模型的 ONNX 导出要求每个动作维度具有显式物理边界，不能用观测统计代替。
name	数据列与物理边界	列名，用于标识该维度的物理含义，并对齐数据布局、绘图与动作边界。需与原始数据的维度名称一致。
node	数据列与物理边界	该列所属的节点，由 YAML 中 columns 映射的键指定，无需在列定义中重复填写。
type	数据列与物理边界	列类型：continuous、discrete 或 category，用于确定数值处理与网络输出形式。离散档位需显式声明相应类型及取值集合，例如 landerhover 的四档推力使用 category。
values	数据列与物理边界	category 列的有序取值集合。顺序决定各取值的编码位置，修改后需重新核对模型与数据的兼容性。
graph	任务名称与配置入口	图结构与列定义：这个任务有哪些量、谁依赖谁。用命名图（graphs）时它是默认那张。
training	任务名称与配置入口	设备、随机种子与 stage 序列。
differentiable	专家函数	函数是否可微。位于最终 delta 计算路径上的函数节点需声明为可微，使损失梯度可以传回上游网络；不满足时会报告 DeltaContractError。配置示例见 examples/thermal_workflows。
ref	专家函数	函数引用，如 builtin.delta_add 或 <module>:<callable>。
columns	决策流图	各节点的数据列定义，包括列名、类型与物理边界。需与原始数据的列顺序和业务含义对应。
nodes	决策流图	单步决策流图的节点定义。节点名同时作为输出变量名，由用户根据任务定义填写。
function	预测节点	把该节点定义成确定性函数节点而非网络节点。取内置 key（如 builtin.delta_add）或 <module>:<callable> 形式的 Python 引用。
inputs	预测节点	该节点依次读取的上游输入，用于定义决策流图的依赖关系。由用户按任务填写，支持历史表达式与显式输入引用。
name	预测节点	节点名，也就是它的输出变量名。
function	奖励函数	该文件里奖励函数的名字。
path	奖励函数	奖励函数所在的 Python 文件路径，相对配置文件自身的位置。
algorithm	训练阶段	本阶段使用的算法，如 venv.bc、venv.revive_p、policy.ppo 或 controller.ffpid。需填写 AlgorithmRegistry 中注册的完整算法键。
inherit_from	训练阶段	policy / controller 阶段所依赖的 venv 阶段名。
name	训练阶段	阶段名。stage 之间靠它互相引用（inherit_from），它同时也是默认的 record_id。
policy_nodes	训练阶段	policy / controller 阶段负责输出动作的节点，必填；其余节点被冻结成环境模型。
reward	训练阶段	奖励函数的来源（文件路径 + 函数名）。策略类算法必填。
stages	运行设置	训练与控制器阶段列表，按声明顺序执行。

按效果调整常用参数

调整学习速度与模型规模

先保持数据划分与评价指标不变。训练震荡时检查学习率、数据量纲与异常值；训练与验证误差都较大时，再比较训练轮数和网络规模。批量较大可能提高吞吐，但也会增加显存占用。

常见入口是 data.batch_size、网络的 hidden_dims，以及所选算法下的 epochs、optimizer.lr。不同算法支持的键与默认值不同，应结合算法参数说明填写。

调整多步预测与控制效果

冰箱单步预测较准、连续推演温度却逐渐偏离时，先检查开门扰动、历史信息和动作延迟，再评估多步训练。倒立摆策略的模型内回报提高后，还应检查独立仿真中的摆角、力矩与动作变化。

推演长度需要与任务采样周期和模型可靠预测范围匹配。世界模型未能准确预测较长时间范围时，单纯增加策略推演长度可能放大误差。按现象选择调整项，见改善预测与控制效果。

查看常用调整配置项（147 项，对应 advanced）

配置项	所在配置	说明
num	数据列与物理边界	discrete 列的取值个数。
data	任务名称与配置入口	数据来源、训练/验证划分与归一化。
description	任务名称与配置入口	给人读的说明，不影响训练。
graphs	任务名称与配置入口	命名图集合，供不同 stage 用 stage.graph 各自挑一张。
name	任务名称与配置入口	配置名称，用于日志与输出文件命名，并保存在 config.resolved.yaml 中。
output	任务名称与配置入口	checkpoint、绘图与 ONNX 导出。
version	任务名称与配置入口	用户配置的格式版本，独立于 revive 软件包版本管理。升级软件包不会自动修改该值。
action_bounds	控制器通用设置	显式 actuator 边界 {列名: [下界, 上界]}；不填时只接受 graph 列定义里的边界。
ffpid	控制器通用设置	FFPID 专属参数。
mpc	控制器通用设置	MPC 专属参数。
residual_pid	控制器通用设置	ResidualPID 专属参数。
tune	控制器通用设置	自动调参配置。
type	控制器通用设置	控制器种类：mpc | ffpid | residual_pid。
enabled	控制器参数搜索	是否自动调参。关掉则直接用配置里的增益。
eval_horizon	控制器参数搜索	各评估片段在世界模型中的推演步数。需覆盖任务相关的响应过程，可参考被控对象的 t63 选择初值。
max_trials	控制器参数搜索	搜索的试验总数，直接决定调参耗时。
objective	控制器参数搜索	控制器参数搜索的排序指标，决定候选增益按跟踪误差或回报等指标比较。
seed	控制器参数搜索	调参搜索的随机种子。换它会换出一组不同的候选，因而是可比性的一部分。
batch_size	数据读取与划分	每个梯度步的样本数。这是全局默认值，stage 可以按算法各自覆盖。
normalization	数据读取与划分	归一化方式：min_max_scaler 或 z_score。统计量随模型保存并用于部署。修改统计量会改变模型的输入输出映射，复用与续训时需核对一致性。
num_workers	数据读取与划分	DataLoader 的 worker 进程数，0 表示在主进程里读。只影响吞吐，不改变训练结果。
path	数据读取与划分	训练数据文件路径。可在 YAML 中填写，也可在命令中通过 --train-data 指定；同时设置时以命令行参数为准。
split_mode	数据读取与划分	训练/验证的切分粒度：outside_traj 按轨迹切（验证集是没见过的轨迹，轨迹级隔离），inside_traj / inside_traj_reverse 在轨迹内部切（同一条轨迹的前后段分属两边，隔离更弱但样本利用率更高）。
train_ratio	数据读取与划分	训练集占比，其余用于验证。仅在未指定 val_path 时生效，划分方式由 split_mode 决定。整个运行共享一次划分，阶段级参数不单独重新划分数据。
val_path	数据读取与划分	可选的独立验证集文件。设置后训练用 path 全量、验证用 val_path（显式轨迹级 holdout），而不是对 path 内部按 train_ratio 切分；此时 val_split 取 1 - train_ratio。
efficient_output	双环境训练设置	仅 legacy：双环境低频 latest、关闭归档、阶段末导出指标；best_only 始终只保留最优轮次。
execution	双环境训练设置	开启双环境后按任务资源自动选择串行或并行；显式 serial/parallel 优先。cpu_per_branch 限制每分支线程数，GPU 并行须指定两张不同且已分配的设备。
cpu_per_branch	分支资源分配	并行执行时，每个分支可使用的 CPU 线程数。
mode	分支资源分配	默认 auto：单卡串行，明确分配双卡且 CPU 额度足够时并行；可显式设 serial/parallel。
integral_limit	前馈 PID 控制器	积分状态的绝对值上限，None 表示不限。用来抑制 windup。
kd	前馈 PID 控制器	微分增益，响应误差的变化率，给闭环增加阻尼。必须非负。
kff	前馈 PID 控制器	前馈增益，直接乘设定值（不是测量值）：action += kff * setpoint。它绕过反馈回路直接提供一部分控制量，所以能在误差还没建立起来时就动作。
ki	前馈 PID 控制器	积分增益，必须非负。用于减小恒定设定值下的稳态偏差。
kp	前馈 PID 控制器	比例增益，必须非负。当前配置校验要求 kp、ki、kd 均大于等于 0，因此无法通过 YAML 配置需要负增益的反作用过程，例如功率增大、温度下降的制冷过程。
measurement_key	前馈 PID 控制器	输入状态里哪一个键是被控量（反馈测量）。它和 setpoint_key 一起定义误差：error = setpoint - measurement。
output_limit	前馈 PID 控制器	控制量输出的绝对值上限，None 表示只受 action_bounds 约束。
setpoint_key	前馈 PID 控制器	输入状态里哪一个键是目标设定值；None 表示由 stage 另行提供。
history	决策流图	历史窗口的全局设置，包括填充方式、输出格式、初始填充和梯度截断。窗口长度在各节点 inputs 中通过 变量@-k 或 变量@[-k:] 声明。
transitions	决策流图	状态转移映射。源配置默认使用 auto；解析后的配置及保存的模型记录中使用具体映射。
future_exogenous_keys	MPC 控制器	规划期内可预知的外生变量列，例如天气预报和排产负载。模型调用端必须提供所列节点的未来序列。MPC 使用这些信息进行规划；单回路 PID 通常根据当前误差生成控制量。
gamma	MPC 控制器	规划期内累计回报的折扣因子，与 horizon 共同决定远期收益的权重。gamma 较小时，窗口末端奖励的影响减弱。
horizon	MPC 控制器	MPC 每次规划的步数，需结合系统时滞与响应时间设置。例如 three_tank 中 h2 对泵的 t63 为 109 个控制步；规划窗口较短时，泵能耗已计入奖励而液位改善尚未出现，可能影响候选动作的选择。
method	MPC 控制器	规划算法，可选 cem（交叉熵方法）、mppi（加权平均）或 random（随机采样搜索）。三种算法均由 MPCPlannerKernel 实现。
num_iterations	MPC 控制器	每个控制步的搜索迭代次数。仅 cem 与 mppi 有效，random 只打一轮。
num_samples	MPC 控制器	每轮采样的候选动作序列条数。它和 num_iterations 一起决定单个控制步的规划开销。
seed	MPC 控制器	候选动作采样的随机种子。CEM / MPPI 每步都在采样，固定它才让同一状态下的规划可复现。
activation	神经网络	隐藏层激活函数名，默认 leakyrelu，在负半轴保留非零梯度。具体效果需结合网络与数据验证。
backbone	神经网络	骨干网络名称，使用网络注册表中的 mlp、res、gru、transformer 或用户注册的网络。
dropout	神经网络	Dropout 概率，0 表示禁用，推理时自动关闭。
hidden_dims	神经网络	各隐藏层的宽度。增大宽度可提高模型容量，同时增加计算与显存开销，并可能提高过拟合风险，需结合数据量和验证结果调整。
layer_norm	神经网络	是否在隐藏层间加 LayerNorm。
network	预测节点	该节点的网络结构，仅用于 network 节点。function 节点通过函数配置定义。
output_dist	预测节点	输出分布，默认为 normal（DiagonalNormal）。动作或策略节点需显式设置 tanh_normal，以将输出限制在 [-1, 1]。预测精度与标准差的校准效果需结合任务验证。
lr	优化器与学习率	基础学习率。过高可能引起训练震荡或发散，过低可能增加收敛所需轮数，可结合损失与验证曲线调整。
lr_decay	优化器与学习率	step / exponential 调度的衰减因子。
scheduler	优化器与学习率	学习率调度器：none | step | cosine | exponential。
type	优化器与学习率	优化器类型：adam | adamw。
weight_decay	优化器与学习率	参数权重衰减（L2）系数。可与 dropout 联合使用，正则强度过大时可能导致欠拟合。
archive_interval	模型、报告与日志	仅 legacy：历史归档间隔；0 关闭；双环境默认 0。
checkpoint_interval	模型、报告与日志	仅 legacy：latest 保存轮数间隔；普通训练默认 1、双环境默认 10。
checkpoint_policy	模型、报告与日志	best_only 仅覆盖最优模型及同轮续训态；legacy 兼容旧周期保存。
checkpoint_seconds	模型、报告与日志	仅 legacy：latest 时间间隔，epoch 边界检查；0 关闭时间触发。
enable_plotting	模型、报告与日志	训练绘图总开关。false 时关闭 best、trend 和 openloop 绘图，可减少文件读写与绘图开销。
export_onnx	模型、报告与日志	训练结束后是否导出 ONNX。标准训练流程要求该项与 require_onnx 同时启用，导出及所要求的验证通过后才能选为运行级模型。
metrics_backend	模型、报告与日志	auto/snapshots/final/tensorboard：每轮快照、结束导出或仅事件历史。
plot_external_inputs	模型、报告与日志	趋势图里是否一并画出外生输入列。
require_onnx	模型、报告与日志	导出失败时是否判 stage 失败并挡住 promotion。关掉等于允许产出不可部署的模型，而这件事只有到上线那天才会被发现。
save_freq	模型、报告与日志	legacy 历史归档间隔；best_only 忽略此字段。
tensorboard	模型、报告与日志	是否写 TensorBoard 事件文件。
trend_plot	模型、报告与日志	是否生成训练趋势图。
trend_plot_interval	模型、报告与日志	趋势图每多少轮更新一次。
dynamics_noise	PPO 策略参数	仅策略训练期动力学扰动：enabled 默认 false，keys 按状态列配置 raw 单位标准差。
entropy_coef	PPO 策略参数	策略熵奖励系数，越大越鼓励探索。也可使用 w_ent；同时填写时以 w_ent 为准。
epsilon	PPO 策略参数	PPO 裁剪目标中的概率比率裁剪范围，用于限制单次策略更新幅度。
gae_lambda	PPO 策略参数	GAE 的 lambda：偏差 / 方差的权衡。1 退化成蒙特卡洛回报，0 退化成 TD(0)。
gamma	PPO 策略参数	回报与优势估计的折扣因子，有效视界约为 1/(1-gamma)，0.99 对应约百步。取值需结合 rollout 长度与末端价值估计：推演仅 20 步而 gamma=0.999 时，窗口外回报较多依赖自举估计。
max_grad_norm	PPO 策略参数	PPO actor / value 更新的梯度范数上限。
n_epochs	PPO 策略参数	PPO 更新轮数的兼容配置。当前训练使用 ppo_runs 控制每批推演数据的更新次数，调整时请设置 ppo_runs。
num_rollout_trajs	PPO 策略参数	并行 rollout 的轨迹条数；不指定时由 ppo_batch_size 或 data.batch_size 推导。
validation_horizon	PPO 策略参数	策略验证的推演步数。未填写时使用训练推演长度：PPO 对应 rollout_horizon，SAC 对应 rollout_length。
value_coef	PPO 策略参数	value loss 在 PPO 总目标里的权重。
value_hidden_dims	PPO 策略参数	value 网络各隐藏层宽度。它与策略网络分开配：value 拟合的是整条轨迹的回报，通常需要比策略更大的容量。
delta_max	残差 PID 控制器	残差相对基线动作的最大偏移量。默认值按加氯任务量纲设置，其他任务需根据允许偏移范围重新确定。上限不足以覆盖目标动作时，输出可能持续饱和。
i_max	残差 PID 控制器	积分项贡献的绝对值上限，用来抑制 windup。它和 delta_max 一样按任务量纲定。
kd	残差 PID 控制器	残差项的非负微分增益。测量噪声较大时可结合 derivative_filter_tau 抑制动作抖动。
ki	残差 PID 控制器	残差项的积分增益，消除常值设定值下的稳态偏差。必须非负。基线取零时慎用：那时残差就是指令本身，积分项会累出退不掉的偏置。
kp	残差 PID 控制器	残差项的比例增益。必须非负，同 FFPID。
measurement_key	残差 PID 控制器	输入状态里哪一个键是被控量。内核算 error = target - measurement。
rate_limit	残差 PID 控制器	相邻两步残差的最大变化量，需根据执行器能力与控制周期设置。vehicle_acc 示例中，每步 0.5 m/s² 的限制使加速度从 0 降到 -3 m/s² 需要 6 步（1.2 s），会影响急刹场景的可行控制范围。平滑偏好可另用奖励代价表达，硬限制需单独验证。
sample_dt_h	残差 PID 控制器	控制周期，单位小时。积分与微分项按它换算，所以它必须与增益标定时用的周期一致。
target	残差 PID 控制器	被控量的设定值。当前增益要求非负，仅支持与该增益方向匹配的被控量；需要负增益的反作用过程暂时无法通过 YAML 配置。
enabled	奖励监督	是否把奖励作为监督信号一起训练（辅助损失）。
weight	奖励监督	奖励监督这项辅助损失在总损失里的权重。
enabled	多步验证	是否执行多步自回归验证。关闭后不生成该路径的 rollout 指标；需要评价长程预测或闭环效果时，应保留独立的多步验证。
expert_action_rollout_enabled	多步验证	额外算一组「动作取自数据而非模型」的 rollout 指标。典型用法是 nodes=['actions']，用来单独看动力学的长期误差。
expert_action_rollout_nodes	多步验证	上述 rollout 中改用专家（数据）取值的节点。
num_rollout_trajectories	多步验证	每次验证推演多少条轨迹。条数太少时曲线不单调、拐点会摇摆。
primary_metric_dims	多步验证	主指标计算使用的节点维度，留空表示全部维度。可选择业务关注的物理量作为模型选择依据，避免全维平均掩盖关键维度的误差变化。
primary_metric_node	多步验证	面向任务的主指标算在哪个节点上（原始量纲）。
rollout_horizon	多步验证	验证时自回归推演多少步。必须小于等于验证轨迹长度，否则该指标整条缺失，训练侧会以「配置了却没收到该指标」报错。
rollout_val_frequency	多步验证	每多少轮做一次 rollout 验证。它比单步验证贵得多，所以通常不是每轮都做。
actor_lr	SAC 策略参数	Actor 学习率。需结合 Critic 的拟合情况与策略更新稳定性调整。
alpha	SAC 策略参数	熵温度。auto_alpha=false 时它是固定值，true 时它只是自动优化的初值。
alpha_lr	SAC 策略参数	自动温度参数的学习率。auto_alpha=false 时它不起作用。
auto_alpha	SAC 策略参数	是否自动优化熵温度，使策略熵向 target_entropy 收敛。
batch_size	SAC 策略参数	算法局部 batch size。更大通常更稳，代价是显存。
bc_pretrain_epochs	SAC 策略参数	SAC 优化前的行为克隆预热轮数，用于初始化历史行为附近的策略；0 表示不预热。
buffer_size	SAC 策略参数	ReplayBuffer 最多存多少条 transition。
critic_lr	SAC 策略参数	Critic 学习率，用于调整 Q 值估计的更新速度。
dynamics_noise	SAC 策略参数	仅策略训练期动力学扰动：enabled 默认 false，keys 按状态列配置 raw 单位标准差。
gamma	SAC 策略参数	回报与 Bellman target 的折扣因子。
max_grad_norm	SAC 策略参数	actor / critic 更新的梯度范数上限，0 表示不裁剪。
num_q	SAC 策略参数	Q 网络个数（集成规模）。target 与 actor 用的是它们的保守聚合。REVIVE 默认 4。
num_rollout_trajs	SAC 策略参数	每个训练 epoch 在世界模型里生成多少条轨迹。
q_hidden_dims	SAC 策略参数	Q 网络各隐藏层宽度。
rollout_length	SAC 策略参数	每个 epoch 在世界模型中生成的单条轨迹长度，即 SAC 的推演步数。SAC 使用 rollout_length，PPO 使用 stage.rollout_horizon，配置时需选择对应算法的字段。可使用 revive suggest-rollout 在已训练的世界模型上评估建议值。
tau	SAC 策略参数	target Q 网络的软更新系数：越小目标越慢、越稳。
updates_per_step	SAC 策略参数	每新增一个 transition 对应做多少次优化更新。
validation_horizon	SAC 策略参数	策略验证的推演步数；None 表示复用该算法的训练长度 rollout_length。
value_hidden_dims	SAC 策略参数	value 网络各隐藏层宽度。它与策略网络分开配：value 拟合的是整条轨迹的回报，通常需要比策略更大的容量。
warmup_steps	SAC 策略参数	开始正式 actor / critic 更新之前先积累多少条 transition，其间只收数据不更新参数。
batches_per_epoch	多步联合训练	每轮抽取 batch_size × batches_per_epoch 个窗口，在合法起点中有放回均匀抽样。null 表示每轮无放回遍历全部合法窗口。
enabled	多步联合训练	是否启用多步联合优化。关闭时仅进行单步监督训练；多步推演表现需要单独验证。
horizon	多步联合训练	一次联合优化累加多少步的 loss（H）。venv.revive_p 下它同时也是判别器看到的序列长度。加大它会明显抬高显存与计算量，batch_size 通常要反向调。
train_mode	多步联合训练	多步训练的输入模式。tf 使用教师强制，每步输入真实值；rollout 使用自回归，每步输入前一步的预测值，用于在训练中考虑误差累积。
batch_size	训练阶段	本阶段的批大小。None 表示沿用 data.batch_size。课程训练可在各阶段分别设置，例如 H=1 时使用 4096、H=200 时使用 256。
bc_pretrain_epochs	训练阶段	策略优化之前先做多少轮行为克隆预热，0 表示不预热。
controller	训练阶段	控制器配置，仅 controller.* 算法用。
env_record_id	训练阶段	改为依赖一个已导出的 venv record_id，而不是同配置里的 stage。
epochs	训练阶段	本阶段的最大训练轮数。启用早停或 patience 时，训练可能提前结束。
frozen_nodes	训练阶段	显式冻结的节点，训练中不更新其参数。
grad_clip	训练阶段	梯度范数裁剪阈值。0 表示关闭（个别算法另有自己的关闭语义）。
graph	训练阶段	可选的 stage 级 graph 名称；为空时用顶层 graph。
loss	训练阶段	主监督损失类型，如 nll / mse。
metric	训练阶段	用于选择最佳检查点的指标。编写当前版本 YAML 时使用 validation.selection.metric，并设置相应优化方向。
node_weights	训练阶段	按节点覆盖 venv 阶段的监督损失权重，默认全为 1.0。
optimizer	训练阶段	优化器配置。
ppo	训练阶段	PPO 专属超参，仅 policy.ppo 用。
rollout	训练阶段	venv 阶段的 rollout 验证配置（嵌套式新格式）。
rollout_horizon	训练阶段	训练时连续推演的步数，未单独设置验证长度时也用于验证。温控、机械运动等任务的误差积累速度不同，应根据本任务的多步误差曲线选择。可使用 revive suggest-rollout 获取建议；SAC 的训练推演长度使用 rollout_length。
sac	训练阶段	SAC 专属超参，仅 policy.sac 用。
cpu_threads	运行设置	严格复现时固定的主进程 PyTorch CPU 线程数。
deterministic	运行设置	启用严格确定性算子；相同环境、seed 和执行计划可复现。
device	运行设置	训练设备：auto、cpu、cuda[:N] 或 npu[:N]。显式指定的设备不可用时会报告错误；auto 按环境探测可用设备。
log_dir	运行设置	全部 run / record / checkpoint / 模型的输出根目录。
run_id	运行设置	运行标识，用于分阶段复用同一目录。标准训练流程通过 CLI 或 RuntimeInputs 指定。
seed	运行设置	模型初始化与训练期采样的随机种子，独立于数据划分使用的 data.split_seed。

按需设置专项功能

历史信息与训练目标

当前观测不足以判断系统状态时，可使用历史窗口。需要重点拟合某些节点、角度或累计变化时，再检查监督目标、序列损失与各项权重，并在相同验证条件下比较效果。

例如车辆跟随需要区分“相同距离但正在接近”和“相同距离但正在远离”，可先补充相对速度等业务变量；变量仍不足时再评估历史输入，避免直接扩大网络却没有提供所需信息。

调整算法专属设置

REVIVE-P 的对抗训练、ADM2 的多步预测、PPO/SAC 的策略更新，以及 MPC 的在线搜索各有不同参数。需要改变某一机制时，先确认作用范围、依赖项和评价方法，再调整相应参数。MPC 增加采样数与规划长度后，还需测量目标设备上的推理时间。

专项设置通常先保留默认值。需要具体功能时，从高级功能或算法参数说明进入。

查看专项设置配置项（191 项，对应 expert）

配置项	所在配置	说明
uncertainty	任务名称与配置入口	不确定性估计配置。
fast_eval_segments	控制器参数搜索	粗筛阶段的评估片段数。
full_eval_segments	控制器参数搜索	复评阶段的评估片段数。
mode	控制器参数搜索	搜索模式。two_stage 先用 fast_eval_segments 粗筛，再对 top_k 用 full_eval_segments 复评。
search	控制器参数搜索	搜索空间覆写：{参数名: [候选值...]}，为空则用算法内置空间。
top_k	控制器参数搜索	粗筛后进入复评的候选个数。
paired_split_role	数据读取与划分	异构/配对数据切分中本份数据扮演的角色：None | A | B。仅 outside_traj 有效。
split_seed	数据读取与划分	数据划分的随机种子，与模型初始化种子分别设置。比较不同初始化或超参数时，可固定该值以保持训练集与验证集不变。
allow_validation_training	双环境训练设置	使用独立验证文件训练 B 分支须显式同意；该文件不再是独立留出测试集。
enabled	双环境训练设置	显式开启双环境训练流程插件；默认始终关闭。
policy_mode	双环境训练设置	dual 独立训练两套策略；single 为两套环境、一套策略的轻量模式。
quality_rules	双环境训练设置	选中模型的业务质量拒绝规则；空列表明确表示未配置质量门槛。
seed_offset	双环境训练设置	B 分支的训练随机种子偏移，不参与数据切分或交叉验证采样。
stages	双环境训练设置	参与插件的阶段名；空列表表示所有阶段，首期仅支持 BC/REVIVE-P/PPO/SAC。
validation	双环境训练设置	交叉验证与矩阵诊断配置，选模沿用统一验证引擎。
devices	分支资源分配	明确分配的两个逻辑设备；空列表在加速器上只使用 training.device，不自动占用其他卡。
domain	分支质量要求	venv 或 policy。
max_environment_gap	分支质量要求	策略在同一起点面板的两个环境上的指标绝对差上限。
maximum	分支质量要求	选中交叉格的指标上限。
metric	分支质量要求	必须实际产出的 canonical 指标。
minimum	分支质量要求	选中交叉格的指标下限。
diagnostic_interval	交叉验证	完整矩阵的独立轮数间隔；0 仅在阶段末对选中模型补评，1 沿用逐轮诊断。
full_matrix	交叉验证	输出同一初始状态面板上的完整交叉矩阵；关闭时仍执行交叉选模。
seed	交叉验证	交叉验证的固定随机种子；与分支训练和数据切分随机流相互独立。
formula	专家特征	自定义公式，与内置特征互斥。
inputs	专家特征	公式所需的输入列；不写时自动推断。
learnable	专家特征	参数是否随训练更新。
name	专家特征	专家特征名。
params	专家特征	公式参数。
anti_windup	前馈 PID 控制器	输出饱和时的抗积分饱和策略。
derivative_filter_tau	前馈 PID 控制器	微分项的一阶低通时间常数，0 表示不滤波。测量带噪时不滤波会让微分项把控制量抖起来。
compute_space	专家函数	函数在原始空间还是归一化空间求值。
materialize	专家函数	是否将构建期用于统计的函数输出写入数据存储，供专家片段读取。默认 false。开启后会增加数据键，并影响基于 next_ 前缀的转移推断和训练器状态键推断；例如 adversarial.ood.x_nodes 需要读取该函数输出时可启用。
params	专家函数	带参内置函数（如 builtin.delta_add_project）的绑定参数。该配置参与节点配置指纹计算并随模型保存，因此仅支持 JSON 标量与列表，不支持任意 Python 对象。
stats_source	专家函数	该节点的归一化统计量取自数据还是函数自身。
strict_shape	专家函数	是否强制校验函数输出形状。
transition_contract	决策流图	跨步转移的计算约定。raw_delta（默认）要求由内置 delta 算子组成的显式 delta_<source> 节点；direct_next 允许网络直接预测下一状态；custom_function 允许可微的 raw 空间函数作为转移目标，并通过真实数据检查执行等价性。ADM2 等需要显式 delta 结构的算法不支持 custom_function。
warmup_depth	决策流图	图级 warmup 深度，0 表示由各节点自动决定。
clip_actions	MPC 控制器	每次生成候选后是否裁剪到 action_bounds 内。
deterministic	MPC 控制器	规划时世界模型取分布均值（true）还是采样（false）。取均值让同一状态下的规划可复现。
num_elites	MPC 控制器	CEM 每轮保留多少条精英用于更新采样分布。仅 method=cem 有效。
temperature	MPC 控制器	仅 method=mppi 有效：候选按 softmax(return / temperature) 加权平均。cem 走的是 topk 硬选择，根本不读这个值。必须为正。
use_policy_prior	MPC 控制器	初始采样分布是否以已训练的策略为先验。关掉则从动作区间中点 ± 半量程起步。
warm_start	MPC 控制器	是否平移上一控制步的最优动作序列，用于初始化当前搜索。CEM 的 top-k 选择可能因 PyTorch 与 ONNX 间 1e-7 量级的浮点差而变化，暖启动会继续传递该差异，影响 parity 验证。需要数值一致性验证时应关闭，并按部署指南检查搜索结构的限制。
allow_function_to_network_policy	阶段间模型继承	允许把函数节点迁移成网络策略节点。
allow_network_to_function_policy	阶段间模型继承	允许把网络节点迁移成函数策略节点。
allow_stateful	阶段间模型继承	允许迁移有状态网络（如 GRU）。
mode	阶段间模型继承	迁移方式：by_reference 直接引用 | copy_compatible 拷贝兼容节点 | preflight_only 只做兼容性检查不迁移。
norm	阶段间模型继承	归一化统计量的处理：strict 要求完全一致 | sync_shared_from_env 从环境侧同步共享变量 | warn 只告警。
on_env_mismatch	阶段间模型继承	环境侧节点不匹配时报错还是告警。
on_policy_mismatch	阶段间模型继承	策略侧节点不匹配时重新初始化、报错还是告警。
reuse_policy_nodes	阶段间模型继承	是否复用已有 artifact 里的策略节点权重。
write_report	阶段间模型继承	是否保存迁移报告。
custom_params	神经网络	自定义网络的扩展参数。网络专属选项写入 custom_params；放在未定义的位置会提示未知字段。
input_embedding	神经网络	按输入节点配置嵌入维度与融合方式，为空表示不做嵌入。
unified_head	神经网络	骨干网络与输出头的统一结构参数，为空时各输出分别使用独立输出头。
dist_config	预测节点	分布的额外配置，如 normal 的 {min_std, max_std}、mix 的 {components: [...]}。
expert_features	预测节点	该节点的专家特征列表。
input_slices	预测节点	输入切片映射：只取上游节点的某几列作为输入。
type	预测节点	节点类型，由配置自动确定。填写 function 时为函数节点，否则为网络节点；用户 YAML 无需填写 type。
warmup_depth	预测节点	节点级 warmup 深度，0 表示用图级默认。
warmup_inputs	预测节点	warmup 的数据源声明，仅对有状态网络（如 GRU）有效。
eta_min_ratio	优化器与学习率	cosine 调度的学习率下限，按 lr 的比例给出。仅 scheduler_interval='update' 有效。
scheduler_interval	优化器与学习率	学习率的更新频率：epoch 表示每轮更新，update 表示每次参数更新后调整。update 仅支持 scheduler='cosine'。
allow_research_snapshots	模型、报告与日志	显式允许有 max_snapshots 上限的判别器研究快照；训练检查点仍只保留 best。
checkpoint_mirrors	模型、报告与日志	auto/commit/final：兼容 checkpoint 文件每次提交或结束时生成。
export_pkl	模型、报告与日志	DEPRECATED：保留仅为兼容旧 YAML 解析，不控制任何导出行为。
onnx_atol	模型、报告与日志	PyTorch / ONNX parity 与 runtime 校验的绝对误差容限。
onnx_export_dtype	模型、报告与日志	ONNX 导出时的计算精度：keep 保持模型精度，float32 或 float64 指定导出精度。
onnx_io_space	模型、报告与日志	ONNX 的输入输出单位：raw 使用原始物理量，processed 使用归一化值。选择 raw 时，归一化计算包含在导出模型中，业务程序按原始单位提供输入。
onnx_opset	模型、报告与日志	ONNX opset 版本。
onnx_rtol	模型、报告与日志	PyTorch / ONNX parity 与 runtime 校验的相对误差容限。
onnx_validate	模型、报告与日志	导出验证等级：checker 检查结构，runtime 检查 ONNX Runtime 执行，parity 比较 PyTorch 与 ONNX 数值，none 不验证。MPC 的 CEM top-k 选择不连续，1e-7 量级的浮点差可能改变精英集合，单纯放宽 atol 不能保证搜索结果一致；具体要求见输出配置指南。
tensorboard_flush_secs	模型、报告与日志	TensorBoard 刷新间隔（秒）。
tensorboard_queue	模型、报告与日志	TensorBoard 待写事件队列大小。
bpc_type	PPO 策略参数	行为约束类型：bc | wpc；bpc_weight>0 时生效。当前 PPO 不支持启用 kl 约束。
bpc_weight	PPO 策略参数	行为约束权重，>0 才开启。
generate_deter	PPO 策略参数	rollout 是否用确定性动作（REVIVE: generate_deter，1 为确定性）。
log_ratio_clip_enabled	PPO 策略参数	是否对 log ratio 做上限裁剪（ratio = exp(clamp_max(log_ratio, max))）。默认关闭以对齐 REVIVE(v1)。
log_ratio_clip_max	PPO 策略参数	log ratio 的裁剪上限。
ppo_batch_num	PPO 策略参数	每批推演数据划分的小批次数，默认 8。与 ppo_runs 共同决定这批数据的更新次数。
ppo_batch_size	PPO 策略参数	每个小批次的样本数；未指定时根据训练数据的批量设置计算。
ppo_runs	PPO 策略参数	每批推演数据进行的 PPO 更新轮数。增大后会对同一批数据进行更多次更新。
segment_sampling_mode	PPO 策略参数	推演起点的采样方式：trajectory_uniform 按轨迹均匀；segment_uniform 按每条轨迹可容纳的整段数 floor(L_i/H) 加权；timestep_uniform 按合法起点数 L_i-H+1 加权。L_i 为轨迹长度，H 为推演长度。
use_last_value_bootstrap	PPO 策略参数	是否使用轨迹末端的价值估计补充后续回报。false 将末端价值设为 0；没有终止信号的持续控制任务可评估开启后的效果。
w_ent	PPO 策略参数	entropy_coef 的别名；同时填写时以 w_ent 为准。
w_vl2	PPO 策略参数	价值网络的 L2 正则权重（REVIVE: w_vl2）。
name	阶段内训练计划	phase 名称。
optimize_nodes	阶段内训练计划	本 phase 更新哪些节点的参数。
optimizer	阶段内训练计划	本 phase 专用的优化器；None 表示沿用 stage 级配置。
repeat	阶段内训练计划	本 phase 连续重复多少次。
baseline	残差 PID 控制器	专家基线动作的来源，包括 callable、参数与来源约定。None 表示使用零动作为基线，此时残差即为输出指令。
apply_to	奖励监督	在哪些训练阶段生效。
detach_unpredicted_inputs	奖励监督	非预测输入是否切断梯度。
differentiable_keys	奖励监督	哪些键保持可微；默认与监督目标一致。
eps	奖励监督	数值稳定用的下限。
grad_log	奖励监督	是否记录梯度统计到日志。
loss	奖励监督	辅助损失的形式。
mode	奖励监督	梯度获取方式。
normalize	奖励监督	是否对奖励差做归一化。
pred_mode	奖励监督	预测值取分布众数还是采样。
reward_consistency_weight	奖励监督	奖励一致性项的权重。
sensitivity_max	奖励监督	灵敏度裁剪的上界。
sensitivity_min	奖励监督	灵敏度裁剪的下界。
support_limit	奖励监督	支撑范围的外推上限。
task_state_weight	奖励监督	任务状态项的权重。
warmup_ratio	奖励监督	辅助损失权重线性爬升占总轮数的比例。
allow_reduce_segments	多步验证	候选片段不足时允许自动减少数量而不是报错。
expert_action_rollout_exclude_nodes	多步验证	上述 rollout 中显式排除的节点。
integrated_displacement_metric_dims	多步验证	位移指标看哪几维速度。
integrated_displacement_metric_dt	多步验证	积分步长；None 表示由数据推断。
integrated_displacement_metric_node	多步验证	位移指标：把原始空间的速度预测误差沿 rollout 积分，得到不依赖 GPS 的位移偏差。
integrated_displacement_metric_scales	多步验证	位移指标各维的尺度。
integrated_displacement_metric_weight	多步验证	位移指标在综合指标里的权重，0 表示只记录不参与。
mae_scale_decay	多步验证	逐步衰减率：第 t 步的权重为 decay^t。1.0 表示各步等权。
min_start_gap	多步验证	同一条轨迹上两个片段起点的最小间隔。
node_clip	多步验证	推演时节点输出的绝对值裁剪，None 表示不裁剪。
num_rollout_segments	多步验证	分层采样时的候选片段数（sampling_mode='segment_stratified'）。
primary_metric_circular_dims	多步验证	其中哪几维是角度类（按周期求差）。
primary_metric_dim_weights	多步验证	各维在主指标里的权重。
primary_metric_scales	多步验证	各维的归一化尺度；应当只用训练集统计。
primary_metric_trajectory_macro	多步验证	按轨迹先聚合再平均（宏平均），而不是所有步一起平均。
sampling_mode	多步验证	片段采样方式：segment_stratified | trajectory。
segment_seed	多步验证	片段采样的随机种子。
segment_select_mode	多步验证	分层内的选取方式：bin_random | uniform。
wdist_test	多步验证	是否计算 Wasserstein 距离（看分布保真度，计算较慢）。
batch_ratio	SAC 策略参数	SAC batch 里生成 transition 的占比。REVIVE 默认 1。
behavioral_policy_init	SAC 策略参数	把 venv 阶段训好的 policy 节点权重拷进 SAC 策略作为初始化。对齐 REVIVE 的 behavioral_policy_init=True：策略从行为策略起步，且 KL anchor 锚定到行为策略而不是随机初始化。
bpc_type	SAC 策略参数	行为约束类型：none | bc。SAC 不支持 wpc。
bpc_weight	SAC 策略参数	行为约束权重，>0 才开启。
critic_pretrain	SAC 策略参数	是否做 critic-only 预训练。
critic_pretrain_epochs	SAC 策略参数	critic-only 预训练的轮数。
critic_target_action_sample_mode	SAC 策略参数	算 critic 目标值时下一步动作怎么取：rsample_with_logprob | rsample | sample。
drop_last_rollout_transition	SAC 策略参数	每段 rollout 少写最后一步 transition，用于对齐 REVIVE 的 buffer_process。
eval_gamma	SAC 策略参数	验证期回报的折扣因子，与训练用的 gamma 分开。REVIVE 的 test_gamma 默认 1.0。
expert_replay_enabled	SAC 策略参数	是否额外维护来自历史数据的经验回放，用于在策略训练时结合已有行为样本。
fixed_checkpoint_dir	SAC 策略参数	固定检查点的存放目录名。
fixed_save_epochs	SAC 策略参数	在这些轮次额外存一份固定检查点。
generate_deter	SAC 策略参数	rollout 是否取分布众数而非采样。REVIVE 默认 1。
policy_forward_action_only	SAC 策略参数	诊断开关：策略前向只执行 action 节点。
policy_rollout_action_mode	SAC 策略参数	rollout 时动作取 sample 还是 mode。默认沿用 revive 的历史行为。
q_network_type	SAC 策略参数	多个 Q 用独立网络（independent）还是向量化 ensemble（vectorize / vectorized）。
replay_sample_rng	SAC 策略参数	replay buffer 的采样 RNG：torch | numpy（numpy 对齐 REVIVE）。
revive_update_order	SAC 策略参数	改用 REVIVE 的更新顺序：critic 更新后立刻 soft update target，再更新 actor。
rollout_clip	SAC 策略参数	rollout 时把节点输出裁剪到 processed 空间的 [-1,1]（对齐 REVIVE）。
segment_sampling_mode	SAC 策略参数	rollout 起点的采样模式，取值同 PPOConfig.segment_sampling_mode。
target_entropy	SAC 策略参数	自动温度的目标熵；None 时按动作维度推导（取 -action_dim）。
w_kl	SAC 策略参数	actor 的 KL(initial_policy ‖ current_policy) 权重。REVIVE 默认 1.0。
detach_after_bootstrap	多步联合训练	bootstrap 阶段之后切断梯度。
detach_history_override	多步联合训练	覆盖历史窗口是否切断梯度；None 表示随算法默认。
direct_sequence_supervision	多步联合训练	直接在序列层面监督，而不是逐步监督。
forced_nodes	多步联合训练	rollout 模式下强制用真值的节点。
initial_state_override	多步联合训练	部署初始状态设置：state 指定状态变量，source 指定数据中的因果估计变量。替换预测起点后仍使用真实标签监督，并将初始偏差计入累计状态损失；null 表示不替换。
integrated_velocity_dims	多步联合训练	该节点的哪几维参与积分。
integrated_velocity_dt	多步联合训练	积分步长。
integrated_velocity_loss_weight	多步联合训练	长时位移目标的权重。指定节点被当作速度向量：预测与目标先还原到原始量纲，选中分量的误差沿时间积分，归一化后的位移误差再与基础序列损失混合。0 表示关闭。
integrated_velocity_node	多步联合训练	被当作速度向量的节点。
integrated_velocity_scales	多步联合训练	各维的归一化尺度。
loss_aggregation	多步联合训练	H 步 loss 的聚合方式：mean | discounted。
loss_discount	多步联合训练	discounted 聚合时的折扣率。
objective	多步联合训练	在原始单位下计算复合序列损失；null 时使用逐步归一化监督损失。可设置 type、node、dims、circular_dims、scales、dim_weights，以及用于累计变化的 displacement 子项。
observed_keys	多步联合训练	rollout 模式下仍从数据读取的键。
sampling_replacement	多步联合训练	窗口采样是否有放回。
state_noise	多步联合训练	训练时向反馈到下一步的状态添加噪声，损失仍使用未加噪的预测计算，帮助模型学习从扰动中恢复。null 表示关闭，仅在 train_mode=rollout 时使用。scale 设置强度，keys 选择状态，unit_pairs 可指定 sin/cos 维度对，以旋转方式加噪并保持单位模长。
step_mode	多步联合训练	每步取值方式：rsample 可重参数采样 | sample | mode。
target_map	多步联合训练	预测键到监督目标键的映射覆写。
trend_loss_half_life_minutes	多步联合训练	趋势项的半衰期，单位分钟。
trend_loss_sample_minutes	多步联合训练	趋势项的采样间隔，单位分钟。
trend_loss_weight	多步联合训练	趋势项损失权重，0 表示关闭。
action_keys	训练阶段	策略动作对应哪些键。空表示取 policy_nodes。
aggregation_mode	训练阶段	多节点误差的汇总方式：dim_weighted 让每个维度权重相同，维度较多的节点贡献较大；node_mean 让每个节点权重相同。
done_key	训练阶段	世界模型输出里哪一个键表示回合终止。该键不存在时按「不终止」处理。
enable_rollout_validation	训练阶段	多步验证开关的兼容字段。当前版本 YAML 使用阶段下的 validation.rollout.enabled。
eval_include_train	训练阶段	策略验证时是否同时评估训练集。默认仅评估验证集；启用后可比较训练集与验证集的回报，但会增加评估开销。
extra	训练阶段	解析后保存算法专属参数的位置。编写 YAML 时将算法参数放入 hyperparameters，无需手动填写 extra。
force_terminal_at_horizon	训练阶段	整段 rollout 未出现 done 时，是否将最后一步标记为终止。标记为终止时 last_value 归零，否则使用 V(s_T) 自举。该设置会影响末端价值估计与回报计算。
init_from_checkpoint	训练阶段	从一个已有 checkpoint 初始化本阶段的权重（venv.revive_p 的 bc 与 adversarial 两侧共用这个值）。None 表示随机初始化。
l2_coef	训练阶段	已弃用。policy_bc.yaml 保留该键，但当前训练实现不读取此值。
logstd_loss_coef	训练阶段	DEPRECATED：同 l2_coef，声明了但无人读取。
migration	训练阶段	异构 graph 的迁移与 preflight 规则。
num_rollout_trajectories	训练阶段	多步验证轨迹数的兼容字段。当前版本 YAML 使用阶段下的 validation.rollout.num_trajectories。
obs_keys	训练阶段	策略观测使用的输入键，按声明顺序在归一化空间拼接。为空时由决策流图推导。
phases	训练阶段	phase 级参数更新配置，仅 algorithm='bc' 时有效。
reward_supervision	训练阶段	把奖励作为监督信号一起训练的配置。
rollout_val_frequency	训练阶段	多步验证频率的兼容字段。当前版本 YAML 使用阶段下的 validation.rollout.interval。
sequence_train	训练阶段	序列训练配置，venv 阶段可选。
state_keys	训练阶段	环境状态节点；None 时由 Graph 的 transition 与算法语义推导。
target_nodes	训练阶段	用于选择目标节点。BC 设置该项会采用策略训练方式；仅调整世界模型的监督目标时，请使用 venv_target_nodes。
venv_target_nodes	训练阶段	世界模型参与损失计算的目标节点。可指定可微函数节点，例如用下一状态特征作为监督目标，让误差沿函数传回上游网络；不改变阶段的训练类型。
plugins	运行设置	可选的内置训练流程插件；缺省不加载插件，保持原训练路径。
dual_environment	可选训练功能	内置双环境流程插件，严格配对，不自动降级为单环境。

修改后确认生效

将调整项写回实际任务的配置文件。在任务目录中执行，config.yaml 替换为自己的文件名：

revive validate --config config.yaml --show-defaults

查看输出中的完整配置，确认参数属于正确的阶段、数值已经生效。配置通过检查后，使用新的运行名称训练，保留原模型和报告；在相同数据、工况和指标下比较选中模型，具体步骤见比较实验结果。

需要了解某个字段时使用 revive info --explain <字段名>。同名字段可能出现在多个算法中，核对输出的算法名称和完整路径后再填写。