使用与部署模型

训练完成后，世界模型用于预测系统变化，策略模型用于生成控制动作。您可以在 Python 中调用模型，也可以使用 ONNX 接入独立推理环境。本页按找到模型、准备输入、执行推理和接入业务的顺序说明。

以下基础示例使用倒立摆的 states 和 actions，从 SDK 根目录执行。模型目录为 examples/pendulum/logs/<run-id>/models，示例中的运行名称 repro 请替换为自己的运行名称。其他任务需要同时替换输入名称、列顺序和维度。

选择模型与部署方式

使用方式	需要准备什么	适合的场景
Python 调用 PT 模型	revive、有效的 SDK 授权、PyTorch、模型文件和任务自定义组件	在 Python 项目中预测、推演或计算控制动作
ONNX 独立运行	onnxruntime、numpy、配套运行工具和完整模型目录	独立服务、目标设备及跨平台接入

模型文件本身不加密。使用加密 SDK 加载 PT 模型或重新导出时，需要有效的 SDK 授权， 配置步骤见安装与授权。独立运行已导出的 ONNX 模型 无需安装 REVIVE SDK 或配置 SDK 许可证，其使用仍遵守适用协议。

训练后从运行级 models/ 目录读取选中模型：

logs/<run-id>/
├── report.md
├── models/
│   ├── env.pt                   # 世界模型
│   ├── policy.pt                # 策略或控制器
│   ├── env.onnx.json            # 世界模型 ONNX 入口说明
│   ├── policy.onnx.json         # 策略 ONNX 入口说明
│   ├── .onnx_generations/       # 实际 ONNX 文件与验证记录
│   └── model_info.json          # 选中模型组的信息
├── venv/<record-id>/            # 世界模型阶段记录
└── policy/<record-id>/          # 策略或控制器阶段记录

只训练世界模型时，不要求生成策略文件。多阶段任务以报告和 model_info.json 中的选中模型为准。best_train_state.pt 用于恢复训练，推理应使用部署模型。

复制部署文件时保留整个 models/ 目录，包括隐藏的 .onnx_generations/，使入口说明与实际模型配套。自定义专家函数或网络还需随 Python 项目保留，并在加载前完成注册，见自定义组件。

图：世界模型预测响应，策略产生动作，业务系统提供实际反馈。

使用 Python 调用模型

预测下一状态与连续推演

import torch
from revive.export import load_env

env = load_env("examples/pendulum/logs/repro/models/env.pt")
env.graph.set_static_vars(["actions"])
state = {
    "states": torch.tensor([[1.0, 0.0, 0.1]], dtype=torch.float32),
    "actions": torch.tensor([[0.0]], dtype=torch.float32),
}
outputs = env.infer_k_steps(state, horizon=1, mode="mode")[0]
print(outputs["next_states"])

trajectory = env.infer_k_steps(
    init_state=state,
    horizon=10,
    static_data={"actions": [torch.zeros(1, 1) for _ in range(10)]},
    mode="mode",
)
next_states_curve = [step["next_states"] for step in trajectory]

states 依次为角度余弦、角度正弦和角速度，actions 为施加力矩，next_states 为下一周期状态。输入采用 [批量, 维度]，示例只有一组状态；输出使用原始物理单位。mode="mode" 执行确定性预测，随机推演可按模型支持情况使用 sample 或 rsample。

上例将 actions 声明为外部给定量，并提供完整的十步动作序列。infer_k_steps 返回每一步的输出列表。换成温控任务时，制冷动作、门状态或其他外生量也要按图结构提供；连续推演的下一状态由模型递推，未来实测状态留作对比标签。

infer_one_step 保留历史返回形式：确定性节点返回原始单位张量，随机节点返回归一化空间的分布对象；不能直接将分布的 mode 用作物理量指标。提供 infer_one_step_values 的新版构建可直接用该方法取得原始单位节点张量；旧包可使用上面的 infer_k_steps(horizon=1)。两种数值入口均按 mode 指定的方式取值。

有历史窗口的世界模型还需通过 prefix_data 提供真实历史前缀，输入轴和长度见历史窗口。

计算策略与控制器动作

import torch
from revive.export import load_policy

