2、环境准备：安装Python、PyTorch或TensorFlow、ONNX、ONNX Runtime、Android Studio或Xcode等开发工具

在开始ONNX Runtime手机端部署之旅前，搭建一套干净、版本匹配的开发环境是决定后续效率的关键。很多初学者在模型转换或编译阶段遇到“莫名其妙”的错误，根源往往不是代码逻辑问题，而是Python版本过旧、PyTorch与ONNX版本不兼容、或Android NDK配置缺失。本章将带你从零开始，梳理从Python基础环境到移动端原生开发工具链的完整安装路径，并给出经过验证的版本组合建议。

上图展示了手机端部署所需的三大环境模块：基础运行时（Python与CUDA）、模型训练/转换链（PyTorch/TensorFlow与ONNX工具链）、移动端构建链（Android Studio/Xcode与ORT移动库）。三者之间通过箭头串联，形成从训练到部署的完整通路。下面我们逐一拆解每个环节的安装要点与版本匹配策略。

2.1 Python环境：版本选择与虚拟环境隔离

核心原理：Python是连接训练框架与转换工具的“胶水语言”。ONNX Runtime的Python API、PyTorch的torch.onnx模块、以及各种模型优化脚本都依赖Python解释器。但Python版本过新（如3.12）可能导致部分依赖库尚未预编译wheel包，过旧（如3.6）则无法支持最新版PyTorch。因此，选择一个“中间地带”版本至关重要。

推荐版本组合：

• Python 3.8~3.11：这是目前PyTorch 2.x和ONNX Runtime 1.16+官方支持最完善的区间。其中3.10是当前兼容性最好的版本，几乎所有第三方库都已提供cp310的预编译包。
• Anaconda或Miniconda：用于创建独立虚拟环境，避免不同项目间的依赖冲突。例如，你可以为“训练环境”和“部署转换环境”分别创建两个conda环境。
• pip版本：确保pip版本在21.3以上，否则可能无法正确解析依赖的marker标记。

操作流程：

1. 访问 python.org 或使用conda安装Python 3.10：

   conda create -n ort_deploy python=3.10 -y
   conda activate ort_deploy

2. 升级pip并安装基础工具：

   python -m pip install --upgrade pip setuptools wheel

3. 验证安装：

   python --version  # 应输出 Python 3.10.x
   pip --version

常见误区：很多初学者直接使用系统自带的Python（如macOS自带的2.7或Ubuntu自带的3.8），这会导致两个问题：一是权限受限，无法全局安装包；二是系统升级可能破坏依赖。务必使用虚拟环境，且不要用sudo pip install，否则会污染系统环境。

2.2 深度学习框架安装：PyTorch与TensorFlow的选择

核心原理：目标检测模型的训练通常在PyTorch或TensorFlow中完成，然后导出为ONNX格式。两个框架的导出路径不同：PyTorch使用torch.onnx.export，TensorFlow使用tf2onnx工具。选择哪个框架取决于你的项目基础——如果已有PyTorch训练的YOLOv5/v8权重，就选PyTorch；如果已有TensorFlow的SSD模型，就选TensorFlow。

安装命令（以PyTorch为例）：

# CPU版本（适合仅做模型转换和验证）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# GPU版本（需要NVIDIA显卡，且已安装CUDA 11.8或12.1）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

对于TensorFlow，建议安装2.13~2.15版本：

pip install tensorflow==2.15.0

版本匹配表：

案例拆解：假设你有一个在PyTorch 1.13上训练的YOLOv5s模型，直接使用最新版PyTorch 2.1加载权重可能会报“weights format不兼容”的错误。此时不必升级训练框架，只需在转换环境中安装PyTorch 1.13即可。我们曾遇到一个项目，因为PyTorch版本升级导致torch.onnx.export导出的ONNX模型中NonMaxSuppression算子的输出顺序发生变化，最终在Android端出现检测框错位。解决方案是锁定PyTorch版本为1.13，并固定onnx版本为1.12。

2.3 ONNX与ONNX Runtime：模型转换与验证的“翻译官”

核心原理：ONNX（Open Neural Network Exchange）是一种开放的模型表示格式，它像“通用语言”一样，让不同框架训练出的模型可以互相转换。ONNX Runtime（ORT）则是微软推出的跨平台推理引擎，它读取ONNX模型并优化执行。在手机端部署中，我们使用onnxruntime的Python包进行模型验证，使用onnxruntime-mobile（Android/iOS）进行端侧推理。

