【实战】从零构建onnxruntime：源码编译全流程与疑难解析

1. 环境准备搭建编译基础环境在开始编译onnxruntime之前我们需要先准备好基础环境。我选择的是Ubuntu 20.04 LTS系统这个版本长期支持且稳定性好实测下来各种依赖库的兼容性也最佳。如果你用的是其他Linux发行版大部分步骤也是类似的只是包管理器的命令可能需要调整。首先更新系统软件包是个好习惯可以避免很多潜在的版本冲突问题sudo apt update sudo apt upgrade -y接下来安装必备的编译工具链这里我列出的都是经过实际验证的版本sudo apt install -y \ build-essential \ cmake3.30.5 \ git \ python3.8 \ python3-pip \ libpython3.8-dev \ protobuf-compiler5.29.4 \ libprotobuf-dev特别要注意的是protobuf的版本我在第一次尝试时用了系统默认的3.x版本结果编译时出现了序列化兼容性问题。后来发现onnxruntime 1.19.2需要protobuf 5.x版本这个坑我帮你踩过了。Python环境建议用virtualenv隔离python3.8 -m pip install virtualenv python3.8 -m virtualenv venv source venv/bin/activate pip install numpy1.24.4 packaging25.02. 获取源码两种方式与避坑指南获取onnxruntime源码有两种主流方式各有优缺点我两种都试过下面详细说说方式一直接下载Release包这是最快捷的方式适合只想快速编译不想折腾Git历史的同学wget https://github.com/microsoft/onnxruntime/archive/refs/tags/v1.19.2.zip unzip v1.19.2.zip cd onnxruntime-1.19.2但这种方式有个潜在问题源码目录不是Git仓库后面编译时可能会报错这个坑后面会讲解决方案。方式二克隆Git仓库适合需要查看提交历史或打算做二次开发的同学git clone --recursive https://github.com/microsoft/onnxruntime.git cd onnxruntime git checkout v1.19.2 git submodule update --init --recursive用Git方式获取的代码更完整但要注意两点必须加--recursive参数因为onnxruntime有很多子模块国内访问GitHub可能较慢可以尝试配置镜像源3. 编译配置参数解析与性能优化进入源码目录后真正的挑战才开始。官方提供的build.sh脚本有二十多个参数我挑几个最关键的说说./build.sh \ --skip_tests \ # 跳过测试加快编译 --config Release \ # 用Release模式 --build_wheel \ # 生成Python wheel包 --build_shared_lib \ # 生成动态链接库 --parallel 8 \ # 用8个线程加速 --enable_pybind \ # 启用Python绑定 --allow_running_as_root # 允许root运行这里有几个经验之谈--parallel参数建议设为你CPU核心数的1.5-2倍我的16核机器设8反而最快如果只是本地调试可以加--cmake_extra_defines ONNXruntime_DEV_MODEON要启用GPU支持需要额外配置CUDA路径4. 常见报错与解决方案报错一Git仓库初始化问题如果看到fatal: not a git repository错误这是因为编译脚本会检查Git信息。解决方法很简单git init git config --global user.name Your Name git config --global user.email youremail.com git add . git commit -m initial commit报错二依赖下载失败这个问题最棘手因为要下载的依赖很多国内网络环境可能导致部分包下载超时。我的解决方案是先在cmake/deps.txt找到下载失败的URL用浏览器或wget手动下载修改deps.txt中的URL为本地路径例如abseil库的修改示例- abseil_cpp;https://github.com/abseil/abseil-cpp/archive/f46495ea96f68fc3f6c394f099b2992743f6ff7f.zip;0e2b6d1dc7f0a808d1e23f7dd985f7bc18d52cbc abseil_cpp;file:///home/user/downloads/abseil-cpp-f46495ea96f68fc3f6c394f099b2992743f6ff7f.zip;0e2b6d1dc7f0a808d1e23f7dd985f7bc18d52cbc报错三Python绑定问题如果遇到Python相关错误检查以下几点virtualenv是否激活python3.8-dev包是否安装尝试设置PYTHON_EXECUTABLE路径export PYTHON_EXECUTABLE$(which python)5. 安装与验证确保编译成功编译完成后产物主要在build/Linux/Release目录下。安装步骤如下安装Python wheel包pip install build/Linux/Release/dist/onnxruntime-1.19.2-cp38-cp38-linux_x86_64.whl安装C库cd build/Linux/Release sudo make install验证安装是否成功import onnxruntime as ort print(ort.get_available_providers()) # 应该看到[CPUExecutionProvider]如果要验证C接口可以运行./onnxruntime_test_all6. 高级技巧自定义编译选项如果你需要深度定制可以修改CMakeLists.txt。我常用的几个自定义选项启用调试符号set(CMAKE_BUILD_TYPE RelWithDebInfo)禁用不需要的Execution Provider--disable_mlops --disable_tvm --disable_dnnl开启详细日志--cmake_extra_defines ONNXRUNTIME_ENABLE_LOGGINGON静态链接protobuf--cmake_extra_defines ONNX_USE_PROTOBUF_SHARED_LIBSOFF7. 性能调优与生产部署编译出的onnxruntime性能可以做进一步优化启用AVX2指令集--cmake_extra_defines ONNXRT_ENABLE_EXTENSION_AVX2ON内存池优化--cmake_extra_defines ONNXRUNTIME_ENABLE_MEMLEAK_CHECKEROFF生产环境建议使用--config MinSizeRel减小二进制体积禁用所有调试选项用strip去除调试符号strip libonnxruntime.so最后提醒一点如果要在不同机器上部署最好保持编译环境一致特别是glibc版本。我在实际项目中遇到过因为glibc版本不一致导致的运行时错误这个坑相当隐蔽。