命令行参考

本页列出 revive、revive1 train 与 revive-sweep 的命令和参数。常用参数直接显示，其余参数按需展开；两部分合起来覆盖全部参数，同一命令的参数说明只列一次。只想知道一次任务按顺序用哪几条命令，见命令行工具。

bash

revive --version  # 查看当前版本
revive --help     # 查看命令列表
revive train --help  # 查看某条命令的参数

全局参数

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--version` `-V`	显示版本信息	`false`	可选，开关，无需附值
`--lang`	消息语言，默认中文；也可用环境变量 REVIVE_LANG	— `zh` / `en`	可选

全局参数写在子命令之前，例如 revive --lang en train --config config.yaml。

要完成的操作	命令
从数据创建任务配置骨架	`revive init`
查看数据、配置和字段说明	`revive info`
检查配置与数据能否用于训练	`revive validate`
执行训练、验证与模型导出	`revive train`
使用旧 YAML/NPZ 启动 2.0 基础训练	`revive1 train`
批量搜索和比较超参数	`revive-sweep`
查看和整理一次训练的结果	`revive report`
构建或检查模型的不确定性信号	`revive uncertainty`
根据数据辅助检查变量边界	`revive suggest-bounds`
根据预测误差辅助选择推演长度	`revive suggest-rollout`
将 PT 部署模型导出为 ONNX	`revive export`
保存在线授权 access key	`revive register`
配置许可证与查看授权信息	`revive license`
迁移本项目早期 2.0 配置格式	`revive migrate-config`

文档统一使用长参数名。相对文件路径请结合命令所在目录和配置文件位置填写。

数据与配置

`revive init`

从数据创建任务配置骨架。

bash

revive init \
  --data train.npz \
  --state states \
  --action actions \
  --out config.min.yaml

从数据生成一份可直接用于 validate / train 的最小配置，以及一份 reward 模板。

指定状态与动作

省略 --state / --action 时，init 会列出数据中的变量与维度，然后以退出码 1 退出：

text

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

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

状态与动作需要用户根据任务定义指定。恰好存在两个建模变量时，工具会按维度提供提示，用户核对后可填写参数重新执行。

生成结果中必须人工复核的两处

列名为占位名（states_0、actions_1 等）。它们会出现在日志、图表与 ONNX 输入名中，建议修改为对应物理量名称，便于解释训练和部署结果。
动作边界取自数据分布（观测半幅 × --bounds-ratio，默认 1.5），计算方法与 suggest-bounds 一致。应按执行器的真实物理上限修正：数据中未出现的动作不代表执行器无法达到。

reward.py 为占位实现。奖励定义了「什么是好的表现」，框架无法推断，训练前必须替换。

生成之后

bash

revive validate --config config.min.yaml --train-data train.npz
revive validate --config config.min.yaml --train-data train.npz --show-defaults

--show-defaults 显示完整生效配置，用户可以据此查看未显式填写字段的取值。

最小配置

常用参数

参数	作用	默认值 / 取值	使用条件
`-d` `--data`	训练数据文件路径 (npz / hdf5)	—	必填
`--state`	状态变量名；省略时列出数据中的可选变量并退出	—	可选
`--action`	动作变量名；省略时列出数据中的可选变量并退出	—	可选
`-o` `--out`	输出配置路径（默认 config.min.yaml）	`config.min.yaml`	可选

其余参数与命令格式

text

usage: revive init [-h] -d DATA [--state STATE] [--action ACTION] [-o OUT]
                   [--venv-only] [--bounds-ratio BOUNDS_RATIO] [--force]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--venv-only`	只生成世界模型阶段，不生成策略阶段与 reward 模板	`false`	可选，开关，无需附值
`--bounds-ratio`	动作边界 = 观测半幅 × ratio（默认 1.5）	`1.5`	可选
`--force`	覆盖已存在的输出文件	`false`	可选，开关，无需附值

`revive info`

查看数据、配置和字段说明。

查看 NPZ/HDF5 数据：

bash

revive info --data train.npz

查看配置摘要：

bash

revive info --config config.yaml

info 用于快速确认键名、形状、数据类型、轨迹边界与配置概要，不能替代带数据的 validate。

按分层查询字段说明：

bash

revive info --explain data.batch_size
revive info --tier basic

常用参数

参数	作用	默认值 / 取值	使用条件
`-d` `--data`	数据文件路径	—	可选
`-c` `--config`	配置文件路径	—	可选

其余参数与命令格式

text

