故障排查

本页按报错信息与失败阶段列出常见问题、原因和处理方法。

训练前可先执行带数据的深度验证，检查配置、图结构与实际输入：

bash

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

安装与环境混装问题先查安装与授权。遇到缺少许可证、设备绑定不匹配或在线申请失败时，先看授权问题； validate 不会申请在线许可证，首次在线用户按首次运行操作。

从报错定位

决策树的每个分支对应 revive 中一个具体的异常类，命中某个分支后即可得到对应的处理步骤。

首先查看异常类型

报错信息的第一行会给出异常类名，它决定问题归属：

revive.config.codec.ConfigCodecError: 配置里有未知字段: ...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

继承 revive.UserError 的异常表示用户可自行修复（配置、数据、命令行）。CLI 遇到此类异常仅输出一行说明，不打印 traceback——traceback 对这类问题没有诊断价值。若看到完整 traceback，则说明是框架内部问题，请连同 traceback 一起提交 issue。

flowchart TD
    A[训练/校验失败] --> B{异常类名}

    B -->|ConfigCodecError| C1[配置字段名或类型写错]
    B -->|DefaultsResolutionError| C2[超参覆写的字段默认层没声明]
    B -->|ConfigResolutionError| C3[运行时输入：数据路径 / run_id / resume]
    B -->|ProfileError| C4[--profile 用法]

    B -->|DataLoadError<br/>DatasetBuildError| D1[数据本身：列、形状、划分]

    B -->|GraphBuildError<br/>LayoutCompileError<br/>TransitionResolutionError<br/>DeltaContractError| E1[图结构：节点、转移、delta 契约]
    B -->|PolicyNodeInferenceError| E2[policy_nodes 无法推断，需显式声明]

    B -->|PreflightError| F1{预检的哪一项}
    F1 -->|onnx_action_bounds| F2[动作节点缺少物理边界]
    F1 -->|execute| F3[图无法执行：自定义函数/网络]
    F1 -->|output| F4[输出契约：canonical 训练强制 ONNX]

    B -->|ValidationPlanError| G1[validation / selection 配置]
    B -->|AlgorithmRegistryError<br/>DefaultsResourceError| G2[默认层被改动或算法未注册]
    B -->|SweepConfigError<br/>OverrideError| G3[Sweep / HPO 配置]

    C1 --> H1[配置解析]
    C2 --> H1
    C3 --> H1
    C4 --> H1
    D1 --> H2[数据与形状]
    E1 --> H2
    E2 --> H2
    F2 --> H3[ONNX 导出与 Parity]
    F3 --> H2
    F4 --> H3
    G1 --> H4[训练与数值稳定性]
    G2 --> H5[见下方「默认层被改动」]
    G3 --> H4

    style A fill:#ffebee,stroke:#c62828,stroke-width:1.5px,color:#b71c1c
    style B fill:#fff8e1,stroke:#f9a825,stroke-width:1.5px,color:#e65100
    style F1 fill:#fff8e1,stroke:#f9a825,color:#e65100
    style H1 fill:#e8eaf6,stroke:#3f51b5,color:#1a237e
    style H2 fill:#e8eaf6,stroke:#3f51b5,color:#1a237e
    style H3 fill:#e8eaf6,stroke:#3f51b5,color:#1a237e
    style H4 fill:#e8eaf6,stroke:#3f51b5,color:#1a237e
    style H5 fill:#e8eaf6,stroke:#3f51b5,color:#1a237e

各异常类及其触发条件逐条列于异常与错误约定。

授权问题

先区分使用的是在线 access key 还是离线许可证。在启动训练的同一环境中执行：

bash

revive --version
revive license status

状态查询只检查已有许可证，不向服务器创建训练申请。首次在线用户仅完成 revive register 时，查询可能返回 missing_license，请按首次运行启动训练。已经取得许可证后出现错误，再按下表处理：