policy = load_policy("examples/pendulum/logs/repro/models/policy.pt")
print(policy.policy_type)
print(policy.is_stateful)

actions = policy.infer(
    {"states": torch.tensor([[1.0, 0.0, 0.1]], dtype=torch.float32)}
)
print(actions["actions"])

这段适用于无状态倒立摆策略，返回按动作节点命名的字典。将输入改为 [B, D] 可同时处理 B 组状态，输出保留相同批量维度；也可以用 infer_batch 处理状态字典列表。

load_policy 同时用于直接策略、MPC、FFPID 和 Residual PID，policy_type 分别标识 direct、mpc、ffpid、residual_pid。需要内部历史或控制器状态的模型，使用下一节的会话调用。

直接策略可通过 policy.impl.set_deterministic(True) 选择确定性动作。动作输出按设备原始单位解释，例如力矩或制冷功率，范围以任务配置和模型说明为准。

MPC 需要匹配的世界模型和奖励；Residual PID 可能还需要基线控制器。若配置了 future_exogenous_keys，应提供当前时刻已知且覆盖规划长度的预报或计划。模型的输入名称、固定规划长度和依赖可从模型元数据中核对。

管理历史输入与会话状态

冰箱当前温度相同，也可能处于刚停止制冷或持续升温的不同过程。加入历史窗口后，模型需要真实历史初始化；PID 还会保存积分和前次误差。每台设备应维护独立会话，新运行过程重新初始化。

对于采用历史窗口的直接策略，可以按下面的函数创建会话。current_inputs 为当前观测字典，history_prefixes 为按 runtime_manifest 准备的真实历史张量字典：

from revive.export import load_policy

def open_policy_session(model_path, current_inputs, history_prefixes=None):
    policy = load_policy(model_path)
    print(policy.runtime_manifest)
    if history_prefixes is not None:
        session = policy.create_session(warmup_prefixes=history_prefixes)
    else:
        session = policy.create_session(initial_inputs=current_inputs)
    result = session.infer_step(current_inputs)
    return session, result.actions

后续每个控制周期调用 session.infer_step(current_inputs)，会话保存新的内部状态。需要预热的模型应传入真实历史；历史长度、输入键和时间轴顺序以模型说明为准。直接策略也可手动调用 init_runtime_state 或 warmup，再通过 infer_step 传递并保存 next_runtime_state。

批量推理期间保持输入与状态的批量一致。设备切换、轨迹结束或批量大小改变时，按模型接口重新 reset 或创建会话。控制器会话使用 session.step(inputs)，初始化参数以其运行状态说明为准。不同设备分别维护积分和历史状态。

导出并验证 ONNX

标准训练流程会生成 ONNX 并记录验证结果。已有完整部署文件时，可以直接进入下一节；更换导出设置或验证数据时，执行：

revive export \
  --artifact examples/pendulum/logs/repro/models/policy.pt \
  --io-space raw \
  --opset 17 \
  --parity-data examples/pendulum/data/pendulum.npz \
  --verification-seed 42 \
  --verification-steps 32

--artifact 指定部署 PT 文件，验证数据需符合模型输入和历史要求。--parity-data 启用 parity 验证，成功后更新模型目录中的 ONNX 入口及验证记录。正式验证输出写入模型所在目录，不能与自定义 --out 同时使用；搬迁时复制完整模型目录。

选择验证方式

方式	检查什么	用途
checker	ONNX 图结构是否合法	定位导出结构问题
runtime	能否在 ONNX Runtime 中执行	检查运行接口；MPC 等场景采用此方式并评估控制效果
parity	同批输入下与原模型的数值差异	检查导出数值一致性，通常作为默认选择

验证记录包含数据条件、容差和运行环境。更换设备、ONNX Runtime 或执行后端后，在目标环境核对输出与推理延迟。MPC 的候选筛选可能因微小数值差异改变动作，验证设置及限制见保存模型与日志。

导出自定义或有状态模型

专家函数和自定义网络需要在加载前注册。导出命令默认从当前目录发现组件，也可用 --project 指定任务目录：

revive export --artifact examples/my_task/logs/repro/models/env.pt --project examples/my_task

有状态模型会生成初始化、预热和逐步推理等入口；控制器还携带控制状态、动作边界及必要依赖。具体形状与入口保存在 env.onnx.json 或 policy.onnx.json 中，使用配套运行工具读取。

