从零到一：Jetson AArch64 架构下的深度学习环境搭建避坑指南

在嵌入式 AI 和边缘计算领域，NVIDIA Jetson 系列设备凭借其强大的 GPU 算力和紧凑的尺寸，成为众多开发者的首选平台。然而，对于初次接触 ARM64 架构的开发者来说，在 Jetson 设备上搭建完整的深度学习环境并非易事。与传统的 x86 架构不同，Jetson 设备基于 ARM64 架构，这意味着许多常见的安装方法和预编译包可能无法直接使用，甚至会导致系统崩溃。

我曾经花费数周时间，尝试了各种方法，踩遍了几乎所有可能的坑，才最终在 Jetson Orin 上成功搭建了稳定运行的 CUDA、cuDNN 和 PyTorch 环境。这段经历让我深刻认识到，在 Jetson 上搭建深度学习环境需要遵循特定的方法论，而不是简单照搬 x86 平台的经验。

本文将分享我在 Jetson ARM64 设备上环境搭建的实战经验，重点解析那些容易导致失败的陷阱，并提供经过验证的解决方案。无论你是刚接触边缘计算的初学者，还是有一定经验的开发者，这些经验都能帮助你少走弯路，快速构建稳定的开发环境。

1. 理解 Jetson 平台的特殊性

Jetson 设备与传统的 x86 Linux 系统有着本质的区别，这决定了我们不能使用常规的安装方法。首先，Jetson 采用 NVIDIA 的 Tegra 处理器，基于 ARM64 架构，这意味着所有软件包都需要针对该架构专门编译。其次，Jetson 使用 NVIDIA 专门优化的 Linux 发行版（L4T），其软件源和包管理与标准 Ubuntu 有所不同。

关键差异点对比：

特性	x86 Linux 系统	Jetson ARM64 系统
架构	x86_64	AArch64
CUDA 安装方式	可从 NVIDIA 官网下载 runfile 或 deb 包	必须通过 JetPack 或 NVIDIA 专属源安装
Python 包兼容性	大多数 wheel 包可直接安装	需要专门为 ARM64 编译的 wheel 包
系统优化	通用 Linux 内核	针对 Tegra 优化的 L4T 内核

在实际操作中，最大的陷阱就是试图使用为 x86 架构设计的安装方法。例如，直接从 NVIDIA 官网下载通用的 CUDA Toolkit 安装包，这几乎必定会导致安装失败或系统不稳定。

经验提示：在 Jetson 上，始终使用 NVIDIA 官方为 Jetson 提供的软件源和安装方法，避免使用通用 Linux 的安装包。

2. JetPack 套件的核心作用

JetPack 是 NVIDIA 为 Jetson 平台量身定制的开发套件，它不仅仅是几个软件的集合，而是一个完整的生态系统解决方案。理解 JetPack 的工作原理是成功搭建环境的关键。

2.1 JetPack 的元包管理机制

JetPack 通过元包（meta-package）管理系统，确保所有组件版本的兼容性。当你安装 nvidia-jetpack 时，实际上是在安装一个包含以下组件的协调集合：

• CUDA Toolkit：针对 Jetson 优化的 CUDA 版本
• cuDNN：深度神经网络加速库
• TensorRT：高性能推理优化器
• VisionWorks：计算机视觉库
• 多媒体 API：硬件加速的多媒体处理接口

安装 JetPack 的基础命令非常简单：

sudo apt update
sudo apt install nvidia-jetpack -y

这个命令会自动安装与你的 Jetson 系统和 L4T 版本兼容的所有必要组件。这是最推荐的方法，因为它避免了手动管理依赖关系的复杂性。

2.2 常见 JetPack 安装问题解决

即使使用 JetPack，有时也会遇到安装问题。以下是一些常见问题及其解决方案：

问题1：安装过程中出现依赖冲突

# 解决方案：修复损坏的依赖关系
sudo apt --fix-broken install
sudo apt update
sudo apt dist-upgrade

问题2：软件源配置错误

确保你的 /etc/apt/sources.list.d/nvidia-l4t-apt-source.list 文件包含正确的软件源。对于 JetPack 6.2，配置应该类似：

