第二章：环境搭建——在树莓派4B / Jetson Nano上部署Python 3.8+、PyTorch、bitsandbytes、transformers
说实话，QLoRA 部署最劝退人的地方，不是模型本身，而是环境。
我见过太多人，模型下载好了，代码写完了，结果卡在 bitsandbytes 编译不过去。嗯，这一章我们就来解决这个问题。
2.1 硬件准备与系统烧录
先说说硬件。树莓派4B 我建议至少 4GB 内存版本，8GB 更稳。Jetson Nano 的话，官方 4GB 版本就行，但记得主动散热——我有一块 Nano 因为散热没做好，跑量化时直接降频，速度慢了三倍。
系统方面：
- 树莓派4B：推荐 Raspberry Pi OS (64-bit) 或 Ubuntu Server 22.04 LTS。我个人习惯用 Ubuntu Server，包管理更顺手。
- Jetson Nano：必须用 NVIDIA 官方的 JetPack 4.6+，自带 CUDA 11.4 和 cuDNN 8.x。别自己装 Ubuntu，驱动会搞死你。
2.2 Python 3.8+ 环境配置
树莓派和 Jetson Nano 默认带的 Python 版本可能不够。我建议直接用 pyenv 管理多版本，干净又灵活。
# 安装依赖
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev
# 安装 pyenv
curl https://pyenv.run | bash
# 添加到 bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc
# 安装 Python 3.10（QLoRA 推荐版本）
pyenv install 3.10.12
pyenv global 3.10.12
为什么选 3.10？因为 bitsandbytes 在 3.11 上编译偶尔会报错，3.8 又太老。3.10 是我实测最稳的版本。
2.3 PyTorch 安装——这里有个坑
PyTorch 在 ARM 设备上不能直接用 pip 装官方版本。官方只提供 x86_64 的 wheel，ARM 得用社区编译版。
树莓派4B：
# 使用 pip 安装预编译的 aarch64 版本
pip install torch==2.0.0 torchvision==0.15.0 --index-url https://download.pytorch.org/whl/cpu
注意这里用的是 CPU 版本。树莓派没有 NVIDIA GPU，所以 CUDA 就别想了。但 QLoRA 的 4-bit 量化在 CPU 上也能跑，就是慢点。
Jetson Nano：
# 先安装 JetPack 自带的 PyTorch（NVIDIA 定制版）
sudo apt install nvidia-jetpack
# 或者从 NVIDIA 论坛下载预编译 wheel
pip install torch-1.12.0a0+git7a1c7a5-cp38-cp38-linux_aarch64.whl
2.4 bitsandbytes——最折腾的一环
bitsandbytes 是 QLoRA 的核心依赖，负责 4-bit 量化。但它在 ARM 上没有官方预编译包，必须从源码编译。
为什么会这样？因为 bitsandbytes 底层用了 CUDA 的 cuda_bf16 和 cuda_fp8 指令，这些在 x86_64 上直接支持，ARM 上需要重新编译。
编译步骤：
# 安装编译依赖
sudo apt install -y build-essential cmake
# 克隆源码
git clone https://github.com/TimDettmers/bitsandbytes.git
cd bitsandbytes
# 编译（Jetson Nano 需要指定 CUDA 架构）
CUDA_VERSION=114 make cuda11x
# 或者直接
make cuda11x
# 安装
pip install -e .
编译大概需要 10-15 分钟。Jetson Nano 的 4 核 A57 跑编译时温度会飙到 80°C，建议加个风扇。
fatal error: cuda_runtime.h: No such file or directory。解决方案是手动设置环境变量：export CUDA_HOME=/usr/local/cuda-11.4。
2.5 transformers 与 accelerate
这两个相对简单，直接 pip 就行。
pip install transformers==4.35.0 accelerate==0.24.0
注意版本匹配。transformers 4.35 以上对 QLoRA 支持更好，但 4.40 之后有些 API 变了。我个人习惯锁定 4.35，稳定。
2.6 验证环境
装完别急着跑模型，先写个简单脚本验证一下。
import torch
import bitsandbytes as bnb
from transformers import AutoModel, AutoTokenizer
# 检查 PyTorch 版本
print(f"PyTorch version: {torch.__version__}")
# 检查 bitsandbytes 是否可用
print(f"bitsandbytes version: {bnb.__version__}")
# 测试 4-bit 量化（Jetson Nano 上）
if torch.cuda.is_available():
model = AutoModel.from_pretrained(
"facebook/opt-125m",
load_in_4bit=True,
device_map="auto"
)
print("4-bit 量化加载成功！")
else:
print("CPU 模式，跳过 GPU 测试")
如果输出没有报错，恭喜你，环境搭好了。
2.7 知识体系总览
下面这张图概括了本章的核心逻辑：
2.8 常见问题速查表
| 问题 | 原因 | 解决方案 |
|---|---|---|
bitsandbytes 编译报错 cuda_runtime.h 找不到 |
CUDA 路径未设置 | export CUDA_HOME=/usr/local/cuda-11.4 |
PyTorch 安装后 import 报错 Illegal instruction |
CPU 不支持某些指令集 | 换用社区编译的 aarch64 版本 |
| transformers 加载模型时 OOM | 内存不足 | 使用 load_in_4bit=True 并设置 device_map="auto" |
| Jetson Nano 上 CUDA 不可用 | JetPack 未正确安装 | 运行 sudo apt install nvidia-jetpack |
嗯，环境搭建就到这里。别嫌麻烦，这一步搞定了，后面跑模型就是水到渠成的事。
📌 核心要点回顾：
- 树莓派用 Ubuntu Server 64-bit，Jetson Nano 用 JetPack 4.6+
- Python 3.10 最稳，用 pyenv 管理版本
- PyTorch 必须用 ARM 编译版，别从官网 pip
- bitsandbytes 从源码编译，注意 CUDA 路径
- 装完一定要跑验证脚本，别偷懒
公众号:蓝海资料掘金营，微信deep3321