不确定性评估

不确定性评估为世界模型的预测补充数据覆盖、预测误差和区间信息。您可以用这些信息发现需要重点复核的工况，并在验证充分后设置动作干预规则。本页说明如何选择信号、构建附加模块、阅读指标和接入推理流程。

使用场景与任务示例

离线数据记录的是已有控制方式访问过的状态和动作。新策略可能选择记录中很少出现的动作，模型也可能遇到新的负载或环境条件。平均预测误差较小，并不意味着每次预测同样可靠。

机器人控制：检查动作是否离开数据范围

在机器人控制中，模型根据 17 维观测与 6 维动作预测后续运动。若新策略经常把关节动作推到数据很少覆盖的区域，可以观察 OOD 信号，并核对这些状态与动作下的预测误差。输入偏离数据分布时，应结合真实仿真结果判断是否保留策略。

水处理：区分浓度误差与业务边界

在水处理中，同一个出口浓度预测在不同流量、温度或仪表条件下可能有不同误差。Risk 可以帮助定位误差较大的转移；针对受支持的一维单步目标，Interval 可给出原始浓度单位的区间，再与业务范围比较。

例如，假设预测浓度为 0.92 mg/L，校准区间为 [0.81,1.03] mg/L，而业务正常范围为 [0.8,1.0] mg/L：点预测位于正常范围，区间却覆盖超限区域。这个示例说明区间与点预测应同时阅读，具体处置由业务规则决定。

附加模块（sidecar）独立保存并绑定世界模型标识。可以针对同一个 env.pt 比较不同插件组合，保持主模型不变。插件效果需要在目标任务的数据上检验。

选择并理解信号

信号	用途	关键字段	单位或含义
OOD	检查输入对训练支持集的偏离	probability、percentile	经校准的概率或支持集分位
Risk	估计本步预测误差	expected_error、upper_error	processed MAE
Interval	给出校准后的预测区间	lower、upper	目标节点的原始物理单位
Constraint	表达领域约束状态	margin、severity	领域物理单位

按业务问题选字段

OOD 描述数据覆盖，Risk 描述预测误差。分布内的样本可能因测量噪声或未观测状态而难以预测；分布外的样本也可能仍符合模型已经学到的规律。两类信号应分别阅读。

expected_error 是误差点估计，upper_error 才是带名义覆盖率的上界。Risk 的 processed MAE 不能直接当成 mg/L、°C 等物理误差使用。Interval 使用原始物理单位，目前支持一维单步目标。Constraint 已定义接口，但内置插件尚未提供。

OOD raw_score 的尺度依赖具体方法；percentile 表示相对支持集的位置；probability 需要带 OOD 标签的数据校准。ensemble std 或模型输出 std 也需要经过校准和验证，才能作为误差范围使用。

四类信号分别校准、验收和设置阈值，保留各自的单位，不混合成一个统一分数。

区分验收与当前可用性

accepted 表示插件是否通过构建时配置的验收，available 表示当前时刻能否提供有效信号。预热不足、输入缺失、预测时域不匹配或信号过期，都可能使当前信号不可用。检查 accepted 时，同时确认已经设置了适用的验收 profile。

配置、构建与校准

从单步误差风险开始

下面以状态 obs、动作 action 的项目为例，将片段加入已有完整训练 YAML。字段名需与项目图一致：

uncertainty:
  enabled: true
  schema_version: 2
  runtime:
    mode: shadow
    sampling_mode: mode
    action_nodes: [action]
  plugins:
    - id: step_risk
      type: direct_risk
      features:
        provider: transition_concat
        config:
          state_keys: [obs]
          action_keys: [action]
          prediction_keys: [obs]
      config: {epochs: 30, hidden_dims: [256, 256]}
      validation:
        profile: risk_default
  routing:
    risk:
      sources: [step_risk.risk]
      decision_field: upper_error
      threshold: 0.15
      threshold_unit: processed_mae
      combine: max_upper
      required: true

shadow 记录信号和判定，保持原动作。action_nodes 明确动作变量；prediction_keys 选择下一状态预测在运行帧中的键。sampling_mode 与部署采样方式保持一致。阈值 0.15 仅演示配置，应根据项目的误差分布和业务容忍度确定。

世界模型完成训练并选定 env.pt 后，自动构建、校准并验收附加模块。完整字段模板位于源码 examples/uncertainty_v2_production.yaml；命令入口见不确定性命令。

准备四类互斥数据

数据角色	用途
support_train	建立支持集模型，如高斯分布或 kNN
plugin_train	训练预测误差等监督插件
calibration	拟合分位数、概率或 conformal 校准
acceptance	使用已固定的插件和阈值进行独立验收

按完整轨迹划分，避免同一轨迹的相邻样本进入不同角色。自动构建流程按轨迹划分训练语料；手动构建时提供对应数据文件。验收数据不用于选择插件或调整阈值。

为已有模型构建附加模块

若已有模型但未启用此功能，可先从固定世界模型与训练 NPZ 生成四角色特征，再构建附加模块。先通过 revive uncertainty materialize-v2 --help 核对安装包是否具备此入口；早期包缺少时需更新 SDK，不能自行拼接特征替代官方物化。命令中的路径需替换为实际文件，输出目录必须尚不存在：

revive uncertainty materialize-v2 \
  --record logs/run/venv/world \
  --config uncertainty.yaml \
  --train-data data/train.npz \
  --output frames \
  --action-node action
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
revive uncertainty inspect --record logs/run/venv/world

角色 NPZ 按插件需要提供 features、errors、ood_labels、groups、strata 等字段。构建后检查模型绑定信息、各插件 accepted、校准指标及 routing 的字段、阈值与单位。更换主模型后，重新为该模型构建附加模块。

