课程导入：学习目标、适用人群、课程结构与环境准备

ONNX Runtime 是微软开源的高性能推理引擎，广泛支持 ONNX 模型格式，并针对 CPU、GPU、NPU 等异构硬件提供统一推理接口。在实际生产环境中，C/C++ 调用 ONNX Runtime 是嵌入式、桌面端、服务端高性能推理的主流选择。本章作为课程的第一讲，将明确学习目标、适用人群、课程整体结构，并带领你完成 ONNX Runtime C 库的安装与编译工具链配置。这是后续所有案例实战的基础，也是从 Python 原型走向 C 部署的关键一步。

一、学习目标：从“能跑通”到“会优化”

本课程的核心目标不是简单地教会你调用几个 API，而是帮助你建立一套完整的 C 语言环境下 ONNX Runtime 部署方法论。具体而言，完成本课程后，你将具备以下能力：

• 基础调用能力：熟练使用 OrtEnv、OrtSessionOptions、OrtSession、OrtValue 等核心对象，完成模型的加载、输入输出张量的创建与读取、推理执行。
• 内存管理能力：理解 ONNX Runtime C API 中内存所有权规则，掌握 OrtCreateTensorWithDataAsOrtValue 与 OrtCreateTensorAsOrtValue 的区别，避免内存泄漏和悬垂指针。
• 性能调优能力：掌握线程数设置、图优化级别、执行模式（顺序/并行）等 Session 选项，能够针对不同硬件平台进行基础性能调优。
• 错误处理能力：熟练使用 OrtStatus 和 OrtGetErrorCode 进行异常诊断，编写健壮的推理代码。
• 工程化能力：能够使用 CMake 构建跨平台 C 推理工程，并集成到现有的 C/C++ 项目中。

二、适用人群：你需要具备哪些基础

本课程面向有一定 C/C++ 编程经验，希望将 ONNX 模型部署到生产环境的开发者。具体来说，适合以下人群：

人群类型	基础要求	本课程带来的价值
C/C++ 后端工程师	熟悉指针、内存管理、编译链接	掌握高性能推理服务的集成方法
算法工程师	熟悉 Python 和 PyTorch/TensorFlow	突破 Python 性能瓶颈，实现 C 级部署
嵌入式开发者	了解交叉编译和资源受限环境	学会在 ARM 平台部署 ONNX 模型
系统架构师	了解服务端架构和性能指标	掌握推理引擎选型与调优策略

如果你只熟悉 Python 而不熟悉 C 语言，建议先补充指针、结构体、函数指针等基础知识。本课程不会从零教授 C 语言语法，但会在涉及关键概念时进行必要解释。

三、课程结构：四阶段递进式学习

整个课程的设计遵循“基础→进阶→实战→部署”的递进逻辑，每一章都包含理论讲解、代码示例、案例拆解和常见误区分析。以下是课程的整体结构概览：

1. 基础篇（第 1-8 章）：环境搭建、核心 API 详解、内存管理、张量操作、Session 配置、错误处理、多线程基础、日志与调试。
2. 进阶篇（第 9-16 章）：图优化与执行模式、线程池调优、IO Binding 零拷贝、自定义算子（Op）、ONNX 算子兼容性分析、动态形状处理、量化基础、FP16 与 INT8 推理。
3. 实战篇（第 17-24 章）：图像分类（ResNet50）、目标检测（YOLOv5）、语义分割（DeepLabV3）、文本分类（BERT）、语音识别前端、推荐系统排序模型、多模型流水线、模型热更新。
4. 部署篇（第 25-30 章）：Windows 服务部署、Linux 守护进程、ARM 嵌入式部署、Docker 容器化、性能基准测试与监控、常见部署问题排查。

四、环境准备：安装 ONNX Runtime C 库与编译工具链

环境准备是本章的实操重点。我们将以 Ubuntu 20.04/22.04 和 Windows 10/11 两个主流平台为例，详细说明安装步骤。如果你使用 macOS 或其他 Linux 发行版，步骤类似，只需调整包管理器命令。

4.1 编译工具链安装

ONNX Runtime C 库以预编译二进制和源码两种形式发布。无论哪种方式，你都需要一个可用的 C/C++ 编译器和构建工具。

Ubuntu/Debian 系统：

# 安装基础编译工具
sudo apt update
sudo apt install -y build-essential cmake git wget

# 验证安装
gcc --version
cmake --version

Windows 系统：

# 推荐使用 Visual Studio 2022 或 Build Tools
# 安装时勾选“使用 C++ 的桌面开发”工作负载
# 同时安装 CMake 和 Git for Windows

# 验证安装（在 PowerShell 中）
gcc --version
cmake --version

4.2 获取 ONNX Runtime C 库

ONNX Runtime 官方发布页面（GitHub Releases）提供预编译的 C 库包。你需要根据目标平台和硬件选择正确的版本：