现象或错误码	检查与处理
`access_key_missing`	在当前用户下执行 `revive register`，或配置离线许可证
离线运行出现 `missing_license`、`invalid_path` 或 `unreadable_license`	检查 `REVIVE_LICENSE` 是否为实际文件的绝对路径、进程是否有读取权限；服务和容器需要单独配置环境变量
`runtime_rejected`、许可证验证失败或设备绑定不匹配	核对有效期、系统时间和实际运行设备；换机或容器重建后，按授权约定重新采集机器信息并申请许可证
`access_denied` 或 `entitlement_rejected`	核对当前账号的 access key 与训练权限；联系技术支持确认权限后再启动任务
`request_uncertain`、`invalid_response` 或提示申请结果待核对	检查网络是否可访问授权服务，保留申请编号并联系技术支持核对；不要删除记录或反复新建任务重试
`online_run_changed`	续训时恢复原配置、数据路径、运行 ID 和日志目录；确实需要修改任务时，使用新的运行 ID
`offline_license_required` 或当前任务不支持在线申请	控制器任务及追加训练轮数使用离线许可证，按离线授权配置
更换许可证后仍报旧错误	检查环境变量是否仍指向旧文件，重启训练或推理进程，使新许可证生效
配置 access key 后仍提示离线许可证失效	指定或已安装的离线许可证优先；更新该文件，或在确认切换授权方式后移除旧离线配置
新机器能读取 PT 文件，但无法用 SDK 加载	PT 文件未加密，但加密 SDK 需要在新环境中配置有效许可证；仅保存 access key 不会为模型加载申请许可证

配置了环境变量时，即使文件缺失也不会自动回退在线授权。容器需在实际运行环境中采集机器信息，是否绑定 machine-id、硬盘或 MAC 以及到期日期均以许可证约定为准。完全断网运行应使用按离线模式签发的许可证。

联系技术支持时提供 REVIVE 版本、Python 版本、错误码、发生时间及已有申请编号。 access key、许可证文件内容和完整账号配置无需放入公开问题记录。

高频问题

`ood.weight_schedule.zero_epoch 必须为正`

venv.revive_p 的 OOD 权重调度默认取本 stage 的 epochs。stage 未声明 epochs（或声明为 0）时，该默认值无法生效。需显式声明：

yaml

hyperparameters:
  epochs: 1000

`onnx_action_bounds` 预检失败，`missing=['action:raw', ...]`

direct policy 会导出为 ONNX，而 ONNX 中需要将动作裁剪到物理边界——边界必须是物理事实，不能从数据统计中估计。应在图的动作列上明确声明：

yaml

columns:
  - name: action
    node: action
    type: continuous
    min: -1.0      # 执行器的实际下限
    max: 1.0

不确定边界取值时，revive suggest-bounds 会基于数据给出一个起点，但最终数值必须由使用者按硬件规格确认。

`Function 'xxx' not registered. Available: [...]`

配置中按名称引用的自定义图函数/网络未完成注册。train 和 validate 从配置文件所在目录 自动发现，export 从当前目录（或 --project 指定的目录）发现：

bash

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

`defaults hash mismatch for algorithms.xxx`

算法默认配置随 SDK 安装包提供。精确续训要求使用与原训练匹配的默认配置，修改默认层可能导致续训失败。输出保存策略升级会读取旧记录冻结的输出默认层；显式迁移 best_only 通过独立策略文件记录，不改写旧配置指纹。其他默认层变更仍需逐项检查兼容性。

不要直接修改 SDK 内的默认配置。 需要调整参数时，在任务配置文件中覆写；升级 SDK 后需要续训时，请先确认原训练状态与目标版本兼容。

`resume identity mismatch` / `continuation manifest ... 冲突`

精确续训要求十二项身份逐位一致：run、record、stage 序号与名称、domain、算法键、图签名、数据指纹、配置指纹、默认层指纹、选优签名、依赖。修改验证设置也会改变训练结果——例如修改 num_trajectories 会经由 checkpoint 选优影响后续阶段。详见精确续训与部署问题与版本升级。

`uncertainty sidecar ... schema v1 已退役`

对该 record 重新执行一次 revive uncertainty build-v2。v2 插件都从 (record, 数据) 构建，不需要读取旧的 calibration.pt。见不确定性评估。

配置解析

未知字段。 Source YAML 是严格 schema。检查字段是否应放在 stage.hyperparameters，算法键是否完整，以及是否误用了旧格式 venv:、policy:、preset:、overrides:。

未知算法。 必须用完整键，例如 venv.bc、policy.ppo；短名 bc / ppo 不是合法写法。

