配置项说明

需要确认某个配置项的用途、类型或默认值时，可以按下面的业务用途查找。如果还没有配置文件，先看编写任务配置；已经能够训练、需要改善效果时，参考配置填写与调整顺序。

查找配置项与默认值

您要设置什么	查看位置
观测、动作、预测关系和网络	变量与模型结构
数据路径、划分、批量和归一化	训练数据
算法、训练轮数、奖励和验证	训练与验证
模型、日志、曲线和 ONNX	模型与日志保存
任务名称和配置说明	任务信息

已知字段名称时，也可在安装 REVIVE 的环境中直接查询：

revive info --explain batch_size
revive info --explain lr

同名参数可能属于不同算法，请同时核对所在位置。字段表列出基础默认值；训练时还会合并所选算法的默认参数和您填写的值。例如学习率应查询算法参数说明，实际取值可通过 revive validate --config config.yaml --show-defaults 确认。

表中“需提供或由配置推导”表示该信息需要确定，不代表必须在 YAML 中重复填写。例如节点名由 graph.nodes 的键给出，列所属的变量由 graph.columns 的键给出。

“任务定义”用于明确业务变量和训练目标，“常用调整”用于改善效果，“专项设置”用于有明确需求的复杂功能。填写与调整顺序见配置填写与调整顺序。

变量与模型结构

这里描述业务量之间的关系。例如冰箱温控的温度、制冷动作和门状态分别对应观测、动作与扰动。变量的名称、列顺序和物理边界应与数据及设备一致。

变量、边界与状态转移

数据列与物理边界

填写在 graph.columns.<变量名>，每一项描述一列。所属变量由外层键确定，列内无需重复填写 node。

配置项	使用需求	类型	基础默认值	说明
name	任务定义	str	需提供或由配置推导	列名，用于标识该维度的物理含义，并对齐数据布局、绘图与动作边界。需与原始数据的维度名称一致。
node	任务定义	str	需提供或由配置推导	该列所属的节点，由 YAML 中 columns 映射的键指定，无需在列定义中重复填写。
type	任务定义	Literal['continuous', 'discrete', 'category']	continuous	列类型：continuous、discrete 或 category，用于确定数值处理与网络输出形式。离散档位需显式声明相应类型及取值集合，例如 landerhover 的四档推力使用 category。
min	任务定义	Optional[float]	null	物理下界，需按执行器或工艺允许范围设置。直接策略模型的 ONNX 导出要求每个动作维度具有显式物理边界，不能用观测统计代替。
max	任务定义	Optional[float]	null	物理上界，要求同 min。应根据执行器或工艺允许范围设置；观测数据的最大值仅表示样本覆盖范围。
num	常用调整	Optional[int]	null	discrete 列的取值个数。
values	任务定义	Optional[List[Any]]	null	category 列的有序取值集合。顺序决定各取值的编码位置，修改后需重新核对模型与数据的兼容性。

决策流图

填写在 graph；多张图使用 graphs.<图名>，由训练阶段选择。

配置项	使用需求	类型	基础默认值	说明
nodes	任务定义	Dict[str, NodeConfig]	{}	单步决策流图的节点定义。节点名同时作为输出变量名，由用户根据任务定义填写。
transitions	常用调整	Union[Literal['auto', 'none'], Dict[str, str]]	auto	状态转移映射。源配置默认使用 auto；解析后的配置及保存的模型记录中使用具体映射。
transition_contract	专项设置	Literal['raw_delta', 'direct_next', 'custom_function']	raw_delta	跨步转移的计算约定。raw_delta（默认）要求由内置 delta 算子组成的显式 delta_<source> 节点；direct_next 允许网络直接预测下一状态；custom_function 允许可微的 raw 空间函数作为转移目标，并通过真实数据检查执行等价性。ADM2 等需要显式 delta 结构的算法不支持 custom_function。
columns	任务定义	Optional[List[ColumnConfig]]	null	各节点的数据列定义，包括列名、类型与物理边界。需与原始数据的列顺序和业务含义对应。
history	常用调整	Optional[Any]	null	历史窗口的全局设置，包括填充方式、输出格式、初始填充和梯度截断。窗口长度在各节点 inputs 中通过 变量@-k 或 变量@[-k:] 声明。
warmup_depth	专项设置	int	0	图级 warmup 深度，0 表示由各节点自动决定。

预测节点与网络

预测节点

填写在 graph.nodes.<节点名>；节点名称来自外层键，类型由是否填写 function 决定，无需单独写 name 或 type。

配置项	使用需求	类型	基础默认值	说明
name	任务定义	str	需提供或由配置推导	节点名，也就是它的输出变量名。
type	专项设置	str	network	节点类型，由配置自动确定。填写 function 时为函数节点，否则为网络节点；用户 YAML 无需填写 type。
inputs	任务定义	List[str]	[]	该节点依次读取的上游输入，用于定义决策流图的依赖关系。由用户按任务填写，支持历史表达式与显式输入引用。
network	常用调整	NetworkConfig	见神经网络	该节点的网络结构，仅用于 network 节点。function 节点通过函数配置定义。
function	任务定义	Optional[FunctionConfig]	null	把该节点定义成确定性函数节点而非网络节点。取内置 key（如 builtin.delta_add）或 <module>:<callable> 形式的 Python 引用。
output_dist	常用调整	str	normal	输出分布，默认为 normal（DiagonalNormal）。动作或策略节点需显式设置 tanh_normal，以将输出限制在 [-1, 1]。预测精度与标准差的校准效果需结合任务验证。
dist_config	专项设置	Optional[Dict[str, Any]]	null	分布的额外配置，如 normal 的 {min_std, max_std}、mix 的 {components: [...]}。
expert_features	专项设置	List[ExpertFeatureConfig]	[]	该节点的专家特征列表。
input_slices	专项设置	Dict[str, str]	{}	输入切片映射：只取上游节点的某几列作为输入。
warmup_inputs	专项设置	Optional[List[str]]	null	warmup 的数据源声明，仅对有状态网络（如 GRU）有效。
warmup_depth	专项设置	int	0	节点级 warmup 深度，0 表示用图级默认。

神经网络

填写在网络节点的 network 中，例如 graph.nodes.actions.network。

配置项	使用需求	类型	基础默认值	说明
backbone	常用调整	str	mlp	骨干网络名称，使用网络注册表中的 mlp、res、gru、transformer 或用户注册的网络。
hidden_dims	常用调整	List[int]	[256, 256]	各隐藏层的宽度。增大宽度可提高模型容量，同时增加计算与显存开销，并可能提高过拟合风险，需结合数据量和验证结果调整。
activation	常用调整	str	leakyrelu	隐藏层激活函数名，默认 leakyrelu，在负半轴保留非零梯度。具体效果需结合网络与数据验证。
dropout	常用调整	float	0.0	Dropout 概率，0 表示禁用，推理时自动关闭。
layer_norm	常用调整	bool	false	是否在隐藏层间加 LayerNorm。
input_embedding	专项设置	Dict[str, Any]	{}	按输入节点配置嵌入维度与融合方式，为空表示不做嵌入。
unified_head	专项设置	Dict[str, Any]	{}	骨干网络与输出头的统一结构参数，为空时各输出分别使用独立输出头。
custom_params	专项设置	Dict[str, Any]	{}	自定义网络的扩展参数。网络专属选项写入 custom_params；放在未定义的位置会提示未知字段。

