课程导入：学习目标、课程结构、环境准备与工具链概览

欢迎来到《TensorRT-LLM模型转换与格式适配实战》课程。在正式开始动手操作之前，我们需要先建立全局视角：这门课要解决什么问题、你将获得哪些能力、课程如何组织、以及你的机器上需要准备哪些环境。这一节是整个实战旅程的“地基”，请务必跟随完成环境验证。

1.1 学习目标：从“能跑通”到“懂适配”

TensorRT-LLM 是 NVIDIA 推出的高性能大语言模型推理框架，它并不直接读取 HuggingFace 的 safetensors 权重，而是需要经过一系列转换与格式适配，生成引擎文件后才能高效运行。很多初学者在第一步就遇到障碍：模型转换失败、精度异常、或者引擎构建时显存溢出。本课程的核心目标，是帮助你建立一套可复用的模型转换与适配方法论。

完成本课程后，你将能够：

  • 理解转换链路：清晰描述从 HuggingFace 权重到 TensorRT-LLM 引擎的完整流程，包括权重格式、tokenizer 模型、配置参数三个核心要素。
  • 独立完成格式转换：熟练使用 convert_checkpoint.py 脚本，将主流开源模型（如 LLaMA、Qwen、ChatGLM、Baichuan 等）转换为 TensorRT-LLM 的 checkpoint 格式。
  • 掌握引擎构建与量化适配：根据推理场景（在线/离线、单卡/多卡）选择合适的精度（FP16、INT8、INT4）与构建参数，生成可部署的 engine 文件。
  • 具备排障能力：面对转换报错、精度对齐失败、显存不足等高频问题，能够根据日志定位原因并调整策略。
课程定位提示：本课程不深入讲解 TensorRT-LLM 的 CUDA kernel 实现细节，而是聚焦于“如何把模型正确、高效地送入 TensorRT-LLM 运行时”。如果你希望了解底层算子优化，建议后续学习 NVIDIA 官方进阶课程。

1.2 课程结构：四大模块递进式学习

全课程共 30 节，分为四个递进模块。每个模块结束后，都配有综合实战练习，帮助你巩固所学。

模块 章节范围 核心主题 实战产出
基础入门 第1-5节 环境搭建、工具链、转换流程概览 成功转换一个最小模型（如 GPT-2）
核心转换 第6-15节 主流模型架构适配、参数映射、量化转换 完成 LLaMA-7B 的 FP16/INT8 引擎构建
高级适配 第16-24节 多卡张量并行、paged KV cache、自定义算子 实现多卡推理并优化吞吐
实战与排障 第25-30节 典型业务场景、性能调优、错误码速查 完成一个端到端部署项目

每一节都遵循“原理讲解 → 代码实操 → 常见误区 → 复盘小结”的闭环结构。建议你准备好一个实验笔记本，记录每次转换的参数组合与报错信息，这将成为你后续排障的宝贵资料。

1.3 环境准备：软硬件清单与版本匹配

TensorRT-LLM 对软硬件环境有严格要求，版本不匹配是导致各种诡异问题的首要原因。请务必按照以下清单核对你的环境。

硬件要求

  • GPU：NVIDIA 显卡，Compute Capability 8.0 及以上（Ampere 架构，如 A100/A30/A10/RTX 30系列；Hopper 架构 H100；Ada 架构 RTX 40系列）。注意：GTX 10/20系列（Pascal/Turing）不支持 TensorRT-LLM 的多数特性。
  • 显存：建议至少 16GB（用于 7B 模型 FP16 推理）。若进行 INT4 量化，8GB 显存可尝试 7B 模型。
  • 系统内存：至少 32GB，转换过程中需要加载原始权重。

软件版本（推荐组合）

