ONNXRuntime构建问题：Python Wheels在pyenv环境中RPATH配置异常分析

问题背景

在ONNXRuntime项目的构建过程中，开发团队发现了一个与Python Wheels包在pyenv环境下运行相关的重要问题。当使用包含MIGraphX和/或ROCm执行提供程序(EP)的Python Wheels时，如果这些包是在pyenv环境中构建的，会出现无法加载共享库libonnxruntime_providers_shared.so的错误，导致简单的导入操作都会失败。

问题现象

用户在尝试导入onnxruntime模块或创建推理会话时，会遇到以下典型错误信息：

Failed to load library libonnxruntime_providers_shared.so with error: 
libonnxruntime_providers_shared.so: cannot open shared object file: No such file or directory

有趣的是，通过pip检查可以发现wheel文件确实安装在正确的位置，但运行时系统却无法找到这些共享库文件。这个问题在1.19.0版本中不存在，但在1.21.0及更高版本中出现。

根本原因分析

通过深入调查，开发团队发现问题的根源在于动态链接库的RPATH/RUNPATH设置异常。使用readelf工具分析不同版本的库文件后，发现了关键差异：

1. 1.19.0版本的libonnxruntime_providers_shared.so正确设置了RUNPATH：

   0x000000000000001d (RUNPATH) Library runpath: [$ORIGIN]
   

2. 1.21.0版本的同一库文件完全缺失了RUNPATH设置

3. 对于onnxruntime_pybind11_state.so文件：

   • 1.19.0版本正确设置了[$ORIGIN:/opt/rocm/lib]
   • 1.21.0版本错误地设置了[$$ORIGIN:/opt/rocm/lib]（多了一个$符号）

解决方案

问题最终被追踪到CMake版本的问题。低版本的CMake（如3.26.x）存在一个bug，会导致：

1. 在设置RPATH时错误地添加额外的$符号
2. 在某些情况下完全遗漏RPATH设置

解决方案是升级CMake到3.28.0或更高版本。测试表明，使用CMake 3.28.0构建的ONNXRuntime能够正确设置RPATH，解决了共享库加载问题。

对构建环境的影响

这一发现对ONNXRuntime的构建环境提出了新的要求：

1. 必须使用CMake 3.28.0或更高版本进行构建
2. 在基于RHEL8（如AlmaLinux 8）的Docker环境中，需要特别注意系统默认提供的CMake版本可能过低
3. 虽然ROCm组件通常需要rocm-cmake，但ONNXRuntime的构建实际上并不依赖它，可以避免相关依赖问题

最佳实践建议

基于这一问题的解决经验，建议ONNXRuntime用户和开发者：

1. 始终使用最新稳定版的CMake进行构建
2. 在容器化构建环境中，显式安装适当版本的CMake，而不是依赖系统默认版本
3. 定期检查构建产物的RPATH/RUNPATH设置，确保动态链接路径正确
4. 对于ROCm/MIGraphX相关的构建，保持ROCm组件版本更新（当前最新为6.3.2）

结论

这个问题的解决不仅修复了pyenv环境下的构建问题，也为ONNXRuntime项目的构建系统提供了重要的质量改进。通过升级CMake版本，确保了跨不同Python环境下的兼容性，特别是对于那些使用pyenv等Python环境管理工具的开发者和用户。这也提醒我们在构建系统依赖管理上需要更加谨慎，及时更新关键工具链组件。