专家函数与特征

专家函数

函数节点使用 function: package.module:function 引用函数，compute_space 等设置与 function 同级；函数参数写在 function_params。

配置项	使用需求	类型	基础默认值	说明
ref	任务定义	str	需提供或由配置推导	函数引用，如 builtin.delta_add 或 <module>:<callable>。
compute_space	专项设置	Literal['raw', 'processed']	raw	函数在原始空间还是归一化空间求值。
differentiable	任务定义	bool	false	函数是否可微。位于最终 delta 计算路径上的函数节点需声明为可微，使损失梯度可以传回上游网络；不满足时会报告 DeltaContractError。配置示例见 examples/thermal_workflows。
strict_shape	专项设置	bool	true	是否强制校验函数输出形状。
stats_source	专项设置	Literal['auto', 'data', 'function']	auto	该节点的归一化统计量取自数据还是函数自身。
materialize	专项设置	bool	false	是否将构建期用于统计的函数输出写入数据存储，供专家片段读取。默认 false。开启后会增加数据键，并影响基于 next_ 前缀的转移推断和训练器状态键推断；例如 adversarial.ood.x_nodes 需要读取该函数输出时可启用。
params	专项设置	Dict[str, Any]	{}	带参内置函数（如 builtin.delta_add_project）的绑定参数。该配置参与节点配置指纹计算并随模型保存，因此仅支持 JSON 标量与列表，不支持任意 Python 对象。

专家特征

填写在网络节点的 expert_features 中。特征用于补充网络输入，具体用法见专家特征。

配置项	使用需求	类型	基础默认值	说明
name	专项设置	str	需提供或由配置推导	专家特征名。
formula	专项设置	Optional[str]	null	自定义公式，与内置特征互斥。
inputs	专项设置	Optional[List[str]]	null	公式所需的输入列；不写时自动推断。
params	专项设置	Dict[str, float]	{}	公式参数。
learnable	专项设置	bool	false	参数是否随训练更新。

训练数据

在 data 中指定数据路径、划分、批量与归一化。例如希望验证模型能否预测新的运行过程时，可以按完整轨迹划分训练集和验证集。操作步骤见设置训练数据。

数据读取与划分

配置项	使用需求	类型	基础默认值	说明
path	常用调整	Optional[str]	null	训练数据文件路径。可在 YAML 中填写，也可在命令中通过 --train-data 指定；同时设置时以命令行参数为准。
train_ratio	常用调整	float	0.8	训练集占比，其余用于验证。仅在未指定 val_path 时生效，划分方式由 split_mode 决定。整个运行共享一次划分，阶段级参数不单独重新划分数据。
batch_size	常用调整	int	256	每个梯度步的样本数。这是全局默认值，stage 可以按算法各自覆盖。
num_workers	常用调整	int	0	DataLoader 的 worker 进程数，0 表示在主进程里读。只影响吞吐，不改变训练结果。
normalization	常用调整	str	min_max_scaler	归一化方式：min_max_scaler 或 z_score。统计量随模型保存并用于部署。修改统计量会改变模型的输入输出映射，复用与续训时需核对一致性。
split_mode	常用调整	str	outside_traj	训练/验证的切分粒度：outside_traj 按轨迹切（验证集是没见过的轨迹，轨迹级隔离），inside_traj / inside_traj_reverse 在轨迹内部切（同一条轨迹的前后段分属两边，隔离更弱但样本利用率更高）。
paired_split_role	专项设置	Optional[str]	null	异构/配对数据切分中本份数据扮演的角色：None | A | B。仅 outside_traj 有效。
split_seed	专项设置	int	42	数据划分的随机种子，与模型初始化种子分别设置。比较不同初始化或超参数时，可固定该值以保持训练集与验证集不变。
val_path	常用调整	Optional[str]	null	可选的独立验证集文件。设置后训练用 path 全量、验证用 val_path（显式轨迹级 holdout），而不是对 path 内部按 train_ratio 切分；此时 val_split 取 1 - train_ratio。

训练与验证

在 training.stages 中安排世界模型、策略或控制器阶段。阶段名称、算法和依赖写在阶段外层，训练参数写入 hyperparameters，验证设置写入 validation。下表按用途归类；PPO、SAC 和控制器参数的 YAML 层级以算法参数说明为准。

训练阶段与运行设置

运行设置

配置项	使用需求	类型	基础默认值	说明
device	常用调整	str	auto	训练设备：auto、cpu、cuda[:N] 或 npu[:N]。显式指定的设备不可用时会报告错误；auto 按环境探测可用设备。
seed	常用调整	int	42	模型初始化与训练期采样的随机种子，独立于数据划分使用的 data.split_seed。
deterministic	常用调整	bool	true	启用严格确定性算子；相同环境、seed 和执行计划可复现。
cpu_threads	常用调整	int	1	严格复现时固定的主进程 PyTorch CPU 线程数。
log_dir	常用调整	str	logs	全部 run / record / checkpoint / 模型的输出根目录。
run_id	常用调整	Optional[str]	null	运行标识，用于分阶段复用同一目录。标准训练流程通过 CLI 或 RuntimeInputs 指定。
stages	任务定义	List[StageConfig]	[]	训练与控制器阶段列表，按声明顺序执行。
plugins	专项设置	Optional[TrainingPluginsConfig]	null	可选的内置训练流程插件；缺省不加载插件，保持原训练路径。

训练阶段

下表同时包含阶段信息和解析后的训练设置。新增配置按 algorithm、hyperparameters、validation 组织；兼容字段的替代写法见相应说明。