操作系统：Ubuntu 22.04 LTS（或 Rocky Linux 8.9）
GPU驱动：≥ 535.104.05
CUDA：12.2（或 12.3）
cuDNN：8.9.5
TensorRT：9.2.0
TensorRT-LLM：0.7.0（或最新 release 分支）
Python：3.10
PyTorch：2.1.0（需与 CUDA 12.2 匹配）
HuggingFace Transformers：4.36.0
版本一致性警告：不要混用不同版本的 TensorRT-LLM 与 TensorRT。例如，TensorRT-LLM 0.7.0 依赖 TensorRT 9.2.0，如果你安装了 9.0.1，在构建引擎时会报 plugin version mismatch 错误。建议使用 NVIDIA 提供的 nvcr.io/nvidia/tensorrt-llm Docker 镜像，避免手动安装的依赖冲突。

环境验证三步走

安装完成后，不要急于转换模型，先执行以下快速验证：

# 1. 检查 GPU 驱动与 CUDA
nvidia-smi
# 期望输出：Driver Version ≥ 535，CUDA Version ≥ 12.2

# 2. 验证 TensorRT-LLM 是否可导入
python -c "import tensorrt_llm; print(tensorrt_llm.__version__)"

# 3. 运行官方自带的示例（需先下载一个小模型）
cd /path/to/TensorRT-LLM/examples/llama
python convert_checkpoint.py --model-dir meta-llama/Llama-2-7b-hf \
                             --output-dir ./tllm_checkpoint \
                             --dtype float16

如果上述命令均能成功执行，说明你的环境已就绪。若第二步报错，请检查 Python 路径是否指向了 TensorRT-LLM 的虚拟环境；若第三步报错，请先确认网络能访问 HuggingFace，或手动下载模型权重。

1.4 工具链全景：从权重到引擎的四个关键角色

在后续课程中，你会反复与以下工具打交道。这里先建立整体认知，后续章节会逐一深入。

阶段一：权重获取 阶段二：格式转换 阶段三：引擎构建 阶段四：运行时 HuggingFace 权重 config.json *.safetensors tokenizer.model convert_checkpoint.py --model-dir --output-dir --dtype float16 TRT-LLM Checkpoint *.safetensors config.json trtllm-build --checkpoint --engine_dir 加载权重 转换格式 读取 Engine *.engine 构建 TensorRT-LLM 运行时（Python/C++ Runtime） 加载 engine → 分配 KV cache → 执行推理 → 输出 token 关键参数：max_batch_size, max_input_len, max_seq_len, gpu_weights_percent 加载 辅助工具 • 模型下载：huggingface-cli / modelscope • 精度校准：calibrate.py（INT8/INT4 量化时使用） • 性能测试：perf.py • 日志分析：trtllm-inspect

上图展示了从 HuggingFace 权重到最终部署的完整链路。请注意：convert_checkpoint.py 只负责格式转换，不负责量化；量化发生在转换过程中（通过 --quantize 参数指定），而引擎构建（trtllm-build）则根据 checkpoint 中的配置生成优化后的 kernel 编排。

1.5 常见误区与复盘

误区一：跳过环境验证直接转换模型。很多学员在未验证 TensorRT-LLM 是否能正常导入的情况下，直接运行转换脚本，遇到 ModuleNotFoundError 或 CUDA error 后，误以为是模型问题，浪费大量时间排查。请务必先完成 1.3 节中的三步验证。
误区二：混淆“权重格式”与“引擎格式”。TensorRT-LLM 的 checkpoint 仍然是 safetensors 格式，但它与 HuggingFace 的原始权重在张量布局、参数命名上完全不同。不要试图用 torch.load 直接加载 TRT-LLM 的 checkpoint 进行推理。
复盘建议：在本节结束时，请确认你已能回答以下问题：① TensorRT-LLM 转换链路由哪几个核心步骤组成？② 每个步骤的输入输出是什么格式？③ 你的 GPU 架构是否满足要求？④ 如果转换时出现 unsupported op 错误，你第一反应应该检查什么？（提示：检查模型架构是否在官方支持列表中。）
← 上一章 📖 返回目录 下一章 →