usage: revive info [-h] [-d DATA] [-c CONFIG] [--test-matrix] [--explain 字段名]
                   [--tier {basic,advanced,expert}] [--evidence]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--test-matrix`	打印验收矩阵（算法 × 三层测试）	`false`	可选，开关，无需附值
`--explain`	解释一个配置字段：分层、默认值、说明、它属于哪个配置块	—	可选
`--tier`	列出某一层的全部字段	— `basic` / `advanced` / `expert`	可选
`--evidence`	与 --test-matrix 同用：逐条列出证据	`false`	可选，开关，无需附值

`revive validate`

检查配置与数据能否用于训练。

该命令不申请在线许可证。首次在线用户先按安装与授权取得许可证，或配置离线许可证，再执行涉及受保护 SDK 功能的预检。

静态验证

bash

revive validate --config config.yaml

检查 YAML 字段、算法键、默认值合并、Stage 依赖与路径解析。缺少数据时无法确认实际维度、归一化、函数输出与 ONNX 输入边界。

深度验证

bash

revive validate \
  --config config.yaml \
  --train-data train.npz \
  --val-data val.npz \
  --seed 42

深度验证会真实执行以下流程：

text

读取轨迹
→ 校验并派生 transition
→ 数据划分与统计
→ 构建每个 Stage 的图
→ 探测自定义网络/函数/reward/baseline
→ 验证 validation plan
→ 检查部署与 ONNX contract

该命令不创建训练 run，也不写入 log_dir。preflight 报出的问题会在训练启动时同样触发，请在这一步修复后再开始训练。

常见失败原因

未知字段（配置里有未知字段: ...（是不是想写 ...？））：字段位置或算法名拼写错误。
缺少动作边界（phase=onnx_action_bounds ... missing=[...]）：需为动作 columns 声明物理 min/max，数值应来自设备规格而非数据统计。
维度不匹配：NPZ 最后一维与 columns 声明或函数实际输出不一致。
奖励加载失败：路径以 config 文件为基准解析，检查函数名与张量接口要求。
ONNX tracing 失败：自定义 callable 中使用了 NumPy、.item()、I/O 或依赖张量取值的分支。

主流程第 2 步

常用参数

参数	作用	默认值 / 取值	使用条件
`-c` `--config`	配置文件路径 (YAML 格式)	—	必填
`-d` `--data` `--train-data`	训练数据文件路径 (可选，验证数据与配置的兼容性)	—	可选
`--val-data`	独立验证数据文件路径 (可选)	—	可选
`--log-dir`	解析日志目录但不创建或修改它	—	可选
`--run-id`	解析运行 ID	—	可选
`--seed`	解析随机种子	—	可选
`--resume`	只读解析 continuation checkpoint，不执行训练	—	可选
`--profile`	按该档位解析后再验证；配合 --show-defaults 可先看清档位到底改了哪几个值	— `smoke`	可选

其余参数与命令格式

text

usage: revive validate [-h] -c CONFIG [-d DATA] [--val-data VAL_DATA]
                       [--log-dir LOG_DIR] [--run-id RUN_ID] [--seed SEED]
                       [--resume RESUME] [--show-defaults] [--explain 字段]
                       [--level {basic,advanced,expert}] [--profile {smoke}]
                       [--data-health]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--show-defaults`	列出每个 stage 超参的生效值及其来源（配置文件 / 算法默认 / 运行时输入）	`false`	可选，开关，无需附值
`--explain`	查询单个字段的生效值与来源，可只给字段名（如 lr）或路径后缀（如 optimizer.lr）	—	可选
`--level`	配合 --show-defaults：只列到这一层为止（basic 只看必写项，advanced 再加上业务专家会调的，expert 全列）。level 是门槛不是标签。	— `basic` / `advanced` / `expert`	可选
`--data-health`	只读数据建模体检，不训练	`false`	可选，开关，无需附值

训练与搜索

`revive train`

执行训练、验证与模型导出。

运行前先完成授权配置：在线用户保存 access key，离线用户安装许可证或设置 REVIVE_LICENSE。短训练同样会执行训练和授权流程。

bash

revive train \
  --config config.yaml \
  --train-data train.npz \
  --val-data val.npz \
  --log-dir logs \
  --run-id experiment-001 \
  --seed 42

命令会执行 YAML 中的全部 Stage，不支持通过 CLI 选择子集或覆盖设备/学习率。只需运行单个 Stage 时，可使用相应完整配置与分阶段接口，见任务入口。流程验证可使用下文的 --profile smoke。

`--profile smoke`：预先验证流程连通性

bash

revive train --config config.yaml --train-data train.npz --profile smoke

该模式缩减训练轮数等运行规模，用于检查当前配置能否完成训练、验证与导出。算法、节点、列名、边界、损失、reward 和优化器保持原配置。实际耗时取决于任务与设备。

由此产生两条性质：

只减不增。覆写取 min(配置值, 档位值)，档位不会使任何一次运行变得更慢更重。
保留 rollout_horizon 与验证设置。前者改变指标的测量范围，后者改变检查点的选取依据——两者改变的都是结论的含义，而非仅仅是精度。

如需预先查看档位实际修改了哪些值，无需真实运行：

bash

revive validate --config config.yaml --train-data train.npz --profile smoke --show-defaults

smoke 模型用于流程验证。缩减训练轮数可能改变候选模型与选模结果，模型效果应在正式配置下评估。 CLI 会显示模式提示，config.resolved.yaml 的 runtime_metadata.profile 也会记录该设置。

恢复训练

bash

revive train --config config.yaml --run-id experiment-001 --resume best

默认从最优轮次的完整状态恢复，也可指定 checkpoints/best_train_state.pt 或 record selector。旧 legacy 记录仍支持 --resume latest，详见精确续训。

