4、第一个编译任务：使用 trtllm-build 编译 LLaMA 模型，理解输入输出路径

好，咱们正式开始动手了。

前面铺垫了那么多理论，我知道你肯定手痒了。这一章，我们就来跑第一个真正的编译任务——用 trtllm-build 把 LLaMA 模型编译成 TensorRT-LLM 引擎。

说白了，这一步就是把 HuggingFace 上那些 PyTorch 权重，变成能在 GPU 上高效推理的二进制文件。我刚开始接触这个流程时，觉得不就是个转换吗？结果第一次就跑飞了，原因就是路径没搞对。嗯，这里要注意，输入输出路径是新手最容易踩的坑。

4.1 整体流程：一张图看懂

先给你看个我画的流程图。别嫌简单，这步搞清楚了，后面所有模型都是这个套路。

看到了吗？整个流程就三步：输入 → 编译 → 输出。但就是这简单的三步，我见过太多人把路径写错了。

4.2 准备工作：先拿到 LLaMA 模型

在跑编译之前，你得先有一个 HuggingFace 格式的 LLaMA 模型。我个人习惯直接从 HuggingFace Hub 下载，或者用你之前微调好的 checkpoint。

假设你已经有了模型，目录结构大概是这样的：

llama-7b-hf/
├── config.json
├── tokenizer.model
├── tokenizer_config.json
├── pytorch_model-00001-of-00002.bin
├── pytorch_model-00002-of-00002.bin
├── pytorch_model.bin.index.json
└── generation_config.json

嗯，这里要注意，config.json 是必须的，tokenizer 文件也是。如果缺少这些，编译会直接报错。

4.3 第一个编译命令

好，模型准备好了。我们打开终端，输入以下命令：

# 最简单的编译命令
trtllm-build \
  --model_dir ./llama-7b-hf \
  --output_dir ./engines/llama-7b \
  --max_input_len 2048 \
  --max_output_len 512

就这么简单？对，就这么简单。但别高兴太早，我第一次跑的时候，--model_dir 写成了相对路径，结果当前目录不对，报了个 FileNotFoundError。后来我学乖了，一律用绝对路径。

4.4 理解输入输出路径

咱们来拆解一下这两个路径：

参数	含义	常见错误
--model_dir	输入路径，指向 HuggingFace 模型文件夹	路径末尾多加了 / 或少写了文件夹名
--output_dir	输出路径，编译后的引擎和配置文件存放位置	忘记创建目录，或者路径中有中文/空格

编译完成后，看看 --output_dir 里多了什么：

engines/llama-7b/
├── config.pbtxt          # 引擎配置（文本格式）
├── llama_float16_tp1_rank0.engine  # 真正的引擎文件
└── model.cache           # 缓存文件（加速下次编译）

那个 .engine 文件就是我们的目标。它包含了所有优化后的网络结构和权重，可以直接被 TensorRT-LLM 的 runtime 加载。

4.5 编译过程中的日志解读

编译时终端会输出一堆日志。别慌，我教你抓重点：

• [INFO] Building engine... —— 开始编译了，去喝杯咖啡吧
• [INFO] Engine built successfully! —— 编译成功，看到这个就稳了
• [WARNING] ... —— 警告可以忽略，但最好看一眼
• [ERROR] ... —— 出错了，看错误信息定位问题

我记得有一次编译 LLaMA-13B，日志卡在 Building engine... 长达 20 分钟。我当时以为死机了，差点强制退出。后来才知道，大模型编译本来就慢，尤其是第一次编译没有缓存的时候。

4.6 验证编译结果

编译完了怎么知道对不对？我一般用两个方法：

1. 检查文件大小： .engine 文件至少几百 MB，如果只有几 KB，那肯定有问题。
2. 用 trtllm-run 简单跑一下： 加载引擎，输入一句话，看能不能正常输出。

验证命令示例：

# 快速验证引擎是否可用
trtllm-run \
  --engine_dir ./engines/llama-7b \
  --input_text "今天天气怎么样？"

如果能看到输出，恭喜你，第一个编译任务完成了！

好了，这一章就到这。你动手试试，有问题随时翻回来对照。下一章我们会深入 trtllm-build 的更多参数，看看怎么控制精度、批量大小这些关键配置。

---