默认值合并失败。 通常由未知超参数、类型写错，或用 null 覆盖了不可为空的值导致。查对应的算法参数参考。

路径错误。 reward、function、自定义网络与 baseline 的相对路径以配置文件所在目录为基准，而不是以执行 shell 的当前目录为基准。

数据与形状

Key 缺失。 图的外部 source 必须存在于 NPZ，或能由 transition/delta 派生。用 revive info --data 检查。

列宽不一致。 节点数组最后一维必须等于 columns 声明的 raw 列数；category 的展开由系统完成， NPZ 仍只存一个 raw 类别值。

Index 错误。 index 必须严格递增，最后一个值等于总行数。每条轨迹的长度至少应大于 transition、 history 与配置的 horizon 之和。

NaN/Inf。 应在数据生成阶段就检查有限值。归一化与损失计算不会自动过滤所有异常值，训练与验证的处理规则需要明确说明缺失值的处理方式。

训练与数值稳定性

Loss 不下降。 先检查目标节点、raw/归一化空间、数据对齐与分布类型，再调整容量或学习率。用单个 batch 进行过拟合测试，可以区分「实现错误」与「泛化失败」。

推演发散。 单步正常但推演发散时，应缩短 horizon，检查 transition、外生输入与动作范围，并考虑序列 rollout 训练。不能只依赖加宽网络。

梯度非有限。 降低学习率与更新比、启用合理的梯度裁剪、检查奖励/归一化尺度、分布 logstd、 PPO ratio 或 SAC 的 Q target。日志中第一个非有限值出现的位置，比最终的 NaN 更有诊断价值。

显存不足。 依次减小 batch size、rollout/序列 horizon、轨迹数、MPC 采样数、网络宽度。清理缓存无法解决配置本身超出预算的问题。

更系统的调优方法见改善预测与控制效果。

精确续训

找不到 latest。 默认 best_only 不生成 latest，请使用 --resume best --run-id <run> 或最优轮次的 checkpoints/best_train_state.pt。旧 legacy 记录仍支持 latest；自动选择器必须只匹配一个 record。

存在歧义。 同一次运行有多个可续训 record 时，使用 run/domain/record selector 或完整的 best_train_state.pt 路径（legacy 也支持 latest.pt）。

身份不一致。 图、数据、默认层、选模规则或 stage 依赖发生变化后，旧 checkpoint 已不属于同一次精确运行，此时请新建 run 或 stage。manifest 记录的是这次训练的身份，修改它会使身份记录与实际训练不符。

文件类型错误。 env.pt、policy.pt、best.pt 是部署/选模输出文件，不能用于续训。

ONNX 导出与 Parity

缺依赖。

bash

python -m pip install -e ".[onnx]"

缺少动作边界。 在 graph.columns 中声明经过确认的 raw min/max，不要依赖数据统计自动推断。

函数 tracing 失败。 移除 NumPy、.item()、文件 I/O、内部随机数，以及依赖张量取值的 Python 分支。所有输出必须是有限张量并保持 batch 轴。

Parity 超差。 检查导出 dtype、opset、动态/固定维、运行时状态回传、随机辅助输入与容差。 不要通过放宽容差来掩盖语义差异。

Bundle 不完整。 重新复制完整的导出目录，或重新导出模型。保留根 sidecar 与其引用的全部文件，不要混用不同次导出的内容。

CUDA 与 NPU

显式设备不可用时会直接失败。 cuda:N / npu:N 是 fail-fast 的，只有 auto 会按 NPU → CUDA → CPU 降级。这是有意设计的：静默回落到 CPU 会使一次本应几小时的训练延长为数天。

python

import torch
print(torch.__version__)
print(torch.version.cuda)
print(torch.cuda.is_available(), torch.cuda.device_count())

昇腾 NPU 需在每个 shell 中先加载 CANN，并使用独立的 NPU 环境：

bash

source /usr/local/Ascend/cann-8.5.0/set_env.sh
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
export TORCH_DEVICE_BACKEND_AUTOLOAD=0

检查 CANN、驱动、设备权限、ASCEND_RT_VISIBLE_DEVICES 与 torch / torch-npu 的精确版本。

单模型多卡 DDP/HCCL 当前不支持；Sweep 的多卡是指多个独立 trial。

