ONNX Runtime SessionOptions 怎样控制推理会话线程数

用 ONNX Runtime 调整推理线程时，先记住一个判断：intra_op_num_threads 管的是“一个算子内部怎么并行”，inter_op_num_threads 管的是“多个算子之间怎么并行”。如果仍使用默认的 ORT_SEQUENTIAL，只设置 inter-op 线程数通常没有你想象中的效果。

官方文档：https://onnxruntime.ai/docs/performance/tune-performance/threading.html

常规单会话场景先固定 intra_op_num_threads，保持顺序执行；模型存在较多可并行分支时，再切换 ORT_PARALLEL 并单独设置 inter_op_num_threads。多会话同时推理时，应优先避免每个会话都按物理核心数创建线程池。

先分清两种并行发生在哪里

ONNX Runtime 的 CPU 推理可以在两个层面使用线程。算子内部并行针对矩阵计算、卷积等单个算子；算子之间并行则针对模型图中彼此没有依赖的节点。两者不是同一个线程池参数，也不是简单相加后就能代表真实并发量。

官方文档把默认的 intra_op_num_threads=0 解释为由运行时按物理 CPU 核心提供默认线程数。手动指定数量后，线程池的规模更容易受控，但不要把某个机器上的最佳值直接当成所有部署环境的固定答案。

intra_op_num_threads 控制哪一层并行

如果你的问题是“一个推理会话最多使用多少个算子内线程”，入口就是 SessionOptions.intra_op_num_threads。下面的示例只展示会话配置，不依赖某个具体模型输出。

import onnxruntime as ort

# 创建会话选项，把单个算子内部的线程池限制为 4 个线程
sess_options = ort.SessionOptions()
sess_options.intra_op_num_threads = 4

# 顺序执行保持默认语义，适合作为单会话调参起点
sess_options.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL

# 模型路径替换成自己的 ONNX 文件，再创建推理会话
session = ort.InferenceSession("model.onnx", sess_options)

这里的“4 个线程”是算子内线程池的会话级配置，不等于程序只会存在 4 个线程。调用线程、其他库的线程以及多个会话各自的线程池，都可能出现在同一个进程里。特别是手动设置线程数时，不要再用“逻辑处理器数量乘以会话数”去估算一定能得到的吞吐。

inter_op_num_threads 什么时候才生效

inter_op_num_threads 面向的是模型图中不同算子之间的并行调度。它通常要和 ORT_PARALLEL 一起设置；如果保持 ORT_SEQUENTIAL，节点会按顺序执行，配置 inter-op 线程数不能把顺序调度自动变成分支并行。

import onnxruntime as ort

# 创建会话选项，并明确打开算子之间的并行执行
sess_options = ort.SessionOptions()
sess_options.execution_mode = ort.ExecutionMode.ORT_PARALLEL

# 设置算子之间的线程池大小；算子内部仍由 intra-op 独立控制
sess_options.inter_op_num_threads = 2
sess_options.intra_op_num_threads = 4

# 线程配置必须在创建会话前完成
session = ort.InferenceSession("model.onnx", sess_options)

并行执行不是对所有模型都更快。模型分支少、算子本身已经很重，或者会话数量较多时，额外的节点级调度可能增加竞争。更稳妥的做法是先用顺序模式得到基线，再只在模型图确实存在可并行分支时比较 ORT_PARALLEL。

多个会话同时运行时别让线程池互相抢资源

单独创建一个会话时，默认线程数通常能提供不错的开箱即用表现；但服务进程里常常会同时保留多个会话，或者同一会话会被并发请求共享。这时每个会话都按默认值扩张，CPU 竞争和上下文切换会变得明显，手动限制 intra_op_num_threads 往往更容易建立可控的资源边界。

import onnxruntime as ort

# 多会话服务先给每个会话一个明确上限，避免都按默认值扩张
sess_options = ort.SessionOptions()
sess_options.intra_op_num_threads = 2
sess_options.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL

# 空闲时间更关注 CPU 占用时，关闭线程等待期间的自旋
sess_options.add_session_config_entry("session.intra_op.allow_spinning", "0")
sess_options.add_session_config_entry("session.inter_op.allow_spinning", "0")

# 配置完成后再创建会话，后续请求复用这个 session
session = ort.InferenceSession("model.onnx", sess_options)