deb https://repo.download.nvidia.com/jetson/common r36.4 main
deb https://repo.download.nvidia.com/jetson/t234 r36.4 main

问题3：磁盘空间不足

Jetson 设备的存储空间通常有限，安装前确保有足够空间：

# 检查磁盘空间
df -h

# 清理不必要的包
sudo apt autoremove
sudo apt clean

实践建议：在开始安装前，始终先更新系统并确保有足够的磁盘空间（至少预留 5GB 以上）。

3. CUDA 和 cuDNN 的正确安装方式

在 Jetson 上安装 CUDA 和 cuDNN 与在 x86 系统上有很大不同。以下是经过验证的正确方法。

3.1 通过 JetPack 自动安装

推荐方法：使用 JetPack 元包自动安装，这是最稳妥的方式：

# 安装 JetPack（包含 CUDA 和 cuDNN）
sudo apt update
sudo apt install nvidia-jetpack -y

# 验证 CUDA 安装
nvcc --version

# 验证 cuDNN 安装
dpkg -l | grep libcudnn

3.2 手动安装的注意事项

在某些特殊情况下，可能需要手动安装特定版本的 CUDA。但这是一条充满陷阱的道路，需要格外小心。

手动安装 CUDA 的步骤：

# 添加 NVIDIA 软件源密钥
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/arm64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb

# 更新软件源
sudo apt update

# 安装特定版本的 CUDA Toolkit
sudo apt install cuda-toolkit-12-4

重要提醒：手动安装 CUDA 时，必须确保版本与你的 JetPack 和 L4T 版本兼容。不匹配的版本会导致系统不稳定甚至无法启动。

3.3 环境变量配置

无论采用哪种安装方式，都需要正确配置环境变量：

# 编辑 ~/.bashrc 文件
nano ~/.bashrc

# 添加以下内容（根据实际 CUDA 版本调整）
export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

# 使配置生效
source ~/.bashrc

避坑指南：不要随意修改 CUDA 的环境变量路径，Jetson 上的 CUDA 安装路径可能与 x86 系统不同。使用 which nvcc 命令确认正确的路径。

4. PyTorch 和 Torchvision 的兼容性安装

在 Jetson 上安装 PyTorch 是最容易出错的环节，因为 PyTorch 官方提供的 pip 包通常不兼容 ARM64 架构。以下是经过验证的安装方法。

4.1 选择正确的 PyTorch 版本

首先，你需要找到与你的 JetPack 版本兼容的 PyTorch wheel 包。NVIDIA 为 Jetson 提供了专门编译的 PyTorch 包，这些包通常包含在文件名中带有 nv 版本标识。

查看 JetPack 版本：

# 查看 L4T 版本（决定兼容性的关键）
cat /etc/nv_tegra_release

# 或者使用
head -n 1 /etc/nv_tegra_release

安装兼容的 PyTorch：

对于 JetPack 6.2（L4T R36.4），可以使用以下命令安装 PyTorch 2.5.0：

# 安装 PyTorch
pip3 install --no-cache-dir https://developer.download.nvidia.com/compute/redist/jp/v61/pytorch/torch-2.5.0a0+872d972e41.nv24.08.17622132-cp310-cp310-linux_aarch64.whl

4.2 安装匹配的 Torchvision

Torchvision 版本必须与 PyTorch 严格匹配，否则会出现各种难以调试的问题。

# 安装与 PyTorch 2.5.0 兼容的 Torchvision
pip install https://github.com/ultralytics/assets/releases/download/v0.0.0/torchvision-0.20.0a0+afc54f7-cp310-cp310-linux_aarch64.whl

4.3 处理依赖关系问题

PyTorch 安装过程中最常见的问题是依赖冲突，特别是 numpy 版本问题：

# 如果出现 numpy 兼容性问题，降级到兼容版本
pip install "numpy<2"

# 安装其他可能缺失的依赖
sudo apt install libopenblas-base libopenmpi-dev

4.4 验证 PyTorch 安装

安装完成后，必须进行全面的验证：