性能与资源

主要成本来源：

功能	主要乘数
序列训练	batch × horizon × 图节点数
PPO	轨迹数 × horizon × 更新轮数
SAC	rollout 长度 × 每步更新数 × Q 数量
MPC	horizon × 采样数 × 迭代数
Validation	轨迹数 × horizon × 频率

优化顺序：

先用 profiler 或日志确认耗时在训练、验证还是导出环节。
减少不必要的验证/绘图频率，但保留最终验证。
调整 batch 与 horizon，而不是只增加 worker。
关闭训练期绘图不影响指标与输出文件。
Sweep 使用共享的预处理数据，避免每个 trial 重复执行 CPU 预处理。

性能测试与功能冒烟是两回事：低 epoch 的冒烟只能证明流程可以完整运行，不能证明算法指标没有回归。

整理诊断材料

最高效的材料组合是：

bash

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

同时保留完整异常信息和调用栈、logs/<run>/config.resolved.yaml、 logs/<run>/<domain>/<record>/record_info.json，以及复现所需的最小数据 schema。

排障时请将这些信息保存在本地；分享前去除凭据、客户标识和不必要的原始数据。当前的支持形式为版本化文档，在线工单与人工响应需另行约定。

异常与错误约定

REVIVE 使用异常类型与触发条件描述错误。本页按配置、图执行、数据、策略和训练等模块列出异常及对应实现，便于定位问题。

实现引用采用 路径::符号 格式，并通过自动化测试检查符号是否存在。

0. 错误分类与处理方式

异常按问题来源与处理方式分为以下两类（见 revive/errors.py）：

类别	判据	CLI 行为
`UserError` 子类	配置有误、数据不符合要求、路径不存在	仅输出一句消息，不打印调用栈
其余异常	框架自身的问题	保留完整调用栈，便于提交问题报告与定位原因

UserError 作为附加基类混入既有异常类型（ConfigCodecError(UserError, ValueError)），因此原本 except ValueError 的调用方无需任何修改。判断依据是类型而非消息内容，因为消息会随文案调整而变化。

0.1 消息语言：双语

用户包括内部算法团队与合作方工程师，双方阅读的语言不同。因此每一条用户可见的消息都以 bi(中文, 英文) 形式编写，运行时按语言选择其中一份：

python

from ..i18n import bi

raise ConfigResolutionError(
    bi(
        f"seed 必须是整数，收到 {seed!r}",
        f"seed must be an integer, got {seed!r}",
    )
)

语言优先级：revive.set_language() > 环境变量 REVIVE_LANG > 默认中文。CLI 另有 --lang {zh,en}。REVIVE_LANG 接受 en_US.UTF-8 这类 locale 写法；值填写错误时仅告警并回落，不会阻止训练启动。

REVIVE 默认使用中文，不跟随系统 locale。需要其他语言时，通过环境变量、CLI 或 Python 接口显式设置。

双语消息的覆盖范围

UserError 从来不是「用户可见错误」的完整分类：ConfigValidator 抛出的是普通 ValueError （而且是先 errors.append(...) 收集、最后统一抛出），不确定性子系统有自己的一套异常类，它们都是用户配置错误时会读到的。因此覆盖面为：

表面	是否双语
任何 `raise` 抛出的消息	是
收集进 `errors` / `mismatches` / `reasons` 等诊断列表的条目	是
`logger.*` 输出的训练日志	是
CLI 的横幅、报告、`--help` 帮助文本	是
注释、docstring、设计文档	否（读者是代码维护者）

唯一豁免：revive/i18n.py 中两条「语言设置有误」的消息。此刻语言正是尚未确定的变量，使用 bi() 会递归调回自身，因此它们将中英写在同一句中。

双语消息的定义方式

消息通过 bi(zh, en) 在调用位置同时定义中文和英文，便于核对上下文与插入值。两个语言参数均为必填，自动化测试还会检查语言归属及格式化字段的一致性。

测试锁定什么

tests/unit/test_bilingual_messages.py：