退出语义

配置、数据、preflight、训练、验证、导出或 required ONNX 任一环节失败都会返回非零状态。不应仅凭日志中出现过某个 checkpoint 就判断 run 成功；应以 record_info.json.status=completed 与 run 级 promoted model 为准。

主流程第 3 步

常用参数

参数	作用	默认值 / 取值	使用条件
`--config`	配置文件路径 (YAML 格式)	—	必填
`--train-data`	训练数据文件路径 (覆盖配置文件中的路径)	—	可选
`--val-data`	独立验证数据文件路径 (可选)	—	可选
`--log-dir`	日志输出目录 (覆盖配置文件中的路径)	—	可选
`--run-id`	运行 ID (同一运行的所有阶段共享)	—	可选
`--seed`	随机种子 (覆盖配置文件中的值)	—	可选
`--resume`	从最优轮次恢复训练 (best 或 best_train_state.pt；旧运行支持 latest)	—	可选
`--profile`	运行档位：只压缩预算（轮数/采样段数），不改任何语义。smoke 用于确认链路通不通，产出的模型不可用于评估	— `smoke`	可选

其余参数与命令格式

text

usage: revive train [-h] --config CONFIG [--train-data TRAIN_DATA]
                    [--val-data VAL_DATA] [--log-dir LOG_DIR]
                    [--run-id RUN_ID] [--seed SEED]
                    [--resume RESUME | --force | --extend-from EXTEND_FROM]
                    [--additional-epochs ADDITIONAL_EPOCHS]
                    [--profile {smoke}] [--verbose]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--force`	预检通过后删除并覆盖本次重建的已有记录（不可恢复）	`false`	可选，开关，无需附值
`--extend-from`	从父 best_train_state.pt 新建追加训练 run；旧运行也支持 latest.pt	—	可选
`--additional-epochs`	预算延长新增 epoch 数，仅与 --extend-from 配对	—	可选
`--verbose`	显示详细输出	`false`	可选，开关，无需附值

`revive1 train`

使用旧 YAML/NPZ 启动 2.0 基础训练。

将 REVIVE 1.x 的基础 metadata YAML 与数值 NPZ 转换后，执行原生 2.0 训练。默认仅训练 BC 世界模型；策略需显式开启。不运行旧训练脚本，不复现旧算法或模型结果。

完整的迁移步骤、Pendulum / Refrigerator / LanderHover 示例、数据转换规则及常见问题，见兼容revive1。本节仅保留参数查询。

bash

revive1 train --help

先用 --dry-run 检查只读计划，确认后移除该参数开始训练。旧 JSON、revive_f、搜索、专家函数、自定义节点和旧模型续训不支持。

常用参数

参数	作用	默认值 / 取值	使用条件
`-cf` `--config-file` `--config_file`	旧 metadata YAML；相对路径基于当前目录	—	必填
`-df` `--data-file` `--data_file`	旧数值 NPZ 训练数据	—	必填
`-rf` `--reward-file` `--reward_file`	普通 get_reward(data) Python 文件；策略训练必填	—	可选
`-tpn` `--target-policy-name` `--target_policy_name`	单个策略输出节点；只有一个候选时可省略	—	可选
`--action-bound`	连续动作的真实物理范围；可重复，不从样本极值推测	`[]`	可选
`--seed` `--global_seed`	训练与数据划分随机种子	—	可选
`--run-id` `--run_id`	新运行标识；禁止覆盖已有目录	—	可选
`--log-dir` `--log_dir`	运行根目录，默认 logs	`logs`	可选
`--profile`	小预算链路验收，不能用于评价模型质量	— `smoke`	可选
`--dry-run`	只读检查并输出转换计划；不写文件、不执行用户 Python、不训练	`false`	可选，开关，无需附值
`--resume`	不支持；请使用原生 2.0 工作流	—	可选

其余参数与命令格式

text

usage: revive1 train [-h] -cf CONFIG_FILE -df DATA_FILE [-vf VAL_FILE]
                     [-rf REWARD_FILE] [-tpn TARGET_POLICY_NAME]
                     [-vm {once,None,tune}] [-pm {once,None,tune}]
                     [--venv-algo {bc,revive_p}] [--policy-algo {ppo,sac}]
                     [--action-bound COLUMN=MIN,MAX]
                     [--transition-dist {normal,tanh_normal}]
                     [--world-epochs WORLD_EPOCHS]
                     [--policy-epochs POLICY_EPOCHS] [--bc_epoch BC_EPOCH]
                     [--revive_epoch REVIVE_EPOCH] [--ppo_epoch PPO_EPOCH]
                     [--sac_epoch SAC_EPOCH] [--world-lr WORLD_LR]
                     [--policy-lr POLICY_LR] [--batch-size BATCH_SIZE]
                     [--venv-rollout-horizon VENV_ROLLOUT_HORIZON]
                     [--policy-rollout-horizon POLICY_ROLLOUT_HORIZON]
                     [--ppo_rollout_horizon PPO_ROLLOUT_HORIZON]
                     [--sac_rollout_horizon SAC_ROLLOUT_HORIZON]
                     [--episode-length EPISODE_LENGTH]
                     [--split-mode {outside_traj,inside_traj,inside_traj_reverse}]
                     [--val-split-ratio VAL_SPLIT_RATIO] [--seed SEED]
                     [--device DEVICE] [--run-id RUN_ID] [--log-dir LOG_DIR]
                     [--profile {smoke}] [--dry-run] [--verbose]
                     [-rcf REVIVE_CONFIG_FILE] [-mrf MATCHER_REWARD_FILE]
                     [-tm TUNING_MODE] [-tisf TUNING_INITIAL_STATE_FILE]
                     [--resume RESUME] [--address ADDRESS]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`-vf` `--val-file` `--val_file`	独立验证 NPZ，不自动混入训练集	—	可选
`-vm` `--venv-mode` `--venv_mode`	仅支持 once；None/tune 会明确报错	`once` `once` / `None` / `tune`	可选
`-pm` `--policy-mode` `--policy_mode`	once 训练策略；默认 None 仅训练世界模型；不支持 tune	`None` `once` / `None` / `tune`	可选
`--venv-algo` `--venv_algo`	2.0 世界模型算法，不复现旧算法实现	`bc` `bc` / `revive_p`	可选
`--policy-algo` `--policy_algo`	2.0 策略算法；SAC 适配仅支持连续动作	`ppo` `ppo` / `sac`	可选
`--transition-dist`	下一状态网络的 2.0 输出分布；tanh_normal 限制归一化输出，不代表推断物理边界	`normal` `normal` / `tanh_normal`	可选
`--world-epochs`	世界模型训练轮数	—	可选
`--policy-epochs`	策略训练轮数	—	可选
`--bc_epoch`	旧轮数参数别名，仅对应算法启用时有效	—	可选
`--revive_epoch`	旧轮数参数别名，仅对应算法启用时有效	—	可选
`--ppo_epoch`	旧轮数参数别名，仅对应算法启用时有效	—	可选
`--sac_epoch`	旧轮数参数别名，仅对应算法启用时有效	—	可选
`--world-lr`	世界模型监督优化器学习率	—	可选
`--policy-lr`	PPO 优化器或 SAC actor 学习率	—	可选
`--batch-size` `--batch_size`	数据批大小；同时覆盖 SAC 的训练批大小	—	可选
`--venv-rollout-horizon` `--venv_rollout_horizon`	世界模型推演与验证长度	—	可选
`--policy-rollout-horizon`	策略推演与验证长度	—	可选
`--ppo_rollout_horizon`	旧策略推演长度别名，仅对应算法启用时有效	—	可选
`--sac_rollout_horizon`	旧策略推演长度别名，仅对应算法启用时有效	—	可选
`--episode-length`	仅无 index/done 时，显式指定等长轨迹长度	—	可选
`--split-mode` `--val_split_mode`	默认按轨迹划分；单轨迹需显式选轨迹内划分或提供验证集	`outside_traj` `outside_traj` / `inside_traj` / `inside_traj_reverse`	可选
`--val-split-ratio` `--val_split_ratio`	验证集比例；未指定时使用 2.0 默认值	—	可选
`--device`	2.0 训练设备，例如 cpu 或 cuda:0	—	可选
`--verbose`	失败时输出完整异常栈	`false`	可选，开关，无需附值
`-rcf` `--revive_config_file` `--revive-config-file`	不支持；请使用原生 2.0 工作流	—	可选
`-mrf` `--matcher_reward_file`	不支持；请使用原生 2.0 工作流	—	可选
`-tm` `--tuning_mode`	不支持；请使用原生 2.0 工作流	—	可选
`-tisf` `--tuning_initial_state_file`	不支持；请使用原生 2.0 工作流	—	可选
`--address`	不支持；请使用原生 2.0 工作流	—	可选

`revive-sweep`

批量搜索和比较超参数。

bash

revive-sweep \
  --config config.yaml \
  --sweep sweep.yaml \
  --backend cuda \
  --gpu-ids 0,1

CLI 可覆盖 trial 数量、搜索算法与资源分配，但搜索空间、目标与数据共享要求仍来自 sweep.yaml。--gpu-ids 为 CUDA/NPU 通用的历史命名；实际设备类型由 --backend 决定。

自动搜索参数

常用参数

参数	作用	默认值 / 取值	使用条件
`-c` `--config`	训练 config.yaml（作 base）	—	必填
`--sweep`	sweep.yaml 搜索配置	—	必填
`--backend`	覆盖 resources.backend	— `auto` / `cpu` / `cuda` / `npu`	可选

其余参数与命令格式

text

usage: revive-sweep [-h] -c CONFIG --sweep SWEEP [--n-trials N_TRIALS]
                    [--algorithm ALGORITHM] [--gpu-ids GPU_IDS]
                    [--backend {auto,cpu,cuda,npu}] [--device-ids DEVICE_IDS]
                    [--cpu-per-trial CPU_PER_TRIAL]
                    [--gpu-per-trial GPU_PER_TRIAL]
                    [--placement {spread,pack}]
                    [--max-concurrent MAX_CONCURRENT]
                    [--enforce-memory-fraction | --no-enforce-memory-fraction]
                    [--plan]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--n-trials`	覆盖 search.n_trials	—	可选
