自动搜索参数
自动搜索用于批量运行多组参数，并按同一验证指标比较结果。先用单次训练确认数据、图和评价目标，再把已明确的参数范围交给搜索工具，可以减少手动修改配置与整理试验的工作。
确定搜索目标
使用场景
| 您遇到的问题 | 搜索可以帮助什么 | 搜索前先完成什么 |
|---|---|---|
| 世界模型可以训练，但学习率取值不确定 | 比较几个学习率的预测误差 | 固定数据划分、验证长度与训练轮数 |
| 多步预测需要权衡精度与训练开销 | 比较少量推演长度或批量组合 | 明确业务响应时间和内存上限 |
| 策略行为约束强度难以确定 | 比较控制回报与动作偏移 | 固定世界模型、奖励和动作范围 |
| 多台计算卡可供试验使用 | 并行执行独立候选 | 测量单个试验的资源需求 |
例如倒立摆 BC 世界模型已能正常训练，希望在 0.0001、0.0003、0.001 三个学习率中选择一组。可以固定多步 MAE 为选模指标，让搜索依次完成三个试验，再检查误差和训练耗时。本页以这项任务说明操作流程，取值需在自己的数据上比较。
先在 SDK 源码根目录安装可选依赖：
pip install -e ".[tune]"准备 config.yaml 作为基础训练配置，sweep.yaml 描述搜索目标、范围和资源。只比较世界模型时，基础配置可以只保留世界模型阶段；若还保留策略阶段，每个试验也会执行其配置的流程，应计入总成本。
定义参数范围
示例：搜索世界模型学习率
把下面的内容保存为 sweep.yaml。示例使用 CPU 顺序运行三组学习率，可按下一节改为加速器：
sweep:
sweep_id: venv-lr
objective:
- stage: venv
metric: best_metric
direction: minimize
search:
algorithm: grid
n_trials: 3
seed: 42
pruner: {type: none}
resources:
backend: cpu
per_trial: {cpu: 2, gpu: 0}
max_concurrent: 1
params:
- path: training.stages.venv.hyperparameters.optimizer.lr
type: categorical
choices: [0.0001, 0.0003, 0.001]objective.stage 指向基础配置中的阶段名，best_metric 使用该阶段实际选模指标。本例需在阶段中使用误差指标并按最小值选模，因此搜索方向为 minimize；搜索奖励最大值时，目标与阶段选模方向应相应一致。
grid 遍历给定候选，choices 是待比较的具体值。n_trials 是总尝试数量，包含失败和剪枝的试验。首次搜索可以不启用剪枝，让少量候选完成相同训练预算。
在基础配置中声明搜索位置
以下 training 片段需要合入包含图与数据的完整任务配置：
training:
stages:
- name: venv
algorithm: venv.bc
hyperparameters:
optimizer:
lr: 0.0003
validation:
rollout:
enabled: true
horizon: 50
force_final: true
selection:
metric: val/rollout/mae
mode: min搜索路径按阶段的 name 定位，training.stages.venv 表示名为 venv 的阶段，使用列表下标不能替代阶段名称。路径还要沿用户 YAML 中已声明的映射逐级查找，因此本例显式写出 optimizer 和 lr，不能只依赖算法默认值补齐这层结构。
若改用 REVIVE-P，监督学习率路径应为 training.stages.venv.hyperparameters.bc.optimizer.lr，基础配置也需声明对应的 bc.optimizer。参数位置与优先级见查看生效参数。
安排试验与资源
设置并发与设备
先估计一个试验的内存、CPU 和设备需求，再增加并发。使用 CUDA 时，可将上例 resources 替换为：
# sweep 下的 resources 片段
resources:
backend: cuda
gpu_ids: [0, 1]
per_trial: {cpu: 2, gpu: 1.0}
placement: spread
max_concurrent: 2per_trial.cpu 包含试验主进程，所以应满足 data.num_workers <= per_trial.cpu - 1。per_trial.gpu 表示每个试验使用的设备份额；小于 1 可以在同卡上安排多个 worker，但仍需确认显存足够。当前单个试验不支持跨多张卡训练，也不支持基于 Ray 的多机执行。
双环境任务还要在每个试验的资源额度内安排 A/B：加速器调度每个试验分配一张本地卡，分支依次执行；CPU 资源足够时可并行。实际模式见阶段的 dual_environment/execution.json，详细配置见双环境训练。
共享重复的数据准备
多组试验使用相同数据与图时，可以共享加载、派生列、划分和归一化结果，减少重复准备。以下配置放在 sweep 下：
shared_data:
mode: required
storage: mmap
cache_scope: sweep
reuse: true
integrity: content
cleanup: keep默认 mode: auto 会在兼容时共享，不兼容时回退为各试验独立准备。required 要求搜索不改变数据与图的准备约定；搜索 data.path、train_ratio、split_mode、split_seed、转移关系或函数节点定义时，不能强制复用同一份准备结果。
比较模型超参数时，通常固定 data.split_seed。检查不同训练随机性可搜索 training.seed，它与数据划分种子相互独立。
预览并执行搜索
开始前完成安装与授权。在线搜索会按计划试验数申请一次授权， 续跑时保持原 sweep_id、搜索定义和预算；修改试验预算时使用新的 sweep_id。 包含 controller.* 阶段的任务需使用离线许可证。
从任务目录执行，基础配置需通过 data.path 等字段指向已准备的数据：
revive validate --config config.yaml --show-defaults
revive-sweep --config config.yaml --sweep sweep.yaml --plan预览列出搜索路径、目标、试验次数、资源申请和各阶段训练/验证规模。它不读取训练数据、不创建 study 或启动训练；依赖数据才能确定的规模会标为待确定。应先确认基础配置能够独立完成训练，再提交批量搜索。
检查计划后执行：
revive-sweep --config config.yaml --sweep sweep.yaml执行会在运行根目录保存 plan.json。实际并发由启动时资源检查决定；若搜索包含训练预算字段，应按各试验的生效配置统计成本。继续已有 study 时，剩余尝试数量以执行时读取的记录为准。
比较并使用结果
结果位于 <training.log_dir>/<sweep_id>/，其中 optuna.db 保存搜索记录。各阶段在 <domain>/_tune_<stage>/ 汇总：
| 文件 | 用来做什么 |
|---|---|
metrics/leaderboard.csv | 查看候选参数和目标指标 |
metrics/comparison.md、comparison.json | 核对数据、奖励、验证定义、预算与资源是否可比 |
config/best_config.yaml | 使用最优参数覆盖后的任务配置 |
domain 为 venv 或 policy，控制器同样归入 policy 域；stage 为阶段名称。只有成功完成且目标值有限的试验才能作为结果候选，没有可选试验时不会生成最佳配置。
先处理失败，再比较指标
试验记录会区分完成、配置问题、数据问题、数值异常、资源不足、取消和剪枝，并保留错误原因。失败不会被替换成一个低分。若候选普遍因同一错误失败，先修复基础配置或资源设置，再继续搜索。
比较报告只在已知且一致的数据与评价条件内排序。不同组的原始目标值需要先对齐条件，不能直接按数值判断哪组更好。还应查看业务约束、动作分布与耗时，选模指标之外的要求可按业务验收检查。
将候选配置用于正式训练
将选中的 best_config.yaml 复制回任务配置目录，例如命名为 config.best.yaml，核对数据、自定义函数和阶段依赖的相对路径，然后执行：
revive validate --config config.best.yaml --show-defaults
revive train --config config.best.yaml --run-id selected-001用新的 run ID 保留正式结果，按照评估与选择模型检查选中模型，再用预留测试数据评价最终方案。手动对比的记录方法见比较实验结果，完整命令参数见命令行参考。