兼容revive1

如果您已经有 REVIVE 1.x 任务的 YAML、NPZ 和奖励函数，可以通过 revive1 train 使用这些输入， 在 REVIVE 2.0 中重新训练世界模型和控制策略。命令会在内部完成基础格式转换，再调用 2.0 的训练、验证与导出流程， 不需要手动生成一份新的训练配置。

本页介绍兼容范围、旧任务的启动方式，以及转换后如何查看结果。完整参数见命令行参考。

兼容的是训练输入

revive1 随当前 REVIVE 2.0 SDK 安装，不是独立的 1.x SDK。它不运行旧 train.py、不恢复旧 ReviveServer API， 也不加载旧模型继续训练。训练采用 2.0 的算法实现和默认参数，不保证与旧版本得到相同的模型或指标。

哪些旧任务可以直接使用

先检查旧任务的输入是否落在以下范围内。基础任务可以直接迁移；包含复杂功能的任务需要按 2.0 原生接口重新配置， 不能只删除报错字段后继续训练。

旧任务内容	当前支持范围
图与列定义	metadata.graph、metadata.columns，保留节点依赖、列顺序与列属性
状态转移	连续状态，使用 next_<状态节点名> 网络预测下一状态
动作	连续动作、类别动作；基础 SAC 适配仅支持连续动作
数据文件	数值 NPZ，支持独立验证集；不读取 object/pickle 数据
奖励函数	独立 Python 文件中的普通 get_reward(data) 函数
训练方式	只训练世界模型，或在一次运行内先训练世界模型、再训练策略
算法选择	世界模型：BC、REVIVE-P；策略：PPO、连续动作 SAC

以下内容不在基础兼容范围内：旧 JSON 参数配置、revive_f、tune 搜索、业务参数优化、专家函数、 自定义节点、时序展开、多参数奖励接口、旧模型续训，以及跳过世界模型后单独复用旧策略。 旧 YAML 中的 nodes、custom_nodes、expert_functions、tunable 等字段即使为空，也会被明确拒绝。

默认使用 BC 世界模型，不训练策略。旧脚本如果默认启用搜索或策略训练，迁移时需要重新选择训练方式。

准备运行环境与文件

按安装与授权安装包含此入口的 REVIVE 2.0 SDK，并在同一 Python 环境中检查：

revive --version
revive1 --version
revive1 train --help

不需要安装旧 SDK。请保留旧任务的 YAML、NPZ，以及需要训练策略时使用的奖励文件。 文中的 data/... 路径相对于执行命令时的当前目录；工具不会到旧 SDK 的数据目录中自动查找文件。

--dry-run 不申请授权、不执行用户 Python，也不写转换文件。真正训练前仍需完成在线 access key 或离线许可证配置； 在线用户由训练流程申请许可证，授权行为与 revive train 相同。

如果已安装当前源码包，但终端暂时找不到 revive1，可用同一 Python 环境检查模块入口：

python -m revive.compat.v1 train --help

若模块也不存在，请更新安装包，不要安装 1.x SDK 来补充这个命令。

从旧命令切换到新入口

旧任务通常通过 python train.py 启动。迁移时改为 revive1 train，保留受支持的文件参数， 不再执行旧训练脚本，也不传入旧 config.json。

1. 先检查转换计划

在旧任务目录中执行，文件名请替换为实际值：

revive1 train \
  --config-file data/task.yaml \
  --data-file data/train.npz \
  --venv-algo bc \
  --venv-mode once --policy-mode None \
  --run-id legacy-check \
  --profile smoke --dry-run

终端会输出 JSON 计划。重点检查图与列定义、源文件路径、输入与输出行数、轨迹数量、数据类型转换， 以及 effective_budget 中各阶段的算法和轮数。没有写出的训练参数采用 2.0 原生默认值， 不会从旧 JSON、旧日志或旧模型中恢复。

只读计划通过，说明基础映射、数据检查和默认参数合并通过；奖励函数能否实际运行、图能否构建以及 ONNX 能否导出， 仍需由正式训练中的可执行预检确认。

2. 进行一次短训练

确认计划后，移除同一命令末尾的 --dry-run，保留 --profile smoke 执行短训练。 只读检查没有占用运行目录，因此可以沿用刚才的运行 ID。

smoke 只缩减训练轮数等预算，不会自动缩短推演长度。短轨迹任务可显式设置 --venv-rollout-horizon；训练策略时还可设置 --policy-rollout-horizon。 这些参数同时影响相应阶段的训练推演和验证长度，应按任务需要确定。

3. 开始正式训练

短训练完成后，使用新的 --run-id，移除 --profile smoke，按需要指定 --world-epochs、--policy-epochs、学习率和推演长度。 如果使用了本页示例中的 --world-epochs 1 等小预算参数，也需一并调整。