配置项	使用需求	类型	基础默认值	说明
name	任务定义	str	需提供或由配置推导	阶段名。stage 之间靠它互相引用（inherit_from），它同时也是默认的 record_id。
algorithm	任务定义	str	bc	本阶段使用的算法，如 venv.bc、venv.revive_p、policy.ppo 或 controller.ffpid。需填写 AlgorithmRegistry 中注册的完整算法键。
graph	常用调整	Optional[str]	null	可选的 stage 级 graph 名称；为空时用顶层 graph。
inherit_from	任务定义	Optional[str]	null	policy / controller 阶段所依赖的 venv 阶段名。
env_record_id	常用调整	Optional[str]	null	改为依赖一个已导出的 venv record_id，而不是同配置里的 stage。
migration	专项设置	Optional[MigrationConfig]	null	异构 graph 的迁移与 preflight 规则。
node_weights	常用调整	Dict[str, float]	{}	按节点覆盖 venv 阶段的监督损失权重，默认全为 1.0。
policy_nodes	任务定义	List[str]	[]	policy / controller 阶段负责输出动作的节点，必填；其余节点被冻结成环境模型。
target_nodes	专项设置	List[str]	[]	用于选择目标节点。BC 设置该项会采用策略训练方式；仅调整世界模型的监督目标时，请使用 venv_target_nodes。
venv_target_nodes	专项设置	List[str]	[]	世界模型参与损失计算的目标节点。可指定可微函数节点，例如用下一状态特征作为监督目标，让误差沿函数传回上游网络；不改变阶段的训练类型。
frozen_nodes	常用调整	List[str]	[]	显式冻结的节点，训练中不更新其参数。
epochs	常用调整	int	100	本阶段的最大训练轮数。启用早停或 patience 时，训练可能提前结束。
bc_pretrain_epochs	常用调整	int	0	策略优化之前先做多少轮行为克隆预热，0 表示不预热。
rollout_horizon	常用调整	int	20	训练时连续推演的步数，未单独设置验证长度时也用于验证。温控、机械运动等任务的误差积累速度不同，应根据本任务的多步误差曲线选择。可使用 revive suggest-rollout 获取建议；SAC 的训练推演长度使用 rollout_length。
batch_size	常用调整	Optional[int]	null	本阶段的批大小。None 表示沿用 data.batch_size。课程训练可在各阶段分别设置，例如 H=1 时使用 4096、H=200 时使用 256。
optimizer	常用调整	OptimizerConfig	见优化器与学习率	优化器配置。
ppo	常用调整	Optional[PPOConfig]	null	PPO 专属超参，仅 policy.ppo 用。
sac	常用调整	Optional[SACConfig]	null	SAC 专属超参，仅 policy.sac 用。
reward	任务定义	Optional[RewardConfig]	null	奖励函数的来源（文件路径 + 函数名）。策略类算法必填。
reward_supervision	专项设置	Optional[RewardSupervisionConfig]	null	把奖励作为监督信号一起训练的配置。
loss	常用调整	str	nll	主监督损失类型，如 nll / mse。
metric	常用调整	str	loss	用于选择最佳检查点的指标。编写当前版本 YAML 时使用 validation.selection.metric，并设置相应优化方向。
grad_clip	常用调整	float	50.0	梯度范数裁剪阈值。0 表示关闭（个别算法另有自己的关闭语义）。
aggregation_mode	专项设置	str	dim_weighted	多节点误差的汇总方式：dim_weighted 让每个维度权重相同，维度较多的节点贡献较大；node_mean 让每个节点权重相同。
rollout	常用调整	Optional[RolloutConfig]	null	venv 阶段的 rollout 验证配置（嵌套式新格式）。
enable_rollout_validation	专项设置	bool	false	多步验证开关的兼容字段。当前版本 YAML 使用阶段下的 validation.rollout.enabled。
rollout_val_frequency	专项设置	int	50	多步验证频率的兼容字段。当前版本 YAML 使用阶段下的 validation.rollout.interval。
num_rollout_trajectories	专项设置	int	10	多步验证轨迹数的兼容字段。当前版本 YAML 使用阶段下的 validation.rollout.num_trajectories。
sequence_train	专项设置	Optional[SequenceTrainConfig]	null	序列训练配置，venv 阶段可选。
phases	专项设置	List[PhaseConfig]	[]	phase 级参数更新配置，仅 algorithm='bc' 时有效。
controller	常用调整	Optional[ControllerConfig]	null	控制器配置，仅 controller.* 算法用。
state_keys	专项设置	Optional[List[str]]	null	环境状态节点；None 时由 Graph 的 transition 与算法语义推导。
obs_keys	专项设置	List[str]	[]	策略观测使用的输入键，按声明顺序在归一化空间拼接。为空时由决策流图推导。
action_keys	专项设置	List[str]	[]	策略动作对应哪些键。空表示取 policy_nodes。
done_key	专项设置	str	done	世界模型输出里哪一个键表示回合终止。该键不存在时按「不终止」处理。
force_terminal_at_horizon	专项设置	bool	true	整段 rollout 未出现 done 时，是否将最后一步标记为终止。标记为终止时 last_value 归零，否则使用 V(s_T) 自举。该设置会影响末端价值估计与回报计算。
eval_include_train	专项设置	bool	false	策略验证时是否同时评估训练集。默认仅评估验证集；启用后可比较训练集与验证集的回报，但会增加评估开销。
l2_coef	专项设置	float	5e-05	已弃用。policy_bc.yaml 保留该键，但当前训练实现不读取此值。
logstd_loss_coef	专项设置	float	0.01	DEPRECATED：同 l2_coef，声明了但无人读取。
init_from_checkpoint	专项设置	Optional[str]	null	从一个已有 checkpoint 初始化本阶段的权重（venv.revive_p 的 bc 与 adversarial 两侧共用这个值）。None 表示随机初始化。
extra	专项设置	Dict[str, Any]	{}	解析后保存算法专属参数的位置。编写 YAML 时将算法参数放入 hyperparameters，无需手动填写 extra。

阶段间模型继承

配置项	使用需求	类型	基础默认值	说明
mode	专项设置	Literal['by_reference', 'copy_compatible', 'preflight_only']	by_reference	迁移方式：by_reference 直接引用 | copy_compatible 拷贝兼容节点 | preflight_only 只做兼容性检查不迁移。
reuse_policy_nodes	专项设置	bool	true	是否复用已有 artifact 里的策略节点权重。
on_env_mismatch	专项设置	Literal['error', 'warn']	error	环境侧节点不匹配时报错还是告警。
on_policy_mismatch	专项设置	Literal['reinit', 'error', 'warn']	reinit	策略侧节点不匹配时重新初始化、报错还是告警。
norm	专项设置	Literal['strict', 'sync_shared_from_env', 'warn']	strict	归一化统计量的处理：strict 要求完全一致 | sync_shared_from_env 从环境侧同步共享变量 | warn 只告警。
allow_function_to_network_policy	专项设置	bool	true	允许把函数节点迁移成网络策略节点。
allow_network_to_function_policy	专项设置	bool	true	允许把网络节点迁移成函数策略节点。
allow_stateful	专项设置	bool	true	允许迁移有状态网络（如 GRU）。
write_report	专项设置	bool	true	是否保存迁移报告。

学习率与阶段内计划

优化器与学习率

通常填写在阶段的 hyperparameters.optimizer；REVIVE-P 的监督训练设置位于 hyperparameters.bc.optimizer。

配置项	使用需求	类型	基础默认值	说明
type	常用调整	str	adam	优化器类型：adam | adamw。
lr	常用调整	float	0.001	基础学习率。过高可能引起训练震荡或发散，过低可能增加收敛所需轮数，可结合损失与验证曲线调整。
weight_decay	常用调整	float	0.0001	参数权重衰减（L2）系数。可与 dropout 联合使用，正则强度过大时可能导致欠拟合。
scheduler	常用调整	str	cosine	学习率调度器：none | step | cosine | exponential。
lr_decay	常用调整	float	0.99	step / exponential 调度的衰减因子。
scheduler_interval	专项设置	str	epoch	学习率的更新频率：epoch 表示每轮更新，update 表示每次参数更新后调整。update 仅支持 scheduler='cosine'。
eta_min_ratio	专项设置	float	0.0	cosine 调度的学习率下限，按 lr 的比例给出。仅 scheduler_interval='update' 有效。

