3. 环境搭建避坑：PyTorch 与 ONNX 版本兼容性、OpenCV 编译时启用 NEON/OpenMP、Python 虚拟环境管理（conda vs venv）

环境搭建，说白了就是给模型找个合适的「家」。

我见过太多人，模型选好了，代码写好了，最后卡在环境上。一折腾就是两三天，心态直接崩掉。今天咱们就把这几个最坑的点，一个一个说清楚。

3.1 PyTorch 与 ONNX 版本兼容性：版本不对，导出就废

先说说 PyTorch 和 ONNX 的兼容性问题。这俩东西，版本不匹配的话，导出模型时各种报错，你根本不知道错在哪。

为什么会这样？

PyTorch 的算子（operator）在不断更新，ONNX 的算子集（opset）也在迭代。你用的 PyTorch 版本太新，ONNX 的 opset 版本跟不上，就会报「Unsupported operator」之类的错误。

我个人习惯的做法是：

• PyTorch 1.8 ~ 1.10：搭配 ONNX opset 11 或 12
• PyTorch 1.11 ~ 1.13：搭配 ONNX opset 13 或 14
• PyTorch 2.0+：搭配 ONNX opset 15 或 16

我在项目中遇到过一件事：用 PyTorch 2.0 导出 MobileViT，ONNX opset 设成了 11，结果死活导不出。后来查了半天，发现是 nn.SiLU 这个激活函数在 opset 11 里不支持。换成 opset 15，一次过。

这里给出一段我常用的导出代码：

import torch
import torch.onnx

# 假设 model 是你的 MobileViT 模型
dummy_input = torch.randn(1, 3, 256, 256)

torch.onnx.export(
    model,
    dummy_input,
    "mobilevit.onnx",
    opset_version=15,          # 关键：指定 opset 版本
    input_names=["input"],
    output_names=["output"],
    dynamic_axes={
        "input": {0: "batch_size"},
        "output": {0: "batch_size"}
    }
)
print("导出成功！")

你想想看，如果这里不指定 opset 版本，PyTorch 会用默认值。默认值有时候是 11，有时候是 12，完全看心情。所以，显式指定 opset 版本，是避免踩坑的第一步。

3.2 OpenCV 编译时启用 NEON/OpenMP：速度翻倍的秘密

OpenCV 在边缘设备上的性能，很大程度上取决于编译选项。默认的 OpenCV 安装包，通常没有启用 NEON 和 OpenMP 优化。

NEON 是什么？

NEON 是 ARM 架构的 SIMD（单指令多数据）扩展。说白了，就是让 CPU 一次处理多个数据。对于图像处理这种大量重复计算的任务，NEON 能带来 2~4 倍的性能提升。

OpenMP 又是什么？

OpenMP 是多线程并行计算的接口。启用后，OpenCV 的某些函数会自动利用多核 CPU 并行计算。

我在项目中遇到过：在树莓派 4B 上跑 MobileViT 的预处理，没启用 NEON 时，一张 256x256 的图像预处理要 15ms。启用 NEON 后，直接降到 5ms。你想想看，这 10ms 的差距，在实时推理场景下有多重要。

编译 OpenCV 时，建议加上以下 CMake 选项：

cmake -DCMAKE_BUILD_TYPE=RELEASE \
      -DCMAKE_INSTALL_PREFIX=/usr/local \
      -DWITH_NEON=ON \
      -DWITH_OPENMP=ON \
      -DWITH_TBB=ON \
      -DWITH_GTK=ON \
      -DWITH_JPEG=ON \
      -DWITH_PNG=ON \
      -DBUILD_opencv_python3=ON \
      -DPYTHON3_EXECUTABLE=$(which python3) \
      ..

编译完成后，可以用以下代码验证 NEON 和 OpenMP 是否启用：

import cv2
print("OpenCV 版本:", cv2.__version__)
print("是否启用 NEON:", cv2.useOptimized())
print("线程数:", cv2.getNumThreads())

如果 cv2.useOptimized() 返回 True，说明优化已启用。如果返回 False，嗯，那你得重新编译了。

3.3 Python 虚拟环境管理：conda vs venv，选哪个？

虚拟环境这东西，说白了就是给每个项目一个独立的 Python 环境。避免「项目 A 需要 PyTorch 1.8，项目 B 需要 PyTorch 2.0」这种冲突。

conda 和 venv 的区别：

特性	conda	venv
包管理	支持 Python 和非 Python 包	仅支持 Python 包
环境隔离	完全隔离，包括系统库	仅隔离 Python 包
安装速度	较慢（依赖 conda 源）	较快（依赖 pip）
磁盘占用	较大（每个环境独立 Python）	较小（共享系统 Python）
适用场景	需要非 Python 依赖（如 CUDA）	纯 Python 项目

我个人习惯是：

• 边缘设备上：用 venv。因为边缘设备存储空间有限，conda 的环境太占地方。
• 开发机上：用 conda。因为开发机需要管理 CUDA、cuDNN 等非 Python 依赖。

举个例子，在树莓派上部署 MobileViT，我一般这样操作：

# 创建虚拟环境
python3 -m venv mobilevit_env

# 激活环境
source mobilevit_env/bin/activate

# 安装依赖
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install onnx onnxruntime opencv-python

如果你用 conda，命令是这样的：

# 创建虚拟环境
conda create -n mobilevit_env python=3.8

# 激活环境
conda activate mobilevit_env

# 安装依赖
conda install pytorch torchvision cpuonly -c pytorch
pip install onnx onnxruntime opencv-python

3.4 本章小结：环境搭建的「黄金法则」

嗯，到这里，环境搭建的几个核心坑点都讲完了。总结一下：

• PyTorch 和 ONNX 版本要匹配：导出时显式指定 opset 版本，别偷懒。
• OpenCV 编译要启用 NEON 和 OpenMP：编译前确认 CMake 选项，别等编译完才发现。
• 虚拟环境选 venv 还是 conda：边缘设备用 venv，开发机用 conda。

环境搭建这件事，说白了就是「慢工出细活」。你花 1 小时把环境搭好，后面能省 10 小时。你花 10 分钟随便搭一下，后面可能要花 100 小时来填坑。

我个人习惯是：每次搭建环境时，把用到的命令和版本号记下来。下次换设备时，直接复制粘贴，省时省力。

好了，这一章就到这里。下一章咱们聊聊模型转换和量化，那又是另一番天地了。

---