企业官网建设流程全解析

简介：onnxruntime-linux-x64-gpu-1.16.2.tgz 是一份面向 Linux x64 平台的 GPU 加速版 ONNX Runtime 资源包，专为需要在 C++ 工程中高效运行 ONNX 格式模型的深度学习推理工程师与算法部署人员设计，提供完整的链接库、头文件及说明文档。压缩包共 23 个文件，以 12 个 h 头文件、4 个 so 动态库文件为主，另有 md/txt 说明文档、版本号及许可证文件；头文件定义 API 接口，动态库负责 CUDA/TensorRT 推理调度，整体体积约 130.38MB。已有 519 人学习。资源包含 include/lib 典型目录结构，解压后即可快速集成到现有工程，实现 GPU 加速；相比 CPU 版本，能显著提升图像分类、自然语言处理等任务上的推理吞吐与响应速度。同时支持多线程执行与动态输入形状，便于灵活处理不同批次的推理请求；另外附带构建版本标识、开源协议与第三方声明等元数据文件，便于确认版本来源与合规商用。对需要借助 NVIDIA GPU 部署模型、并关注 CUDA/cuDNN 依赖匹配的开发者，这是一个开箱即用的基础组件。

1. 一个 tgz 包为什么值得花十分钟弄明白

你多半是在找 "onnxruntime-linux-x64-gpu-1.16.2.tgz" 这个文件，可能是从模型部署项目的依赖清单，或者某个 C++ 推理服务的构建脚本里看到的。这个文件名拆开就是三件事：onnxruntime 是微软的跨平台推理引擎，linux-x64-gpu 说明它是给 Linux x86_64 机器用的 GPU 版本，1.16.2 是 2023 年的稳定版本号，tgz 是发布时的压缩打包格式。它解决的痛点是：训练好的 PyTorch 模型导出成 ONNX 之后，服务端需要一个足够快、足够省心的推理运行时，而这个包就是那个运行时的 Linux 原生形态，解压即用，不碰 pip 也不碰 conda。

做后端推理的人会立刻意识到它的价值：一个不依赖 Python 解释器、只靠动态库和头文件就能跑的推理引擎，意味着你可以把它直接链进 C++ 服务、封装成内部 SDK、塞进 Docker 镜像，甚至塞进 K8s 的 GPU 调度里。适合的人群很明确——手里有 ONNX 模型、目标机器是带 N 卡的 Linux 服务器、而且不想被 GPU 容器镜像里那套 CUDA 版本地狱反复折磨的人。下面我从这个包里到底有什么讲起，一直讲到参数怎么调、坑在哪。

2. onnxruntime 1.16.2 GPU 版：包里面到底是什么，以及它和 CPU 包、ONNX 的关系

2.1 从 ONNX 到 onnxruntime：推理引擎和模型格式的分工

先说一个经常被新同事问混的概念：ONNX 和 onnxruntime 是两回事。ONNX 是模型的一种中间表示格式，类似"模型世界的通用语言"，PyTorch 的 .pt 转成 ONNX 之后，就变成了一堆算子的计算图描述，本身没有执行能力。而 onnxruntime 是执行这堆算子描述的解释器兼编译器，它拿到 ONNX 文件后，会把计算图加载进来，做图优化、算子融合，然后把每个算子映射到具体的执行后端上。

"执行后端"就是常听到的 EP（Execution Provider）。CPU 机器用的是 CPU EP，N 卡上用 CUDA EP，能进一步加速的还可以接 TensorRT EP。onnxruntime-linux-x64-gpu-1.16.2.tgz 这个包特殊的地方在于：它默认带 CUDA EP，也就是说库文件在编译时已经链接了 CUDA runtime 和 cuDNN，不需要你自己去 Pytorch 里折腾扩展。日常里很多人用 pip 装 onnxruntime-gpu，那拿到的是 Python wheel；而手头这个 .tgz 是给 C/C++ 程序用的原生发布包，里面是 .so 动态库和头文件。