阶段内训练计划

训练阶段内需要改变轮数或推演长度时，使用 hyperparameters.phases（REVIVE-P 为 hyperparameters.bc.phases），各项按顺序执行，具体组合见设置训练流程。

配置项	使用需求	类型	基础默认值	说明
name	专项设置	str	""	phase 名称。
optimize_nodes	专项设置	List[str]	[]	本 phase 更新哪些节点的参数。
optimizer	专项设置	Optional[OptimizerConfig]	null	本 phase 专用的优化器；None 表示沿用 stage 级配置。
repeat	专项设置	int	1	本 phase 连续重复多少次。

策略与奖励

PPO 策略参数

使用 algorithm: policy.ppo 时，将这些参数填写在 hyperparameters，无需增加 ppo 嵌套层。

配置项	使用需求	类型	基础默认值	说明
dynamics_noise	常用调整	Optional[Dict[str, Any]]	null	仅策略训练期动力学扰动：enabled 默认 false，keys 按状态列配置 raw 单位标准差。
epsilon	常用调整	float	0.2	PPO 裁剪目标中的概率比率裁剪范围，用于限制单次策略更新幅度。
gamma	常用调整	float	0.99	回报与优势估计的折扣因子，有效视界约为 1/(1-gamma)，0.99 对应约百步。取值需结合 rollout 长度与末端价值估计：推演仅 20 步而 gamma=0.999 时，窗口外回报较多依赖自举估计。
gae_lambda	常用调整	float	0.95	GAE 的 lambda：偏差 / 方差的权衡。1 退化成蒙特卡洛回报，0 退化成 TD(0)。
entropy_coef	常用调整	float	0.01	策略熵奖励系数，越大越鼓励探索。也可使用 w_ent；同时填写时以 w_ent 为准。
w_ent	专项设置	Optional[float]	null	entropy_coef 的别名；同时填写时以 w_ent 为准。
value_coef	常用调整	float	0.5	value loss 在 PPO 总目标里的权重。
max_grad_norm	常用调整	float	0.5	PPO actor / value 更新的梯度范数上限。
n_epochs	常用调整	int	10	PPO 更新轮数的兼容配置。当前训练使用 ppo_runs 控制每批推演数据的更新次数，调整时请设置 ppo_runs。
ppo_runs	专项设置	int	2	每批推演数据进行的 PPO 更新轮数。增大后会对同一批数据进行更多次更新。
ppo_batch_num	专项设置	int	8	每批推演数据划分的小批次数，默认 8。与 ppo_runs 共同决定这批数据的更新次数。
ppo_batch_size	专项设置	Optional[int]	null	每个小批次的样本数；未指定时根据训练数据的批量设置计算。
num_rollout_trajs	常用调整	Optional[int]	null	并行 rollout 的轨迹条数；不指定时由 ppo_batch_size 或 data.batch_size 推导。
validation_horizon	常用调整	Optional[int]	null	策略验证的推演步数。未填写时使用训练推演长度：PPO 对应 rollout_horizon，SAC 对应 rollout_length。
w_vl2	专项设置	float	0.001	价值网络的 L2 正则权重（REVIVE: w_vl2）。
bpc_type	专项设置	str	bc	行为约束类型：bc | wpc；bpc_weight>0 时生效。当前 PPO 不支持启用 kl 约束。
bpc_weight	专项设置	float	0.0	行为约束权重，>0 才开启。
generate_deter	专项设置	int	0	rollout 是否用确定性动作（REVIVE: generate_deter，1 为确定性）。
value_hidden_dims	常用调整	List[int]	[256, 256]	value 网络各隐藏层宽度。它与策略网络分开配：value 拟合的是整条轨迹的回报，通常需要比策略更大的容量。
log_ratio_clip_enabled	专项设置	bool	false	是否对 log ratio 做上限裁剪（ratio = exp(clamp_max(log_ratio, max))）。默认关闭以对齐 REVIVE(v1)。
log_ratio_clip_max	专项设置	float	40.0	log ratio 的裁剪上限。
segment_sampling_mode	专项设置	str	timestep_uniform	推演起点的采样方式：trajectory_uniform 按轨迹均匀；segment_uniform 按每条轨迹可容纳的整段数 floor(L_i/H) 加权；timestep_uniform 按合法起点数 L_i-H+1 加权。L_i 为轨迹长度，H 为推演长度。
use_last_value_bootstrap	专项设置	bool	false	是否使用轨迹末端的价值估计补充后续回报。false 将末端价值设为 0；没有终止信号的持续控制任务可评估开启后的效果。

SAC 策略参数

使用 algorithm: policy.sac 时，将这些参数填写在 hyperparameters，无需增加 sac 嵌套层。

