ONNX Runtime 怎样生成算子级延迟 profiling JSON

我第一次排查 ONNX Runtime 推理变慢时，最容易犯的错是只看一次总耗时，然后猜测“是不是模型太大”。更稳妥的做法是先让运行时把每个算子和相关线程事件写进 profiling JSON，再根据事件类别缩小范围。

在创建 InferenceSession 前把 SessionOptions.enable_profiling 设为 True，完成与真实负载接近的推理后调用 session.end_profiling()。返回值就是生成的 JSON 文件路径，里面可以按 cat、name 和 dur 读取算子级延迟。

官方地址：https://onnxruntime.ai/docs/performance/tune-performance/profiling-tools.html

先分清会话级 profiling 和一次总耗时

ONNX Runtime 的 profiling 是会话选项。它不是给某一次普通计时额外打印一行数字，而是让会话积累线程、算子延迟等详细性能事件。因此开关必须在创建会话前设置；会话已经创建后再修改一个独立的 options 对象，不会回头补录之前的事件。

图中的分组只表达静态关系：会话选项决定记录范围，推理调用产生事件，结束 profiling 再把事件写成文件。它是结构说明图，不是运行截图，也不代表某个模型已经得到固定耗时。

用代表性输入生成一份可分析的 JSON

下面的示例把模型输入准备部分故意写得简单：input_ids 和形状只是示意，实际项目应按 session.get_inputs() 返回的名称、类型和形状准备 feed。重点在于 profiling 开关、推理调用和结束时机。

import json
from pathlib import Path

import numpy as np
import onnxruntime as ort

# 先创建并配置会话选项，profiling 必须在建会话前打开。
options = ort.SessionOptions()
options.enable_profiling = True

# 这里的 provider 与模型环境有关；没有 CUDA 时可以改成 CPUExecutionProvider。
session = ort.InferenceSession(
    "model.onnx",
    sess_options=options,
    providers=["CPUExecutionProvider"],
)

# 输入名和形状仅作示意，实际使用时要按模型元数据调整。
feed = {"input_ids": np.zeros((1, 8), dtype=np.int64)}

# 用接近真实请求的输入运行，必要时可重复几次减少一次性初始化的干扰。
session.run(None, feed)

# 结束会话级 profiling，并取得生成文件的路径。
profile_path = Path(session.end_profiling())
print(f"profile 文件：{profile_path}")

# 只读取事件结构做后续分析，不把示意输出当成固定运行结果。
events = json.loads(profile_path.read_text(encoding="utf-8"))
print(f"事件数量：{len(events.get('traceEvents', []))}")

如果只想分析特定负载，可以让 profiling 会话只覆盖那一段请求，然后立即结束。不要把模型加载、预热、业务序列化和正式请求混在一起后再凭一个数字下结论；profiling 的价值在于保留“这个数字由哪些事件组成”的线索。

读取 Node、Kernel 和 dur，避免重复计算

生成的文件属于标准性能 tracing 文件。常见事件会带有 cat、name 和 dur 等字段。Node 更接近主机侧算子事件；启用对应 GPU profiling 后，还可能看到 Kernel 事件。两者是有关联的记录，不应简单相加后当成端到端延迟。

import json
from collections import Counter

# profile_path 指向上一段代码返回的 JSON 文件。
with open(profile_path, "r", encoding="utf-8") as stream:
    trace = json.load(stream)

events = trace.get("traceEvents", [])
counts = Counter()
for event in events:
    # 跳过没有类别或名称的元数据事件，避免把它们当成算子耗时。
    category = event.get("cat")
    name = event.get("name")
    duration = event.get("dur")
    if category and name and duration is not None:
        counts[category] += 1
        # dur 的单位以当前 trace 的时间约定为准，先保留原值再比较。
        if category in {"Node", "Kernel"}:
            print(category, name, duration)

print("事件分类：", counts)

排查时可以先按 Node 找到耗时异常的算子，再结合是否存在对应 Kernel 记录判断设备侧关联。这个过程适合定位下一步要查的算子、执行提供者或数据搬运，不等于单凭一份 trace 就能证明某个优化一定有效。

我会优先检查的三个边界

第一，输入是否代表真实请求。全零输入、过短序列或只有一次冷启动，得到的 trace 只能说明那种输入下的事件结构，不能直接代表线上延迟。

第二，结束时机是否明确。end_profiling() 用来结束记录并返回文件路径。拿到路径后再读取文件，避免在写出前就开始解析。

第三，主机与设备事件是否混看。如果要分析 CUDA kernel，需要满足官方文档列出的 GPU profiling 条件。即使文件里同时出现 Node 和 Kernel，也应把它们作为关联线索分别解读，而不是把每条事件无条件求和。

这三个边界能把“模型慢”拆成更具体的问题：是输入负载不同、初始化混入了样本，还是某个算子与执行提供者之间存在额外开销。定位到具体事件后，再决定是否需要调整图优化、线程、I/O Binding 或 provider 配置。

相关问题

为什么设置了 enable_profiling 却没有文件？

先确认开关是在创建 InferenceSession 前设置，并且确实调用了 end_profiling()。只创建 options 或只执行推理而不结束 profiling，都不能代替完整的导出动作。

profiling JSON 能直接说明哪个算子最慢吗？

它能提供算子级事件和持续时间线索，但仍要结合输入形状、预热状态、执行提供者以及 Node/Kernel 的关系判断。不要把一次样本的最大 dur 当成所有请求的固定结论。

应该用会话 profiling 还是 RunOptions profiling？

本文讨论会话级 profiling，适合覆盖一段代表性推理。若只想观察单次运行，应根据所用语言绑定的 RunOptions API 选择单次 profiling，并保持同样的“明确范围、结束导出、按事件类别解读”原则。

总结一下：先在建会话前打开 profiling，用代表性输入产生事件，调用 end_profiling() 拿到 JSON，再按 Node、Kernel 和 dur 分层阅读。这样得到的是一份可以继续排查的证据线索，而不是脱离负载的单个总耗时。