📚 课程目录第4章环境搭建与工具链

4. 环境搭建与工具链

自动驾驶模型要在车端或边缘计算平台上稳定跑起来，第一步不是写推理代码，而是把整条工具链搭对。TensorRT 本身只是推理运行时，它依赖 NVIDIA 驱动、CUDA、cuDNN，还需要容器化保证环境可复现，再配合 Polygraphy、trtexec、Nsight Systems 完成验证、性能测试与瓶颈定位。本章按“依赖关系—安装流程—容器化—工具链分工—排障复盘”的顺序，把这条链路讲清楚。

一、核心原理：工具链的依赖层级

TensorRT 的版本兼容性非常严格，它并不是“装最新版就好”。TensorRT 在编译期绑定特定 CUDA 版本，运行时又依赖对应区间的 NVIDIA 驱动；cuDNN 为卷积、归一化等算子提供加速实现，TensorRT 的某些插件与解析路径会调用它。因此正确的理解方式是：驱动决定可用的 CUDA 上限，CUDA 决定可用的 TensorRT 与 cuDNN 组合，TensorRT 决定可用的 ONNX 解析能力与算子集。任何一层错配，典型表现就是 libcudnn.so 找不到、cudaErrorNoKernelImageForDevice、或引擎反序列化失败。

下图给出本节工具链的整体依赖与数据流关系：从模型文件出发，经 Polygraphy 检查、trtexec 构建引擎，最终由 TensorRT Runtime 执行，并由 Nsight Systems 观测全链路耗时。

二、安装流程：从驱动到 TensorRT

推荐顺序是“先确认驱动，再装 CUDA，再装 cuDNN，最后装 TensorRT”。在 Ubuntu 上，可用 nvidia-smi 查看驱动版本与支持的 CUDA 上限，再决定安装哪一版 CUDA Toolkit。安装时建议使用 runfile 或官方 apt 源，避免与系统自带驱动冲突。

# 1. 查看驱动与 CUDA 上限
nvidia-smi

# 2. 安装 CUDA Toolkit（示例：CUDA 12.2）
sudo sh cuda_12.2.0_535.54.03_linux.run --toolkit --silent

# 3. 配置环境变量
export PATH=/usr/local/cuda-12.2/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.2/lib64:$LD_LIBRARY_PATH

# 4. 安装 cuDNN（解压后拷贝到 CUDA 目录）
sudo cp cudnn-*-linux-x64-v8.9.7.29/include/* /usr/local/cuda/include/
sudo cp cudnn-*-linux-x64-v8.9.7.29/lib/* /usr/local/cuda/lib64/

# 5. 安装 TensorRT（tar 包方式）
tar -xzvf TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-12.0.tar.gz
export LD_LIBRARY_PATH=$PWD/TensorRT-8.6.1.6/lib:$LD_LIBRARY_PATH

常见误区：直接 pip install tensorrt 只安装 Python 绑定，不会安装底层运行时库；在容器外混用 apt 与 tar 包安装，容易出现 libnvinfer.so 版本冲突。生产环境优先使用 NGC 官方镜像。

三、Docker 容器化：环境可复现的关键

自动驾驶项目往往涉及多台开发机、CI 服务器和车端设备，手工装环境几乎无法保证一致。使用 NVIDIA Container Toolkit 后，容器内可直接访问 GPU。推荐基于 nvcr.io/nvidia/tensorrt:23.09-py3 这类 NGC 镜像，它已内置匹配好的 CUDA、cuDNN、TensorRT 与 Polygraphy。

# 安装 nvidia-container-toolkit 后运行
docker run --gpus all -it --rm \
  -v /data/models:/models \
  -v /data/engines:/engines \
  nvcr.io/nvidia/tensorrt:23.09-py3

# 容器内验证
trtexec --version
polygraphy --version

容器化的价值不只是“方便”，而是把驱动、CUDA、TensorRT 的版本组合固化成镜像标签，让引擎构建与推理结果可复现。车端部署时，通常只把构建好的 .plan 引擎和精简运行时拷入，避免携带完整工具链。

四、工具链分工与典型用法

三个工具各司其职：Polygraphy 负责“模型对不对”，trtexec 负责“引擎快不快”，Nsight Systems 负责“时间花在哪”。下表给出它们的定位与常用命令。

工具	核心作用	典型命令/参数	输出关注点
Polygraphy	ONNX 结构检查、精度逐层比对	`polygraphy run model.onnx --trt`	算子支持、数值误差
trtexec	构建引擎、吞吐与延迟基准	`--onnx= --saveEngine= --fp16`	GPU Compute Time、Throughput
Nsight Systems	采集时间线，定位 CPU/GPU 瓶颈	`nsys profile --stats=true`	内核耗时、H2D/D2H 拷贝

# 用 trtexec 构建 FP16 引擎并测试
trtexec --onnx=detector.onnx \
        --saveEngine=detector_fp16.plan \
        --fp16 --workspace=4096 \
        --shapes=input:1x3x640x640 \
        --iterations=200 --avgRuns=50

# 用 Polygraphy 对比 ONNX 与 TensorRT 输出
polygraphy run detector.onnx --trt \
  --onnxrt --val-range input:[0,1] \
  --atol 1e-2 --rtol 1e-2

# 用 Nsight Systems 采集推理时间线
nsys profile -o trt_profile --force-overwrite true \
  trtexec --loadEngine=detector_fp16.plan --iterations=100

五、案例与排障复盘

某自动驾驶感知项目在开发机上用 FP16 引擎达到 8ms 延迟，但换到车端后变成 22ms。排查步骤是：先用 nvidia-smi 确认车端驱动版本，发现低于引擎构建时的 CUDA 要求，导致 TensorRT 回退到兼容模式；再用 Nsight Systems 采集时间线，发现大量 H2D 拷贝未与计算重叠。修正方式是统一容器镜像版本，并在推理代码中使用 CUDA Stream 与 pinned memory 做异步拷贝，延迟恢复到 9ms 左右。

排障顺序建议：先看版本兼容（驱动/CUDA/TensorRT），再看模型解析（Polygraphy），再看引擎性能（trtexec），最后看运行时时间线（Nsight Systems）。按这个顺序能避免在错误层面反复试错。

把这条工具链搭稳之后，后续的精度校准、动态 shape、插件开发和车端集成才有可靠基线。环境一致性、版本匹配和可观测性，是 TensorRT 部署中比“调参”更值得先投入的三件事。