不少做服务端的人最初会困惑：既然 Python 里能用 onnxruntime-gpu，为什么还要用这个 tgz？因为在生产环境里，Python 拉起进程的开销、GIL、依赖管理，都会成为瓶颈。把 ONNX Runtime 作为原生库编译进你自己的 C++ 服务，推理延迟更低、内存更可控，也更容易跟已有的高性能框架嵌在一起。这个 tgz 就是那条原生路线的入口。

2.2 Linux x64 GPU 版 tgz 的构成：库文件、头文件和 CUDA 依赖

把 onnxruntime-linux-x64-gpu-1.16.2.tgz 解压之后，典型的目录结构长这样（我用最常见的官方发布布局为例）：

$ tar -tzf onnxruntime-linux-x64-gpu-1.16.2.tgz onnxruntime-linux-x64-gpu-1.16.2/ onnxruntime-linux-x64-gpu-1.16.2/include/ onnxruntime-linux-x64-gpu-1.16.2/include/onnxruntime_c_api.h onnxruntime-linux-x64-gpu-1.16.2/include/onnxruntime_cxx_api.h onnxruntime-linux-x64-gpu-1.16.2/include/onnxruntime_cxx_inline.h onnxruntime-linux-x64-gpu-1.16.2/include/onnxruntime_float16.h onnxruntime-linux-x64-gpu-1.16.2/lib/ onnxruntime-linux-x64-gpu-1.16.2/lib/libonnxruntime.so onnxruntime-linux-x64-gpu-1.16.2/lib/libonnxruntime.so.1.16.2 onnxruntime-linux-x64-gpu-1.16.2/lib/libonnxruntime_providers_cuda.so onnxruntime-linux-x64-gpu-1.16.2/README.txt

这些文件里，include 下面的头文件是给 C/C++ 程序编译时用的声明；lib 目录里的 libonnxruntime.so 是主动态库，负责图解析、优化和调度；libonnxruntime_providers_cuda.so 是 CUDA 执行提供程序的负载库，真正把算子分派到 GPU kernel 上。注意，1.16.2 这个版本里，CUDA EP 的负载是以动态库形式提供的，不是静态编译进主库的，所以运行时既要能找到 libonnxruntime.so，也要能找到 providers 库。

最关键的是依赖关系。官方 GPU 包在编译时链的是某一特定版本的 CUDA toolkit 和 cuDNN，不是你机器上随便装的 CUDA。1.16.2 时代的官方 GPU 包，默认按 CUDA 11.8 + cuDNN 8.x 构建，但也有单独发布过 CUDA 12 的变体。如果文件名里没额外标注，我一般先按 CUDA 11.8 处理，然后用 ldd 去验证实际链接库，别赌。用 ldd 看依赖：

$ ldd lib/libonnxruntime_providers_cuda.so linux-vdso.so.1 (0x00007ffe6a1c3000) libcudart.so.11.0 => /usr/local/cuda-11.8/lib64/libcudart.so.11.0 libcudnn.so.8 => /usr/lib/x86_64-linux-gnu/libcudnn.so.8 ...

看到 libcudart.so.11.0 和 libcudnn.so.8，就能确认这个包是按 CUDA 11.x 构建的。如果系统里只有 CUDA 12，ldd 会报"找不到 libcudart.so.11.0"，这时候你有两个选择：换一个有 CUDA 11.8 的镜像，或者去找明确标注 cuda12 的发布包。不要尝试把文件做软链强行骗过去，版本不匹配迟早会在算子调用时炸出更隐蔽的错。

2.3 为什么选 1.16.2 这个版本：CUDA/cuDNN 匹配和兼容性