配置项	使用需求	类型	基础默认值	说明
dynamics_noise	常用调整	Optional[Dict[str, Any]]	null	仅策略训练期动力学扰动：enabled 默认 false，keys 按状态列配置 raw 单位标准差。
gamma	常用调整	float	0.99	回报与 Bellman target 的折扣因子。
tau	常用调整	float	0.005	target Q 网络的软更新系数：越小目标越慢、越稳。
alpha	常用调整	float	0.2	熵温度。auto_alpha=false 时它是固定值，true 时它只是自动优化的初值。
auto_alpha	常用调整	bool	true	是否自动优化熵温度，使策略熵向 target_entropy 收敛。
target_entropy	专项设置	Optional[float]	null	自动温度的目标熵；None 时按动作维度推导（取 -action_dim）。
actor_lr	常用调整	float	0.0003	Actor 学习率。需结合 Critic 的拟合情况与策略更新稳定性调整。
critic_lr	常用调整	float	0.0003	Critic 学习率，用于调整 Q 值估计的更新速度。
alpha_lr	常用调整	float	0.0003	自动温度参数的学习率。auto_alpha=false 时它不起作用。
buffer_size	常用调整	int	100000	ReplayBuffer 最多存多少条 transition。
batch_size	常用调整	int	256	算法局部 batch size。更大通常更稳，代价是显存。
warmup_steps	常用调整	int	1000	开始正式 actor / critic 更新之前先积累多少条 transition，其间只收数据不更新参数。
updates_per_step	常用调整	int	1	每新增一个 transition 对应做多少次优化更新。
replay_sample_rng	专项设置	str	torch	replay buffer 的采样 RNG：torch | numpy（numpy 对齐 REVIVE）。
q_hidden_dims	常用调整	List[int]	[256, 256]	Q 网络各隐藏层宽度。
q_network_type	专项设置	str	independent	多个 Q 用独立网络（independent）还是向量化 ensemble（vectorize / vectorized）。
num_q	常用调整	int	2	Q 网络个数（集成规模）。target 与 actor 用的是它们的保守聚合。REVIVE 默认 4。
value_hidden_dims	常用调整	List[int]	[256, 256]	value 网络各隐藏层宽度。它与策略网络分开配：value 拟合的是整条轨迹的回报，通常需要比策略更大的容量。
max_grad_norm	常用调整	float	0.0	actor / critic 更新的梯度范数上限，0 表示不裁剪。
rollout_length	常用调整	int	20	每个 epoch 在世界模型中生成的单条轨迹长度，即 SAC 的推演步数。SAC 使用 rollout_length，PPO 使用 stage.rollout_horizon，配置时需选择对应算法的字段。可使用 revive suggest-rollout 在已训练的世界模型上评估建议值。
validation_horizon	常用调整	Optional[int]	null	策略验证的推演步数；None 表示复用该算法的训练长度 rollout_length。
eval_gamma	专项设置	float	1.0	验证期回报的折扣因子，与训练用的 gamma 分开。REVIVE 的 test_gamma 默认 1.0。
num_rollout_trajs	常用调整	int	16	每个训练 epoch 在世界模型里生成多少条轨迹。
segment_sampling_mode	专项设置	str	timestep_uniform	rollout 起点的采样模式，取值同 PPOConfig.segment_sampling_mode。
generate_deter	专项设置	int	0	rollout 是否取分布众数而非采样。REVIVE 默认 1。
policy_rollout_action_mode	专项设置	str	sample	rollout 时动作取 sample 还是 mode。默认沿用 revive 的历史行为。
policy_forward_action_only	专项设置	bool	false	诊断开关：策略前向只执行 action 节点。
critic_target_action_sample_mode	专项设置	str	rsample_with_logprob	算 critic 目标值时下一步动作怎么取：rsample_with_logprob | rsample | sample。
drop_last_rollout_transition	专项设置	bool	false	每段 rollout 少写最后一步 transition，用于对齐 REVIVE 的 buffer_process。
expert_replay_enabled	专项设置	bool	false	是否额外维护来自历史数据的经验回放，用于在策略训练时结合已有行为样本。
batch_ratio	专项设置	float	1.0	SAC batch 里生成 transition 的占比。REVIVE 默认 1。
critic_pretrain	专项设置	bool	false	是否做 critic-only 预训练。
critic_pretrain_epochs	专项设置	int	0	critic-only 预训练的轮数。
revive_update_order	专项设置	bool	false	改用 REVIVE 的更新顺序：critic 更新后立刻 soft update target，再更新 actor。
fixed_save_epochs	专项设置	List[int]	[]	在这些轮次额外存一份固定检查点。
fixed_checkpoint_dir	专项设置	str	fixed_checkpoints	固定检查点的存放目录名。
bc_pretrain_epochs	常用调整	int	0	SAC 优化前的行为克隆预热轮数，用于初始化历史行为附近的策略；0 表示不预热。
bpc_type	专项设置	str	none	行为约束类型：none | bc。SAC 不支持 wpc。
bpc_weight	专项设置	float	0.0	行为约束权重，>0 才开启。
rollout_clip	专项设置	bool	false	rollout 时把节点输出裁剪到 processed 空间的 [-1,1]（对齐 REVIVE）。
w_kl	专项设置	float	0.0	actor 的 KL(initial_policy ‖ current_policy) 权重。REVIVE 默认 1.0。
behavioral_policy_init	专项设置	bool	false	把 venv 阶段训好的 policy 节点权重拷进 SAC 策略作为初始化。对齐 REVIVE 的 behavioral_policy_init=True：策略从行为策略起步，且 KL anchor 锚定到行为策略而不是随机初始化。

奖励函数

配置项	使用需求	类型	基础默认值	说明
path	任务定义	str	""	奖励函数所在的 Python 文件路径，相对配置文件自身的位置。
function	任务定义	str	compute_reward	该文件里奖励函数的名字。

奖励监督

配置项	使用需求	类型	基础默认值	说明
enabled	常用调整	bool	false	是否把奖励作为监督信号一起训练（辅助损失）。
mode	专项设置	str	autograd	梯度获取方式。
apply_to	专项设置	List[str]	["finetune"]	在哪些训练阶段生效。
weight	常用调整	float	0.05	奖励监督这项辅助损失在总损失里的权重。
loss	专项设置	str	smooth_l1	辅助损失的形式。
normalize	专项设置	bool	true	是否对奖励差做归一化。
pred_mode	专项设置	str	mode	预测值取分布众数还是采样。
differentiable_keys	专项设置	Union[str, List[str]]	target_keys	哪些键保持可微；默认与监督目标一致。
detach_unpredicted_inputs	专项设置	bool	true	非预测输入是否切断梯度。
grad_log	专项设置	bool	true	是否记录梯度统计到日志。
eps	专项设置	float	1e-06	数值稳定用的下限。
task_state_weight	专项设置	float	0.05	任务状态项的权重。
reward_consistency_weight	专项设置	float	0.005	奖励一致性项的权重。
sensitivity_min	专项设置	float	0.25	灵敏度裁剪的下界。
sensitivity_max	专项设置	float	4.0	灵敏度裁剪的上界。
support_limit	专项设置	float	1.2	支撑范围的外推上限。
warmup_ratio	专项设置	float	0.3	辅助损失权重线性爬升占总轮数的比例。

多步训练与验证

多步验证

当前 YAML 使用阶段下的 validation.rollout；例如推演步数写作 horizon，执行频率写作 interval。完整写法见评估与选择模型。

配置项	使用需求	类型	基础默认值	说明
enabled	常用调整	bool	true	是否执行多步自回归验证。关闭后不生成该路径的 rollout 指标；需要评价长程预测或闭环效果时，应保留独立的多步验证。
rollout_horizon	常用调整	int	50	验证时自回归推演多少步。必须小于等于验证轨迹长度，否则该指标整条缺失，训练侧会以「配置了却没收到该指标」报错。
rollout_val_frequency	常用调整	int	50	每多少轮做一次 rollout 验证。它比单步验证贵得多，所以通常不是每轮都做。
num_rollout_trajectories	常用调整	int	10	每次验证推演多少条轨迹。条数太少时曲线不单调、拐点会摇摆。
node_clip	专项设置	Optional[float]	null	推演时节点输出的绝对值裁剪，None 表示不裁剪。
expert_action_rollout_enabled	常用调整	bool	false	额外算一组「动作取自数据而非模型」的 rollout 指标。典型用法是 nodes=['actions']，用来单独看动力学的长期误差。
expert_action_rollout_nodes	常用调整	List[str]	[]	上述 rollout 中改用专家（数据）取值的节点。
expert_action_rollout_exclude_nodes	专项设置	List[str]	[]	上述 rollout 中显式排除的节点。
num_rollout_segments	专项设置	int	1024	分层采样时的候选片段数（sampling_mode='segment_stratified'）。
sampling_mode	专项设置	str	segment_stratified	片段采样方式：segment_stratified | trajectory。
segment_select_mode	专项设置	str	bin_random	分层内的选取方式：bin_random | uniform。
min_start_gap	专项设置	Optional[int]	null	同一条轨迹上两个片段起点的最小间隔。
allow_reduce_segments	专项设置	bool	true	候选片段不足时允许自动减少数量而不是报错。
segment_seed	专项设置	int	42	片段采样的随机种子。
mae_scale_decay	专项设置	float	1.0	逐步衰减率：第 t 步的权重为 decay^t。1.0 表示各步等权。
wdist_test	专项设置	bool	false	是否计算 Wasserstein 距离（看分布保真度，计算较慢）。
primary_metric_node	常用调整	Optional[str]	null	面向任务的主指标算在哪个节点上（原始量纲）。
primary_metric_dims	常用调整	List[int]	[]	主指标计算使用的节点维度，留空表示全部维度。可选择业务关注的物理量作为模型选择依据，避免全维平均掩盖关键维度的误差变化。
primary_metric_circular_dims	专项设置	List[int]	[]	其中哪几维是角度类（按周期求差）。
primary_metric_scales	专项设置	List[float]	[]	各维的归一化尺度；应当只用训练集统计。
primary_metric_dim_weights	专项设置	List[float]	[]	各维在主指标里的权重。
primary_metric_trajectory_macro	专项设置	bool	false	按轨迹先聚合再平均（宏平均），而不是所有步一起平均。
integrated_displacement_metric_node	专项设置	Optional[str]	null	位移指标：把原始空间的速度预测误差沿 rollout 积分，得到不依赖 GPS 的位移偏差。
integrated_displacement_metric_dims	专项设置	List[int]	[]	位移指标看哪几维速度。
integrated_displacement_metric_dt	专项设置	Optional[float]	null	积分步长；None 表示由数据推断。
integrated_displacement_metric_scales	专项设置	List[float]	[]	位移指标各维的尺度。
integrated_displacement_metric_weight	专项设置	float	0.0	位移指标在综合指标里的权重，0 表示只记录不参与。