使用 ONNX 运行模型

加载模型并计算输出

从 SDK 根目录安装配套运行工具的依赖：

pip install -r revive/deploy/onnxruntime/requirements.txt

然后加载模型入口说明文件：

import sys
sys.path.insert(0, "revive/deploy/onnxruntime")
from revive_runtime import Bundle

bundle = Bundle.load("examples/pendulum/logs/repro/models/policy.onnx.json")
print(bundle.describe())
session = bundle.open(batch=1)
session.reset()
outputs = session.step({"states": [[1.0, 0.0, 0.1]]})
print(outputs["actions"])

revive/deploy/onnxruntime/revive_runtime.py 与 bundle_contract.py 配套使用，独立部署时一起复制。运行端依赖 NumPy 与 ONNX Runtime。Bundle 根据模型说明读取文件、输入输出和调用关系，应用代码无需自行编写加载器。

模型入口说明包含输入名称、类型、形状、动作范围和验证信息。世界模型使用 env.onnx.json，可调用 session.rollout(inputs, horizon=10) 连续推演；没有状态转移映射的外生输入会沿用首次传入值，需要变化时自行逐步调用 step。

初始化状态与历史

从模型说明检查 stateful、warmup_supported 和 warmup_inputs。允许冷启动时使用 session.reset(inputs)；需要真实历史时使用 session.warmup(history_inputs) 建立状态，再逐步提供当前观测。

预热需要的张量轴由模型决定，不能统一假定时间轴在第一个或第二个位置。每台设备和每组批量分别建立会话，运行中保持批量大小一致。

PID 的积分、滤波等状态由运行工具反馈到下一步。MPC 还需要固定规划长度、采样数、迭代数对应的输入，以及匹配的环境依赖；配套工具按模型说明安排调用。直接集成其他 ONNX 执行器时，还需自行处理这些状态和规划器辅助输入，详细约定见源码 revive/deploy/onnxruntime/README.md。

检查输入与模型文件

运行工具检查输入名称、形状、非有限值以及模型声明的类别或有序离散取值。连续输入超出历史数据范围时，应由业务侧结合已验证工况判断适用性；动作和设备限制按业务规则处理。

运行工具会自动检查模型文件；出现文件缺失或不匹配时，重新复制完整目录或重新导出。较早的文件若缺少输入域信息，可通过重新导出补齐检查信息。直接使用第三方 ONNX Session 时，业务输入校验和状态管理需要由接入程序实现。

接入业务系统

启动推理服务

以下命令从 SDK 根目录执行，使用已经完成训练的模型：

python revive/deploy/onnxruntime/serve.py \
  --bundle examples/pendulum/logs/repro/models/policy.onnx.json

保持服务终端运行，在另一个终端查看接口并请求动作：

curl -s http://localhost:8000/contract
curl -s -X POST http://localhost:8000/step \
  -H 'Content-Type: application/json' \
  -d '{"inputs": {"states": [[1.0, 0.0, 0.1]]}}'

响应的 outputs.actions 为模型计算的力矩。参考服务演示模型调用，业务系统负责将数据采集、设备执行、请求管理和异常处理接入自己的服务。

容器部署可以使用 revive/deploy/onnxruntime/Dockerfile，从 SDK 根目录执行：

docker build -t revive-onnx-serve revive/deploy/onnxruntime
docker run --rm -p 8000:8000 \
  -v "$PWD/examples/pendulum/logs/repro/models:/models:ro" \
  revive-onnx-serve --bundle /models/policy.onnx.json

模型目录单独挂载，更新时保留模型与报告对应关系。

对接输入、输出与设备会话

接入内容	需要确认什么
输入	节点名、列顺序、形状、单位、采样周期与数据延迟
输出	动作单位、允许范围、如何传给执行设备
会话	每台设备独立维护状态，明确 reset 和预热时机
性能	在实际设备上测量推理延迟，满足控制周期
运行结果	对照实测反馈持续检查目标跟踪、动作变化与工况覆盖

参考 HTTP 接口如下：