版本号是另一个绕不开的话题。我见过太多人上来就装最新版，结果系统里 CUDA 是 12.4，而新版本 onnxruntime-gpu 要求 cuDNN 9，于是要么重装 cuDNN，要么被 Docker 镜像搞得焦头烂额。1.16.2 的好处是：它对 CUDA 11.8 的适配已经非常成熟，身边大多数还在用 CUDA 11 的推理集群都能直接跑；而且这个版本的 CUDA EP 在卷积和 Transformer 类算子上的融合策略相当稳，没有后来几个版本早期那种频繁调整导致的不稳定。

从依赖兼容性来看，1.16.2 官方要求 GCC 版本在 9 以下都还能编 C++ 程序，glibc 2.27 以上的系统基本都能跑，这对 CentOS 7 和 Ubuntu 18.04 等老系统很友好。如果团队里还有人维护老镜像，选 1.16.2 而不是 1.17 或 1.18，能省掉大量"镜像里缺新 glibc 符号"的麻烦。当然，CUDA 12 已经在很多新机器上是默认装了，那就要看你的驱动版本和 cuDNN 现状，别教条。

版本选择上我给个通用判断：驱动支持 CUDA 11.8 且不打算动 CUDA 环境的，直接选这个 tgz；如果你必须要用 CUDA 12，那就去找对应的 cuda12 包，不要拿一个名字类似的旧包硬凑。版本定下来之后，后面的安装和配置才能成立。下面进入真正动手的部分。

3. 在 Linux x64 上安装 onnxruntime-gpu 1.16.2：从解压到跑通第一段推理

3.1 环境检查：显卡驱动、CUDA、cuDNN、glibc

安装这个包之前，我习惯先在目标机器上用 10 分钟把底层环境理清楚，省得后面排错排到怀疑人生。第一个要看的是 NVIDIA 驱动是否正常，直接跑 nvidia-smi：

$ nvidia-smi Tue Mar 4 10:23:11 2025 +-----------------------------------------------------------------------------+ | NVIDIA-SMI 470.82.00 Driver Version: 470.82.00 CUDA Version: 11.4 | +-----------------------------------------------------------------------------+ | GPU Name Persistence-M | Bus-Id ... | 0 Tesla T4 On | 00000000:00:1E.0 | On | N/A | +-----------------------------------------------------------------------------+

注意CUDA Version这行。它表示当前驱动能支持的最高 CUDA 运行时版本，不一定是已经装了 CUDA toolkit。onnxruntime 的 GPU 包在运行时需要的不是你机器上装了哪个版本的 CUDA toolkit，而是驱动是否兼容。比如这里驱动是 470.82，它最高支持 CUDA 11.4，那 1.16.2 里链接的 libcudart.so.11.0（也就是 CUDA 11.0 运行时）是可以被兼容的，因为 11.4 驱动向前兼容 11.0 运行时。但如果你驱动只支持 CUDA 10.2，而 onnxruntime 要的是 CUDA 11.0 运行时，初始化时一定会报错。

第二步确认 cuDNN 是否已安装。大多数发行版不会自带 cuDNN，需要手动放好。检查方式：

$ ls /usr/lib/x86_64-linux-gnu/ | grep cudnn libcudnn.so.8 libcudnn_adv_train.so.8 libcudnn_cnn_infer.so.8 libcudnn_cnn_train.so.8 ...

如果什么都没有，后面加载 CUDA EP 时会直接报找不到 libcudnn.so.8。最后确认 glibc 版本，因为这个包是用较老的 GNU C 标准库编译的，glibc 版本过低才会出问题，一般 2.27 以上就行：

$ ldd --version | head -n1 ldd (GNU libc) 2.31

这一步的意义是把你机器的能力边界摸清，再决定后面是直接解压还是先补环境。不要跳过，我见过不少人拿着一个 GPU 包，在没装 N 卡驱动的机器上折腾了一下午，最后才发现是驱动问题。

3.2 解压 tgz 并配置 Python 绑定或 C++ 链接