多步联合训练

填写在 hyperparameters.sequence_train；REVIVE-P 的相应设置位于 hyperparameters.bc.sequence_train。

配置项	使用需求	类型	基础默认值	说明
enabled	常用调整	bool	false	是否启用多步联合优化。关闭时仅进行单步监督训练；多步推演表现需要单独验证。
horizon	常用调整	int	100	一次联合优化累加多少步的 loss（H）。venv.revive_p 下它同时也是判别器看到的序列长度。加大它会明显抬高显存与计算量，batch_size 通常要反向调。
train_mode	常用调整	str	tf	多步训练的输入模式。tf 使用教师强制，每步输入真实值；rollout 使用自回归，每步输入前一步的预测值，用于在训练中考虑误差累积。
observed_keys	专项设置	List[str]	[]	rollout 模式下仍从数据读取的键。
forced_nodes	专项设置	List[str]	[]	rollout 模式下强制用真值的节点。
detach_after_bootstrap	专项设置	bool	false	bootstrap 阶段之后切断梯度。
detach_history_override	专项设置	Optional[bool]	null	覆盖历史窗口是否切断梯度；None 表示随算法默认。
step_mode	专项设置	str	rsample	每步取值方式：rsample 可重参数采样 | sample | mode。
loss_aggregation	专项设置	str	mean	H 步 loss 的聚合方式：mean | discounted。
loss_discount	专项设置	float	1.0	discounted 聚合时的折扣率。
target_map	专项设置	Dict[str, str]	{}	预测键到监督目标键的映射覆写。
direct_sequence_supervision	专项设置	bool	false	直接在序列层面监督，而不是逐步监督。
initial_state_override	专项设置	Optional[Dict[str, str]]	null	部署初始状态设置：state 指定状态变量，source 指定数据中的因果估计变量。替换预测起点后仍使用真实标签监督，并将初始偏差计入累计状态损失；null 表示不替换。
trend_loss_weight	专项设置	float	0.0	趋势项损失权重，0 表示关闭。
trend_loss_sample_minutes	专项设置	float	5.0	趋势项的采样间隔，单位分钟。
trend_loss_half_life_minutes	专项设置	float	30.0	趋势项的半衰期，单位分钟。
integrated_velocity_loss_weight	专项设置	float	0.0	长时位移目标的权重。指定节点被当作速度向量：预测与目标先还原到原始量纲，选中分量的误差沿时间积分，归一化后的位移误差再与基础序列损失混合。0 表示关闭。
integrated_velocity_node	专项设置	Optional[str]	null	被当作速度向量的节点。
integrated_velocity_dims	专项设置	List[int]	[]	该节点的哪几维参与积分。
integrated_velocity_dt	专项设置	float	1.0	积分步长。
integrated_velocity_scales	专项设置	List[float]	[]	各维的归一化尺度。
batches_per_epoch	常用调整	Optional[int]	null	每轮抽取 batch_size × batches_per_epoch 个窗口，在合法起点中有放回均匀抽样。null 表示每轮无放回遍历全部合法窗口。
sampling_replacement	专项设置	bool	false	窗口采样是否有放回。
objective	专项设置	Optional[Dict[str, Any]]	null	在原始单位下计算复合序列损失；null 时使用逐步归一化监督损失。可设置 type、node、dims、circular_dims、scales、dim_weights，以及用于累计变化的 displacement 子项。
state_noise	专项设置	Optional[Dict[str, Any]]	null	训练时向反馈到下一步的状态添加噪声，损失仍使用未加噪的预测计算，帮助模型学习从扰动中恢复。null 表示关闭，仅在 train_mode=rollout 时使用。scale 设置强度，keys 选择状态，unit_pairs 可指定 sin/cos 维度对，以旋转方式加噪并保持单位模长。

控制器

控制器通用设置

通过阶段的 algorithm: controller.<类型> 选择控制器，所需参数直接填写在 hyperparameters，无需再增加 controller 嵌套层。

配置项	使用需求	类型	基础默认值	说明
type	常用调整	str	mpc	控制器种类：mpc | ffpid | residual_pid。
mpc	常用调整	Optional[MPCControllerConfig]	null	MPC 专属参数。
ffpid	常用调整	Optional[FFPIDControllerConfig]	null	FFPID 专属参数。
residual_pid	常用调整	Optional[ResidualPIDControllerConfig]	null	ResidualPID 专属参数。
tune	常用调整	Optional[ControllerTuneConfig]	null	自动调参配置。
action_bounds	常用调整	Optional[Dict[str, List[float]]]	null	显式 actuator 边界 {列名: [下界, 上界]}；不填时只接受 graph 列定义里的边界。

控制器参数搜索

配置项	使用需求	类型	基础默认值	说明
enabled	常用调整	bool	true	是否自动调参。关掉则直接用配置里的增益。
objective	常用调整	str	reward_mean	控制器参数搜索的排序指标，决定候选增益按跟踪误差或回报等指标比较。
mode	专项设置	str	two_stage	搜索模式。two_stage 先用 fast_eval_segments 粗筛，再对 top_k 用 full_eval_segments 复评。
max_trials	常用调整	int	40	搜索的试验总数，直接决定调参耗时。
top_k	专项设置	int	5	粗筛后进入复评的候选个数。
fast_eval_segments	专项设置	int	64	粗筛阶段的评估片段数。
full_eval_segments	专项设置	int	256	复评阶段的评估片段数。
eval_horizon	常用调整	int	100	各评估片段在世界模型中的推演步数。需覆盖任务相关的响应过程，可参考被控对象的 t63 选择初值。
seed	常用调整	int	42	调参搜索的随机种子。换它会换出一组不同的候选，因而是可比性的一部分。
search	专项设置	Dict[str, List[Any]]	{}	搜索空间覆写：{参数名: [候选值...]}，为空则用算法内置空间。