同一运行 ID 不允许覆盖或续训；失败后也应修正问题、换一个新的 ID 再运行。 短训练的作用是检查流程，不能用来评价模型质量。

迁移 1.2.0 的示例任务

以下命令对应保留的 1.2.0 examples/task/ 输入，不是 2.0 安装包内同名任务的新配置。 请先进入对应的旧任务目录，再执行命令。三类基础任务已做过小预算 CPU 训练与导出验收， 但这不表示 1.2.0 的全部示例或同一任务的所有变体均已兼容。

Pendulum：连续动作与策略训练

进入旧 examples/task/Pendulum/，使用原 YAML、NPZ 和奖励文件：

revive1 train \
  --config-file data/Env-GAIL-pendulum.yaml \
  --data-file data/expert_data.npz \
  --reward-file data/pendulum-reward.py \
  --target-policy-name actions \
  --venv-algo bc --policy-algo ppo \
  --venv-mode once --policy-mode once \
  --action-bound action=-2,2 \
  --transition-dist tanh_normal \
  --world-epochs 1 --policy-epochs 1 \
  --venv-rollout-horizon 4 --policy-rollout-horizon 4 \
  --batch-size 64 --device cpu --seed 42 \
  --run-id pendulum-v2-smoke \
  --profile smoke --dry-run

确认后移除 --dry-run 执行训练。其中有三个需要区分的名字与选项：

• actions 是图中的动作节点名，交给 --target-policy-name。
• action 是该节点下面的列名，交给 --action-bound。原 YAML 没有声明动作物理边界，因此显式补充 [-2, 2]。
• --transition-dist tanh_normal 为下一状态网络选择归一化空间内的有界采样。原奖励函数直接计算 acos， 无界的状态采样可能超出其定义域并产生 NaN；工具不会自动改写奖励公式。

上述输出分布不是所有任务的通用修复，也不替代状态物理边界或其他约束的定义。 其他任务应根据状态含义选择分布，详见下文动作边界与输出分布。

只需要世界模型时，不必提供奖励文件：

revive1 train \
  --config-file data/Env-GAIL-pendulum.yaml \
  --data-file data/expert_data.npz \
  --target-policy-name actions --action-bound action=-2,2 \
  --venv-algo bc --policy-mode None \
  --transition-dist tanh_normal \
  --world-epochs 1 --venv-rollout-horizon 4 \
  --batch-size 64 --device cpu --seed 42 \
  --run-id pendulum-world-smoke \
  --profile smoke --dry-run

需要尝试 REVIVE-P 世界模型时，将 --venv-algo bc 改为 --venv-algo revive_p。 连续动作任务需要 SAC 策略时，将两阶段命令中的 --policy-algo ppo 改为 --policy-algo sac， 并使用新的运行 ID。算法切换只选择 2.0 实现，不恢复旧算法参数。

Refrigerator：外部输入与单轨迹数据

进入旧 examples/task/Refrigerator/，使用普通 refrigeration.yaml，而不是带专家函数或时序配置的变体：

revive1 train \
  --config-file data/refrigeration.yaml \
  --data-file data/refrigeration.npz \
  --reward-file data/refrigeration_reward.py \
  --target-policy-name action \
  --venv-algo bc --policy-algo ppo --policy-mode once \
  --split-mode inside_traj \
  --world-epochs 1 --policy-epochs 1 \
  --venv-rollout-horizon 4 --policy-rollout-horizon 4 \
  --batch-size 64 --device cpu --seed 42 \
  --run-id refrigerator-v2-smoke \
  --profile smoke --dry-run

图中的 door_open 保留为外部输入。动作列 power_action 已在 YAML 中声明 [0, 10]，不必重复传入边界。 这份数据为单轨迹，因此显式使用轨迹内划分；如果您有独立验证数据，也可以使用 --val-file， 而不是改变划分方式。原 Float64 数据会在转换副本中变为 Float32，原 NPZ 保持不变。

LanderHover：类别动作与显式下一状态

进入旧 examples/task/LanderHover/：

revive1 train \
  --config-file data/LanderHover.yaml \
  --data-file data/LanderHover.npz \
  --reward-file data/LanderHover.py \
  --target-policy-name action \
  --venv-algo bc --policy-algo ppo --policy-mode once \
  --world-epochs 1 --policy-epochs 1 \
  --venv-rollout-horizon 4 --policy-rollout-horizon 4 \
  --batch-size 64 --device cpu --seed 42 \
  --run-id landerhover-v2-smoke \
  --profile smoke --dry-run

类别动作保留 YAML 中的 values: [0, 1, 2, 3]，不使用连续动作边界。 此类动作使用 PPO，不能直接改为基础 SAC 适配。数据中的 next_obs 按轨迹检查后保留； 额外 rew 数组也会保留，但策略奖励仍来自 LanderHover.py，不会自动使用数据中的 rew。 布尔型 done 在转换副本中变为数值 0/1，不改变轨迹边界。

