环境搭建：Docker镜像拉取、TensorRT-LLM源码编译、验证安装
说实话，环境搭建这一步，往往是整个课程里最磨人的环节。我见过太多同学在群里问「编译报错了怎么办」「镜像拉不下来啊」。别急，今天我就把踩过的坑、绕过的路，一次性给你讲清楚。
咱们的目标很明确：把 TensorRT-LLM 跑起来，能调通，能推理。嗯，就这么简单。
1. 为什么我推荐用 Docker？
你想想看，TensorRT-LLM 依赖的东西太多了：CUDA、cuDNN、TensorRT、PyTorch……版本稍微不对付，编译就崩给你看。我刚开始搞的时候，直接在裸机上配环境，折腾了两天，最后发现是 CUDA 版本和驱动不匹配。从那以后，我就学乖了——能用 Docker 绝不用裸机。
Docker 镜像的好处是：
- 环境隔离：一个镜像就是一个完整的环境，不会污染宿主机
- 版本锁定：官方镜像里的 CUDA、cuDNN 版本都是验证过的
- 可复现：你拉的这个镜像，跟我在生产环境用的完全一样
2. 拉取官方 Docker 镜像
TensorRT-LLM 官方提供了预编译的 Docker 镜像，省去了很多麻烦。我个人建议直接用 nvcr.io/nvidia/tensorrt-llm 这个仓库。
先看看你机器上的 CUDA 驱动版本：
nvidia-smi | grep "CUDA Version"然后根据驱动版本选择对应的镜像。举个例子，如果你的驱动支持 CUDA 12.x，那就拉这个：
docker pull nvcr.io/nvidia/tensorrt-llm:latest如果你在国内，拉取可能会慢。我一般用 --platform linux/amd64 指定架构，然后配个镜像加速器。嗯，这里要注意：镜像标签一定要跟你的 CUDA 驱动匹配，否则容器里跑不了。
3. 从源码编译 TensorRT-LLM
有时候官方镜像不满足需求，比如你想加个自定义算子，或者想用最新的开发分支。这时候就得自己编译了。
编译前，先准备好依赖：
- CUDA Toolkit：建议 12.x 版本，11.x 也能用但有些新特性不支持
- cuDNN：跟 CUDA 版本匹配，我一般用 8.9.x
- TensorRT：8.6 或更高版本，注意是
libnvinfer那个包 - PyTorch：2.0 以上，带 CUDA 支持的
然后克隆源码：
git clone https://github.com/NVIDIA/TensorRT-LLM.git
cd TensorRT-LLM
git submodule update --init --recursive这里有个细节：submodule 一定要更新，否则编译会缺头文件。我刚开始就漏了这一步，结果报了一堆 fatal error: NvInfer.h: No such file or directory。
接下来是编译命令：
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release \
-DBUILD_PYT=ON \
-DBUILD_TRTLLM_PLUGINS=ON
make -j$(nproc)-j$(nproc) 是用所有 CPU 核心并行编译，能快不少。不过如果你的机器内存不大（比如 32GB 以下），建议改成 -j4，否则编译到一半可能 OOM。
4. 验证安装是否成功
编译完或者拉完镜像，怎么知道能不能用？我一般做三步验证：
4.1 检查 Python 包
python -c "import tensorrt_llm; print(tensorrt_llm.__version__)"如果没报错，说明核心库装好了。如果报 ModuleNotFoundError，检查一下 PYTHONPATH 有没有包含编译好的 build/tensorrt_llm 目录。
4.2 跑一个简单的推理
我习惯用官方自带的示例来验证。比如跑一个 GPT 模型的推理：
cd examples/gpt
python run.py --model_dir /path/to/model --engine_dir /path/to/engine能看到输出 token 就说明通了。如果报 CUDA 错误，八成是驱动版本问题。
4.3 检查 GPU 利用率
推理的时候，开另一个终端跑 nvidia-smi，看看 GPU 利用率是不是上去了。如果一直是 0%，说明推理没走 GPU，可能是 TensorRT 引擎没加载成功。
watch -n 1 nvidia-smi 实时监控 GPU 状态，比手动敲命令方便多了。
5. 常见问题与避坑指南
| 问题 | 原因 | 解决方法 |
|---|---|---|
编译报错 cuda_runtime.h: No such file |
CUDA 路径没设置 | export CUDA_HOME=/usr/local/cuda-12.x |
| 镜像拉取超时 | 网络问题 | 换国内镜像源，或者用代理 |
| 推理时显存不足 | 模型太大或 batch size 太大 | 减小 batch size，或者用量化 |
| Python import 报错 | PYTHONPATH 没设置 | export PYTHONPATH=/path/to/build:$PYTHONPATH |
我曾经遇到过一个特别坑的问题：编译成功了，但推理结果全是乱码。查了半天，发现是 TensorRT 版本跟源码不匹配。所以，一定要用官方推荐的版本组合，别自己瞎搭配。
6. 本章知识体系
下面这张图，是我自己总结的环境搭建流程，你照着走基本不会出错：
说白了，环境搭建就两条路：要么用 Docker 省心，要么自己编译折腾。我个人建议初学者先用 Docker，等熟悉了再尝试编译。毕竟，我们的目标是学量化推理，不是学编译。
好了，环境搭好了，下一章咱们就开始玩真的——用 TensorRT-LLM 跑一个模型推理。嗯，到时候你会觉得，今天这点折腾都是值得的。