allow_spinning 不是线程数量开关，而是线程池在暂时没有工作时是否继续自旋等待。关闭它可能减少空闲 CPU 消耗，但在对低延迟特别敏感的场景里也可能改变等待行为。它应该和线程数量分开观察，不要把两种效果混在一次调参结论里。

需要更细的等待控制时再看两个配置键

官方文档还提供了 session.intra_op.spin_duration_us、session.inter_op.spin_duration_us 和 spin_backoff_max。它们调整的是自旋窗口和暂停密度，不会改变线程池的线程总数。只有当线程数量已经稳定，仍需要在延迟、CPU 占用和功耗之间做细调时，才值得把这些键加入实验。

import onnxruntime as ort

# 用时间窗口限制等待期，数值单位是微秒；这里只配置 intra-op
sess_options = ort.SessionOptions()
sess_options.add_session_config_entry("session.intra_op.spin_duration_us", "1000")

# 使用 2 的幂作为退避上限，降低连续 SpinPause 的密度
sess_options.add_session_config_entry("session.intra_op.spin_backoff_max", "8")

# 仍然要在所有配置完成后创建会话
session = ort.InferenceSession("model.onnx", sess_options)

如果已经把 allow_spinning 设为 0，依赖自旋的退避设置就没有实际作用。排查时先确认等待策略是否打开，再判断窗口和退避参数，顺序会更清楚。

一份可复用的配置思路

下面的版本把常见选择集中到一个函数里：默认使用顺序执行；调用方明确传入并行模式后，才设置 inter-op 线程数。它适合放到服务初始化处，避免每个请求重复创建会话。

import onnxruntime as ort

def build_session_options(intra_threads=4, parallel=False, inter_threads=2):
    # 先设置算子内部线程数，给单会话资源一个明确上限
    options = ort.SessionOptions()
    options.intra_op_num_threads = intra_threads

    if parallel:
        # 只有模型图采用并行执行时，才启用算子之间的线程池
        options.execution_mode = ort.ExecutionMode.ORT_PARALLEL
        options.inter_op_num_threads = inter_threads
    else:
        # 顺序执行不依赖 inter-op 线程数，显式写出便于阅读配置意图
        options.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL

    return options

# 在应用启动时创建并复用会话；不要在每次请求中反复建 session
session_options = build_session_options(intra_threads=4, parallel=False)
session = ort.InferenceSession("model.onnx", session_options)

这段配置没有声称某个线程数一定最快。真正落地时，至少分别比较单会话、多会话和不同模型分支数量下的资源占用，再决定是否切换到 ORT_PARALLEL。如果部署在 NUMA 机器上，还要把线程亲和性与跨节点缓存开销单独纳入评估。

调参时可以按这张清单排查

• 只想限制单个算子的并行度：先看 intra_op_num_threads，不要先改 inter-op。
• 想让模型分支同时调度：确认 execution_mode 已设置为 ORT_PARALLEL，再看 inter_op_num_threads。
• 多个会话同时运行：先降低每个会话的 intra-op 上限，避免线程池总量随会话数线性膨胀。
• 空闲 CPU 偏高：单独检查 allow_spinning，不要把它误判成线程数配置失效。
• 换了机器或模型：重新比较，不要把一个环境中的经验值直接复制到另一个环境。

把这几个边界分开后，SessionOptions 的线程配置就不再是“随便填一个数字”：先决定并行发生在哪一层，再决定线程池大小，最后才考虑等待策略和 NUMA 亲和性。

相关问题

intra_op_num_threads 设置为 0 是不是不创建线程？

不是。官方文档把未设置或设置为 0 解释为使用默认线程策略，运行时会按物理 CPU 核心提供 intra-op 线程。0 表示交给默认策略，不表示关闭线程池。

设置了 inter_op_num_threads 为什么看不到变化？

先看 execution_mode。如果仍是 ORT_SEQUENTIAL，模型图按顺序调度，inter-op 设置不会产生节点级并行的效果；另外模型本身也需要存在可并行的分支。

线程数越多，推理一定越快吗？

不一定。线程竞争、内存带宽、模型分支数量和会话并发都会影响结果。线程数应当作为部署参数比较，而不是当成固定的性能承诺。