物化按完整轨迹划分四个互斥角色，使用实际模型生成特征与误差，并记录模型、配置、输入数据和角色文件摘要；不重训或覆盖世界模型。不应传入项目最终测试集。这里的角色互斥发生在给定训练语料内部，不表示这些轨迹未参与世界模型训练，也不替代独立业务验收。新版构建支持将动作声明为图节点或显式外部输入，其他所需外部观测也须存在于数据中。

OOD 需要带标签的数据

常规训练日志通常没有 OOD 标签。缺少标签时，无法校准 OOD 概率，也无法计算 AUROC / FPR95，ood_default 因而不能通过验收。此时可将 OOD 用作诊断信号，并保持相关通道 required: false。

要将 OOD 纳入动作判定，应准备带明确分布内外标签的校准与验收数据，并验证标签代表业务关心的变化，例如新的动作范围或负载区间。

阅读指标与比较效果

排序、校准与覆盖

评价内容	指标	阅读方法
高误差样本能否被排在前面	Spearman / Kendall、nAURC、尾部召回	秩相关和召回越高越好，nAURC 越低越好
能否区分分布内外	AUROC、FPR@95TPR、固定误报率下的 TPR	同时检查识别能力与业务误报成本
概率是否与实际发生率一致	ECE、Brier	检查概率校准
误差上界或区间是否有效	实际覆盖率、区间宽度	在接近名义覆盖率的同时，保持有用的区间宽度

内置 risk_default 要求 Spearman ≥ 0.30、nAURC ≤ 0.60；ood_default 要求 AUROC ≥ 0.80、FPR@95TPR ≤ 0.60；hybrid_default 同时检查两组条件。这些是通用门槛，项目还应检查逐工况表现和具体业务指标。

用任务条件解释结果

机器人控制可按动作幅度和运动状态分组，水处理可按流量、温度和仪表工况分组。整体排序较好，而某个工况内不能识别高误差样本时，插件对该工况的帮助仍然有限。

高覆盖率也需要结合区间宽度：范围过宽可能覆盖大部分结果，却无法支持有用决策。读取 percentile 时关注饱和比例；若大量样本都达到 1.0，单靠分位阈值难以区分风险。

先在相同模型、轨迹和评价条件下比较插件，再在验收数据上检查固定阈值的误报率、拒绝率和剩余预测误差，同时记录推理耗时。模型和数据变化后重新校准，不能把一个任务的阈值直接用于另一个任务。

接入推理与动作判定

先观察，再启用干预

shadow 和 diagnostic 保持原动作，记录信号和判定；enforce 允许判定影响动作。先覆盖具有代表性的运行周期，检查信号、误报率和拒绝率，再依据验收结果选择运行模式。

判定包括 allow、warn、degrade、reject、fallback。首先判断信号是否可用，再检查约束和阈值。必需通道不可用时按配置回退；约束违例、风险超限和非必需通道缺失分别按对应规则处理。

评估候选动作并提交状态

运行时使用 preview 评估候选，使用 commit 推进选定动作对应的模型及插件状态，使用 discard 丢弃未采用的候选。这样可以在带历史或 GRU 状态的模型中比较动作，而不让未执行的候选改变后续状态。

下面是推理流程片段。initial_state、state、proposed_action 为项目提供的原始物理量字典，actual_next 为执行后收到的反馈；历史长度按项目需要设置：

from revive.export import load_env

env = load_env("path/to/env.pt")
session = env.uncertainty.create_rollout_session(
    initial_state_raw=initial_state, history_depth=72, device="cpu",
)
pending = session.preview(state, proposed_action)
if pending.assessment.decision.allows_proposed_action:
    chosen = pending
else:
    fallback_action, reason = session.resolve_terminal_action(pending)
    session.discard(pending)
    chosen = session.preview(
        state, fallback_action, action_source="uncertainty_fallback",
    )
session.commit(chosen)
session.observe(chosen, actual_next)

调用方将选中的动作交给设备，并在真实反馈到达后调用 observe 更新误差与漂移统计。附加模块的采样模式、路由和阈值应与校准验收时一致。

必需信号、降频与回退

required: true 表示通道不可用时必须按配置处理，不能把缺失信号当成零风险。插件 frequency 大于 1 时不会每步计算；max_signal_age 决定已有读数还能使用多久。必需通道引用降频插件时，应设置允许的正信号年龄，相关非法组合会在配置检查中被拒绝。

回退动作由设备和运行状态决定。选择 terminal_action: safe_default 时，在 runtime.safe_default_action 中按动作名称明确提供原始单位的值。框架不会替业务确定安全动作；例如停止加药或关闭加热在不同工况下可能有不同后果。

导出和运行监测

附加模块随模型部署文件包保存。ONNX 加载约定见使用与部署模型。运行中持续观察实际覆盖率、不可用比例和干预比例。新工况导致持续欠覆盖时，收集代表性数据并重新校准和验收。

常见问题

现象	检查与处理
OOD 插件 accepted: false	检查是否具有 OOD 标签以及 profile 指标；数据条件不足时先作诊断
Risk 排序能力很低	核对动作名称、状态与预测字段，再检查误差标签及工况覆盖
覆盖率高但判定几乎全开或全关	查看区间宽度、percentile 饱和及实际 decision_field
加载时报模型标识不匹配	为当前 env.pt 重新构建附加模块
必需通道周期性回退	核对插件计算频率、max_signal_age 和预热状态
运行后的覆盖率下降	检查工况漂移、时间对齐与实际反馈，使用新数据重新校准

更多训练与部署错误见故障排查。