专家函数

专家函数把已知的业务公式放进决策流图，让模型直接使用设备关系、单位换算或状态更新公式。这样可以把学习重点放在未知的过程上。本页以加热设备为例，完成函数编写、配置、训练和模型使用。

使用场景

当一个变量能由决策时已经获得的信息可靠计算时，可以使用专家函数。例如，加热器额定功率与控制比例已知，就能计算实际加热功率；已知当前状态及其变化量，就能合成下一状态；已知流量和浓度，就能计算质量流率。

以温控为例，控制器输出 0～1 的加热命令，加热器额定功率为 4 kW。当命令为 0.5 时，输入热功率为 2 kW。这段关系直接写成公式。温度变化还受风机、环境温度、热负载和设备热容量影响，由世界模型从运行数据学习。

您掌握的知识	合适的用法	示例
能确定某个变量的计算结果	专家函数节点	`heat = 4 × heater`
能构造有帮助的输入，但不能确定预测结果	专家特征	向温度网络补充内外温差
需要从数据学习关系或未知参数	网络节点或自定义网络	学习温度变化与热负载的关系

使用公式前，先确认它适用的设备和工况。如果加热器在高温下功率衰减，固定的线性换算就需要相应调整。公式输入也应在调用时可得，不能引用尚未测得的未来温度。

示例：计算加热功率

下面使用源码中的 examples/thermal_workflows/ 示例目录。数据按一分钟采样，相关变量为：

变量	含义与单位	来源
`heater`	加热命令，范围 [0,1]	已记录动作或策略输出
`heat`	加热功率，kW	专家函数计算
`temperature`	设备温度，°C	当前观测
`fan`、`ambient`、`load`	风机命令、环境温度、热负载	动作与外部输入

在配置同级的 custom_functions/thermal.py 中定义函数：

python

from revive.graph.function_registry import register_function


@register_function("thermal_power")
def thermal_power(data):
    return 4.0 * data["heater"]

thermal_power 是 YAML 引用的注册名。输入采用原始物理单位，输出应为 PyTorch 张量，并保留批量维度。例如 heater 为 [B,1] 时，返回的 heat 也为 [B,1]。多维数据取列时使用 [..., i:j]，保持最后一维为特征维。

将函数接入模型

以下为 examples/thermal_workflows/config.yaml 的图结构片段，数据和训练阶段使用该文件的完整配置：

yaml

graph:
  nodes:
    heat:
      inputs: [heater]
      function: thermal_power
      differentiable: true
    delta_temperature:
      inputs: [temperature, heat, fan, ambient, load]
      network:
        backbone: thermal_tutorial_mlp
        custom_params: {width: 16}
      output_dist: normal
    next_temperature:
      inputs: [temperature, delta_temperature]
      function: builtin.delta_add
  transitions: {temperature: next_temperature}

heat 节点计算功率；delta_temperature 网络学习温度变化；next_temperature 使用内置加法得到下一温度。函数节点的输出可以继续作为其他函数或网络的输入，因此能沿着业务过程组合多个已知关系。

differentiable: true 声明函数可以传播梯度。本例的张量乘法满足这一条件。需要梯度时，在函数内保持 PyTorch 运算，避免转成 NumPy、取出 Python 标量或重新创建脱离输入的张量。声明本身不会修复已经断开的梯度。

命令行会从配置目录发现 custom_functions/。自定义注册名应保持唯一，builtin. 前缀留给内置函数。图变量的列定义与物理范围见编写任务配置。

检查并训练

在源码仓库根目录执行以下命令。已有示例数据时跳过第一行；重新生成会覆盖示例数据文件。

bash

python examples/thermal_workflows/prepare_data.py
revive validate --config examples/thermal_workflows/config.yaml
revive train --config examples/thermal_workflows/config.yaml --run-id thermal_function

预检会使用实际小批量检查图和组件。训练结果位于示例目录下的 logs/thermal_function/。查看 report.md 中的温度预测误差，以及 models/env.pt 是否生成。

在自己的项目中，先用容易手算的输入检查公式：加热命令 0、0.5、1 应分别得到 0、2、4 kW。再检查批量输入、边界值和缺失数据处理。包含除法、对数或开方的公式，还要检查分母和定义域。

专家函数按公式计算，不会自动学习设备参数。效果比较应保持数据划分和验证窗口一致，观察加入已知关系后，单步与多步预测是否更符合业务过程。

加载与部署

Python 调用端先注册项目组件，再加载模型：

python

from revive import discover_project_components
from revive.export import load_env

project = "examples/thermal_workflows"
discover_project_components(project)
env = load_env(f"{project}/logs/thermal_function/models/env.pt")

模型需要与训练时的函数实现一起使用。交接时保存自定义代码、配置和模型文件；函数发生变化后，重新检查模型兼容性与预测结果。

需要 ONNX 时，在仓库根目录执行：

bash

revive export --artifact examples/thermal_workflows/logs/thermal_function/models/env.pt \
  --project examples/thermal_workflows

是否能够导出取决于函数使用的算子。导出后按使用与部署模型检查数值一致性，并用业务样本核对单位和输出范围。

常见问题

现象	处理方法
提示找不到函数	核对注册名；将实现放在配置目录下的 `custom_functions/`，Python 调用时先发现组件
输出形状不符	保留输入的批量维度，按节点列数组织最后一维
数值相差固定倍数	检查流量、温度、时间等单位是否一致，公式输入使用原始物理量
上游网络没有梯度	检查可微声明及张量计算，排除 NumPy 转换和取标量操作
公式在部分工况不准确	重新确定公式适用范围，将未知或变化的关系交给网络学习

专家函数 ​

使用场景 ​

示例：计算加热功率 ​

将函数接入模型 ​

检查并训练 ​

加载与部署 ​

常见问题 ​