环境确认没问题后，解压这个 tgz 只需要一条命令。我习惯把它放到 /opt 下面统一管理，避免把动态库散落在项目目录里造成混乱：

$ sudo mkdir -p /opt/onnxruntime $ cd /tmp $ tar -xzf onnxruntime-linux-x64-gpu-1.16.2.tgz -C /opt/onnxruntime $ cd /opt/onnxruntime $ mv onnxruntime-linux-x64-gpu-1.16.2 ./1.16.2 $ ls 1.16.2/lib/ libonnxruntime.so libonnxruntime.so.1.16.2 libonnxruntime_providers_cuda.so

mv 那一步的作用是把带版本号的目录改名，方便以后在同一个 /opt/onnxruntime 下装多个版本，切换时只改链接路径或环境变量。这一步做完，要让系统能找到这些库，设置 LD_LIBRARY_PATH 或者写进 ld.so.conf：

$ export LD_LIBRARY_PATH=/opt/onnxruntime/1.16.2/lib:$LD_LIBRARY_PATH $ echo '/opt/onnxruntime/1.16.2/lib' | sudo tee /etc/ld.so.conf.d/onnxruntime.conf $ sudo ldconfig

之后任何程序链接 libonnxruntime.so 时都能直接找到。如果你用的是 CMake，在 CMakeLists.txt 里做两件事：一是 include 头文件目录，二是把库目录加进链接搜索路径，然后用 target_link_libraries 链接 libonnxruntime.so 和 libonnxruntime_providers_cuda.so。这里最容易搞混的是：链接主库时，CMake 会自动跟着 .so 里的 SONAME 去解析其他依赖，所以不需要手动链接 libcudart 和 libcudnn，运行时由动态加载器去解决。

如果只是想在 Python 里快速验证这个包是否可用，也可以直接把 lib 目录加到系统库路径，然后确认 Python 侧能 import 成功。Python 的 onnxruntime 包自身带一套 Python 绑定，但如果你用的是从 tgz 解压出来的 C++ 动态库，Python 侧一般是走 ctypes 去调用，或者干脆只用来验证底层库能不能加载。常见做法是：先装同一个版本的 onnxruntime-gpu pip 包用来测试 API，再把真正的性能验证放到 C++ 侧，避免两种绑定混在一起干扰判断。

3.3 跑通一段最小推理脚本

无论以后走 C++ 还是 Python，我拿到一个新环境的第一件事，都是先用一个最小脚本确认 GPU EP 能真正工作。Python 侧用 onnxruntime 自带 API 最省事：

import onnxruntime as ort import numpy as np # 显式指定 CUDA 提供程序，避免默认走 CPU EP sess_options = ort.SessionOptions() sess_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL # 注意 providers 顺序：CUDA EP 放最前面 sess = ort.InferenceSession( "model.onnx", sess_options, providers=["CUDAExecutionProvider", "CPUExecutionProvider"], ) # 打印实际生效的提供程序 print(sess.get_providers()) # 造一个和模型输入匹配的随机张量，跑一次推理 input_name = sess.get_inputs()[0].name input_shape = sess.get_inputs()[0].shape x = np.random.randn(*[s if isinstance(s, int) and s > 0 else 1 for s in input_shape]).astype(np.float32) output = sess.run(None, {input_name: x}) print("output len:", len(output))

这段代码里有两个地方是关键。第一，providers 参数里必须把 "CUDAExecutionProvider" 放在 "CPUExecutionProvider" 前面，onnxruntime 会优先使用排在最前并且当前会话能正常初始化的执行提供程序。第二，调用sess.get_providers()返回的是实际生效的 provider 列表，如果里面只有 CPUExecutionProvider，说明 CUDA EP 初始化失败了，这时候不要继续调推理参数，先回头查依赖。