接口	用途
GET /healthz、GET /contract	查询服务状态与模型接口说明
POST /reset	按当前观测初始化会话
POST /warmup	使用真实历史建立会话状态
POST /step	推理一步
POST /rollout	世界模型连续推演

请求可携带 session_id 区分设备，输入张量使用嵌套数组。有状态模型先初始化或预热；后续 step 只传当前输入。形状或字段错误通常返回 400，尚未初始化的有状态会话返回 409。默认会话数、推演长度和请求读取时间分别限制为 128、10000 步、10 秒，可按业务资源调整。

处理异常与更新模型

提前确定输入缺失、过期、推理超时或超出验证工况时的处理方式，例如等待新数据或切回现有控制方案。更新模型时保留上一版本的完整模型、依赖和接口信息，先在目标环境核对固定输入的输出，再切换业务流量。

完成业务验收后，保存模型目录、配置、扩展代码、依赖清单、报告与操作说明。需要继续训练时另行保留完整训练记录。

接入不确定性信号时，按不确定性运行说明检查校准、验收和会话更新。信号的 accepted 与 ONNX 验证分别表示不同结果，应分别确认。

处理部署问题与版本升级

根据现象排查

现象	优先处理
找不到文件或加载类型不符	检查路径，世界模型用 load_env，策略用 load_policy，不要传训练检查点
自定义函数或网络未注册	加载前发现任务组件，导出时指定 --project
模型与依赖不匹配	恢复匹配的扩展代码、环境模型、奖励或基线文件
ONNX 摘要不匹配或缺少入口文件	重新复制整个模型目录，包含隐藏文件
有状态模型未初始化	按模型要求 reset 或 warmup，再调用 step
导出结构错误或 parity 超差	核对自定义运算、输入、历史、精度与执行环境，见ONNX 故障排查

加载文件的版本与依赖应匹配。下面的简表用于判断采用继续使用原环境、重新导出还是重建附加文件：

输出文件	版本标记	当前值	处理方式
PT 部署模型	manifest_schema_version	3	保留匹配的模型结构、归一化与自定义组件
ONNX 部署文件包	contract_version	revive.onnx.bundle.v2	版本不符时使用支持的导出流程重新导出
不确定性 sidecar	schema_version	2	使用相应模型与数据重新构建

核对 ONNX 说明文件版本

字段	当前值
schema_version	2
export_identity.schema_version	1
verification_identity.schema_version	1
runtime_manifest.schema_version	1

旧 v1 说明文件需要重新导出。模型文件、调用入口与验证记录应来自同一次导出，直接修改版本字段不能完成转换。

升级前验证已有模型

在独立环境安装目标版本，保留原环境与完整模型。先加载 PT 模型，核对一批固定输入的输出，再在目标 ONNX 运行环境验证。需要继续训练时，还要检查完整训练状态与原配置是否兼容，见恢复中断训练。

修改自定义函数会影响模型依赖，调整归一化、状态形状、MPC 固定参数或执行后端也可能需要重新导出并验证。比较或更新模型时，应保存各自配套的代码与文件。

处理旧版本项目

1.x 与 2.0 使用独立 Python 环境。可以下载本版本迁移工具，工具说明也位于源码 scripts/migration/README.md。

从 SDK 根目录执行，或解压工具包后从其根目录执行。以下命令将支持的 1.x 配置与数据转换到新的输出目录：

python -m scripts.migration.legacy_inputs \
  --config /old/metadata.yaml \
  --data /old/expert_data.npz \
  --output /new/conversion \
  --action-node actions \
  --algorithm venv.bc \
  --action-bound action=-2,2 \
  --epochs 1 \
  --device cpu

actions 为节点名，action 为列名，边界按任务确认。转换结果包含配置、数据和映射报告；核对报告后执行输出的预检与训练命令。工具支持的旧配置字段和数据结构有明确范围，专家函数、自定义节点、未知字段等需要按报告单独处理。原文件保持不变，输出目录必须尚不存在。

改名前开发版 revive2 的 Graph、环境或直接策略 PT，可按 scripts/migration/revive2_artifact.py 说明，提供旧环境的固定输入与参考输出进行显式转换。该入口不适用于 1.x 模型、自定义扩展、历史状态、控制器或续训检查点。迁移后仍需在目标任务中验证预测和控制效果。