安装命令：

# 安装ONNX模型处理库
pip install onnx==1.14.1

# 安装ONNX Runtime（CPU版，用于验证）
pip install onnxruntime==1.16.3

# 如果需要进行GPU加速验证（可选）
pip install onnxruntime-gpu==1.16.3

操作流程：

1. 使用onnx.checker.check_model验证模型结构完整性。
2. 使用onnxruntime.InferenceSession加载模型，输入随机张量进行推理，确认输出shape与预期一致。
3. 使用onnxsim简化模型，减少冗余算子：

   pip install onnxsim
   onnxsim input.onnx output_sim.onnx

常见误区：很多教程只安装onnxruntime而不安装onnx库，导致无法使用onnx.checker和onnx.shape_inference。这两个工具在排查模型转换错误时至关重要。另外，onnxruntime的版本必须与onnx版本匹配，否则可能出现“Opset version not supported”的错误。

2.4 移动端开发工具：Android Studio与Xcode

核心原理：手机端部署需要将ONNX Runtime的C++库打包进移动应用。Android平台使用JNI调用C++库，iOS平台使用Objective-C/Swift调用C++库。因此，你需要安装完整的移动开发环境，包括SDK、NDK（Android）或Xcode Command Line Tools（iOS）。

Android环境准备：

• Android Studio：建议安装最新稳定版（如Flamingo或Giraffe），并确保SDK Manager中安装了Android SDK Platform 33+、NDK（r25c或r26b）、CMake 3.22+。
• NDK版本选择：ONNX Runtime Mobile的Android AAR包要求NDK版本不低于r23。如果NDK版本过旧，会出现undefined reference to 'ANativeWindow_lock'等链接错误。
• Gradle配置：在build.gradle中设置android.ndkVersion为已安装的NDK版本。

iOS环境准备：

• Xcode：从App Store安装最新版Xcode（15+），并打开一次以完成组件初始化。
• Command Line Tools：在终端执行xcode-select --install。
• CocoaPods：用于集成onnxruntime-mobile的iOS框架：

  sudo gem install cocoapods

案例拆解：我们在一个Android项目中，最初使用NDK r21，结果在链接onnxruntime-mobile的AAR时出现dlopen failed: library "libonnxruntime.so" not found。排查后发现，NDK r21的libc++_shared.so版本过旧，与ORT的C++ ABI不兼容。升级到NDK r25c并重新编译后，问题解决。这个案例说明，移动端构建链的版本匹配比Python端更严格。

2.5 环境验证与排障：从“装好”到“能用”

核心原理：环境安装完成后，必须通过一个最小化测试来验证全链路是否打通。这个测试包括：创建一个简单的PyTorch模型 → 导出ONNX → 用onnxruntime加载并推理 → 在Android模拟器上运行。任何一步失败，都需要根据错误信息定位是Python环境问题、模型转换问题还是移动端构建问题。

验证脚本（Python端）：

import torch
import onnx
import onnxruntime as ort

# 1. 创建一个简单的模型
class SimpleModel(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.conv = torch.nn.Conv2d(3, 16, 3, padding=1)
    def forward(self, x):
        return self.conv(x)

model = SimpleModel().eval()
dummy_input = torch.randn(1, 3, 224, 224)

# 2. 导出ONNX
torch.onnx.export(model, dummy_input, "test.onnx",
                  opset_version=12, input_names=["input"], output_names=["output"])

# 3. 验证ONNX模型
onnx_model = onnx.load("test.onnx")
onnx.checker.check_model(onnx_model)

# 4. 使用ORT推理
sess = ort.InferenceSession("test.onnx")
result = sess.run(None, {"input": dummy_input.numpy()})
print("Output shape:", result[0].shape)  # 应输出 (1, 16, 224, 224)

常见错误与解决方案：

总结复盘：环境准备的核心不是“装最新”，而是“装匹配”。建议在项目开始时，先记录下所有关键组件的版本号，并写入requirements.txt或environment.yml。当团队协作时，使用conda env export > environment.yml导出环境配置，确保所有成员使用完全一致的依赖。此外，建议在移动端真机测试前，先在模拟器上跑通最小示例，因为模拟器的ABI（x86_64）与真机（arm64-v8a）不同，某些原生库可能只在arm64下可用。