两个参数必填且非空；
语言归属未写反（第一个含中日韩字符、第二个不含）；
两半插入的是同一组值——中文消息报了字段名而英文漏带时，读英文的用户会拿到一句正确但无法定位问题的话，而这种缺失没有任何运行时症状；
新代码不能绕过 bi()（raise / append / logger / CLI 四个面各有一条检查）；
真实切换语言运行一遍实际报错与 --help。

编写测试时不要断言英文消息片段，也不要断言中文片段——应断言异常类型，或使用 set_language() 固定语言后再断言关键词。

1. Builder / Config 异常

异常	来源	触发条件
`FileNotFoundError`	`revive/config/parser.py::ConfigParser.parse`	配置文件不存在
`ValueError`	`revive/config/validator.py::ConfigValidator.validate_or_raise`	配置不满足 graph/data/training 约束
`DataLoadError`	`revive/builder/pipeline.py::_load_data`	数据文件不存在或格式不支持
`DatasetBuildError`	`revive/builder/exceptions.py::DatasetBuildError`	数据集构建失败
`GraphBuildError`	`revive/builder/exceptions.py::GraphBuildError`	图构建失败或未知网络类型
`DimensionInferenceError`	`revive/builder/graph_builder.py::_sum_dims`	无法从输入数据推断节点维度

2. Graph / Runtime 异常

异常	来源	触发条件
`ValueError`	`revive/graph/model.py::__init__`	`GraphModel` 缺少 `NormModule`
`ValueError`	`revive/graph/model.py::add_node`	重复注册节点
`ValueError`	`revive/data/batch.py::require_space`	`Batch.space` 未标记或与期望空间不匹配
`NotImplementedError`	`revive/graph/model.py::forward_raw_values`	请求尚未支持的 `return_runtime_state=True`
`ValueError`	`revive/graph/model.py::rollout`	`skip_nodes` 缺失对应 `static_data` / `override_values`
`ValueError`	`revive/graph/model.py::load`	artifact 缺少 `node_configs` / `transition` 等关键字段

3. Data 异常

异常	来源	触发条件
`ValueError`	`revive/data/trajectory_store.py::__init__`	backend 长度与轨迹索引不一致
`ValueError`	`revive/data/trajectory_store.py::_auto_derive_next_states`	删去轨迹末步后没有有效数据
`ValueError`	`revive/data/dataset_provider.py::__init__`	`DatasetProvider` 缺少 `norm_module`
`TypeError`	`revive/data/dataset_provider.py::__init__`	provider 输入不是 `TrajectoryDataset`
`ValueError`	`revive/data/dataset_provider.py::_split_dataset`	未知 `split_mode`

4. Policy / Reward 异常

异常	来源	触发条件
`ValueError`	`revive/policy/mpc_policy.py::__init__`	无法推断每个 action key 的维度
`ValueError`	`revive/policy/mpc_policy.py::infer`	未知 MPC 优化方法
`ValueError`	`revive/builder/reward_loader.py::load`	奖励配置为空或路径为空
`FileNotFoundError`	`revive/builder/reward_loader.py::_load_module`	奖励函数文件不存在
`AttributeError`	`revive/builder/reward_loader.py::load`	奖励函数名不存在

4b. Controller Stage 校验异常

ConfigValidator 对 algorithm: controller 的 stage 做专项校验（revive/config/validator.py::_validate_controller_stage）。以下为聚合后由 validate_or_raise 抛出的 ValueError（错误信息累积在列表中）：

触发条件	来源
`controller.type` 缺失或非 `mpc/ffpid/residual_pid`	`revive/config/validator.py::_validate_controller_stage`
`type=residual_pid` 但缺 `controller.residual_pid` 配置块	`revive/config/validator.py::_validate_controller_stage`
`type in (ffpid, residual_pid)` 但 `policy_nodes` 数量 != 1（第一版单 action key 约束）	`revive/config/validator.py::_validate_controller_stage`
residual_pid 值域非法：`kp/ki/kd < 0` 或 `delta_max/rate_limit/i_max < 0` 或 `sample_dt_h <= 0`	`validator.py` (`_validate_residual_pid_values`)；同源运行期校验在 `revive/train/controller_tuning/backends/residual_pid_backend.py::_check_values`
`sequence_train.target_map` 的输出 key ∉ `target_keys`，或 source key ∉ batch（fail-fast）	`revive/train/trainers/world_model/bc_trainer.py::_validate_sequence_target_map`
`direct_sequence_supervision` 但 target 非单节点 / 节点无 `forward_sequence` / `output_dist != deterministic`	`revive/train/trainers/world_model/bc_trainer.py::_direct_sequence_node_and_target`