旧参数如何对应

文件参数保留常用短名和下划线别名；新命令推荐使用长参数名。以下是迁移时最常见的对应关系：

旧参数或写法	revive1 train 中的写法	说明
-cf / --config_file	--config-file	基础 metadata YAML
-df / --data_file	--data-file	训练 NPZ
-vf / --val_file	--val-file	独立验证 NPZ，不能与训练文件为同一路径
-rf / --reward_file	--reward-file	普通奖励文件，开启策略时必填
-tpn / --target_policy_name	--target-policy-name	仅选择一个策略节点；多个候选时必须指定
-vm / --venv_mode	--venv-mode once	不支持 None 或 tune
-pm / --policy_mode	--policy-mode once 或 None	默认 None，不开启策略
--venv_algo / --policy_algo	--venv-algo / --policy-algo	从当前支持的算法中选择
--run_id / --log_dir	--run-id / --log-dir	日志根目录默认 logs；不指定 ID 时自动生成
--global_seed	--seed	同时设置训练与数据划分种子
--batch_size	--batch-size	数据批大小，同时覆盖 SAC 的训练批大小
--bc_epoch / --revive_epoch	--world-epochs	旧别名仍可用，但只能对应当前选中的世界模型算法
--ppo_epoch / --sac_epoch	--policy-epochs	只有相应策略启用时才有效
--venv_rollout_horizon	--venv-rollout-horizon	世界模型推演与验证长度
--ppo_rollout_horizon / --sac_rollout_horizon	--policy-rollout-horizon	相应策略推演与验证长度
--val_split_mode	--split-mode	默认 outside_traj，不自动处理单轨迹
--val_split_ratio	--val-split-ratio	验证比例；传入独立验证集时不能同时设置
--debug	按用途选择 --profile smoke、--verbose	没有一对一兼容别名；分别控制小预算和详细日志
-rcf、--address、旧搜索与续训参数	无基础映射	明确拒绝，不能原样透传

--world-lr 调整世界模型的监督优化器；REVIVE-P 对应其中的 BC 部分，不改对抗部分优化器。 --policy-lr 调整 PPO 优化器或 SAC actor，不同时改变 SAC critic、alpha 的学习率。 轮数或推演长度同时使用通用参数和旧算法专用别名时，冲突值会报错； 与当前训练阶段无关的轮数、学习率和推演参数也会报错。

revive1 是独立命令入口，不接收 revive 的全局参数或 revive train 的全部参数。 请以 revive1 train --help 为准。

YAML、数据与奖励如何转换

图结构与列定义

以下是支持的旧 YAML 结构，列名与 NPZ 维度需按实际任务填写：

metadata:
  graph:
    actions: [states]
    next_states: [states, actions]
  columns:
    - position: {dim: states, type: continuous}
    - velocity: {dim: states, type: continuous}
    - force: {dim: actions, type: continuous, min: -2, max: 2}

转换后，metadata.graph 成为原生图节点，columns 按 dim 分组，states → next_states 成为 direct_next 状态转移。工具保留直接预测下一状态的结构，不强制改为 delta_* 增量模型。 状态转移必须是连续变量；依赖成环、列定义缺失、未知字段和部分复杂图结构会直接报错。

NPZ 与轨迹边界

节点数组使用 (行数, 维度)，键名对应图变量。以上 YAML 对应 states 的两列和 actions 的一列。 数据需为有限数值；工具会检查行数、列数、类别值与已声明的边界。

• index 是严格递增的一维整数数组，表示各轨迹的排他结束下标；例如 [200, 400] 表示两条各 200 行的轨迹。
• 也可提供二值 done 标记，最后一行必须结束；同时提供 index 和 done 时，两者必须完全一致。
• 两者都没有时，才可通过 --episode-length N 显式声明等长轨迹，总行数必须能整除 N。工具不会猜测轨迹边界。
• 全部下一状态数组缺失时，只在各轨迹内部取下一行，并删除每条轨迹没有后继的末行。例如两条 200 行轨迹转换为两条 199 行轨迹。
• 全部下一状态数组已存在时，检查其与轨迹内下一行状态是否一致，保留用户给定的末行下一状态；部分存在、部分缺失时拒绝自动对齐。
• 浮点数组转为 Float32，布尔数组转为 Float32 的 0/1；可能发生的浮点舍入及类型变化会记录在报告中。整数索引保持整数。
• 额外的 rew、reward 数组会对齐保留，不自动作为策略奖励；其他未映射数组会报错。

默认 outside_traj 按轨迹划分训练与验证数据，至少需要两条轨迹。 只有一条轨迹时，显式使用 --split-mode inside_traj，或者提供独立验证集：