跑通后，如果你想确认算子真的被分派到了 GPU，可以开启 session 的日志和 profiling。更直接的方法是在 Python 脚本运行的同时，另开一个终端观察 nvidia-smi 的进程显存占用。GPU 推理时，nvidia-smi 里能看到一个 python 进程占用了几十到几百 MiB 的显存，这是 CUDA EP 初始化时分配的上下文和工作区。如果没有显存变化但也没报错，十有八九是因为模型太小、图优化把它折叠到了 CPU 上。

4. 配置 GPU 会话：执行提供程序、显存优化和日志

4.1 从 CPU EP 切到 CUDA EP：provider 顺序和会话选项

很多人以为指定了 providers 就会自动用 GPU，这是个危险的误解。onnxruntime 的 CUDA EP 并不是一个全量覆盖所有算子的执行器，它只接管那些已经实现了 CUDA kernel 的算子。模型里如果存在 CUDA EP 不支持的算子，比如某些自定义 OP，运行时会沿着 provider 列表继续往下找，找到 CPU EP 去执行，这个行为叫算子回落（fallback）。回落本身不是坏事，但它会导致同一张图里不同算子在 GPU 和 CPU 之间来回拷贝数据，性能会断崖式下跌。

所以 provider 顺序不只是"谁优先"那么简单，背后是"谁尽量承担更多算子"的调度策略。正确的配置方式是：在会话初始化时，把 CUDA EP 放最前面，并给 CUDA EP 单独设置选项。C++ 侧用OrtCUDAProviderOptions，Python 侧用字典传参：

