【Bug已解决】[Feature Request] Respect OMP_NUM_THREADS (and new ORT_*_NUM_THREADS env vars) when sizing default thread pools 解决方案一、现象长什么样在用 ONNX Runtime 做推理时用户希望通过环境变量控制默认线程池大小比如容器里限制 CPU 核数、或和 OpenMP 对齐但发现 ORT完全忽略OMP_NUM_THREADS也不认自己新增的ORT_INTRA_OP_NUM_THREADS/ORT_INTER_OP_NUM_THREADS之类的环境变量硬是用“逻辑 CPU 数”把线程池开满导致容器里 CPU 配额为 4 核却被开成 64 线程、和同进程的 OpenMP 线程数不一致引发 oversubscription、或在受限环境里因线程过多被限流。现象# 现象 A设了 OMP_NUM_THREADS4ORT 仍开满核 # ORT 用 std::thread::hardware_concurrency() 直接开 64 线程 # 无视 OMP_NUM_THREADS4 # 现象 B新加的 ORT_*_NUM_THREADS 不生效 # 用户设 ORT_INTRA_OP_NUM_THREADS2ORT 没读这个变量线程数不变 # 现象 C和 OpenMP 线程 oversubscription # ORT 开 64 OpenMP 开 64 128 线程抢 64 核性能反而下降、延迟抖动最坑的是现象 A用户以为设了OMP_NUM_THREADS就控制了所有计算库结果 ORT 自作主张开满容器配额形同虚设排查半天才发现是 ORT 没读这个变量。二、背景多线程推理库通常会读环境变量来决定默认线程池大小OMP_NUM_THREADS是 OpenMP 的事实标准MKL_NUM_THREADS、OMP_NUM_THREADS等也是常见约定。ONNX Runtime 自己有 intra-op算子内并行和 inter-op算子间并行两套线程池理应也尊重这些环境变量尤其是OMP_NUM_THREADS作为“默认并行度”的通用信号。问题在于 ORT 在“未显式指定线程数”时直接调用hardware_concurrency()取全核数跳过了对环境变量的读取。新增的ORT_*_NUM_THREADS变量要么没在“默认大小”分支里被读要么读取优先级低于“全核数”。于是用户的所有环境变量控制都失效。这是线程池/资源配置审查里典型的坑默认线程数计算直接取硬件核数忽略了既有的环境变量约定OMP_NUM_THREADS 等和新变量。三、根因默认大小分支不读环境变量SessionOptions在未设intra_op_num_threads时直接用hardware_concurrency()没先看OMP_NUM_THREADS/ORT_*_NUM_THREADS。新增变量未被读取ORT_INTRA_OP_NUM_THREADS等只在“显式 API 设置”路径生效没在“默认推导”路径读取环境变量。优先级混乱即使读了多个变量OMP / ORT_*/MKL之间的优先级没定义导致行为不确定。本质是默认线程池大小的推导跳过环境变量读取且新增 ORT 变量未被纳入默认推导、优先级未定义。四、最小可运行复现下面用 Python 模拟“默认线程数直接取核数忽略 OMP_NUM_THREADS”import os def size_default_pool_buggy(): buggy: 直接取硬件核数不读环境变量。 return os.cpu_count() or 1 # 忽略 OMP_NUM_THREADS def size_default_pool_fixed(): fixed: 按优先级读 OMP_NUM_THREADS / ORT_INTRA_OP_NUM_THREADS 都没有才退回硬件核数。 for var in (ORT_INTRA_OP_NUM_THREADS, OMP_NUM_THREADS): val os.environ.get(var) if val and val.isdigit(): return int(val) return os.cpu_count() or 1 os.environ[OMP_NUM_THREADS] 4 print(buggy:, size_default_pool_buggy()) # 64忽略 4 print(fixed:, size_default_pool_fixed()) # 4尊重环境变量buggy返回 64核数fixed返回 4读到了OMP_NUM_THREADS。五、解决方案第一层最小直接修复最小修复默认线程池大小推导时按优先级读取环境变量都没设才退回硬件核数// 修正默认线程数推导尊重环境变量 int GetDefaultIntraOpThreadCount() { // 优先级ORT_INTRA_OP_NUM_THREADS OMP_NUM_THREADS 硬件核数 if (const char* ort std::getenv(ORT_INTRA_OP_NUM_THREADS)) { if (int n ParsePositiveInt(ort)) return n; } if (const char* omp std::getenv(OMP_NUM_THREADS)) { if (int n ParsePositiveInt(omp)) return n; } return std::thread::hardware_concurrency(); }这一层改动最小默认分支先读变量再退回核数环境变量控制恢复。但依赖“每处默认推导都加这套读取”下看第二层。六、解决方案第二层结构性改进把“默认线程池大小的推导规则环境变量优先级 退回核数”固化成单一事实来源。下面这个 dataclass 集中管理C 侧和 Python 校验侧共享同一规则from dataclasses import dataclass, field from typing import Dict, List, Optional dataclass class OrtThreadpoolEnvPolicy: 单一事实来源默认线程池大小的推导契约。 # 优先级从高到低 env_priority: List[str] field(default_factorylambda: [ ORT_INTRA_OP_NUM_THREADS, ORT_INTER_OP_NUM_THREADS, OMP_NUM_THREADS, MKL_NUM_THREADS]) def resolve(self, env: Dict[str, str], hardware_concurrency: int) - int: for var in self.env_priority: val env.get(var) if val and val.strip().isdigit(): n int(val) if n 0: return n return max(1, hardware_concurrency) # 都没设则退回核数 def assert_respects_env(self, env: Dict[str, str], hw: int, expected: int) - None: got self.resolve(env, hw) if got ! expected: raise AssertionError( fthread pool size {got} ignores env (expected {expected}))这一层的关键收益统一优先级env_priority定义清晰的变量优先级行为确定退回核数兜底都没设才用硬件核数且max(1, ...)防 0可校验assert_respects_env验证环境变量确实被尊重单一事实来源所有线程池大小推导收口在OrtThreadpoolEnvPolicy。七、解决方案第三层断言 / CI 守护把第二层钉成 pytest挂进 CI确保环境变量被尊重import pytest from your_package.ort_threadpool_env import OrtThreadpoolEnvPolicy def test_omp_respected(): # 断言 1OMP_NUM_THREADS 被尊重 p OrtThreadpoolEnvPolicy() assert p.resolve({OMP_NUM_THREADS: 4}, 64) 4 def test_ort_var_takes_precedence(): # 断言 2ORT_* 变量优先级高于 OMP p OrtThreadpoolEnvPolicy() env {ORT_INTRA_OP_NUM_THREADS: 2, OMP_NUM_THREADS: 8} assert p.resolve(env, 64) 2 def test_fallback_to_hw(): # 断言 3都不设时退回硬件核数 p OrtThreadpoolEnvPolicy() assert p.resolve({}, 64) 64 def test_zero_core_safe(): # 断言 4硬件核数为 0 时至少返回 1 p OrtThreadpoolEnvPolicy() assert p.resolve({}, 0) 1四条断言从“OMP 被尊重”“ORT 优先”“退回核数”“零核安全”四面把环境变量回归钉死在 CI。八、排查清单ORT 不尊重线程数环境变量时设了OMP_NUM_THREADS线程池仍开满查默认大小推导是否直接取hardware_concurrency()而没读变量现象 A。新增的ORT_INTRA_OP_NUM_THREADS不生效查它是否在“默认推导”路径被读而非只在显式 API 路径现象 B。多个变量同设谁优先定义清晰优先级ORT_* OMP MKL 核数避免不确定。用第二层OrtThreadpoolEnvPolicy优先级统一 退回核数 可校验。加第三层 pytest断言“OMP 被尊重、ORT 优先、退回核数、零核安全”。容器/受限环境必须能靠环境变量限制线程数否则 oversubscription 拖垮性能。九、小结ORT 默认线程池不尊重环境变量的 bug 本质是未显式指定线程数时默认推导直接取硬件核数跳过了OMP_NUM_THREADS等约定变量且新增的ORT_*_NUM_THREADS也没纳入默认推导、优先级未定义导致容器配额形同虚设、与 OpenMP oversubscription。修复分三层——第一层默认推导按优先级读ORT_*/OMP_NUM_THREADS都没设才退回核数第二层用OrtThreadpoolEnvPolicy这个 dataclass 把推导规则优先级 兜底 校验收口成单一事实来源第三层用四条 pytest 把“OMP 被尊重、ORT 优先、退回核数、零核安全”钉死在 CI。核心心法默认线程池大小必须尊重既有环境变量约定OMP_NUM_THREADS 等并定义清晰优先级仅在全未设置时才退回硬件核数。