Inference Stack · TensorRT-LLM

TensorRT-LLM 部署前沿大模型

本册覆盖 TensorRT-LLM 1.4.0rc2 的完整部署链路：参数语义、显存与 KV 计算、并行拓扑、逐模型可复制命令、调优方法与故障排查。

引擎TensorRT-LLM 1.4.0rc2
核验2026-11-06
来源官方文档与仓库

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-LLM1.4.0rc2.post12026-10-28，最新 rc
稳定版1.2.12026-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 语义完全不同。

012026 的部署格局

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

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 并行拆成三层：

CODE
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.3743B / 39B1,048,576MLA + DSAFP8 / NVFP4 / W4A81.3.0rc25
Kimi-K32.8T / 16 of 8961,048,576KDA + 稀疏 MLAMXFP4源码构建
Qwen3.5-397B-A17B397B / 17B262,144GDN + GQANVFP4 / BF161.4.0rc2
Qwen3.8-2.4T-A95B2.4T / 95B—GDN + GQAFP81.4.0rc2
MiniMax-M3427B / 26B1,048,576MSA 块稀疏BF16 / MXFP8 / NVFP4Blackwell 镜像
gpt-oss-120b117B / 5.1B131,072滑窗 + 全注意力MXFP41.3.x

02显存预算与 KV 计算

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

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

free_gpu_memory_fraction 的语义是：

CODE
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：

CODE
KV_bytes_per_token = 2 × n_layers × n_kv_heads × head_dim × dtype_bytes
架构n_kv_heads相对 MHA
MHA= n_heads1×
GQA= n_heads / g1/g
MQA= 11/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

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

混合注意力（额外项）

Kimi-K3 的 KDA 层：

CODE
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 的分配情况。查找关键字：