provider_options = [ { "device_id": 0, "cudnn_conv_algo_search": "EXHAUSTIVE", "arena_extend_strategy": "kSameAsRequested", "gpu_mem_limit": 4 * 1024 * 1024 * 1024, # 4GB }, {}, ] sess = ort.InferenceSession( "model.onnx", sess_options, providers=["CUDAExecutionProvider", "CPUExecutionProvider"], provider_options=provider_options, )

provider_options 列表的长度必须和 providers 列表对齐，不设选项的地方传空字典。这里的device_id指定用哪块显卡，多卡机器上这个字段意义很大。另外要提醒的是：gpu_mem_limit的单位是字节，不是 MiB。很多人想设 8GB 结果写成 8192，内存被限制成了 8KB，直接 OOM 后一脸懵。

4.2 三个必调参数：gpu_mem_limit、arena_extend_strategy、cudnn_conv_algo_search

先看gpu_mem_limit。它限制的是 onnxruntime 的 CUDA memory arena 能占用的最大显存。这个值设得太大，会跟同机其他进程抢显存；设得太小，运行大 batch 时会频繁触发显存重新向 CUDA 申请和归还，反而慢。我一般按模型大小和 batch 峰值来估算，给足 20%-30% 余量。比如模型权重加激活峰值大约 3GB，我会设 4GB 左右，防止偶尔的 batch 波动导致 OOM。

arena_extend_strategy是显存扩展策略，常见取值是kNextPowerOfTwo和kSameAsRequested。前者是默认行为，每次向 CUDA 申请显存时按 2 的幂次扩展，好处是减少系统调用次数，坏处是显存碎片化严重，可能会白白占着两三倍的实际需要。后者更克制，只按请求大小原样扩展，能显著降低显存峰值，但频繁调 cudaMalloc 的开销也摆在那。如果是显存紧张但延迟要求不极致的服务，我强烈建议改成kSameAsRequested；如果是离线批量推理且显存充足，默认值就行。

cudnn_conv_algo_search是 cuDNN 卷积算法搜索策略。它有三个常用取值：HEURISTIC、EXHAUSTIVE、DEFAULT。HEURISTIC用启发式选算法，快但未必最优；EXHAUSTIVE会真正跑一遍多种算法的计时，挑最快的，首次推理时会有明显延迟，但之后使用缓存的算法结果。很多做服务的人会留个坑：明明开到 EXHAUSTIVE，第一次请求却超时严重。解决方法是把预热做在服务启动阶段，等所有卷积算法都缓存完再对外提供流量。这个参数直接影响卷积算子的 kernel 选择，对视觉模型影响很大，对纯 Transformer 结构模型影响相对小。

除此之外，还有一个容易被忽略的选项do_copy_in_default_stream。CUDA EP 默认会把某些数据拷贝放到另一个 stream 上，以提升流重叠效率。但如果你自己写的代码里有对 CUDA stream 的强同步假设，这个默认行为可能导致结果还没拷回 CPU 就读了旧数据。把它显式设置为 false 可以回到传统同步路径，虽然性能略降，但排查问题的成本更低。

4.3 验证 GPU 真的被用上：nvidia-smi、日志和 profiling

配置完参数，光看不报错还不够，得确认 GPU 利用率真的上来了。第一个手段是开 onnxruntime 的 verbose 日志：

sess_options.log_severity_level = 0 sess_options.log_verbosity_level = 1

日志级别调到 0 后，初始化会话时屏幕上会出现Added CUDAExecutionProvider之类的信息。如果看到Failed to create CUDAExecutionProvider后面跟着一个错误码，那说明依赖或驱动有问题，日志里一般会带走入歧途的原因。

第二个手段是跑推理的同时观察 nvidia-smi：

$ watch -n 0.5 nvidia-smi

重点看 GPU-Util 那一列。如果推理时 GPU-Util 一直保持 0%，说明模型很可能没有真正跑到 GPU 上。这时候常见原因有两个：模型太小、单次推理耗时太短，watch 采样跟不上；或者整个模型被 CUDA EP 打回 CPU EP 了。前者不算问题，后者需要打开 profiling 确认算子分派。用 onnxruntime 的 profiling 最直接：

sess_options.enable_profiling = True # ... 跑几次推理 ... prof_file = sess.end_profiling()

跑完后会生成一个 json 文件，里面每个算子节点都带有provider字段。搜一下文件里有没有大量算子的 provider 是CPUExecutionProvider，有就说明模型里存在不支持的算子，需要查具体是哪个 OP，再决定是换模型实现还是给这个 OP 注册自定义实现。

还有一个思路是直接从 API 的句柄里查。C++ 侧可以用Ort::Session::GetProfiling拿 profiling 数据，Python 侧则可以直接看sess.get_profiling_start_time_ns()配合外部 profiler。但最省事的还是上面那种：开启 profiling，跑一次，翻 json。工具链不复杂，重点是你得有这个验证意识，而不是只信控制台没有报错。

5. onnxruntime 1.16.2 GPU 常见问题与避坑：5 条血泪记录

5.1 解压后 import onnxruntime 报 libcudnn.so.8 找不到

现象：Python 里 import onnxruntime 直接抛 OSError，提示libcudnn.so.8: cannot open shared object file；但你觉得 cuDNN 明明装了，因为 /usr/local/cuda 下面能搜到 cudnn 的目录。

原因：CUDA 的安装目录和系统动态库目录不是一回事。很多发行版上 cuDNN 被解压到了 /usr/local/cuda/lib64，但 ldconfig 并不会默认扫描这个目录；而 onnxruntime 的运行库是通过标准动态库搜索路径去加载 libcudnn.so.8，找不到就是找不到。

解决：

$ sudo ln -s /usr/local/cuda/lib64/libcudnn.so.8 /usr/lib/x86_64-linux-gnu/libcudnn.so.8 $ sudo ldconfig

软链之后再用 ldd 确认一次。另外注意，如果同时存在多个 libcudnn.so.8 版本，软链要指向和 onnxruntime 构建要求一致的那一个。1.16.2 GPU 包要求 cuDNN 8.x，不要去链一个 libcudnn.so.9 过来，版本跳太多，算子在初始化时会报别的错。

5.2 CUDA 版本明明够新，却提示 CUDA driver version is insufficient

现象：nvidia-smi 显示 CUDA Version 12.2，驱动版本很新，跑 onnxruntime 会话时却报错CUDA error: CUDA driver version is insufficient for CUDA runtime version。

原因：这个报错通常发生在 driver API 版本低于 runtime API 版本要求时。nvidia-smi 里显示的 CUDA Version 是驱动支持的最高 CUDA 版本，但 onnxruntime 1.16.2 按 CUDA 11.8 构建，它链接的 runtime 是 CUDA 11.x，本应该能被新版驱动兼容。问题往往出在环境变量CUDA_HOME或LD_LIBRARY_PATH把你机器上另一套旧 CUDA runtime 给提前加载了，比如装了 CUDA 10.2 的 toolkit，导致运行时拿到的 libcudart 是 10.2 的版本，跟驱动的 API 版本对不上。

解决：先确认当前环境加载的是哪个 libcudart：

$ ldconfig -p | grep libcudart $ echo $LD_LIBRARY_PATH

如果 LD_LIBRARY_PATH 里有指向旧 CUDA 的路径，把它去掉，或重新设置指向 CUDA 11.8 的路径。装 onnxruntime 的老系统上，这种"新驱动配旧运行时"的错位经常发生，别急着怪版本不兼容。

5.3 显存占用忽高忽低，甚至 OOM

现象：同一个模型，每次跑推理的显存占用波动很大，batch 稍大就 OOM；用gpu_mem_limit限制了上限后，反而更频繁 OOM。

原因：onnxruntime 的 CUDA memory arena 默认扩展策略是 2 的幂次增长。比如实际需要 1.5GB，arena 可能一次性向 CUDA 申请 2GB，下次再翻到 4GB。虽然这些显存没有全部用完，但已经被这个进程占死，其他进程再申请就 OOM。gpu_mem_limit设置过小也会导致 arena 无法容纳工作区，每个算子都重新申请显存，更容易在峰值时触发 OOM。

解决：把arena_extend_strategy改成kSameAsRequested，并且把gpu_mem_limit设成模型峰值加 30% 余量。注意这里的限制只作用于 onnxruntime 自己的 arena，不会限制它调用 cuDNN 时临时分配的 workspace。如果用的是 TensorRT EP，还要额外看 TensorRT 的 workspace 配置，别混淆两套机制的显存上限。

5.4 多卡机器上只认第 0 张卡，其他卡用不上

现象：机器上有 4 张 N 卡，onnxruntime 永远只把显存吃在第 0 张卡上，其他卡利用率一直为 0；想指定某张卡，在 provider_options 里改了device_id也没用。

原因：最常见的两个坑。一是device_id在 Python API 里需要放在 provider_options 字典里传，而不是作为 SessionOptions 的字段；二是 CUDA 环境变量CUDA_VISIBLE_DEVICES的影响，它会把物理卡重新映射成逻辑编号，你看到的 device_id 不一定是物理卡。

解决：先跑nvidia-smi -L看物理卡索引，再跑echo $CUDA_VISIBLE_DEVICES看有没有被设置过。如果设置了，逻辑 device_id 和物理 id 是对不上的。以 CUDA_VISIBLE_DEVICES 为准来编排 device_id。在多卡推理服务里，我一般会为每个进程显式设置CUDA_VISIBLE_DEVICES=1，再在 onnxruntime 里用device_id: 0，让它只认这一张卡，避免跨卡上下文切换。这个思路在容器里也适用，K8s 给 GPU 容器注入的 nvidia.com/gpu 环境变量就是通过 CUDA_VISIBLE_DEVICES 限制可见卡。

5.5 CPU 和 GPU 混跑时 sess.run 卡死

现象：模型里既有 CPU 算子又有 GPU 算子，第一次跑没报错，第二次起sess.run偶发卡死，或者 GPU 利用率降为 0 但进程还在。

原因：onnxruntime 的 CUDA EP 默认使用独立的 CUDA stream 执行异步操作，CPU EP 的算子要在 GPU 和 CPU 之间做张量同步。当一个模型的图结构导致跨 EP 依赖链很长时，默认的 stream 同步策略可能让某些算子等待一个永远没发信号的事件，表现就是程序挂起。这个现象在自定义算子或者动态 shape 模型里更常见。

解决：在 provider_options 里把do_copy_in_default_stream设为 false，并强制使用同步执行。Python 里可以传{"do_copy_in_default_stream": False}。这会让数据拷贝和算子执行在同一个默认流里串行化，吞吐略降，但彻底避免跨 stream 同步死锁。再不行，就看sess.run的参数run_options，把run_options.terminate = True作为诊断手段，定位是哪层同步卡住。

6. 从 1.16.2 出发：验证推理速度、压测和升级到更高版本

6.1 用同一模型对比 CPU EP 与 GPU EP 的延迟

环境都稳定后，第一件事不是调参数，而是量化收益。我习惯用同一个 ONNX 模型，分别用 CPU EP 和 GPU EP 跑 200 次推理，取 P50 和 P95 延迟。注意预热：每次会话建立后先跑 20 次，让 cuDNN 的算法搜索和显存 arena 都稳定下来，再开始计时。否则第一次推理的耗时会被算子自动调优拉高，误判性能。

用 Python 计时时要小心 CUDA 的异步特性，time.time()包住一次sess.run，得到的往往不是真实的 GPU 执行时间，因为算子被塞进 stream 后就返回了。稳妥做法是在 CPU 和 GPU 之间强制同步一次，或者在 session 端开 profiling。更实用的是在服务入口处压测，用真实 batch 和真实并发来对比，比单次计时更有说服力。如果 GPU EP 的 P95 没有比 CPU EP 快 30% 以上，先别急着下结论，可能是模型太小、图优化把关键算子留在了 CPU 上，或者数据预处理成了瓶颈。

6.2 升级套路：替换 tgz 前先做兼容性检查

onnxruntime 版本迭代很快，1.16.2 之后出现了很多新特性，但升级前必须做兼容性检查，否则可能引入玄学问题。我的固定套路是：先看目标版本的发布说明，确认它支持的 CUDA/cuDNN 版本；然后在隔离环境里解压新 tgz，用同一模型、同一脚本跑一遍预测结果与旧版本对比，比对输出张量的最大误差。ONNX Runtime 在不同版本之间算子实现有优化，浮点结果允许有微小差异，但如果有超过 1e-3 的相对误差，就要怀疑算子融合策略变了，先排查是不是某些图优化被默认开启。

另一个必须检查的是头文件 API 的兼容性。如果你在 C++ 代码里用了Ort::Session::Run或自定义算子 API，1.16.2 到 1.18 的迁移中，部分接口有破坏性变化。最稳的方式是把 include 目录换成新版本后直接编译一遍，编译过的代码基本不存在运行时才发现 API 签名不匹配的问题。tgz 包里带着的头文件就是你的编译期检查器，别跳过这一步。

看好ldd libonnxruntime_providers_cuda.so是否引入新的依赖库，比如从 cuDNN 8 切到 cuDNN 9。如果升级后要求 cuDNN 9，而你的系统里只有 cuDNN 8，你得先解决 cuDNN 共存或者重装，这个成本往往比 onnxruntime 本身的升级更麻烦。我的教训是：升级之前先备份旧 tgz 的 lib 目录，升级后至少盯两周线上业务，一旦出现诡异错误立刻切回旧版本。那行切换脚本多写两行，不算白费。

希望这份从解压到调优的完整笔记能帮到你，至少在以后再遇到一个同样名如onnxruntime-linux-x64-gpu-1.16.2.tgz的包时，心里有数它是什么、该怎么用、坏了从哪儿查。

本文还有配套的精品资源，点击获取