`--algorithm`	覆盖 search.algorithm (grid\|random\|tpe\|cmaes)	—	可选
`--gpu-ids`	覆盖 resources.gpu_ids；CUDA/NPU 通用，逗号分隔，如 0,1,2,3	—	可选
`--device-ids`	已废弃的 --gpu-ids 兼容别名	—	可选
`--cpu-per-trial`	覆盖 resources.per_trial.cpu（正整数）	—	可选
`--gpu-per-trial`	覆盖 resources.per_trial.gpu（CUDA/NPU 通用份额）	—	可选
`--placement`	覆盖 resources.placement	— `spread` / `pack`	可选
`--max-concurrent`	覆盖 resources.max_concurrent（正整数或 auto）	—	可选
`--enforce-memory-fraction`	按 per_trial.gpu 限制 CUDA/NPU 进程 allocator	—	可选，开关，无需附值
`--no-enforce-memory-fraction`	只做逻辑 GPU 份额调度，不限制 allocator	—	可选，开关，无需附值
`--plan`	只打印解析后的试验计划，不启动训练或创建 study	`false`	可选，开关，无需附值

结果分析

`revive report`

查看和整理一次训练的结果。

bash

revive report --run logs/pendulum_min

将一次 run 中分散的记录汇总为一页 Markdown 报告。训练结束时会自动生成 <run 目录>/report.md，该命令用于重新生成报告，或阅读他人运行的结果。