平台	架构	推荐版本	说明
Linux	x86_64	onnxruntime-linux-x64-<version>.tgz	支持 CPU 和 CUDA（需单独下载 GPU 版）
Linux	aarch64	onnxruntime-linux-aarch64-<version>.tgz	适用于 Jetson 等 ARM 设备
Windows	x64	onnxruntime-win-x64-<version>.zip	包含 .dll 和 .lib 文件
macOS	x86_64 / arm64	onnxruntime-osx-<version>.tgz	注意区分 Intel 和 Apple Silicon

以 Linux x64 为例，下载并解压：

# 下载 1.17.0 版本（请根据实际需要选择版本）
wget https://github.com/microsoft/onnxruntime/releases/download/v1.17.0/onnxruntime-linux-x64-1.17.0.tgz
tar -xzf onnxruntime-linux-x64-1.17.0.tgz
cd onnxruntime-linux-x64-1.17.0

# 查看目录结构
ls -la
# 关键目录：
# include/  —— 头文件（onnxruntime_c_api.h, onnxruntime_cxx_api.h 等）
# lib/      —— 共享库（libonnxruntime.so）和静态库（libonnxruntime.a）

4.3 配置 CMake 工程

我们使用 CMake 作为构建系统，因为它跨平台且易于集成。以下是一个最小化的 CMakeLists.txt 配置：

cmake_minimum_required(VERSION 3.16)
project(OnnxRuntimeCDemo)

set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

# 指定 ONNX Runtime 路径（根据你的实际解压路径修改）
set(ONNX_RUNTIME_DIR "/path/to/onnxruntime-linux-x64-1.17.0")

include_directories(${ONNX_RUNTIME_DIR}/include)
link_directories(${ONNX_RUNTIME_DIR}/lib)

add_executable(demo main.c)

target_link_libraries(demo onnxruntime)

编写一个最简单的测试程序 main.c，验证环境是否配置成功：

#include <stdio.h>
#include <onnxruntime_c_api.h>

int main() {
    const OrtApi* api = OrtGetApiBase()->GetApi(ORT_API_VERSION);
    if (!api) {
        printf("Failed to get ONNX Runtime API.\n");
        return -1;
    }
    printf("ONNX Runtime C API version: %d\n", ORT_API_VERSION);
    return 0;
}

编译并运行：

mkdir build && cd build
cmake ..
make
./demo

如果输出 ONNX Runtime C API version: 14（版本号可能不同），说明环境配置成功。

4.4 验证安装：运行第一个推理示例

为了进一步验证环境完整性，我们加载一个最小的 ONNX 模型并执行推理。这里使用一个简单的加法模型（输入两个浮点数，输出它们的和）。你可以使用 Python 快速生成该模型：

import onnx
from onnx import helper, TensorProto

# 定义输入输出
X = helper.make_tensor_value_info('X', TensorProto.FLOAT, [1])
Y = helper.make_tensor_value_info('Y', TensorProto.FLOAT, [1])
Z = helper.make_tensor_value_info('Z', TensorProto.FLOAT, [1])

# 定义节点（Add）
node = helper.make_node('Add', ['X', 'Y'], ['Z'])

# 创建图
graph = helper.make_graph([node], 'add_graph', [X, Y], [Z])
model = helper.make_model(graph, opset_imports=[helper.make_opsetid("", 13)])
onnx.save(model, 'add_model.onnx')
print("Model saved.")

然后在 C 代码中加载该模型并执行推理。完整的代码示例将在下一章详细讲解，这里仅展示核心流程：

// 伪代码，完整实现见第 2 章
OrtEnv* env = NULL;
OrtSessionOptions* session_options = NULL;
OrtSession* session = NULL;

OrtCreateEnv(ORT_LOGGING_LEVEL_WARNING, "test", &env);
OrtCreateSessionOptions(&session_options);
OrtCreateSession(env, "add_model.onnx", session_options, &session);

// 创建输入张量
float x_val = 3.0f, y_val = 4.0f;
// ... 创建 OrtValue 并执行 OrtRunSession

// 输出结果应为 7.0

五、常见误区与总结复盘

在环境准备阶段，初学者最容易犯以下错误，需要特别注意：

• 版本不匹配：ONNX Runtime 的 C API 版本与库版本必须一致。如果你使用 ORT_API_VERSION 定义的最新版本，但链接的是旧版库，会导致运行时错误。建议始终使用官方发布包中头文件定义的版本。
• 动态库路径问题：在 Linux 下运行程序时，如果提示找不到 libonnxruntime.so，需要设置 LD_LIBRARY_PATH 或使用 rpath。在 Windows 下，需要将 DLL 放在 exe 同目录或系统 PATH 中。
• 头文件包含顺序：ONNX Runtime 的头文件依赖标准库头文件，建议在包含 onnxruntime_c_api.h 之前先包含必要的 C 标准头文件。
• 忽略错误处理：ONNX Runtime C API 几乎每个函数都返回 OrtStatusPtr，初学者往往忽略检查返回值，导致问题难以定位。建议封装一个 CheckStatus 宏，统一处理错误。