MPC 控制器

配置项	使用需求	类型	基础默认值	说明
method	常用调整	str	cem	规划算法，可选 cem（交叉熵方法）、mppi（加权平均）或 random（随机采样搜索）。三种算法均由 MPCPlannerKernel 实现。
horizon	常用调整	int	10	MPC 每次规划的步数，需结合系统时滞与响应时间设置。例如 three_tank 中 h2 对泵的 t63 为 109 个控制步；规划窗口较短时，泵能耗已计入奖励而液位改善尚未出现，可能影响候选动作的选择。
num_samples	常用调整	int	100	每轮采样的候选动作序列条数。它和 num_iterations 一起决定单个控制步的规划开销。
num_elites	专项设置	int	10	CEM 每轮保留多少条精英用于更新采样分布。仅 method=cem 有效。
num_iterations	常用调整	int	5	每个控制步的搜索迭代次数。仅 cem 与 mppi 有效，random 只打一轮。
temperature	专项设置	float	1.0	仅 method=mppi 有效：候选按 softmax(return / temperature) 加权平均。cem 走的是 topk 硬选择，根本不读这个值。必须为正。
gamma	常用调整	float	0.99	规划期内累计回报的折扣因子，与 horizon 共同决定远期收益的权重。gamma 较小时，窗口末端奖励的影响减弱。
deterministic	专项设置	bool	true	规划时世界模型取分布均值（true）还是采样（false）。取均值让同一状态下的规划可复现。
use_policy_prior	专项设置	bool	true	初始采样分布是否以已训练的策略为先验。关掉则从动作区间中点 ± 半量程起步。
clip_actions	专项设置	bool	true	每次生成候选后是否裁剪到 action_bounds 内。
warm_start	专项设置	bool	true	是否平移上一控制步的最优动作序列，用于初始化当前搜索。CEM 的 top-k 选择可能因 PyTorch 与 ONNX 间 1e-7 量级的浮点差而变化，暖启动会继续传递该差异，影响 parity 验证。需要数值一致性验证时应关闭，并按部署指南检查搜索结构的限制。
future_exogenous_keys	常用调整	List[str]	[]	规划期内可预知的外生变量列，例如天气预报和排产负载。模型调用端必须提供所列节点的未来序列。MPC 使用这些信息进行规划；单回路 PID 通常根据当前误差生成控制量。
seed	常用调整	int	0	候选动作采样的随机种子。CEM / MPPI 每步都在采样，固定它才让同一状态下的规划可复现。

前馈 PID 控制器

配置项	使用需求	类型	基础默认值	说明
kp	常用调整	float	1.0	比例增益，必须非负。当前配置校验要求 kp、ki、kd 均大于等于 0，因此无法通过 YAML 配置需要负增益的反作用过程，例如功率增大、温度下降的制冷过程。
ki	常用调整	float	0.0	积分增益，必须非负。用于减小恒定设定值下的稳态偏差。
kd	常用调整	float	0.0	微分增益，响应误差的变化率，给闭环增加阻尼。必须非负。
kff	常用调整	float	0.0	前馈增益，直接乘设定值（不是测量值）：action += kff * setpoint。它绕过反馈回路直接提供一部分控制量，所以能在误差还没建立起来时就动作。
integral_limit	常用调整	Optional[float]	null	积分状态的绝对值上限，None 表示不限。用来抑制 windup。
output_limit	常用调整	Optional[float]	null	控制量输出的绝对值上限，None 表示只受 action_bounds 约束。
derivative_filter_tau	专项设置	float	0.0	微分项的一阶低通时间常数，0 表示不滤波。测量带噪时不滤波会让微分项把控制量抖起来。
anti_windup	专项设置	str	clamp	输出饱和时的抗积分饱和策略。
setpoint_key	常用调整	Optional[str]	null	输入状态里哪一个键是目标设定值；None 表示由 stage 另行提供。
measurement_key	常用调整	Optional[str]	null	输入状态里哪一个键是被控量（反馈测量）。它和 setpoint_key 一起定义误差：error = setpoint - measurement。

残差 PID 控制器

配置项	使用需求	类型	基础默认值	说明
kp	常用调整	float	0.0	残差项的比例增益。必须非负，同 FFPID。
ki	常用调整	float	0.0	残差项的积分增益，消除常值设定值下的稳态偏差。必须非负。基线取零时慎用：那时残差就是指令本身，积分项会累出退不掉的偏置。
kd	常用调整	float	0.0	残差项的非负微分增益。测量噪声较大时可结合 derivative_filter_tau 抑制动作抖动。
target	常用调整	float	0.9	被控量的设定值。当前增益要求非负，仅支持与该增益方向匹配的被控量；需要负增益的反作用过程暂时无法通过 YAML 配置。
delta_max	常用调整	float	0.05	残差相对基线动作的最大偏移量。默认值按加氯任务量纲设置，其他任务需根据允许偏移范围重新确定。上限不足以覆盖目标动作时，输出可能持续饱和。
rate_limit	常用调整	float	0.01	相邻两步残差的最大变化量，需根据执行器能力与控制周期设置。vehicle_acc 示例中，每步 0.5 m/s² 的限制使加速度从 0 降到 -3 m/s² 需要 6 步（1.2 s），会影响急刹场景的可行控制范围。平滑偏好可另用奖励代价表达，硬限制需单独验证。
i_max	常用调整	float	0.05	积分项贡献的绝对值上限，用来抑制 windup。它和 delta_max 一样按任务量纲定。
sample_dt_h	常用调整	float	0.08333333333333333	控制周期，单位小时。积分与微分项按它换算，所以它必须与增益标定时用的周期一致。
measurement_key	常用调整	Optional[str]	null	输入状态里哪一个键是被控量。内核算 error = target - measurement。
baseline	专项设置	Optional[Dict[str, Any]]	null	专家基线动作的来源，包括 callable、参数与来源约定。None 表示使用零动作为基线，此时残差即为输出指令。

双环境训练

可选训练功能

配置项	使用需求	类型	基础默认值	说明
dual_environment	专项设置	DualEnvironmentConfig	见双环境训练设置	内置双环境流程插件，严格配对，不自动降级为单环境。

双环境训练设置

