# TensorRT-LLM 2026 前沿大模型部署手册

> 版本基准：TensorRT-LLM 1.4.0rc2（2026-10-28）　·　稳定版 1.2.1（2026-04-20）　·　文档核验：2026-11-06
> 参数与命令取自 nvidia.github.io/TensorRT-LLM 官方文档（含逐模型 Deployment Guide），模型规模取自各模型 `config.json`。

---

## 目录

- [00 导读](#00-导读)
- [01 2026 的部署格局](#01-2026-的部署格局)
- [02 显存预算与 KV 计算](#02-显存预算与-kv-计算)
- [03 架构与参数作用点](#03-架构与参数作用点)
- [04 核心参数详解](#04-核心参数详解)
- [05 并行策略选型](#05-并行策略选型)
- [06 逐模型实战配置](#06-逐模型实战配置)
- [07 调优方法论](#07-调优方法论)
- [08 生产化与排错](#08-生产化与排错)
- [09 附录](#09-附录)

---

## 00 导读

### TensorRT-LLM 的定位

2026 年 TensorRT-LLM 的产品形态已经和早期完全不同。**它不再是「先 build 引擎再 serve」的 AOT 流程**，而是转向了 **PyTorch backend + JIT 编译**：

- `trtllm-serve` 直接加载 HuggingFace 格式的 checkpoint，启动时即时编译内核
- 配置通过 YAML 文件传入（`--config config.yml`），而不是 `trtllm-build` 的一大串参数
- 老的 `trtllm-build` 工作流仍然存在，但新模型的 Deployment Guide 全部基于 `trtllm-serve`

这意味着**部署体验大幅简化**，但也带来一个新问题：**首次启动非常慢**（要编译内核、autotune、捕获 CUDA Graph），而且镜像版本与模型支持强绑定。

### 数据基准

| 组件 | 基线 | 说明 |
| :-- | :-- | :-- |
| TensorRT-LLM | 1.4.0rc2.post1 | 2026-10-28，最新 rc |
| 稳定版 | 1.2.1 | 2026-04-20 |
| Python | ≥ 3.10, < 4 | 官方 wheel 要求 |
| CUDA Driver | ≥ 575（Blackwell）/ ≥ 580（GB300） | 见各模型指南 |
| 容器 | `nvcr.io/nvidia/tensorrt-llm/release:<tag>` | 推荐直接用容器 |

> **版本策略**：NGC 上带 `rcN` 后缀的是每周从 main 发布、含最新模型支持的版本；不带后缀的是每月 QA 过的稳定版。**要跑新模型，用 rc 版**。

### 三个必须先建立的心智模型

**① 它是「内核最优」而非「易用最优」的引擎。**
TensorRT-LLM 的价值在于 NVIDIA 手写的融合内核（TRTLLM-GEN、XQA、DeepGEMM、MLA 专用 kernel）。这些内核在 Blackwell 上通常能比通用实现快 20%–50%，代价是**只支持验证过的模型与硬件组合**。

**② 并行配置散落在 YAML 里，不在命令行。**
`tensor_parallel_size` / `enable_attention_dp` / `moe_expert_parallel_size` 全部写在 YAML。命令行只保留 `--tp_size` 这类快捷参数，但**混用时以 YAML 为准**。

**③ `free_gpu_memory_fraction` 是显存闸门。**
它的含义是「模型加载后，剩余显存中拿出多少比例做 KV Cache」。注意是**剩余显存的比例**，不是总量的比例。这和 vLLM 的 `gpu_memory_utilization` 语义完全不同。

---

## 01 2026 的部署格局

### 变化一：模型支持以「验证矩阵」形式给出

TensorRT-LLM 不像 vLLM 那样追求「什么模型都能跑」，而是给出明确的验证列表。截至 2026-11，官方 Deployment Guide 覆盖：

| 模型 | 指南 | 验证硬件 |
| :-- | :-- | :-- |
| GLM-5 / 5.2 / 5.3 | ✅ | 8× B200，8× GB300 |
| Kimi-K3 | ✅ | GB300 NVL（DEP16 / TEP16 / TEP8） |
| Qwen3.5 / Qwen3.8 | ✅ | B200 / B300 / GB200 / GB300 |
| MiniMax-M3 | ✅ | Blackwell |
| gpt-oss | ✅ | Blackwell / Hopper |
| Nemotron-3 系列 | ✅ | Blackwell |
| Qwen3.8-Flash-Next | ✅ | Blackwell |

**没有出现在列表里的模型，不保证能跑**。这是选型时的第一条约束。

### 变化二：MoE 并行成为核心议题

TensorRT-LLM 把 MoE 并行拆成三层：

```
MoE 执行模式
├─ TP   每个专家的权重在所有 GPU 上切片，每卡看到所有 token
├─ EP   每个专家的完整权重在单卡，每卡只看到路由到本地专家的 token
└─ ETP  混合：每卡存一部分专家（EP），再对这些权重切片（TP）
```

并引入 **Wide-EP**：通过专家复制（expert replication）和 EPLB（Expert Parallelism Load Balancer）解决「热专家」问题——某些专家被路由到的 token 远多于其他专家，导致 EP rank 间负载严重不均。

### 变化三：多模态与混合注意力成为常态

2026 年的旗舰模型大量使用：
- **MLA + DSA**（GLM-5.3）：复用 DeepSeek V3.2 的 `DeepseekV32Attention`
- **KDA + 稀疏 MLA**（Kimi-K3）：93 层中大部分是线性注意力，每 4 层一次全 MLA
- **GDN + GQA**（Qwen3.5）：3 层门控 delta 网络 + 1 层 GQA 交替

这带来一个新概念：**混合模型的「状态池」**。Kimi-K3 的每个 KDA 层为每条序列保留常数大小的循环状态，这部分**不在分页 KV 池里**，需要单独预留显存。官方在 Kimi-K3 指南里把 `free_gpu_memory_fraction` 设为 **0.25** 就是为此。

### 2026 前沿模型一览

| 模型 | 总参 / 激活 | 上下文 | 注意力 | 精度 | TRT-LLM 最低版本 |
| :-- | :-- | --: | :-- | :-- | :-- |
| **GLM-5.3** | 743B / 39B | 1,048,576 | MLA + DSA | FP8 / NVFP4 / W4A8 | 1.3.0rc25 |
| **Kimi-K3** | 2.8T / 16 of 896 | 1,048,576 | KDA + 稀疏 MLA | MXFP4 | 源码构建 |
| **Qwen3.5-397B-A17B** | 397B / 17B | 262,144 | GDN + GQA | NVFP4 / BF16 | 1.4.0rc2 |
| **Qwen3.8-2.4T-A95B** | 2.4T / 95B | — | GDN + GQA | FP8 | 1.4.0rc2 |
| **MiniMax-M3** | 427B / 26B | 1,048,576 | MSA 块稀疏 | BF16 / MXFP8 / NVFP4 | Blackwell 镜像 |
| **gpt-oss-120b** | 117B / 5.1B | 131,072 | 滑窗 + 全注意力 | MXFP4 | 1.3.x |

---

## 02 显存预算与 KV 计算

### 显存划分：与 vLLM 的关键差异

```
┌──────────────────────────────────────────────────────────┐
│  Weights  │  Runtime / Workspace  │  KV Cache  │  Graph  │
└──────────────────────────────────────────────────────────┘
              └──── free_gpu_memory_fraction 作用于这段 ────┘
```

`free_gpu_memory_fraction` 的语义是：

```
KV_cache_bytes = (GPU_total - model_weights - runtime_overhead) × free_gpu_memory_fraction
```

**不是** `GPU_total × fraction`。理解错这个会差出一倍。

官方建议：

- 默认 **0.75**
- OOM 时降到 **0.6** 或 **0.7**
- 混合模型（含状态池）可能低到 **0.25**（如 Kimi-K3）

### KV Cache 计算

公式与 vLLM 相同，因为底层都是分页 KV：

#### MHA / GQA / MQA（统一公式）

三种架构共用同一个公式，差异只在 `n_kv_heads`：

```
KV_bytes_per_token = 2 × n_layers × n_kv_heads × head_dim × dtype_bytes
```

| 架构 | `n_kv_heads` | 相对 MHA |
| :-- | :-- | :-- |
| MHA | `= n_heads` | 1× |
| GQA | `= n_heads / g` | 1/g |
| MQA | `= 1` | 1/n_heads |

> GQA 不是「另一种算法」，而是把 KV head 数除以分组比 g。Llama-3-70B 是 64 q-heads / 8 kv-heads，KV 只有 MHA 的 1/8。

> **TP 时的例外**：TRT-LLM 官方明确说明，GQA / MQA / MLA 在 `num_heads < tensor_parallel_size` 时 KV-cache 会在每个 GPU 上**复制**，此时上面的公式要乘 TP 倍数。

#### MLA

```
KV_bytes_per_token = n_layers × (kv_lora_rank + qk_rope_head_dim) × dtype_bytes
```

#### 混合注意力（额外项）

Kimi-K3 的 KDA 层：

```
KDA_state_bytes = n_kda_layers × d_state × dtype_bytes × batch
                                          ↑ 每条序列一份，不随长度增长
```

Qwen3.5 的 GDN 层同理，由 `kv_cache_config.mamba_ssm_cache_dtype` 控制精度（可选 `auto` / `float16` / `bfloat16` / `float32`）。

> **`tokens_per_block` 的选择**：Kimi-K3 官方固定用 **64**。原因写在指南里：早期版本需要这个页大小来避免一个不支持 96 个 query head 的 MLA fallback 路径。

### 怎么确认显存够不够

TensorRT-LLM 启动后会在日志里打印 KV cache 的分配情况。查找关键字：

```
[TRT-LLM] KV cache size: ... tokens
[TRT-LLM] Max batch size: ...
```

如果启动时 OOM，按这个顺序调：

1. 降 `kv_cache_config.free_gpu_memory_fraction`（0.75 → 0.6 → 0.5）
2. 降 `--max_num_tokens`（8192 → 4096 → 3072）
3. 降 `--max_batch_size`（128 → 64 → 32）
4. 降 `cuda_graph_config.max_batch_size`
5. 最后才考虑降 `--max_seq_len`

> **内存碎片**：官方建议设 `PYTORCH_ALLOC_CONF=max_split_size_mb:8192` 缓解碎片导致的 OOM。

---

## 03 架构与参数作用点

### 三层结构

```
┌─────────────────────────────────────────────────────────┐
│  trtllm-serve（OpenAI 兼容 HTTP Server）                 │
│  · /v1/chat/completions  /v1/completions  /v1/responses │
│  · /health  /metrics  /version  /start_profile          │
│  · tool_parser / reasoning_parser                       │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│  LLM API（PyTorch backend）                              │
│  · 请求调度、KV 管理、CUDA Graph                         │
│  · TorchLlmArgs：YAML 里的所有配置                        │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│  Executor（MPI / Ray / 本地）                            │
│  · TP / PP / EP / Attention-DP                          │
│  · 每 rank 一个进程，各自持有分片权重与 KV                 │
└─────────────────────────────────────────────────────────┘
```

### 一次请求的路径

```
① HTTP 接入        trtllm-serve 的 FastAPI
                     ↓
② 输入处理         分词 → chat template（Jinja）
                     ↓  --tool_parser / --reasoning_parser
③ 调度             token 预算分配 → chunked prefill（若开启）
                     ↓  --max_num_tokens / enable_chunked_prefill
④ KV 分配          从分页池取 block
                     ↓  kv_cache_config.tokens_per_block
⑤ 前向             融合内核（TRTLLM-GEN / XQA / DeepGEMM）
                     ↓  moe_config.backend / attention backend
⑥ 输出             反分词 → 流式返回
                     ↓  stream_interval
```

### YAML 与命令行的分工

```
命令行（trtllm-serve 直接参数）
├─ --tp_size / --pp_size / --ep_size     并行规模
├─ --max_batch_size                      最大 batch
├─ --max_num_tokens                      单步 token 上限
├─ --host / --port
├─ --served_model_name
├─ --tool_parser / --reasoning_parser
└─ --config <yaml>                       其余全部

YAML（config.yml）
├─ cuda_graph_config
├─ kv_cache_config
├─ moe_config
├─ speculative_config
├─ enable_chunked_prefill
├─ enable_attention_dp
├─ moe_expert_parallel_size / moe_tensor_parallel_size
├─ cache_transceiver_config（PD 分离）
└─ stream_interval
```

> **优先级**：YAML 里的值会覆盖命令行的同名快捷参数。混用时要小心。例如 YAML 里写 `tensor_parallel_size: 16`，命令行再传 `--tp_size 8` 会报冲突。

---

## 04 核心参数详解

### 4.1 并行

| 参数（YAML） | 命令行快捷 | 含义 |
| :-- | :-- | :-- |
| `tensor_parallel_size` | `--tp_size` | TP 宽度。**MoE 模型下 `moe_tensor_parallel_size × moe_expert_parallel_size` 必须等于它** |
| `pipeline_parallel_size` | `--pp_size` | PP 宽度 |
| `moe_expert_parallel_size` | `--ep_size` | MoE 层的 EP 宽度 |
| `moe_tensor_parallel_size` | — | MoE 层的 TP 宽度（混合 ETP 时用） |
| `enable_attention_dp` | — | `true` 时注意力层走数据并行（权重复制、KV 分区） |
| `cp_config.cp_size` | — | 上下文并行宽度（长序列） |

> **ETP 的约束**：`moe_tensor_parallel_size × moe_expert_parallel_size == tensor_parallel_size`。例：TP8 可以配 `moe_tp=4, moe_ep=2`，或 `moe_tp=1, moe_ep=8`，或 `moe_tp=8, moe_ep=1`。

### 4.2 KV Cache

```yaml
kv_cache_config:
  enable_block_reuse: false          # 前缀复用（等价 vLLM 的 prefix caching）
  free_gpu_memory_fraction: 0.75     # 剩余显存的多少给 KV
  dtype: auto                        # KV 精度：auto / fp8 / ...
  tokens_per_block: 64               # 块大小
  mamba_ssm_cache_dtype: auto        # 混合模型的 SSM 状态精度
  mamba_state_config:
    periodic_snapshot_interval: 0    # KDA 状态的快照间隔（0 = 关闭）
```

| 字段 | 要点 |
| :-- | :-- |
| `enable_block_reuse` | 开启后，具有相同前缀的请求可复用 KV。**多轮对话/Agent 必开**。注意：多模态模型目前**不兼容** `kv_cache_reuse` |
| `free_gpu_memory_fraction` | 见 [02 章](#02-显存预算与-kv-计算) |
| `dtype` | `fp8` 可让 KV 减半，通常无损 |
| `tokens_per_block` | Kimi-K3 固定 64；GLM 系常用 32/64 |
| `mamba_ssm_cache_dtype` | Qwen3.5 的 GDN 状态精度。`bfloat16` 比 `float32` 省一半 |
| `periodic_snapshot_interval` | **混合模型开 block reuse 时必须设**（如 256），否则前缀命中无法恢复循环状态 |

> **混合模型的关键限制**：Kimi-K3 / Qwen3.5 这类含线性注意力的模型，**只有在快照边界上才暴露可复用的前缀**。设 `periodic_snapshot_interval: 0`（默认）时，`enable_block_reuse: true` 几乎不生效。

### 4.3 CUDA Graph

```yaml
cuda_graph_config:
  enable_padding: true      # 把 batch padding 到最近的捕获尺寸
  max_batch_size: 128       # 最大捕获 batch，应与 --max_batch_size 一致
```

- `enable_padding: true` 能显著提升性能，但会浪费一些计算
- `max_batch_size` 设得比 `--max_batch_size` 小，超出的 batch 会回退到 eager
- CUDA Graph 吃显存，与 `free_gpu_memory_fraction` 此消彼长

### 4.4 MoE 后端

```yaml
moe_config:
  backend: DEEPGEMM         # CUTLASS（默认）/ DEEPGEMM / TRTLLM / ...
  max_num_tokens: 33024     # MoE 层的 token 上限（可与全局不同）
  use_low_precision_moe_combine: true   # EP combine 用低精度载荷
```

**必须显式指定**：GLM-5 指南明确写了「默认 MoE backend 是 CUTLASS，对 GLM-5 你必须显式设置」。

| 模型 | 精度 | 硬件 | 必须的 backend |
| :-- | :-- | :-- | :-- |
| GLM-5 / 5.3 | FP8 | B200 / GB200 | `DEEPGEMM` |
| GLM-5 / 5.3 | NVFP4 | B200 / GB200 | `TRTLLM`（DEEPGEMM 不支持 NVFP4） |
| Kimi-K3 | MXFP4 | GB300 | 自动（`moe-backend auto`） |

### 4.5 投机解码

```yaml
speculative_config:
  decoding_type: MTP                    # MTP / EAGLE / ...
  num_nextn_predict_layers: 1           # MTP 层数
  max_draft_len: 3                      # 草稿长度（MTP3 场景设 3）
```

| 模型 | 支持的方法 | 备注 |
| :-- | :-- | :-- |
| GLM-5 / 5.3 | MTP | `num_nextn_predict_layers` 只能为 1 |
| Qwen3.5 / 3.8 | MTP | 内置 1 个 recurrent MTP 模块 |
| Kimi-K3 | Suffix automaton | 聚合与分离模式均支持 |
| DeepSeek 系 | MTP | TRT-LLM 有专门的 MTP 优化（relaxed acceptance） |

> **NVFP4 + MTP 目前不兼容**（GLM-5 指南明确写了）。要用 MTP 就选 FP8。

### 4.6 PD 分离

```yaml
cache_transceiver_config:
  backend: NIXL
```

所有 context / generation worker 必须使用**相同的** `cache_transceiver_config`。context worker 额外设 `disable_overlap_scheduler: true`。

```yaml
# disagg_config.yaml（orchestrator）
hostname: localhost
port: 8000
context_servers:
  num_instances: 1
  urls:
    - "localhost:8001"
generation_servers:
  num_instances: 1
  urls:
    - "localhost:8002"
```

```bash
trtllm-serve disaggregated -c disagg_config.yaml
```

### 4.7 解析器

| 参数 | 说明 |
| :-- | :-- |
| `--tool_parser` | `qwen3_coder`、`glm47`、`kimi_k3`、`deepseek_v3` 等。`auto` 会按模型类型选 |
| `--reasoning_parser` | `qwen3_5`、`glm45`、`deepseek_r1`、`nemotron-v3` 等 |

> **GLM-5.3 的推理控制已变**：绑定了 `enable_thinking` 的客户端需要改造。5.3 无法关闭思考，改用 `reasoning_effort`（`low`/`high`/`max`，默认 `max`），另有 `clear_thinking` 控制多轮是否保留历史推理。

---

## 05 并行策略选型

<!-- engine-topologies:start -->
### 本引擎的推理拓扑与 KV 存放

> 全局 tensor_parallel_size 与 MoE 内的 moe_tensor_parallel_size / moe_expert_parallel_size 不同，后两者乘积等于前者。enable_attention_dp 改变注意力布局；ETP、EPLB 副本不包含在下列纯 TP/EP 示例内。

#### TensorRT-LLM · A · Attention TP4 + routed TP4

配置要点：`tensor_parallel_size:4; moe_tp:4; moe_ep:1; attention_dp:false`（机制示例，须满足模型与硬件约束）。

![TensorRT-LLM · A · Attention TP4 + routed TP4](assets/topologies/tensorrt-llm/topology-1.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

#### TensorRT-LLM · B · Attention TP4 + routed EP4

配置要点：`tensor_parallel_size:4; moe_tp:1; moe_ep:4; attention_dp:false`（机制示例，须满足模型与硬件约束）。

![TensorRT-LLM · B · Attention TP4 + routed EP4](assets/topologies/tensorrt-llm/topology-2.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

#### TensorRT-LLM · C · attention-DP4 + routed TP4

配置要点：`tensor_parallel_size:4; moe_tp:4; moe_ep:1; attention_dp:true`（机制示例，须满足模型与硬件约束）。

![TensorRT-LLM · C · attention-DP4 + routed TP4](assets/topologies/tensorrt-llm/topology-3.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

#### TensorRT-LLM · D · attention-DP4 + routed EP4

配置要点：`tensor_parallel_size:4; moe_tp:1; moe_ep:4; attention_dp:true`（机制示例，须满足模型与硬件约束）。

![TensorRT-LLM · D · attention-DP4 + routed EP4](assets/topologies/tensorrt-llm/topology-4.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

官方依据：[TensorRT-LLM](https://nvidia.github.io/TensorRT-LLM/features/parallel-strategy.html)。
<!-- engine-topologies:end -->


### 六种并行

```
TP    张量并行：切权重，每层 all-reduce
PP    流水并行：按层切，stage 间传激活
DP    数据并行：复制模型，各跑各的请求
EP    专家并行：专家分散，all-to-all
CP    上下文并行：长序列切分
Wide-EP  宽专家并行：EP + 专家复制 + EPLB 负载均衡
```

### 注意力层与 MoE 层要分开配置

TensorRT-LLM 的一个关键设计：**注意力层和 FFN/MoE 层的并行方式可以不同**。

```yaml
# 注意力走 DP（KV 分区），MoE 走 EP
tensor_parallel_size: 16
enable_attention_dp: true
moe_expert_parallel_size: 16
```

这正是 Kimi-K3 的 DEP16 配置：注意力数据并行到 16 个 rank，896 个专家分片到 16 个 EP rank。

### 三种 MoE 执行模式对比

| 模式 | 每卡持有 | 每卡看到 | 通信 | 适合 |
| :-- | :-- | :-- | :-- | :-- |
| **TP** | 每个专家的切片 | 所有 token | all-reduce | 小 EP、低延迟 |
| **EP** | 部分专家的完整权重 | 只看到路由来的 token | all-to-all（少量） | 大规模、高吞吐 |
| **ETP** | 部分专家的切片 | 部分 token | all-to-all + all-reduce | 折中 |

### Wide-EP 解决什么问题

大规模 MoE 有两个固有问题：

1. **负载不均**：「热专家」接收的 token 远多于冷专家
2. **通信开销**：EP 规模越大，all-to-all 越贵

Wide-EP 的解法：

- **专家槽位与专家解耦**：同一专家的多个副本可以放在不同 GPU
- **动态放置**：按负载模式调整专家位置
- **EPLB**：离线预计算 或 在线动态调整

配置示例（Qwen3.8 高吞吐）：

```yaml
# qwen3.8-ep32-static544.yaml
# 544 个全局槽位，重复的 expert id 表示热专家的副本
# layer_updates_per_iter: 0 保持静态
```

> 官方提醒：这个 544 槽位的放置方案**只对 Qwen3.8-2.4T-A95B + EP32 + 特定 MTP 模式 + 特定流量分布**有效。任何输入变化都要重新生成。

### 选型决策

```
模型在官方验证列表里？
├─ 否 → 换 vLLM / SGLang，不要硬上
└─ 是 → 单机能装下？
        ├─ 能 → 需要最高吞吐？
        │       ├─ 是 → DP（attention）+ EP，大 batch
        │       └─ 否 → TP，小 batch，低延迟
        └─ 不能 → 多节点
                ├─ 跨机 NVLink（GB200/GB300 NVL）→ TP + EP
                └─ 普通 IB → TP（单机）+ PP（跨机）
```

### PD 分离的拓扑

官方 Qwen3.5 GB300 示例：

```
GB300 NVL72，4 GPU / tray
├─ 1P1D：1 个 prefill GPU + 2 个 decode GPU（3 卡）
├─ 每 rank 预留 128 GiB host KV cache
├─ 整节点 4 rank 时预留 512 GiB host 内存
└─ 需要 etcd + NATS（Dynamo 编排）
```

> **主机内存是隐藏约束**：GB300 每 4-GPU 节点 840 GiB 主机内存，4 rank 全占时 512 GiB 给 KV cache，剩下 328 GiB 要装权重加载、staging、OS。扩 worker 前先算这笔账。

---

## 06 逐模型实战配置

### 6.1 通用起手式

```bash
# 1) 拉镜像
docker run --rm -it \
  --ipc=host --gpus all \
  -p 8000:8000 \
  -v $HOST_MODELS_DIR:/models \
  --name tensorrt_llm \
  nvcr.io/nvidia/tensorrt-llm/release:1.4.0rc2 \
  /bin/bash

# 2) 容器内启动
trtllm-serve /models/<model> \
  --host 0.0.0.0 --port 8000 \
  --max_batch_size 128 \
  --max_num_tokens 8192 \
  --tp_size 8 \
  --config /tmp/config.yml
```

### 6.2 GLM-5 / 5.2 / 5.3

**架构**：复用 DeepSeek V3.2 的 `DeepseekV32Attention`，MLA + DSA，DSA 参数从 config.json 自动读取。

**Checkpoint 命名注意**：

- GLM-5.3：基础仓库 `zai-org/GLM-5.3` 是 **FP8**，BF16 在 `-BF16` 仓库
- GLM-5 / 5.2：基础仓库是 **BF16**，FP8 在 `-FP8` 仓库

**这个命名规则是反的**，容易搞错。判断方法：看 checkpoint 的 `quantization_config`。

#### B200 FP8 配置

```yaml
# /tmp/config.yml
cuda_graph_config:
  enable_padding: true
  max_batch_size: 128
enable_attention_dp: false
enable_chunked_prefill: true
kv_cache_config:
  enable_block_reuse: false
  free_gpu_memory_fraction: 0.75
dtype: fp8
stream_interval: 10
moe_config:
  backend: DEEPGEMM
```

```bash
trtllm-serve /models/GLM-5.3 \
  --served_model_name zai-org/GLM-5.3 \
  --host 0.0.0.0 --port 8000 \
  --max_batch_size 128 \
  --max_num_tokens 8192 \
  --tp_size 8 \
  --ep_size 8 \
  --pp_size 1 \
  --config /tmp/config.yml
```

#### B200 FP8 + MTP

```yaml
cuda_graph_config:
  enable_padding: true
  max_batch_size: 128
enable_attention_dp: false
enable_chunked_prefill: true
kv_cache_config:
  enable_block_reuse: false
  free_gpu_memory_fraction: 0.75
dtype: auto
speculative_config:
  decoding_type: MTP
  num_nextn_predict_layers: 1
stream_interval: 10
moe_config:
  backend: DEEPGEMM
```

#### B200 NVFP4

只需改两处：checkpoint 换成 NVFP4，`moe_config.backend` 改成 `TRTLLM`。

```yaml
moe_config:
  backend: TRTLLM
```

> MTP 与 NVFP4 **目前不兼容**。

#### 验证

```bash
curl -s -o /dev/null -w "Status: %{http_code}\n" "http://localhost:8000/health"

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"zai-org/GLM-5.3","prompt":"What is the capital of France?","max_tokens":16,"temperature":0}'
```

### 6.3 Kimi-K3

**架构**：93 层解码器，大部分是 KDA（线性注意力，常数状态），每 4 层一次全 MLA。896 专家 top-16。路由专家权重 MXFP4（group size 32），其余 BF16。

**必须从源码构建**：

```bash
python3 scripts/build_wheel.py --cuda_architectures 103-real --skip_building_wheel --yes
.venv-3.12/bin/python -m pip install -e .
.venv-3.12/bin/python -m pip install fla-core einops
```

> `--cuda_architectures`：GB300 用 `103-real`，B200 用 `100-real`。用 103 构建的也能在 B200 跑，但会缺少 `sm100a` 专用 batched-GEMM 内核。

**三种部署形态**：

| 形态 | 注意力布局 | 每 rank 权重 | 需要 |
| :-- | :-- | --: | :-- |
| **DEP16**（高吞吐） | attention-DP（复制） | 210 GB | GB300 级显存 |
| **TEP8** | attention-TP, EP8 | 213 GB | GB300 级显存 |
| **TEP16**（低延迟） | attention-TP, EP16 | 115 GB | GB200（SM100） |

> TEP8 装不下的原因写在官方文档里：8 路专家分片本身就要 181 GB/rank，加上非专家权重就爆了。

#### DEP16 配置

```yaml
# kimi-k3-config.yml
tensor_parallel_size: 16
enable_attention_dp: true
moe_expert_parallel_size: 16
max_batch_size: 32
max_num_tokens: 8192
max_seq_len: 8192
trust_remote_code: true
disable_overlap_scheduler: false
enable_chunked_prefill: true
cuda_graph_config:
  enable_padding: true
  max_batch_size: 32
moe_config:
  max_num_tokens: 33024
  use_low_precision_moe_combine: true
kv_cache_config:
  enable_block_reuse: false
  free_gpu_memory_fraction: 0.25
  tokens_per_block: 64
```

**为什么 `free_gpu_memory_fraction` 只有 0.25**：每个 KDA 层为每条请求保留循环状态，这部分不在分页 KV 池里。留 0.25 是给运行时和状态池腾空间。

#### 多节点启动（4 节点 × 4 GPU = 16 rank）

```bash
MODEL=/path/to/kimi-k3-checkpoint
REPO=/path/to/TensorRT-LLM
EXTRA_LLM_API_FILE=/path/to/kimi-k3-config.yml

srun -N 4 \
  --ntasks 16 --ntasks-per-node 4 \
  --mpi=pmix --gpus-per-node=4 \
  --container-image=/path/to/tensorrt-llm-container.sqsh \
  --container-mount-home \
  --container-mounts=${REPO}:${REPO},${MODEL}:${MODEL},${EXTRA_LLM_API_FILE}:${EXTRA_LLM_API_FILE}:ro \
  bash -c "
    ulimit -n 65536
    # Node-local caches: shared NFS races during autotune JIT
    export TRITON_CACHE_DIR=/tmp/triton-cache-rank\${SLURM_PROCID:-0}
    export FLASHINFER_WORKSPACE_BASE=/tmp/flashinfer-rank\${SLURM_PROCID:-0}
    mkdir -p \"\$TRITON_CACHE_DIR\" \"\$FLASHINFER_WORKSPACE_BASE\"
    export PATH=\"${REPO}/.venv-3.12/bin:\$PATH\"
    exec ${REPO}/tensorrt_llm/llmapi/trtllm-llmapi-launch \
      trtllm-serve ${MODEL} \
        --host 0.0.0.0 --port 8000 \
        --config ${EXTRA_LLM_API_FILE}
  "
```

> `TRITON_CACHE_DIR` 和 `FLASHINFER_WORKSPACE_BASE` 必须指向**节点本地磁盘**。放在共享 NFS 上，多 rank 并发 autotune 会因 stale file handle 崩溃。这是官方文档里明确写出的坑。

**混合模型开 block reuse**：

```yaml
kv_cache_config:
  enable_block_reuse: true
  mamba_state_config:
    periodic_snapshot_interval: 256   # 每 256 token 快照一次 KDA 状态
```

### 6.4 Qwen3.5 / Qwen3.8

**架构**：3 层 GDN（门控 delta 网络）+ 1 层 GQA 交替，512 路由专家 top-10。

| 属性 | Qwen3.8-2.4T-A95B | Qwen3.5-397B-A17B |
| :-- | :-- | :-- |
| 解码层数 | 92 | 60 |
| Hidden size | 8192 | 4096 |
| GDN / GQA 层 | 69 / 23 | 45 / 15 |
| 路由专家 / 激活 | 512 / 10 | 512 / 10 |
| 内置 MTP | 1 个 recurrent 模块 | 1 个 recurrent 模块 |
| 推荐精度 | Block-scaled FP8 | NVFP4 + FP8 KV |
| 模态 | 纯文本 | 文本 + 图像 + 视频 |

> **共享实现 ≠ 配置可互换**。官方明确警告：Qwen3.8 更大、用 FP8、纯文本；Qwen3.5 NVFP4 是多模态 wrapper。并行、量化后端、缓存大小、专家放置都必须按具体 checkpoint 选。

#### 硬件需求

| Checkpoint | B200 | B300 | GB200 | GB300 |
| :-- | :-- | :-- | :-- | :-- |
| Qwen3.8-2.4T FP8 | 16 卡 | 16 卡 | 16 卡 | 16 卡 |
| Qwen3.5-397B NVFP4 | 4 卡 | 4 卡 | 4 卡 | 4 卡 |

#### 官方配置模板

```bash
TRTLLM_DIR=/app/tensorrt_llm
EXTRA_LLM_API_FILE=${TRTLLM_DIR}/examples/configs/curated/qwen3.5.yaml

trtllm-serve <model_path> \
  --host 0.0.0.0 --port 8000 \
  --reasoning_parser qwen3_5 \
  --tool_parser qwen3 \
  --config ${EXTRA_LLM_API_FILE}
```

可用配置：

| 模型 | 档位 | 配置文件 |
| :-- | :-- | :-- |
| Qwen3.8 MoE FP8 | 低延迟 | `qwen3.8-low-latency.yaml` |
| Qwen3.8 MoE FP8 | 低延迟 + MTP3 | `qwen3.8-low-latency-mtp3.yaml` |
| Qwen3.8 MoE FP8 | 高吞吐 | `qwen3.8-high-throughput.yaml` |
| Qwen3.8 MoE FP8 | 高吞吐 + MTP3 | `qwen3.8-high-throughput-mtp3.yaml` |
| Qwen3.5-397B NVFP4 | 通用 | `qwen3.5.yaml` |

**官方性能参考**（GB300，8192 输入 / 1024 输出）：

| 目标 | 投机 | 拓扑 | 并发 | 结果 |
| :-- | :-- | :-- | --: | :-- |
| 低延迟 | 关闭 | TP16/EP1 | 1 | 133.5 tok/s/user（7.49 ms TPOT） |
| 低延迟 | MTP3 | TP16/EP1 | 1 | 383.1 tok/s/user（2.61 ms TPOT） |
| 高吞吐 | 关闭 | Attn-DP32/EP32 + Static544 | 3264 | 4059 tok/s/GPU |
| 高吞吐 | MTP3 | Attn-DP32/EP32 + Static544 | 2304 | 4118 tok/s/GPU |

> MTP3 的性能数据基于**受控的接受长度 2.3**，不是自然接受率。

### 6.5 MiniMax-M3

427B / 26B，MSA 块稀疏注意力，原生多模态。

```yaml
# config.yml
cuda_graph_config:
  enable_padding: true
  max_batch_size: 64
enable_chunked_prefill: true
kv_cache_config:
  free_gpu_memory_fraction: 0.7
moe_config:
  backend: TRTLLM
```

```bash
trtllm-serve MiniMaxAI/MiniMax-M3 \
  --tp_size 8 --ep_size 8 \
  --max_batch_size 64 \
  --max_num_tokens 8192 \
  --reasoning_parser minimax_m3 \
  --tool_parser minimax_m3 \
  --config /tmp/config.yml
```

### 6.6 gpt-oss-120b

最小可跑单位，适合验证环境。

```yaml
# config.yml
cuda_graph_config:
  enable_padding: true
  max_batch_size: 128
kv_cache_config:
  free_gpu_memory_fraction: 0.8
moe_config:
  backend: TRTLLM      # Blackwell 上 MXFP4 走 TRTLLM
```

```bash
trtllm-serve openai/gpt-oss-120b \
  --tp_size 1 \
  --max_batch_size 128 \
  --max_num_tokens 8192 \
  --tool_parser openai \
  --reasoning_parser openai \
  --config /tmp/config.yml
```

### 6.7 配置速查

| 模型 | TP | EP | Attn-DP | MoE backend | 特殊 |
| :-- | --: | --: | :-- | :-- | :-- |
| GLM-5.3 FP8 | 8 | 8 | false | `DEEPGEMM` | MTP 可用 |
| GLM-5.3 NVFP4 | 8 | 8 | false | `TRTLLM` | MTP 不可用 |
| Kimi-K3 DEP16 | 16 | 16 | **true** | auto | `free_gpu_memory_fraction: 0.25` |
| Kimi-K3 TEP16 | 16 | 16 | false | auto | 低延迟 |
| Qwen3.8 FP8 | 16 | 1 | false | — | 低延迟档 |
| Qwen3.8 FP8 | 32 | 32 | **true** | — | 高吞吐 + Static544 |
| Qwen3.5 NVFP4 | 4 | — | — | — | `qwen3.5.yaml` |

---

## 07 调优方法论

### 先定义指标

| 指标 | 定义 |
| :-- | :-- |
| **TTFT** | time to first token |
| **TPOT** | time per output token |
| **ITL** | inter-token latency |
| **E2EL** | end-to-end latency |
| **tok/s/GPU** | 每 GPU 总吞吐（输入+输出） |
| **tok/s/user** | 单用户输出吞吐 = 1000 / TPOT(ms) |

### 官方压测脚本

```bash
cat << 'EOF' > bench.sh
concurrency_list="32 64 128 256 512 1024 2048 4096"
multi_round=5
isl=1024
osl=1024
result_dir=/tmp/glm5_output

for concurrency in ${concurrency_list}; do
  num_prompts=$((concurrency * multi_round))
  python -m tensorrt_llm.serve.scripts.benchmark_serving \
    --model zai-org/GLM-5.3 \
    --backend openai \
    --dataset-name random \
    --random-input-len ${isl} \
    --random-output-len ${osl} \
    --random-prefix-len 0 \
    --random-ids \
    --num-prompts ${num_prompts} \
    --max-concurrency ${concurrency} \
    --ignore-eos \
    --tokenize-on-client \
    --percentile-metrics "ttft,tpot,itl,e2el" \
    --save-result \
    --result-dir "${result_dir}" \
    --result-filename "concurrency_${concurrency}.json"
done
EOF
chmod +x bench.sh && ./bench.sh
```

> 全套跑完**非常耗时**。建议先跑 2–3 个并发点定位拐点。

### 两个优化目标

TensorRT-LLM 的配置明显分成两族，官方在 Qwen3.8 指南里给出了对照：

**低延迟族**

```yaml
max_batch_size: 16 or 32
max_num_tokens: 3072
cuda_graph_config:
  max_batch_size: 16 or 32
kv_cache_config:
  free_gpu_memory_fraction: 0.6
speculative_config:
  decoding_type: MTP
  max_draft_len: 3
```

**高吞吐族**

```yaml
max_batch_size: 512 or 1024
max_num_tokens: 8192
cuda_graph_config:
  enable_padding: true
  max_batch_size: <same as above>
kv_cache_config:
  free_gpu_memory_fraction: 0.85
enable_attention_dp: true
moe_expert_parallel_size: <large>
```

### 按场景的配方

| 场景 | 关键配置 | 理由 |
| :-- | :-- | :-- |
| **低延迟对话** | 小 `max_batch_size` + MTP3 + `enable_padding: true` | MTP 在 batch=1 时收益最大 |
| **高吞吐批处理** | 大 `max_batch_size` + Attn-DP + EP + 大 `free_gpu_memory_fraction` | 摊薄权重读取 |
| **长上下文** | `enable_chunked_prefill: true` + 大 `max_seq_len` + CP | 分块避免单步爆炸 |
| **多轮 Agent** | `enable_block_reuse: true` + `periodic_snapshot_interval` | 前缀复用 |
| **PD 分离** | `cache_transceiver_config` + `disable_overlap_scheduler` on prefill | 隔离阶段 |

### 启动时间

TensorRT-LLM 的冷启动是三家里最慢的（要 JIT 编译 + autotune + 捕获 graph）。可以做的：

| 手段 | 效果 |
| :-- | :-- |
| 复用 `TRITON_CACHE_DIR` | 避免重复 autotune |
| 复用 `FLASHINFER_WORKSPACE_BASE` | 避免重复下载 cubin |
| 降低 `cuda_graph_config.max_batch_size` | 减少捕获数量 |
| 预热 | 压测前先发几条请求触发捕获 |

> 官方提示：**第一次查询可能因初始化和编译而明显变慢**。

---

## 08 生产化与排错

### 8.1 容器

```bash
docker run --rm -it \
  --ipc=host \
  --gpus all \
  -p 8000:8000 \
  -v "$HOST_MODELS_DIR":/models \
  --name tensorrt_llm \
  nvcr.io/nvidia/tensorrt-llm/release:1.4.0rc2 \
  /bin/bash
```

镜像 tag 选择：

| 需求 | 用哪个 |
| :-- | :-- |
| 稳定生产 | 无 `rcN` 后缀的月度版 |
| 最新模型支持 | 带 `rcN` 的周更版 |
| 特定模型 day-0 | 官方指南指定的 tag（如 `1.3.0a0.dev202610151219`） |

### 8.2 端点

| 端点 | 用途 |
| :-- | :-- |
| `/v1/models` | 列出模型 |
| `/v1/completions` | 文本补全 |
| `/v1/chat/completions` | 对话 |
| `/v1/responses` | Responses API |
| `/v1/embeddings` | 向量（`trtllm-serve embeddings` 子命令） |
| `/health` | 健康检查 |
| `/metrics` | Prometheus 指标 |
| `/version` | 版本 |
| `/start_profile` / `/stop_profile` | 性能剖析（prototype） |

```bash
curl -s -o /dev/null -w "Status: %{http_code}\n" "http://localhost:8000/health"

curl -s http://localhost:8000/metrics | grep -E 'trtllm_|gpu_mem|inflight'
```

关键指标：GPU 显存使用、inflight batching 详情、每 iteration 的统计。

### 8.3 故障排查

| 现象 | 原因 | 处理 |
| :-- | :-- | :-- |
| CUDA OOM | KV 或 graph 吃太多 | 降 `free_gpu_memory_fraction`（0.75→0.6）；降 `max_num_tokens`（8192→3072）；降 `max_batch_size` |
| 内存碎片导致 OOM | PyTorch allocator 碎片 | `PYTORCH_ALLOC_CONF=max_split_size_mb:8192` |
| 启动就报 MoE backend 错误 | 没显式指定 | GLM-5 必设 `moe_config.backend` |
| NVFP4 跑不起来 | 用了 DEEPGEMM | 改 `TRTLLM` |
| MTP 不生效 | 用了 NVFP4 checkpoint | 换 FP8 |
| Kimi-K3 多 rank 崩溃 | Triton/FlashInfer 缓存在共享盘 | `TRITON_CACHE_DIR` 指向本地 |
| 前缀缓存不生效（混合模型） | 未设快照间隔 | `periodic_snapshot_interval: 256` |
| 首查询特别慢 | JIT 编译 + graph 捕获 | 正常现象，先预热 |
| 多模态 KV 复用报错 | `kv_cache_reuse` 与多模态不兼容 | `enable_block_reuse: false` |
| Checkpoint 加载失败 | 拿错了 FP8/BF16 仓库 | 查 `config.json` 的 `quantization_config` |

### 8.4 性能剖析

```bash
curl -X POST http://localhost:8000/start_profile
# 跑负载
curl -X POST http://localhost:8000/stop_profile
```

生成的 trace 可导入 Chrome Tracing 或 Nsight Systems 分析。

---

## 09 附录

### A. 参数速查

| 参数 | 位置 | 一句话 |
| :-- | :-- | :-- |
| `tensor_parallel_size` | YAML / `--tp_size` | TP 宽度 |
| `pipeline_parallel_size` | YAML / `--pp_size` | PP 宽度 |
| `moe_expert_parallel_size` | YAML / `--ep_size` | MoE 的 EP 宽度 |
| `moe_tensor_parallel_size` | YAML | MoE 的 TP 宽度（ETP 时用） |
| `enable_attention_dp` | YAML | 注意力走 DP |
| `max_batch_size` | CLI | 最大 batch |
| `max_num_tokens` | CLI | 单步 token 上限 |
| `max_seq_len` | YAML | 最大序列长度 |
| `kv_cache_config.free_gpu_memory_fraction` | YAML | 剩余显存的多少给 KV |
| `kv_cache_config.enable_block_reuse` | YAML | 前缀复用 |
| `kv_cache_config.tokens_per_block` | YAML | KV 块大小 |
| `kv_cache_config.mamba_ssm_cache_dtype` | YAML | 混合模型 SSM 状态精度 |
| `cuda_graph_config.enable_padding` | YAML | batch padding 到捕获尺寸 |
| `cuda_graph_config.max_batch_size` | YAML | 最大捕获 batch |
| `moe_config.backend` | YAML | MoE 内核后端 |
| `moe_config.use_low_precision_moe_combine` | YAML | EP combine 低精度 |
| `speculative_config.decoding_type` | YAML | `MTP` 等 |
| `speculative_config.max_draft_len` | YAML | 草稿长度 |
| `enable_chunked_prefill` | YAML | 分块 prefill |
| `disable_overlap_scheduler` | YAML | 关闭调度重叠（PD prefill 用） |
| `cache_transceiver_config.backend` | YAML | PD 传输后端（`NIXL`） |
| `stream_interval` | YAML | 流式输出间隔 |
| `--tool_parser` | CLI | 工具调用解析器 |
| `--reasoning_parser` | CLI | 推理内容解析器 |

### B. 环境变量

| 变量 | 作用 |
| :-- | :-- |
| `TRITON_CACHE_DIR` | Triton 编译缓存（多 rank 时必须本地） |
| `FLASHINFER_WORKSPACE_BASE` | FlashInfer 缓存（同上） |
| `PYTORCH_ALLOC_CONF` | 内存分配器调优（`max_split_size_mb:8192`） |
| `TLLM_SPEC_DECODE_FORCE_NUM_ACCEPTED_TOKENS` | 强制接受 token 数（仅基准测试） |
| `TRTLLM_ENABLE_RENDER_ENDPOINTS` | 启用 `/render` 端点 |
| `MIMALLOC_PURGE_DELAY` | mimalloc 回收延迟 |

### C. 来源

| 来源 | 用途 |
| :-- | :-- |
| nvidia.github.io/TensorRT-LLM/latest/commands/trtllm-serve | serve 命令与端点 |
| nvidia.github.io/TensorRT-LLM/latest/features/parallel-strategy | 并行策略与 ETP 约束 |
| nvidia.github.io/TensorRT-LLM/latest/deployment-guide/* | 逐模型验证配置 |
| nvidia.github.io/TensorRT-LLM/latest/commands/trtllm-bench | 压测 |
| pypi.org/project/tensorrt-llm | 版本核验 |
| NGC catalog | 镜像 tag |

---

*本文档基于 2026-11-06 可获取的公开资料整理。TensorRT-LLM 的模型支持与镜像版本强绑定，部署前请以对应 Deployment Guide 的 Prerequisites 章节为准。*