报告内容

训练任务的信息分别保存在 run_info.json、metrics_summary.json、各 record 的 record_info.json、models/*.onnx.json 和 config.resolved.yaml 中。报告汇总以下四类信息：

训练与验证指标的数值。
检查点的选择依据，包括指标、优化方向和训练轮次。
ONNX 与 PyTorch 的数值一致性结果，包括容差与运行时版本。
训练数据的指纹。

报告同时列出指标值与选择依据，例如「按 val/rollout/mae 取最小，第 31 个 epoch」。

第 3 条将容差与 onnxruntime 版本、provider 一并记录，是因为「结果一致」这一结论仅在特定的运行时组合下成立，比较 parity 结果时需同时核对这些条件。

冒烟运行的标识

以 --profile smoke 运行的 run，报告开头会显示醒目的提示，并列出缩减的训练参数，使日后翻看这份输出文件的人能一眼看出它来自 2 个 epoch 的冒烟运行。

只读，不重新计算

报告汇总已保存的运行记录，不重新执行模型评估。需要新评估结果时，应使用独立评估流程。

同样因此，报告生成失败不会将一次成功的训练判定为失败：训练日志中会保留一条 warning， run 输出文件不受任何影响。

bash

revive report --run logs/pendulum_min --stdout      # 输出到标准输出
revive report --run logs/pendulum_min --out /tmp/r.md

常用参数

参数	作用	默认值 / 取值	使用条件
`-r` `--run`	run 目录（<log-dir>/<run-id>）	—	必填
`-o` `--out`	输出路径；省略时写入 <run 目录>/report.md	—	可选

其余参数与命令格式

text

usage: revive report [-h] -r RUN [-o OUT] [--stdout]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--stdout`	打印到标准输出而不写文件	`false`	可选，开关，无需附值

`revive uncertainty`

构建或检查模型的不确定性信号。

为已导出的 env record 构建旁路不确定性输出文件，或检查已发布 sidecar 的身份绑定。

bash

revive uncertainty materialize-v2 --help
revive uncertainty build-v2 --help
revive uncertainty inspect  --record logs/run/venv/world

旁路的含义

sidecar 不修改 env.pt。世界模型仍是动力学信息的唯一事实源，不确定性输出文件单独保存、单独携带身份、单独验收。这一边界是有意设计的：调整不确定性方案无需重训世界模型；反之，世界模型更新版本后，旧 sidecar 会因身份不匹配而拒绝加载，而不是继续给出一组与模型不符的分数。

`materialize-v2`

从冻结的世界模型与训练 NPZ 生成可交给 build-v2 的特征文件，无需重训：

bash

revive uncertainty materialize-v2 \
  --record logs/run/venv/world \
  --config uncertainty.yaml \
  --train-data data/train.npz \
  --output frames \
  --action-node action

--output 必须是新目录。四个角色按轨迹不相交地划分，清单记录模型、配置与数据哈希。这些角色均来自所提供的训练语料；角色不相交不代表世界模型有独立测试证据。不要传入留作最终评价的数据。命令缺失时请先核对已安装 SDK 的版本与 --help。

`build-v2`

bash

revive uncertainty build-v2 \
  --record logs/run/venv/world \
  --config uncertainty.yaml \
  --data support_train=frames/support_train.npz \
  --data plugin_train=frames/plugin_train.npz \
  --data calibration=frames/calibration.npz \
  --data acceptance=frames/acceptance.npz \
  --action-node action

输入为已物化的特征矩阵，而非原始数据集。物化由 FrameRecorder 完成——构建期与运行时使用同一条 frame 生成路径，因此「构建时计算的分数」与「部署时计算的分数」不会因特征拼装方式不同而发生静默错位。

--data ROLE=PATH 按用途提供数据，训练、校准与验收的数据角色应严格区分：

角色	用途	混用的后果
`support_train`	拟合支持集（OOD 类）	—
`plugin_train`	训练插件本体	—
`calibration`	拟合 conformal / isotonic 修正量	用训练集校准 → 覆盖率虚高
`acceptance`	独立验收	用校准集验收 → 验收环节为自身打分
`external_test`	可选的额外独立测试	不用于拟合或校准

--action-node 可显式指定动作节点；未指定时读取配置中的 runtime.action_nodes。动作必须是图节点或图声明的外部输入；仍需结合业务核对动作语义，确保状态与动作正确对应。

`inspect`

bash

revive uncertainty inspect --record logs/run/venv/world

打印已发布 sidecar 的 manifest 摘要：插件清单、各自的身份哈希、验收结论。部署前最应关注的是 accepted——其为 false 时，该信号不应接入 gate。

一个常见的配置疏漏

插件的质量门槛可以通过匹配的 validation.profile 或显式 min_* / max_* 阈值配置。没有设置适用门槛时，accepted: true 本身不能说明信号已经达到业务要求；使用前应检查实际执行的规则和独立验收指标。

不确定性评估

其余参数与命令格式

text

usage: revive uncertainty [-h] ACTION ...

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选

revive uncertainty build-v2

text

usage: revive uncertainty build-v2 [-h] --record RECORD --config CONFIG
                                   [--data ROLE=PATH] [--action-node NAME]
                                   [--project-dir PROJECT_DIR]
                                   [--device DEVICE]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--record`	stage_dir（含 model/ 的目录）	—	必填
`--config`	uncertainty v2 配置 YAML	—	必填
`--data`	按角色提供 NPZ，可重复。角色: support_train / plugin_train / calibration / acceptance / external_test。每个 NPZ 至少含 features；可选 errors / ood_labels / groups。插件特征空间不同时用 features__<plugin_id> 分别给出	`[]`	可选
`--action-node`	控制器动作名，可重复。必须是图节点或图声明的外部输入	`[]`	可选
`--project-dir`	自定义组件根目录；默认取 --config 所在目录	—	可选
`--device`	—	`cpu`	可选

revive uncertainty materialize-v2

text

usage: revive uncertainty materialize-v2 [-h] --record RECORD --config CONFIG
                                         --train-data TRAIN_DATA --output
                                         OUTPUT [--project-dir PROJECT_DIR]
                                         [--action-node ACTION_NODE]
                                         [--device DEVICE] [--seed SEED]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--record`	stage_dir (contains model/env.pt)	—	必填
`--config`	uncertainty v2 YAML	—	必填
`--train-data`	Training NPZ; never the final test split	—	必填
`--output`	New directory for role NPZ files and manifest	—	必填
`--project-dir`	—	—	可选
`--action-node`	—	`[]`	可选
`--device`	—	`cpu`	可选
`--seed`	—	`20260802`	可选

revive uncertainty inspect

text

usage: revive uncertainty inspect [-h] --record RECORD

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--record`	stage_dir	—	必填

调优辅助

`revive suggest-bounds`

根据数据辅助检查变量边界。

bash

revive suggest-bounds \
  --config config.yaml \
  --data train.npz \
  --ratio 1.5

默认仅输出报告。通过 --node-ratio node:ratio 覆盖单节点倍率，通过 --nodes 限定节点范围，通过 --out 写出新的 YAML。该工具从不覆盖已声明的边界，也不会将建议值自动应用到运行时。

使用方式与安全边界

常用参数

参数	作用	默认值 / 取值	使用条件
`-c` `--config`	配置文件路径 (YAML 格式)	—	必填
`-d` `--data`	训练数据文件路径	—	必填
`--val-data`	可选：独立验证数据文件路径，与训练数据合并后一起统计	—	可选
`--out`	把建议边界写回为新的配置文件（省略则只打印报告，不写文件）	—	可选

其余参数与命令格式

text

usage: revive suggest-bounds [-h] -c CONFIG -d DATA [--val-data VAL_DATA]
                             [--ratio RATIO] [--node-ratio NODE_RATIO]
                             [--nodes NODES [NODES ...]] [--out OUT]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--ratio`	默认扩边倍数：建议半宽 = 观测半宽 x ratio（默认 1.5，必须 >= 1.0）	`1.5`	可选
`--node-ratio`	按 node 覆盖 ratio，格式 node:ratio（可多次指定）	—	可选
`--nodes`	只处理指定的 node（默认处理 graph.columns 涉及的全部 node）	—	可选

`revive suggest-rollout`

根据预测误差辅助选择推演长度。

bash

revive suggest-rollout \
  --config config.yaml \
  --data train.npz \
  --model logs/run-1/models/env.pt

在验证集上执行一次自回归推演，测量误差随步数增长的曲线，并据此为策略阶段的 rollout_horizon 给出建议。该命令为只读操作：不修改配置，不影响训练行为。

建议值是上界而非最优值。 曲线测量的是行为策略下的误差，而策略训练时动作来自正在学习的策略；偏离数据分布后真实误差只会更大，因此按建议值配置属于安全侧而非最优侧。

常用参数：

--measure-horizon 测量时推演的步数，必须不小于建议上限，否则无法测到钳位边界（默认 200）
--tolerance 容忍系数 C，建议值 = C × 拐点；不指定时采用算法侧标定值
--segments 推演的片段数，过少会使曲线非单调、拐点不稳定（默认 64）
--json 输出机器可读的结果

常用参数

参数	作用	默认值 / 取值	使用条件
`-c` `--config`	配置文件路径 (YAML)	—	必填
`-d` `--data`	训练数据文件路径	—	必填
`--val-data`	显式验证集路径	—	可选
`-m` `--model`	已训练的环境模型（部署格式 env.pt）	—	必填

其余参数与命令格式

text

usage: revive suggest-rollout [-h] -c CONFIG -d DATA [--val-data VAL_DATA] -m
                              MODEL [--measure-horizon MEASURE_HORIZON]
                              [--tolerance TOLERANCE] [--segments SEGMENTS]
                              [--device DEVICE] [--json]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--measure-horizon`	测量时推演多少步。必须不小于建议上限，否则测不到钳位边界。默认 200。	`200`	可选
`--tolerance`	容忍系数 C：建议值 = C × 拐点。默认取算法侧标定值。	—	可选
`--segments`	测量时推演多少条 rollout 片段。片段太少曲线会非单调、拐点乱跳，默认 64。	`64`	可选
`--device`	计算设备	`cpu`	可选
`--json`	输出机器可读 JSON	`false`	可选，开关，无需附值

模型导出

`revive export`

将 PT 部署模型导出为 ONNX。

bash

revive export \
  --artifact logs/run/models/env.pt \
  --format onnx \
  --io-space raw \
  --opset 17 \
  --validate parity \
  --parity-data validation.npz

输入必须是具体的部署 .pt 文件，不能是续训 checkpoint。有状态/Controller artifact 会根据 deployment metadata 自动分派到对应的 bundle 导出器。

使用与部署模型

常用参数

参数	作用	默认值 / 取值	使用条件
`--artifact`	env.pt 或 direct/PID policy.pt 路径	—	必填
`--format`	导出格式（第一阶段仅 onnx）	`onnx` `onnx`	可选
`--out`	输出路径，默认同目录 env.onnx / policy.onnx	—	可选
`--validate`	校验级别	`checker` `checker` / `runtime` / `parity` / `none`	可选
`--parity-data`	.npz 真实验证轨迹，生成正式 verification.json（隐含 --validate parity）	—	可选

其余参数与命令格式

text

usage: revive export [-h] --artifact ARTIFACT [--format {onnx}] [--out OUT]
                     [--target-nodes TARGET_NODES [TARGET_NODES ...]]
                     [--io-space {raw,processed}] [--opset OPSET]
                     [--project PROJECT]
                     [--validate {checker,runtime,parity,none}]
                     [--batch-size BATCH_SIZE] [--input-shape INPUT_SHAPE]
                     [--parity-data PARITY_DATA]
                     [--verification-seed VERIFICATION_SEED]
                     [--verification-steps VERIFICATION_STEPS]
                     [--parity-batch-sizes PARITY_BATCH_SIZES [PARITY_BATCH_SIZES ...]]
                     [--atol ATOL] [--rtol RTOL]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--target-nodes`	覆盖 artifact 中的 target_nodes / policy_nodes	—	可选
`--io-space`	I/O 空间，默认 raw	`raw` `raw` / `processed`	可选
`--opset`	ONNX opset 版本（默认 17）	`17`	可选
`--project`	项目目录，用于注册自定义图函数与网络（默认当前目录）。配置里按名字引用的实现要在加载 artifact 之前注册上，否则 .pt 根本打不开	—	可选
`--batch-size`	dummy 输入 batch	`2`	可选
`--input-shape`	维度覆盖 key:D（可多次），用于无法从 NormModule 推断的输入	—	可选
`--verification-seed`	真实验证轨迹和 MPC 显式随机输入选择种子（默认 0）	`0`	可选
`--verification-steps`	stateful/controller parity 的最大多步长度（默认 32）	`32`	可选
`--parity-batch-sizes`	runtime parity 的 batch sizes（无 --parity-data 时用生成样本）	`[1, 2, 8]`	可选
`--atol`	runtime parity 绝对容差	`1e-05`	可选
`--rtol`	runtime parity 相对容差	`0.0001`	可选

授权与迁移

`revive register`

保存在线授权 access key。

保存在线授权的 access key，省略参数时按提示输入，终端不会回显：

bash

revive register

配置保存到当前用户的 ~/.revive/config.yaml，字段名为 accesskey。注册只保存配置，训练开始时才向授权服务申请许可证：

bash

revive train --config config.yaml --train-data train.npz --run-id experiment-001

首次申请前，revive license status 提示缺少许可证不代表 access key 无效。不同任务使用不同的运行 ID；中断续训保持原配置、数据路径、运行 ID 和日志目录，按恢复中断训练选择检查点。

申请会发送机器信息、SDK 版本、匿名化的图节点连接关系、数据行数及训练数量等信息，不会上传真实训练配置、训练数据、本地文件路径、日志、模型或训练结果，也不会补交历史文件。申请结果不明确时，保留申请编号，联系技术支持核对后再继续。完整配置与首次运行步骤见安装与授权。

其余参数与命令格式

text

usage: revive register [-h] [access_key]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`access_key`	省略时隐藏输入	—	可选，位置参数

`revive license`

配置许可证与查看授权信息。

安装已有离线许可证并检查状态：

bash

revive license install /absolute/path/license.lic
revive license status

安装命令先验证文件，通过后才保存；无效文件不会覆盖已有许可证。也可以通过环境变量选择文件：

bash

export REVIVE_LICENSE=/absolute/path/license.lic
revive license status

状态查询只检查已有许可证，不创建在线训练申请。首次在线用户配置 access key 后，通过训练命令申请许可证，具体步骤见首次运行。

需要申请绑定设备的许可证时，在实际运行环境中导出机器信息并提交给技术支持：

bash

revive license machine-info --output machine_info.json

设备绑定和有效期以实际许可证为准。显式选择或已安装的离线许可证优先于在线授权，文件失效时不会自动回退在线申请。续期或更换许可证后，启动新的训练或推理进程。

加密 SDK 的训练、PT 加载及相关导出功能需要有效授权；模型文件本身不加密，独立运行已导出的 ONNX 模型无需 SDK 授权。配置步骤见离线授权，报错处理见授权问题。

其余参数与命令格式

text

usage: revive license [-h] {machine-info,install,status} ...

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选

revive license machine-info

text

usage: revive license machine-info [-h] --output OUTPUT

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--output`	—	—	必填

revive license install

text

usage: revive license install [-h] [--directory DIRECTORY] license_file

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`license_file`	—	—	必填，位置参数
`--directory`	—	—	可选

revive license status

text

usage: revive license status [-h]

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选

`revive migrate-config`

迁移本项目早期 2.0 配置格式。

bash

revive migrate-config old_config.yaml            # 仅报告，不写盘
revive migrate-config old_config.yaml -o new.yaml # 报告并写出迁移结果

将本项目早期 2.0 配置格式迁移到当前格式，逐项报告三类变化：纯改名、结构重组、已删除的键。

能够明确映射的字段会自动改写；无法确定的字段仅报告待处理项并给出迁移指引，由用户结合任务定义完成修改。

-o/--output 迁移结果的写出位置；不指定时仅报告不写盘
--report 仅报告改动，不写盘（即使指定了 -o） · 部署问题与版本升级

REVIVE 1.x 的基础 YAML 和 NPZ 可使用 revive1 train 转换并训练；仅需导出输入时使用独立迁移脚本；本命令不恢复 1.x API 或模型。

常用参数

参数	作用	默认值 / 取值	使用条件
`config`	要迁移的旧配置文件 (YAML)	—	必填，位置参数
`-o` `--output`	迁移结果写到这里；不给就只报告不写盘	—	可选

其余参数与命令格式

text

usage: revive migrate-config [-h] [-o OUTPUT] [--report] config

参数	作用	默认值 / 取值	使用条件
`-h` `--help`	show this help message and exit	—	可选
`--report`	只报告改动，不写盘（即使给了 -o）	`false`	可选，开关，无需附值

命令行参考 ​

数据与配置 ​

revive init ​

指定状态与动作 ​

生成结果中必须人工复核的两处 ​

生成之后 ​

revive info ​

revive validate ​

静态验证 ​

深度验证 ​

常见失败原因 ​

训练与搜索 ​

revive train ​

--profile smoke：预先验证流程连通性 ​

恢复训练 ​

退出语义 ​

revive1 train ​

revive-sweep ​

结果分析 ​

revive report ​

报告内容 ​

冒烟运行的标识 ​

只读，不重新计算 ​

revive uncertainty ​

旁路的含义 ​

materialize-v2 ​

build-v2 ​

inspect ​

一个常见的配置疏漏 ​

调优辅助 ​

revive suggest-bounds ​

revive suggest-rollout ​

模型导出 ​

revive export ​

授权与迁移 ​

revive register ​

revive license ​

revive migrate-config ​

命令行参考

数据与配置

`revive init`

指定状态与动作

生成结果中必须人工复核的两处

生成之后

`revive info`

`revive validate`

静态验证

深度验证

常见失败原因

训练与搜索

`revive train`

`--profile smoke`：预先验证流程连通性

恢复训练

退出语义

`revive1 train`

`revive-sweep`

结果分析

`revive report`

报告内容

冒烟运行的标识

只读，不重新计算

`revive uncertainty`

旁路的含义

`materialize-v2`

`build-v2`

`inspect`

一个常见的配置疏漏

调优辅助

`revive suggest-bounds`

`revive suggest-rollout`

模型导出

`revive export`

授权与迁移

`revive register`

`revive license`

`revive migrate-config`