📚 课程目录第2章 Jetson系统环境与工具链部署

2. Jetson系统环境与工具链部署

拿到一块Jetson开发板（如Orin Nano、Xavier NX或AGX Orin）之后，第一件真正影响后续所有性能诊断与优化工作的事情，不是马上跑benchmark，而是把系统环境和工具链部署正确。JetPack SDK是NVIDIA为Jetson系列提供的统一软件栈，它把L4T（Linux for Tegra，基于Ubuntu的板级系统）、CUDA、cuDNN、TensorRT、VPI、DeepStream等组件打包在一起，通过统一的版本号发布。理解JetPack的组成结构，是判断“环境是否可用”的前提。

JetPack的组成与版本对应关系

JetPack并不是一个单独的安装包，而是一个版本化的组件集合。以JetPack 5.x和6.x为例，每个JetPack版本都严格绑定一组组件版本：L4T版本、CUDA版本、cuDNN版本、TensorRT版本。例如JetPack 5.1.2对应L4T 35.4.1、CUDA 11.4、cuDNN 8.6、TensorRT 8.5.2；JetPack 6.0对应L4T 36.3、CUDA 12.2、cuDNN 8.9、TensorRT 8.6。这些版本不是可以随意混搭的，TensorRT的引擎文件（.plan）与构建它的TensorRT版本强绑定，跨版本加载会直接失败。因此在部署阶段就要把版本关系固定下来，而不是等到推理报错时再回头排查。

部署JetPack有两条主要路径：一是使用NVIDIA官方提供的SD Card Image（适用于Nano、Orin Nano等带SD卡槽的型号），直接烧录即可获得完整环境；二是使用SDK Manager在Ubuntu主机上通过USB对开发板进行刷机，这种方式可以选择组件、支持eMMC型号，并能同时安装主机端工具。对于需要精确控制组件版本或做批量部署的场景，SDK Manager更可控。

系统版本与兼容性检查

部署完成后，第一步是确认板子上实际运行的L4T版本。执行：

cat /etc/nv_tegra_release
# 输出示例（合理假设）：
# R35 (release), REVISION: 4.1, GCID: 34567890, BOARD: t186ref, EABI: aarch64

这里的R35.4.1就是L4T版本，它对应JetPack 5.1.2。如果这个版本与你要安装的PyTorch、TensorRT或DeepStream所要求的版本不一致，后续一定会出问题。例如NVIDIA官方提供的PyTorch wheel文件名中会带有“cp38”和“l4t”标识，必须与板上的Python版本和L4T版本同时匹配。

接着检查CUDA是否真正可用。Jetson上的CUDA是集成在L4T中的，不需要单独安装驱动，但需要确认环境变量和工具链：

nvcc --version
# 应输出 CUDA 11.4 或对应版本

ls /usr/local/cuda/bin/
# 确认 nvcc、deviceQuery 等存在

/usr/local/cuda/bin/deviceQuery
# 输出 Result = PASS 表示 CUDA 设备识别正常

如果deviceQuery输出PASS，说明CUDA运行时能够正确枚举GPU设备。这一步很关键，因为很多“TensorRT推理失败”的根因其实是CUDA设备没有被正确识别。

cuDNN与TensorRT的验证

cuDNN和TensorRT通常以deb包形式随JetPack安装，可以用dpkg确认：

dpkg -l | grep -E "cudnn|tensorrt"
# 应看到 libcudnn8、libnvinfer8、libnvonnxparsers8 等包

trtexec --version
# TensorRT 8.5.2 等版本信息

trtexec是TensorRT自带的命令行工具，它既能验证TensorRT运行时是否正常，也能用来做ONNX转engine、性能测试。如果trtexec能正常输出版本并跑通一个简单模型，说明TensorRT环境基本可用。一个常用的快速验证方式是：

trtexec --onnx=model.onnx --saveEngine=model.plan --fp16
# 若成功，会输出 engine 构建耗时、层信息、吞吐量等

这里需要注意，TensorRT engine与构建它的TensorRT版本、GPU架构（如sm_87对应Orin）强绑定。在Orin上构建的engine不能直接拿到Xavier上运行，反之亦然。因此在多型号部署时，要么在目标设备上重新构建engine，要么使用TensorRT的兼容模式（如--hardwareCompatibilityLevel），但后者会牺牲部分性能。

Python环境与框架版本匹配

如果后续要用PyTorch或TensorFlow，必须使用NVIDIA为Jetson预编译的wheel包，而不是pip上的通用aarch64包。以PyTorch为例，NVIDIA会在developer.nvidia.com/embedded/pytorch页面提供对应JetPack版本的wheel。安装后应验证：

python3 -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
# 期望输出 True

如果torch.cuda.is_available()返回False，通常说明PyTorch wheel与CUDA版本不匹配，或者环境变量LD_LIBRARY_PATH没有包含CUDA库路径。可以在~/.bashrc中补充：

export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

建议在部署完成后立即记录一份“环境快照”：L4T版本、CUDA版本、cuDNN版本、TensorRT版本、Python版本、PyTorch版本。这份快照在后续排查性能问题或复现实验时非常有用，因为很多性能差异其实来自环境版本差异，而不是代码本身。

兼容性检查的实用判断依据

判断环境是否“干净可用”，可以按以下顺序快速核对：第一，cat /etc/nv_tegra_release确认L4T版本；第二，nvcc --version与deviceQuery确认CUDA；第三，dpkg -l | grep tensorrt与trtexec --version确认TensorRT；第四，python3 -c "import torch; print(torch.cuda.is_available())"确认框架层。四步都通过，才说明工具链部署完整。任何一步失败，都应先解决该层问题，再往上排查，避免在错误的环境上做性能分析，得到不可信的结论。

此外，Jetson的电源模式（nvpmodel）和时钟频率（jetson_clocks）也会影响性能表现，但它们属于系统优化范畴，建议在环境验证通过后再调整。环境部署阶段的目标只有一个：让L4T、CUDA、cuDNN、TensorRT、Python框架五者版本一致且可调用，为后续的性能诊断提供可信的基线。