CODE
[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架构与参数作用点

三层结构

CODE
┌─────────────────────────────────────────────────────────┐
│  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                 │
└─────────────────────────────────────────────────────────┘

一次请求的路径

CODE
① 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 与命令行的分工

CODE
命令行（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_sizeTP 宽度。MoE 模型下 moe_tensor_parallel_size × moe_expert_parallel_size 必须等于它
pipeline_parallel_size--pp_sizePP 宽度
moe_expert_parallel_size--ep_sizeMoE 层的 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.2KV 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 章
dtypefp8 可让 KV 减半，通常无损
tokens_per_blockKimi-K3 固定 64；GLM 系常用 32/64
mamba_ssm_cache_dtypeQwen3.5 的 GDN 状态精度。bfloat16 比 float32 省一半
periodic_snapshot_interval混合模型开 block reuse 时必须设（如 256），否则前缀命中无法恢复循环状态
混合模型的关键限制

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

4.3CUDA 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.4MoE 后端

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.3FP8B200 / GB200DEEPGEMM
GLM-5 / 5.3NVFP4B200 / GB200TRTLLM（DEEPGEMM 不支持 NVFP4）
Kimi-K3MXFP4GB300自动（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.3MTPnum_nextn_predict_layers 只能为 1
Qwen3.5 / 3.8MTP内置 1 个 recurrent MTP 模块
Kimi-K3Suffix automaton聚合与分离模式均支持
DeepSeek 系MTPTRT-LLM 有专门的 MTP 优化（relaxed acceptance）
NVFP4 + MTP 目前不兼容

（GLM-5 指南明确写了）。要用 MTP 就选 FP8。

4.6PD 分离

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_parserqwen3_coder、glm47、kimi_k3、deepseek_v3 等。auto 会按模型类型选
--reasoning_parserqwen3_5、glm45、deepseek_r1、nemotron-v3 等
GLM-5.3 的推理控制已变

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

05并行策略选型

本引擎的推理拓扑与 KV 存放

为便于阅读，下图使用小规模设备组解释机制，不代表旗舰模型能装入这些设备。

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

图中 moe_tp / moe_ep / attention_dp 为排版缩写，分别对应 YAML 的 moe_tensor_parallel_size、moe_expert_parallel_size、enable_attention_dp，不能把缩写直接写入配置文件。

TensorRT-LLM · A · Attention TP4 + routed TP4tensor_parallel_size:4; moe_tp:4; moe_ep:1; attention_dp:false示例：4 设备、8 个路由专家；GQA 有 8 个 KV head；无共享专家的模型省略左支路。同一请求 / 同一批 token设备 0 · Attn Layer权重 TP 切片 1/4KV heads 0–1（1/4）设备 1 · Attn Layer权重 TP 切片 2/4KV heads 2–3（1/4）设备 2 · Attn Layer权重 TP 切片 3/4KV heads 4–5（1/4）设备 3 · Attn Layer权重 TP 切片 4/4KV heads 6–7（1/4）共享专家 Shared Experts本图选取 TP4 权重切分所有 token 均进入此支路融合 / 其他放置方式另行核对路由专家 Routed Experts同一 token 的所选专家并行计算全部 E0–E7权重切片 1/4全部 E0–E7权重切片 2/4全部 E0–E7权重切片 3/4全部 E0–E7权重切片 4/4AllReduce：汇合权重切片结果共享输出 + 路由输出进入后续层；继续使用各模块的并行组
TensorRT-LLM · A · Attention TP4 + routed TP4 · KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。
TensorRT-LLM · B · Attention TP4 + routed EP4tensor_parallel_size:4; moe_tp:1; moe_ep:4; attention_dp:false示例：4 设备、8 个路由专家；GQA 有 8 个 KV head；无共享专家的模型省略左支路。同一请求 / 同一批 token设备 0 · Attn Layer权重 TP 切片 1/4KV heads 0–1（1/4）设备 1 · Attn Layer权重 TP 切片 2/4KV heads 2–3（1/4）设备 2 · Attn Layer权重 TP 切片 3/4KV heads 4–5（1/4）设备 3 · Attn Layer权重 TP 切片 4/4KV heads 6–7（1/4）共享专家 Shared Experts本图选取 TP4 权重切分所有 token 均进入此支路融合 / 其他放置方式另行核对路由专家 Routed ExpertsAllToAll dispatchE0–E1完整专家权重E2–E3完整专家权重E4–E5完整专家权重E6–E7完整专家权重AllToAll combine共享输出 + 路由输出进入后续层；继续使用各模块的并行组
TensorRT-LLM · B · Attention TP4 + routed EP4 · KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。
TensorRT-LLM · C · attention-DP4 + routed TP4tensor_parallel_size:4; moe_tp:4; moe_ep:1; attention_dp:true示例：4 设备、8 个路由专家；GQA 有 8 个 KV head；无共享专家的模型省略左支路。不同请求 / 本地批次设备 0 · Attn Layer本地完整权重KV：请求 A 的完整历史设备 1 · Attn Layer本地完整权重KV：请求 B 的完整历史设备 2 · Attn Layer本地完整权重KV：请求 C 的完整历史设备 3 · Attn Layer本地完整权重KV：请求 D 的完整历史共享专家 Shared Experts本图选取本地完整副本所有 token 均进入此支路融合 / 其他放置方式另行核对路由专家 Routed ExpertsAllGather：汇集各 rank 的 token全部 E0–E7权重切片 1/4全部 E0–E7权重切片 2/4全部 E0–E7权重切片 3/4全部 E0–E7权重切片 4/4ReduceScatter：返回本地 token共享输出 + 路由输出进入后续层；继续使用各模块的并行组
TensorRT-LLM · C · attention-DP4 + routed TP4 · KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。
TensorRT-LLM · D · attention-DP4 + routed EP4tensor_parallel_size:4; moe_tp:1; moe_ep:4; attention_dp:true示例：4 设备、8 个路由专家；GQA 有 8 个 KV head；无共享专家的模型省略左支路。不同请求 / 本地批次设备 0 · Attn Layer本地完整权重KV：请求 A 的完整历史设备 1 · Attn Layer本地完整权重KV：请求 B 的完整历史设备 2 · Attn Layer本地完整权重KV：请求 C 的完整历史设备 3 · Attn Layer本地完整权重KV：请求 D 的完整历史共享专家 Shared Experts本图选取本地完整副本所有 token 均进入此支路融合 / 其他放置方式另行核对路由专家 Routed ExpertsAllToAll dispatchE0–E1完整专家权重E2–E3完整专家权重E4–E5完整专家权重E6–E7完整专家权重AllToAll combine共享输出 + 路由输出进入后续层；继续使用各模块的并行组
TensorRT-LLM · D · attention-DP4 + routed EP4 · KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

官方依据：TensorRT-LLM 并行与配置文档。图示策略存在不代表某个模型、精度、硬件组合已实测。

六种并行

CODE
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每个专家的切片所有 tokenall-reduce小 EP、低延迟
EP部分专家的完整权重只看到路由来的 tokenall-to-all（少量）大规模、高吞吐
ETP部分专家的切片部分 tokenall-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 模式 + 特定流量分布有效。任何输入变化都要重新生成。

选型决策

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

PD 分离的拓扑

官方 Qwen3.5 GB300 示例：

CODE
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.2GLM-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.3Kimi-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 GBGB300 级显存
TEP8attention-TP, EP8213 GBGB300 级显存
TEP16（低延迟）attention-TP, EP16115 GBGB200（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.4Qwen3.5 / Qwen3.8

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

属性Qwen3.8-2.4T-A95BQwen3.5-397B-A17B
解码层数9260
Hidden size81924096
GDN / GQA 层69 / 2345 / 15
路由专家 / 激活512 / 10512 / 10
内置 MTP1 个 recurrent 模块1 个 recurrent 模块
推荐精度Block-scaled FP8NVFP4 + FP8 KV
模态纯文本文本 + 图像 + 视频
共享实现 ≠ 配置可互换

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

硬件需求

CheckpointB200B300GB200GB300
Qwen3.8-2.4T FP816 卡16 卡16 卡16 卡
Qwen3.5-397B NVFP44 卡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低延迟 + MTP3qwen3.8-low-latency-mtp3.yaml
Qwen3.8 MoE FP8高吞吐qwen3.8-high-throughput.yaml
Qwen3.8 MoE FP8高吞吐 + MTP3qwen3.8-high-throughput-mtp3.yaml
Qwen3.5-397B NVFP4通用qwen3.5.yaml

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

目标投机拓扑并发结果
低延迟关闭TP16/EP11133.5 tok/s/user（7.49 ms TPOT）
低延迟MTP3TP16/EP11383.1 tok/s/user（2.61 ms TPOT）
高吞吐关闭Attn-DP32/EP32 + Static54432644059 tok/s/GPU
高吞吐MTP3Attn-DP32/EP32 + Static54423044118 tok/s/GPU

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

6.5MiniMax-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.6gpt-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配置速查

模型TPEPAttn-DPMoE backend特殊
GLM-5.3 FP888falseDEEPGEMMMTP 可用
GLM-5.3 NVFP488falseTRTLLMMTP 不可用
Kimi-K3 DEP161616trueautofree_gpu_memory_fraction: 0.25
Kimi-K3 TEP161616falseauto低延迟
Qwen3.8 FP8161false—低延迟档
Qwen3.8 FP83232true—高吞吐 + Static544
Qwen3.5 NVFP44———qwen3.5.yaml

07调优方法论

先定义指标

指标定义
TTFTtime to first token
TPOTtime per output token
ITLinter-token latency
E2ELend-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: trueMTP 在 batch=1 时收益最大
高吞吐批处理大 max_batch_size + Attn-DP + EP + 大 free_gpu_memory_fraction摊薄权重读取
长上下文enable_chunked_prefill: true + 大 max_seq_len + CP分块避免单步爆炸
多轮 Agentenable_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/responsesResponses API
/v1/embeddings向量（trtllm-serve embeddings 子命令）
/health健康检查
/metricsPrometheus 指标
/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 OOMKV 或 graph 吃太多降 free_gpu_memory_fraction（0.75→0.6）；降 max_num_tokens（8192→3072）；降 max_batch_size
内存碎片导致 OOMPyTorch 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_sizeYAML / --tp_sizeTP 宽度
pipeline_parallel_sizeYAML / --pp_sizePP 宽度
moe_expert_parallel_sizeYAML / --ep_sizeMoE 的 EP 宽度
moe_tensor_parallel_sizeYAMLMoE 的 TP 宽度（ETP 时用）
enable_attention_dpYAML注意力走 DP
max_batch_sizeCLI最大 batch
max_num_tokensCLI单步 token 上限
max_seq_lenYAML最大序列长度
kv_cache_config.free_gpu_memory_fractionYAML剩余显存的多少给 KV
kv_cache_config.enable_block_reuseYAML前缀复用
kv_cache_config.tokens_per_blockYAMLKV 块大小
kv_cache_config.mamba_ssm_cache_dtypeYAML混合模型 SSM 状态精度
cuda_graph_config.enable_paddingYAMLbatch padding 到捕获尺寸
cuda_graph_config.max_batch_sizeYAML最大捕获 batch
moe_config.backendYAMLMoE 内核后端
moe_config.use_low_precision_moe_combineYAMLEP combine 低精度
speculative_config.decoding_typeYAMLMTP 等
speculative_config.max_draft_lenYAML草稿长度
enable_chunked_prefillYAML分块 prefill
disable_overlap_schedulerYAML关闭调度重叠（PD prefill 用）
cache_transceiver_config.backendYAMLPD 传输后端（NIXL）
stream_intervalYAML流式输出间隔
--tool_parserCLI工具调用解析器
--reasoning_parserCLI推理内容解析器

B. 环境变量

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

C. 来源

来源用途
nvidia.github.io/TensorRT-LLM/latest/commands/trtllm-serveserve 命令与端点
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 章节为准。