4、Python与虚拟环境：安装Miniconda或venv、创建独立环境、管理依赖包

在Raspberry Pi 5上进行AI推理开发，Python环境管理是决定项目可持续性的关键环节。树莓派系统自带的Python版本往往与AI框架（如PyTorch、TensorFlow、ONNX Runtime）的依赖要求存在冲突，且系统级Python环境一旦被污染，可能导致整个操作系统不稳定。本章将系统讲解如何在树莓派5上使用Miniconda或venv构建隔离的Python环境，并掌握依赖包管理的核心方法，确保你的AI推理项目具备可复现性与可维护性。

上图展示了树莓派5上Python环境隔离的完整链路。系统自带的Python 3.11位于/usr/bin/python3，其site-packages目录受系统权限保护。若直接使用pip install安装AI框架，不仅可能破坏系统依赖，还会因ARM架构的编译问题导致安装失败。因此，建立独立环境是AI推理项目的第一步，也是最重要的一步。

4.1 核心原理：为什么需要虚拟环境

树莓派5的官方系统（Raspberry Pi OS）基于Debian，其Python包管理遵循Debian的apt体系。系统Python环境中的包由apt统一管理，版本通常较旧且不可随意升级。例如，系统自带的python3-numpy可能为1.24版本，而PyTorch 2.x要求numpy>=1.21且<2.0，看似兼容，但OpenCV的预编译轮子（wheel）可能依赖更新的numpy API。这种版本冲突在AI项目中极为常见。

虚拟环境的核心原理是创建一个独立的目录结构，其中包含自己的Python解释器副本（或符号链接）和独立的site-packages目录。当激活虚拟环境后，PATH环境变量会优先指向虚拟环境中的bin目录，使得python、pip命令均指向虚拟环境内的可执行文件。这样，你在环境中安装的任何包都不会影响系统Python，反之亦然。

4.2 操作流程：Miniconda安装与环境创建

在树莓派5上安装Miniconda，需要下载ARM64架构的安装脚本。以下是完整流程：

# 1. 下载Miniconda安装脚本（ARM64架构）
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh

# 2. 运行安装脚本（建议安装到用户目录）
bash Miniconda3-latest-Linux-aarch64.sh -b -p $HOME/miniconda3

# 3. 初始化conda（使conda命令在终端中可用）
$HOME/miniconda3/bin/conda init bash

# 4. 重新加载shell配置
source ~/.bashrc

# 5. 验证安装
conda --version
# 输出示例: conda 24.1.2

安装完成后，创建AI推理专用环境：

# 创建Python 3.10环境（AI框架兼容性最佳）
conda create -n ai_env python=3.10 -y

# 激活环境
conda activate ai_env

# 验证Python版本
python --version
# 输出: Python 3.10.13

# 安装核心AI依赖（使用pip以获得最新版本）
pip install numpy==1.26.4 opencv-python==4.9.0.80
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

对于偏好轻量级方案的开发者，venv同样适用：

# 创建venv环境（使用系统Python 3.11）
python3 -m venv ~/ai_venv

# 激活环境
source ~/ai_venv/bin/activate

# 验证
which python
# 输出: /home/pi/ai_venv/bin/python

4.3 案例拆解：树莓派5上的PyTorch环境搭建实战

假设你需要在树莓派5上部署一个基于PyTorch的图像分类模型，输入为USB摄像头实时画面。以下是完整的环境搭建与依赖管理过程：

步骤	操作	关键参数/命令	验证方式
1. 系统准备	更新系统包	sudo apt update && sudo apt upgrade -y	无报错
2. 安装Miniconda	下载并安装	bash Miniconda3-latest-Linux-aarch64.sh -b	conda --version
3. 创建环境	Python 3.10	conda create -n torch_env python=3.10 -y	conda activate torch_env
4. 安装PyTorch	CPU版本	pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu	python -c "import torch; print(torch.__version__)"
5. 安装视觉库	OpenCV与摄像头支持	pip install opencv-python picamera2	python -c "import cv2; print(cv2.__version__)"
6. 导出依赖	生成requirements.txt	pip freeze > requirements.txt	文件内容完整

在实际部署中，你可能会遇到libcamera相关的依赖问题。树莓派5的摄像头通过libcamera框架驱动，而OpenCV的VideoCapture默认使用V4L2接口。解决方案是安装picamera2库，它提供了与OpenCV兼容的接口：

# 安装picamera2（树莓派5专用）
sudo apt install -y python3-picamera2

# 在Python中测试摄像头
from picamera2 import Picamera2
import cv2
import numpy as np

picam2 = Picamera2()
picam2.configure(picam2.create_preview_configuration(main={"format": 'RGB888', "size": (640, 480)}))
picam2.start()

# 捕获一帧
frame = picam2.capture_array()
print(f"捕获帧形状: {frame.shape}")  # 输出: (480, 640, 3)

4.4 依赖包管理：版本锁定与复现

AI项目的依赖管理需要精确到版本号。以下表格对比了三种常见的依赖管理策略：

策略	命令	优点	缺点	适用场景
pip freeze	pip freeze > requirements.txt	精确锁定所有包版本	包含无关依赖，跨平台兼容性差	单机部署、快速复现
conda env export	conda env export > environment.yml	包含conda包和pip包	文件较大，包含系统特定路径	跨平台团队协作
手动指定	在requirements.txt中手动写核心依赖	简洁、可读性强	可能遗漏传递依赖	项目初始化、文档展示

推荐的做法是：在项目根目录维护一个requirements.txt，只列出直接依赖的核心包，并注释说明版本选择原因：

# AI推理核心依赖
numpy==1.26.4  # 确保与PyTorch兼容
opencv-python==4.9.0.80  # 摄像头图像处理
torch==2.2.0  # CPU版本，支持ARM64
torchvision==0.17.0
picamera2==0.3.17  # 树莓派5摄像头驱动
onnxruntime==1.17.1  # 可选，用于模型优化

4.5 常见误区与排障指南

在树莓派5上管理Python环境时，以下问题最为常见：

排障时，首先检查环境是否激活：which python应指向虚拟环境路径。其次，使用pip list查看已安装包版本，对比官方文档要求。最后，若遇到Illegal instruction错误，说明包编译时使用了不兼容的CPU指令集，需更换为预编译轮子或降低版本。

4.6 总结复盘：环境管理的最佳实践

经过本章学习，你应该掌握以下核心要点：

• 环境隔离是AI项目的第一道防线，无论是Miniconda还是venv，都能有效防止依赖冲突。
• Miniconda更适合树莓派5，因为它能管理Python版本，且conda-forge提供了丰富的ARM64预编译包。
• 依赖管理必须版本锁定，使用requirements.txt记录核心依赖，并定期更新。
• 摄像头与AI框架的集成需要额外安装picamera2，并注意OpenCV与libcamera的兼容性。