【树莓派5实战指南】ONNX Runtime本地Wheel包安装与避坑全解析

1. 为什么选择本地Wheel包安装

在树莓派5上部署AI模型时，很多开发者第一反应是使用pip install onnxruntime直接安装。但实际操作过的朋友都知道，这条路在树莓派上基本走不通。官方PyPI仓库提供的ONNX Runtime包大多针对x86架构，而树莓派5使用的是ARM架构，直接pip安装往往会遇到找不到合适版本的问题。

我刚开始玩树莓派5的时候也踩过这个坑。当时想着简单点直接pip安装，结果等了半天只等到一个"no matching distribution found"的错误提示。后来查了很多资料才发现，在ARM设备上最稳妥的方式就是使用预编译的Wheel包进行本地安装。

本地安装Wheel包有几个明显优势：首先是速度快，不需要从源码开始编译，省去了数小时的编译时间；其次是稳定性高，预编译的Wheel包都经过测试，避免了编译过程中可能出现的各种奇怪错误；最重要的是资源占用少，树莓派5的内存和存储资源有限，源码编译需要大量swap空间，而本地安装几乎不需要额外资源。

2. 安装前的环境准备

2.1 确认系统架构和Python版本

在开始安装之前，我们必须先确认树莓派5的系统架构和Python版本，这是选择正确Wheel包的关键。打开终端，执行以下命令：

python3 --version
uname -a

你会看到类似这样的输出：

Python 3.11.2
Linux raspberrypi 6.1.0-rpi8-rpi-2712 #1 SMP PREEMPT Debian 1:6.1.73-1+rpt1 (2024-01-25) aarch64 GNU/Linux

这里的关键信息是：Python 3.11 和 aarch64 架构。记下这两个信息，后面下载Wheel包时需要用到。

2.2 安装必要的依赖包

虽然使用Wheel包可以避免大部分编译工作，但一些基础依赖还是需要提前安装的：