# 创建验证脚本 test_pytorch.py
import torch
print('PyTorch 版本:', torch.__version__)
print('CUDA 可用:', torch.cuda.is_available())
print('CUDA 版本:', torch.version.cuda)
print('GPU 名称:', torch.cuda.get_device_name(0))

# 测试 GPU 计算
x = torch.randn(1, 1, 28, 28).cuda()
model = torch.nn.Conv2d(1, 10, 5).cuda()
output = model(x)
print('卷积计算结果形状:', output.shape)

运行验证脚本：

python3 test_pytorch.py

如果输出显示 CUDA 可用且计算正常，说明安装成功。

重要提示：如果验证过程中出现任何错误，不要继续后续步骤。首先解决 PyTorch 的问题，因为这是深度学习开发的基础。

5. 环境优化和故障排除

即使成功安装了所有组件，仍然需要进行一些优化配置以确保最佳性能和稳定性。

5.1 电源管理配置

Jetson 设备有不同的电源模式，影响性能和功耗：

# 查看当前电源模式
sudo nvpmodel -q

# 设置最大性能模式（模式0）
sudo nvpmodel -m 0

# 设置最大时钟频率
sudo jetson_clocks

5.2 内存和交换空间优化

由于 Jetson 设备内存有限，配置适当的交换空间很重要：

# 创建交换文件
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 永久生效，添加到 /etc/fstab
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

5.3 常见问题解决方案

问题：ImportError: libxxx.so.x 找不到

# 更新动态链接库缓存
sudo ldconfig

# 查找缺失的库
find /usr -name "libxxx.so*"

问题：CUDA out of memory

# 监控 GPU 内存使用情况
sudo tegrastats

# 或者在 Python 中减少批处理大小
# 使用 torch.cuda.empty_cache() 定期清理缓存

问题：系统卡顿或无响应

# 检查系统负载
htop

# 检查温度（过热会导致降频）
cat /sys/class/thermal/thermal_zone*/temp

5.4 性能监控工具

安装和使用系统监控工具：

# 安装 jtop（Jetson 状态监控工具）
sudo pip3 install -U jetson-stats

# 运行 jtop
sudo jtop

jtop 提供了全面的系统监控信息，包括 CPU、GPU、内存使用情况，以及温度和电源状态。

6. 容器化开发环境

对于复杂的项目，建议使用 Docker 容器来管理开发环境，这样可以避免污染系统环境，也便于环境复现。

6.1 安装 NVIDIA Container Toolkit

# 设置软件源和GPG密钥
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 安装 nvidia-container-toolkit
sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

6.2 使用 NVIDIA 提供的容器

NVIDIA 提供了预配置的深度学习容器，大大简化了环境搭建：

# 拉取 PyTorch 容器
docker pull nvcr.io/nvidia/l4t-pytorch:r36.4.0-pth2.1.0-py3

# 运行容器（支持 GPU）
docker run --runtime nvidia -it --rm --network host nvcr.io/nvidia/l4t-pytorch:r36.4.0-pth2.1.0-py3

6.3 构建自定义容器

如果需要特定配置，可以基于官方容器构建自定义环境：

# Dockerfile
FROM nvcr.io/nvidia/l4t-pytorch:r36.4.0-pth2.1.0-py3

# 安装额外依赖
RUN pip3 install --no-cache-dir \
    matplotlib \
    seaborn \
    pandas \
    scikit-learn

# 设置工作目录
WORKDIR /workspace

构建和运行自定义容器：

# 构建镜像
docker build -t my-pytorch-env .

# 运行容器
docker run --runtime nvidia -it --rm --network host -v $(pwd):/workspace my-pytorch-env

通过容器化方式，你可以为每个项目创建独立的环境，避免版本冲突，也便于团队协作和部署。

在 Jetson ARM64 设备上搭建深度学习环境确实有其特殊性，但一旦掌握了正确的方法论，就能避免大多数常见问题。关键是要记住：始终使用 NVIDIA 官方为 Jetson 提供的工具和软件源，严格保持组件版本的兼容性，并在每一步都进行验证测试。

实际项目中，我建议先在一个简单的测试脚本上验证环境稳定性，然后再开始复杂的模型开发。这样可以在早期发现潜在问题，避免在项目后期遇到难以调试的环境问题。