命令行工具

安装之后，一次任务从数据到部署文件的每一步都用 revive 完成。本页按您实际的使用顺序，介绍其中最常用的 7 条命令：每条命令做什么、什么时候用、产出什么。需要查某个参数时，见命令行参考。

使用前先完成安装与授权。在线用户配置 access key，离线用户安装许可证；首次在线运行步骤也在该页说明。

已有 REVIVE 1.x 的 YAML 与 NPZ 时，见兼容revive1，按独立页面中的步骤迁移旧任务。

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

命令	做什么
revive info	查看数据、配置和字段说明
revive init	从数据创建任务配置骨架
revive suggest-bounds	根据数据辅助检查变量边界
revive validate	检查配置与数据能否用于训练
revive train	执行训练、验证与模型导出
revive report	查看和整理一次训练的结果
revive export	将 PT 部署模型导出为 ONNX

全局参数写在子命令之前，例如 revive --lang en train --config config.yaml。文档统一使用长参数名；相对路径请按您执行命令所在的目录填写。

revive info

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

revive info --data train.npz          # 看数据：键名、形状、类型、轨迹边界
revive info --config config.yaml      # 看配置：图结构、节点、数据与训练设置摘要
revive info --explain max             # 看字段：某个配置字段的分层、默认值和说明
revive info --tier basic              # 看分层：basic / advanced / expert 的全部字段

什么时候用：刚拿到一份数据、还没动手写配置时，用 --data 确认键名、形状、数据类型和轨迹边界是否符合您的预期；写配置的过程中，用 --explain 查单个字段该填什么，用 --tier basic 通览必填字段；接手别人的配置时，用 --config 看一眼摘要。--explain 收的是裸字段名（max、stages），不是 columns.max 这样的路径；同名字段属于多个配置块时会一并列出。

产出：终端输出，不写任何文件。--data 看的是数据本身，不检查配置与数据是否匹配——那是 validate 的事；--explain 与 --tier 读的是配置 schema，不需要任何数据或配置文件。

revive init

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

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

什么时候用：第一次为一份数据写配置时。--state / --action 需要您自己指定：工具不会去猜哪个变量是状态、哪个是动作——猜错了不会报错，只会让模型静默地学到错误的映射。

产出：一份可以直接交给 validate / train 的最小配置，外加一份占位 reward.py。生成结果有两处需要您手工修改：占位列名（states_0 这类）请换成物理量名称，动作边界请按执行器的真实上限修正。奖励是「什么算好」的定义，框架推断不出来，训练前必须替换。

revive suggest-bounds

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

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

什么时候用：动作边界拿不准写多少时，用它从数据分布取一组候选值供您参考。

产出：默认只打印报告，加 --out 才写出新的 YAML；已经声明过的边界一律不覆盖。候选值请您核对之后再写进配置——数据里没出现过的动作，不代表执行器达不到。

revive validate

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

revive validate \
  --config config.yaml \
  --train-data train.npz

什么时候用：每次改完配置、正式训练之前都建议跑一次。不带数据时只检查 YAML 本身；带上数据会真实走一遍读轨迹、派生 transition、划分统计、逐阶段建图、探测自定义网络与奖励、核对 ONNX 契约的完整流程。 首次在线用户先按安装与授权取得许可证，或配置离线许可证；本命令不会申请在线授权。

产出：通过，或者一条具体的失败原因。它不创建 run，也不写 log_dir。这一步报出来的问题，训练启动时同样会触发，所以在这里修完再训练更省时间。

revive train

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

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

什么时候用：完成授权配置和任务准备后。建议先加 --profile smoke 检查流程，再去掉它正式训练，两次运行使用不同的 --run-id。在线许可证由训练命令申请；中断后按恢复中断训练继续原任务。

产出：logs/<run-id>/ 下的整套运行记录：训练检查点、通过验证与选模的部署模型（env.pt，需要策略时还有 policy.pt）、ONNX 文件和 report.md。smoke 只压缩预算、不改语义，它的指标不能当作模型效果的结论。

revive report

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

revive report --run logs/pendulum_min

什么时候用：训练结束后要读结果，或者要看别人跑的 run。训练结束时已经自动写过一份 report.md，这条命令用于重新生成，或者输出到别处。

产出：一页 Markdown，汇总四类信息：指标数值、选模依据（按哪个指标、取哪个轮次）、ONNX 与 PyTorch 的数值一致性结果及其容差和运行时版本、训练数据指纹。它只汇总已保存的记录，不重新评估模型。

revive export

将 PT 部署模型导出为 ONNX。

revive export \
  --artifact logs/run/models/env.pt \
  --format onnx \
  --validate parity \
  --parity-data validation.npz

什么时候用：要把模型接进不安装 REVIVE 的业务系统时。训练时已经导出过一次，这条命令用于单独重导，或者换一组导出参数重导。

产出：ONNX 文件及其 sidecar。--artifact 必须是部署用的 .pt，续训检查点不接受。--validate parity 会用您给的数据比对 ONNX 与 PyTorch 的输出。

其余命令

下面几条用于特定场景，用途、参数和示例都在命令行参考：

命令	用途
revive1 train	使用旧 YAML/NPZ 启动 2.0 基础训练
revive-sweep	批量搜索和比较超参数
revive uncertainty	构建或检查模型的不确定性信号
revive suggest-rollout	根据预测误差辅助选择推演长度
revive license	配置许可证与查看授权信息
revive register	保存在线授权 access key
revive migrate-config	迁移本项目早期 2.0 配置格式