revive1 train \
  --config-file data/task.yaml \
  --data-file data/train.npz \
  --val-file data/val.npz \
  --run-id legacy-with-val \
  --profile smoke --dry-run

训练集和验证集分别转换，分别检查边界与维度。提供 --val-file 后，不要再设置 --val-split-ratio。 采用轨迹内划分时，需结合业务检查相邻时刻的相关性，避免把流程通过误认为独立评估充分。

动作边界与输出分布

开启策略训练时，连续动作的每一列都必须有物理 min/max，可以来自旧 YAML， 也可以用重复的 --action-bound 列名=最小值,最大值 显式补充或覆盖。 边界名称是列名，不是图节点名；取值应来自设备或环境定义，不能由样本极值猜测。

选中的纯连续动作节点使用 tanh_normal 有界采样。下一状态网络默认使用 normal； --transition-dist tanh_normal 则为全部下一状态网络选择归一化空间内的有界采样。 它不推断真实状态的物理约束，也不保证多变量之间的约束成立。奖励中含有 acos、log 等运算时， 尤其需要检查状态采样能否超出函数定义域。

奖励函数

策略训练需要单个独立 Python 文件，包含未装饰的 get_reward(data)，例如：

def get_reward(data):
    position = data["states"][..., 0:1]
    action = data["actions"][..., 0:1]
    return -(position ** 2 + 0.01 * action ** 2)

data 中的值是张量，键名需与任务图一致。原文件中所需的第三方依赖应在当前 2.0 环境中安装。 不支持额外接收 graph 的奖励接口、相对导入，或直接导入旧 revive API 的实现； 这些情况应按业务目标与奖励和训练配置手动迁移。

只读计划仅检查函数签名与部分导入形式，不执行文件。正式训练会加载并执行其代码， 因此请使用自己确认可信的奖励文件。实际张量形状与可执行性由原生预检检查。

查看转换结果与模型

真正执行后，两类输出分别保存在日志根目录下：

logs/
├── .revive1-inputs/<run-id>/
│   ├── config.yaml       # 转换后的 2.0 原生配置
│   ├── train.npz         # 转换后的训练数据
│   ├── val.npz           # 提供独立验证集时生成
│   ├── reward.py         # 开启策略并提供奖励文件时生成
│   └── report.json       # 转换记录与运行状态
└── <run-id>/
    ├── models/           # env.pt、可选 policy.pt 及相应 ONNX 产物
    └── report.md         # 标准训练结果报告，其他记录由原生流程保存

.revive1-inputs 是隐藏目录，终端中可用 ls -a logs 查看。转换文件放在运行目录之外， 让原生训练创建自己的运行目录；不要只移动 logs/<run-id>/ 后就假设转换配置中的绝对路径仍然有效。

report.json 记录源文件与输出摘要、参数映射、行数和类型变化，以及 completed、failed 或 interrupted 状态。 原 YAML、NPZ 和奖励文件不修改；失败时保留已产生的转换文件与失败报告。训练期间不要修改输入文件。

完成后可用原生命令整理结果：

revive report --run logs/pendulum-v2-smoke

模型是 2.0 产物，应使用使用模型中的接口加载，或按模型部署使用 ONNX。 不要继续用依赖旧 ReviveServer、旧 pickle 结构的测试脚本直接加载新模型。

常见问题

提示或现象	应如何处理
revive1 找不到	核对当前 Python 环境与安装包版本，检查 python -m revive.compat.v1 train --help
Policy action bounds missing	按动作列补充真实边界；不要把节点名当作列名
策略候选不唯一	用 --target-policy-name 指定一个动作节点；复杂多控制任务改用原生配置
outside_traj requires at least two trajectories	提供独立验证集，或显式选择轨迹内划分
Missing episode boundaries / index and done disagree	检查原始轨迹标记；仅无标记的等长轨迹可使用 --episode-length
Unmapped data arrays / 未知 YAML 字段	确认额外数据或配置的业务含义；复杂功能需手动迁移，不能简单忽略
下一状态与下一行不一致	检查 episode 边界、时间对齐与 next 数据；不要跨轨迹拼接
奖励返回 NaN 或训练失败	检查奖励定义域、张量运算与输出分布；使用 --verbose 查看异常栈
运行目录或转换目录已存在	使用新的运行 ID，保留旧结果用于排查；此入口不覆盖、不续训
只读计划通过，训练仍报错	只读检查不执行奖励、建图和 ONNX；按原生预检的具体错误处理
旧 JSON 中的参数没有生效	该入口不读取旧 JSON；通过受支持的命令行参数显式设置，或改写原生配置

需要专家函数、历史窗口、多控制节点、搜索或更复杂的训练编排时，继续阅读编写配置 和高级功能，使用原生 revive train 定义任务。