行为变化（校验放宽）： controller stage 的 policy_nodes 不再校验节点存在性（revive/config/validator.py::_validate_stage，对所有 controller stage 含 mpc/ffpid 生效），因 residual PID 的 action 可能是非节点的 external input 列（action_feature）。非 controller stage 的 policy_nodes 节点存在性校验保持不变。

4c. ConfigValidator 分支全表

ConfigValidator 将所有错误累积成列表，由 validate_or_raise 一次抛出——而非遇到第一个即停止。这是有意设计的：配置错误通常不止一处，逐个报告会让使用者来回修改多轮。

下表逐条对应 revive/config/validator.py 中的每个 _validate* 分支，以及从中拆分出的规则模块；tests/unit/test_error_contract_doc.py 保证新增分支必须在此登记。

分支	管什么	典型错误
`revive/config/validator.py::_validate_graph`	图结构	一个节点都没有；节点名用了 `__hist_` / `__stateful_` 运行时保留前缀；节点缺输入；未知节点类型
`revive/config/warmup_rules.py::validate_warmup_contract`	warmup 约定	声明了 `graph.warmup_depth` 却没有任何节点声明 `warmup_inputs`、也没用历史语法——约定无法被满足，前缀会被静默丢弃
`revive/config/validator.py::_validate_data`	数据块	`train_ratio` 不在 (0, 1)（没有显式 val 文件时就切不出验证集）；未知 `normalization` / `split_mode`；`batch_size` 非正
`revive/config/validator.py::_validate_output`	输出约定	`output.onnx.enabled/required` 不为 true（标准训练不提供 ONNX opt-out，失败不得静默完成）；`onnx_validate` 取值非法
`revive/config/validator.py::_validate_training`	训练块	一个阶段都没有；`device` 非法
`revive/config/validator.py::_validate_stage`	单个阶段	`stage.graph` 指向不存在的 graph；PPO 缺 `reward` 或 `policy_nodes`；`epochs <= 0`
`revive/config/validator.py::_validate_adm2_stage`	ADM2 独立 venv 阶段	还写着 `inherit_from`（ADM2 不再依赖上游 venv）；`metric` / `adm2.backend` 取值非法；缺 `adm2.target`
`revive/config/validator.py::_validate_migration`	迁移声明	不支持的 `migration.*` 取值
`revive/config/validator.py::_validate_controller_stage`	controller 阶段	缺 `policy_nodes` / `reward` / `controller` 块；`algorithm` 与 `controller.type` 不一致
`revive/config/validator.py::_validate_controller_search`	调参搜索空间	搜的字段不在该 backend 白名单里；`search.*` 不是非空列表；同一字段既显式填了又出现在 `tune.search` 中
`revive/config/validator.py::_validate_mpc_values`	MPC 值域	`method` 非 `random/cem/mppi`；`horizon` / `num_samples` / `num_elites` 非正
`revive/config/validator.py::_validate_ffpid_values`	FFPID 值域	`kp/ki/kd`、`derivative_filter_tau` 为负
`revive/config/validator.py::_validate_residual_pid_values`	残差 PID 值域	`sample_dt_h <= 0`；增益或限幅为负

5. Training 异常

异常	来源	触发条件
`ValueError`	`revive/train/trainers/policy/ppo_trainer.py::_init_ppo`	`segment_sampling_mode` 非法
`ValueError`	`revive/train/trainers/policy/sac_trainer.py::_init_sac`	SAC 使用不支持的 `bpc_type`
`ValueError`	`revive/train/orchestrator.py::resolve_world_model_source`	policy/controller 父 stage identity 缺失或无法唯一解析
`FileNotFoundError`	`revive/train/orchestrator.py::resolve_world_model_source`	`logs/<run_id>/venv/<venv_record_id>/model/env.pt` 不存在（venv 阶段未导出 deployment）
`RuntimeError`	`revive/train/orchestrator.py::resolve_world_model_source`	env.pt 加载失败（损坏或与当前结构不兼容）
`RuntimeError`	`revive/train/trainers/policy/ppo_trainer.py::_get_store`	provider 不可用，无法采样 rollout 片段