配置项	使用需求	类型	基础默认值	说明
enabled	专项设置	bool	false	显式开启双环境训练流程插件；默认始终关闭。
policy_mode	专项设置	Literal['dual', 'single']	dual	dual 独立训练两套策略；single 为两套环境、一套策略的轻量模式。
stages	专项设置	List[str]	[]	参与插件的阶段名；空列表表示所有阶段，首期仅支持 BC/REVIVE-P/PPO/SAC。
seed_offset	专项设置	int	100000	B 分支的训练随机种子偏移，不参与数据切分或交叉验证采样。
allow_validation_training	专项设置	bool	false	使用独立验证文件训练 B 分支须显式同意；该文件不再是独立留出测试集。
validation	专项设置	DualEnvironmentValidationConfig	见交叉验证	交叉验证与矩阵诊断配置，选模沿用统一验证引擎。
efficient_output	常用调整	bool	true	仅 legacy：双环境低频 latest、关闭归档、阶段末导出指标；best_only 始终只保留最优轮次。
execution	常用调整	DualEnvironmentExecutionConfig	见分支资源分配	开启双环境后按任务资源自动选择串行或并行；显式 serial/parallel 优先。cpu_per_branch 限制每分支线程数，GPU 并行须指定两张不同且已分配的设备。
quality_rules	专项设置	List[DualEnvironmentQualityRule]	[]	选中模型的业务质量拒绝规则；空列表明确表示未配置质量门槛。

交叉验证

配置项	使用需求	类型	基础默认值	说明
full_matrix	专项设置	bool	true	输出同一初始状态面板上的完整交叉矩阵；关闭时仍执行交叉选模。
seed	专项设置	int	42	交叉验证的固定随机种子；与分支训练和数据切分随机流相互独立。
diagnostic_interval	专项设置	int	0	完整矩阵的独立轮数间隔；0 仅在阶段末对选中模型补评，1 沿用逐轮诊断。

分支资源分配

配置项	使用需求	类型	基础默认值	说明
mode	常用调整	str	auto	默认 auto：单卡串行，明确分配双卡且 CPU 额度足够时并行；可显式设 serial/parallel。
cpu_per_branch	常用调整	int	1	并行执行时，每个分支可使用的 CPU 线程数。
devices	专项设置	List[str]	[]	明确分配的两个逻辑设备；空列表在加速器上只使用 training.device，不自动占用其他卡。

分支质量要求

配置项	使用需求	类型	基础默认值	说明
domain	专项设置	str	venv	venv 或 policy。
metric	专项设置	str	""	必须实际产出的 canonical 指标。
minimum	专项设置	Optional[float]	null	选中交叉格的指标下限。
maximum	专项设置	Optional[float]	null	选中交叉格的指标上限。
max_environment_gap	专项设置	Optional[float]	null	策略在同一起点面板的两个环境上的指标绝对差上限。

模型与日志保存

在 output 中选择保存模型、训练状态、曲线与 ONNX 的方式。需要恢复训练时保留完整训练状态；部署时使用模型目录。当前 YAML 的绘图和 ONNX 设置分别放在 output.plotting、output.onnx，完整写法见保存模型与日志。

模型、报告与日志

配置项	使用需求	类型	基础默认值	说明
checkpoint_policy	常用调整	str	best_only	best_only 仅覆盖最优模型及同轮续训态；legacy 兼容旧周期保存。
allow_research_snapshots	专项设置	bool	false	显式允许有 max_snapshots 上限的判别器研究快照；训练检查点仍只保留 best。
save_freq	常用调整	int	1	legacy 历史归档间隔；best_only 忽略此字段。
checkpoint_interval	常用调整	Optional[int]	null	仅 legacy：latest 保存轮数间隔；普通训练默认 1、双环境默认 10。
checkpoint_seconds	常用调整	Optional[float]	null	仅 legacy：latest 时间间隔，epoch 边界检查；0 关闭时间触发。
archive_interval	常用调整	Optional[int]	null	仅 legacy：历史归档间隔；0 关闭；双环境默认 0。
metrics_backend	常用调整	str	auto	auto/snapshots/final/tensorboard：每轮快照、结束导出或仅事件历史。
checkpoint_mirrors	专项设置	str	auto	auto/commit/final：兼容 checkpoint 文件每次提交或结束时生成。
tensorboard_queue	专项设置	int	256	TensorBoard 待写事件队列大小。
tensorboard_flush_secs	专项设置	int	10	TensorBoard 刷新间隔（秒）。
tensorboard	常用调整	bool	true	是否写 TensorBoard 事件文件。
export_onnx	常用调整	bool	true	训练结束后是否导出 ONNX。标准训练流程要求该项与 require_onnx 同时启用，导出及所要求的验证通过后才能选为运行级模型。
require_onnx	常用调整	bool	true	导出失败时是否判 stage 失败并挡住 promotion。关掉等于允许产出不可部署的模型，而这件事只有到上线那天才会被发现。
onnx_opset	专项设置	int	17	ONNX opset 版本。
onnx_io_space	专项设置	str	raw	ONNX 的输入输出单位：raw 使用原始物理量，processed 使用归一化值。选择 raw 时，归一化计算包含在导出模型中，业务程序按原始单位提供输入。
onnx_validate	专项设置	str	parity	导出验证等级：checker 检查结构，runtime 检查 ONNX Runtime 执行，parity 比较 PyTorch 与 ONNX 数值，none 不验证。MPC 的 CEM top-k 选择不连续，1e-7 量级的浮点差可能改变精英集合，单纯放宽 atol 不能保证搜索结果一致；具体要求见输出配置指南。
onnx_export_dtype	专项设置	str	keep	ONNX 导出时的计算精度：keep 保持模型精度，float32 或 float64 指定导出精度。
onnx_atol	专项设置	float	1e-05	PyTorch / ONNX parity 与 runtime 校验的绝对误差容限。
onnx_rtol	专项设置	float	0.0001	PyTorch / ONNX parity 与 runtime 校验的相对误差容限。
export_pkl	专项设置	bool	true	DEPRECATED：保留仅为兼容旧 YAML 解析，不控制任何导出行为。
plot_external_inputs	常用调整	bool	false	趋势图里是否一并画出外生输入列。
trend_plot	常用调整	bool	true	是否生成训练趋势图。
trend_plot_interval	常用调整	int	10	趋势图每多少轮更新一次。
enable_plotting	常用调整	bool	true	训练绘图总开关。false 时关闭 best、trend 和 openloop 绘图，可减少文件读写与绘图开销。

任务信息

在配置文件顶层填写任务名称、格式版本和说明，并通过 graph、data、training、output 组织各部分。version 表示配置格式版本，与安装的 SDK 版本分别管理。

任务名称与配置入口

配置项	使用需求	类型	基础默认值	说明
name	常用调整	str	default	配置名称，用于日志与输出文件命名，并保存在 config.resolved.yaml 中。
version	常用调整	str	2.0	用户配置的格式版本，独立于 revive 软件包版本管理。升级软件包不会自动修改该值。
description	常用调整	str	""	给人读的说明，不影响训练。
graph	任务定义	GraphConfig	见决策流图	图结构与列定义：这个任务有哪些量、谁依赖谁。用命名图（graphs）时它是默认那张。
graphs	常用调整	Dict[str, GraphConfig]	{}	命名图集合，供不同 stage 用 stage.graph 各自挑一张。
data	常用调整	DataConfig	见数据读取与划分	数据来源、训练/验证划分与归一化。
training	任务定义	TrainingConfig	见运行设置	设备、随机种子与 stage 序列。
output	常用调整	OutputConfig	见模型、报告与日志	checkpoint、绘图与 ONNX 导出。
uncertainty	专项设置	Any	见不确定性设置	不确定性估计配置。