5b. 模型导出 / 加载异常 (revive.export)

异常	来源	触发条件
`FileNotFoundError`	`revive/export/save.py::_load_best`	部署导出时找不到部署格式 `best.pt`（该 stage 从未产生 best），使 stage fail-fast
`ValueError`	`revive/export/save.py::_load_best`	`best.pt` 不是 GraphModel 部署格式（缺 `state_dict`）
`FileNotFoundError`	`revive/export/save.py::save_controller_record`	controller bundle `best.pt` 不存在
`ValueError`	`revive/export/save.py::save_controller_record`	未知 `controller_type`（非 mpc/ffpid/residual_pid）
`ValueError`	`revive/export/load.py::_read_deployment`	`.pt` 顶层非 dict，或缺 `deployment`/`kind` 元数据块（裸 checkpoint 而非 deployment 输出文件）
`ValueError`	`revive/export/load.py::load_env / load_policy`	`kind` 错配（`load_env` 读到非 env、`load_policy` 读到非 policy）；`load_model` 收到目录或未知 kind
`ValueError`	`revive/export/load.py::load_policy`	direct policy 缺 `policy_nodes`；或未知 `policy_type`
`ValueError`	`revive/export/load.py::_load_controller_policy`	controller policy 无法定位 env（既无同目录 env.pt 也无 env_source）；mpc 的 reward_fn 缺失/加载失败
`ValueError`	`revive/export/load.py::resolve_env_path`	policy 元数据缺 `env_source`

6. 处理规则

不要吞没 ConfigValidator、GraphBuildError、DimensionInferenceError 这类结构性错误。
对 rollout / plotting 的非关键路径失败，可记录 warning，但必须保留主训练错误语义。
新增异常类型时，同步更新本文件与相关 feature 的验收标准。

故障排查 ​

从报错定位 ​

首先查看异常类型 ​

授权问题 ​

高频问题 ​

ood.weight_schedule.zero_epoch 必须为正 ​

onnx_action_bounds 预检失败，missing=['action:raw', ...] ​

Function 'xxx' not registered. Available: [...] ​

defaults hash mismatch for algorithms.xxx ​

resume identity mismatch / continuation manifest ... 冲突 ​

uncertainty sidecar ... schema v1 已退役 ​

配置解析 ​

数据与形状 ​

训练与数值稳定性 ​

精确续训 ​

ONNX 导出与 Parity ​

CUDA 与 NPU ​

性能与资源 ​

整理诊断材料 ​

相关页 ​

异常与错误约定 ​

0. 错误分类与处理方式 ​

0.1 消息语言：双语 ​

双语消息的覆盖范围 ​

双语消息的定义方式 ​

测试锁定什么 ​

1. Builder / Config 异常 ​

2. Graph / Runtime 异常 ​

3. Data 异常 ​

4. Policy / Reward 异常 ​

4b. Controller Stage 校验异常 ​

4c. ConfigValidator 分支全表 ​

5. Training 异常 ​

5b. 模型导出 / 加载异常 (revive.export) ​

6. 处理规则 ​

故障排查

从报错定位

首先查看异常类型

授权问题

高频问题

`ood.weight_schedule.zero_epoch 必须为正`

`onnx_action_bounds` 预检失败，`missing=['action:raw', ...]`

`Function 'xxx' not registered. Available: [...]`

`defaults hash mismatch for algorithms.xxx`

`resume identity mismatch` / `continuation manifest ... 冲突`

`uncertainty sidecar ... schema v1 已退役`

配置解析

数据与形状

训练与数值稳定性

精确续训

ONNX 导出与 Parity

CUDA 与 NPU

性能与资源

整理诊断材料

相关页

异常与错误约定

0. 错误分类与处理方式

0.1 消息语言：双语

双语消息的覆盖范围

双语消息的定义方式

测试锁定什么

1. Builder / Config 异常

2. Graph / Runtime 异常

3. Data 异常

4. Policy / Reward 异常

4b. Controller Stage 校验异常

4c. ConfigValidator 分支全表

5. Training 异常

5b. 模型导出 / 加载异常 (revive.export)

6. 处理规则