TensorRT-LLM 源码完全拆解（一）：整体架构与模块全景——构建期已消失，PyTorch 后端如何接管推理引擎

系列进度与本篇定位

这是「四个推理框架源码系统学习」系列的第四站。前三站已经走完：

• vLLM（16 篇）：从整体架构、EngineCore.step 调度闭环，到 Scheduler、KVCacheManager、GPUModelRunner、Attention Backend、PagedAttention Kernel、FusedMoE、Sampler，最后用一篇源码阅读地图把十六篇串成一条路径。可参考 vLLM 源码完全拆解（十六）：把十五篇机制拼成一张可执行的源码阅读地图。
• SGLang（18 篇）：从进程拓扑、Req 状态机、PrefillAdder 预算、RadixCache 所有权，到 Overlap Scheduler、ForwardBatch、Attention Backend、CUDA Graph、Sampling/Grammar、投机解码、P/D 分离、多 LoRA、多模态、HiCache、DP Attention + EPLB、弹性 EP 与故障恢复。可参考 SGLang 源码完全拆解（一）：整体架构、进程拓扑与请求数据流。
• llama.cpp（8 篇）：从 ggml 后端抽象、计算图与内存分配器、GGUF 装载与 mmap，到 llama_context 与 KV Cache、采样与 GBNF、图构建与注意力、后端 kernel、服务化调度。可参考 llama.cpp 源码完全拆解（一）：整体架构与模块全景——ggml 后端抽象、llama_model/llama_context 与图构建。

前三站的读法有一个共同点：它们都是「Python 编排 + 底层 kernel」的两层结构，我们可以顺着 Python 一路读到 CUDA。TensorRT-LLM 不一样——它曾经是最重的那一层，而现在刚刚经历了一次伤筋动骨的重构。

所以本系列第一篇不讲调度细节，先把地形摸清楚：它被砍掉了什么、留下的骨架长什么样、哪些模块是这套框架真正独有的东西。

最重要的事实：TensorRT engine 后端已被移除

如果你手上是 2024 年之前的资料，几乎一定会看到这样一个流程：

1
HF checkpoint → convert_checkpoint.py → trtllm-build → engine 文件 → runtime 加载

这是 TensorRT-LLM 早期的核心形态：先用一个「转换脚本」把 HuggingFace 权重转成中间格式，再调用 NVIDIA TensorRT 编译器离线构建出一个序列化的 .engine 文件，运行时加载这个 engine 直接执行。这个形态有明确的工程收益（编译期做完算子融合、kernel 自动调优、形状特化），代价也很明确：模型改一行就要重新构建一次，构建过程动辄几十分钟到几小时。

现在这套东西没了。仓库里 docs/source/legacy/tensorrt-backend-removal.md 写得非常直接：

Breaking change. The TensorRT engine backend has been removed. PyTorch is now the sole execution backend for TensorRT LLM.

对应的迁移表里，被删掉的东西包括：

这段变化值得单独强调，因为它改变了读源码的方式。你已经不需要理解 TensorRT 的 builder / network / plugin 机制，也不再需要在 cpp/tensorrt_llm/ 里找 engine 反序列化逻辑。今天的 TensorRT-LLM 是一个「以 PyTorch 为核心的推理引擎」：模型用原生 PyTorch 定义（tensorrt_llm/_torch/models/modeling_*.py），kernel 用 CUDA/CUTLASS/CuTe DSL 写（cpp/tensorrt_llm/kernels/、cute_dsl_kernels/），中间由一个 Python 执行器把它们调度起来。

一个自然的疑问是：那「TensorRT-LLM」这个名字里的 TensorRT 去哪了？ 答案是它退化成了一个可选的、性能取向的 kernel 提供方，而不是必须经过的编译阶段。真正撑起框架的是下面这套执行器体系。

图：TensorRT-LLM 官方文档给出的架构总览。自上而下是 LLM API、PyExecutor（含 Scheduler / KV Cache Manager / Decoder / Model Engine）、以及底层的 TensorRT-LLM C++ Runtime 与各类 kernel。（来源：NVIDIA/TensorRT-LLM 官方文档 docs/source/media/）

这张图是理解本篇的关键：它直接给出了「请求进来之后，被谁接住、被谁调度、最后被什么执行」的分层。接下来我们逐层拆开。

仓库地形：一个仓库里的六种东西

读一个陌生框架，先看顶层目录比读 README 更快。TensorRT-LLM 主分支的顶层结构是这样的（省略配置文件）：

1
cpp/                  C++ 侧全部内容
2
  include/            对外头文件
3
  kernels/            独立 kernel 库（xqa、fmha_v2）
4
  tensorrt_llm/       C++ 核心：batch_manager / executor / runtime / kernels
5
  micro_benchmarks/   微基准
6
tensorrt_llm/         Python 侧全部内容
7
  _torch/             PyTorch 后端主体（下一篇的主角）
8
  llmapi/             LLM API 与 LLM 对象
9
  models/             模型定义（旧路径，逐步迁往 _torch/models）
10
  quantization/       量化配置与 mode
11
  executor/           Executor API 的 Python 封装
12
  commands/           CLI（trtllm-serve / trtllm-bench 等）
13
  bench/ evaluate/ serve/ tokenizer/ ...
14
kernels/              （已归并到 cpp/kernels）
15
examples/             分场景示例（quickstart_advanced 等）
16
triton_backend/       Triton Inference Server 后端适配
17
triton_kernels/       Triton kernel
18
docs/                 文档
19
scripts/              构建与环境脚本

这里有一个非常值得注意的结构特征：同一个框架里同时存在 Python 与 C++ 两套「核心」，而且它们不是简单的主从关系。

• tensorrt_llm/_torch/ 是 Python 后端的主体，包含模型定义、注意力后端、MoE、投机解码、KV Cache 管理、编译路径、显存管理等几乎所有推理逻辑。
• cpp/tensorrt_llm/ 包含 batch_manager（批管理、KV Cache Manager、缓存传输）、executor（请求/响应抽象、序列化）、runtime（缓冲区、通信、虚拟内存）、kernels（真正的 CUDA 算子）。

关键问题是：哪些逻辑在 Python，哪些下沉到 C++？ 官方文档给的答案很具体——调度器与 KV Cache Manager 当前使用 C++ binding，但接口用 Python 实现，因此可以自定义：

Both CapacityScheduler and MicroBatchScheduler currently use C++ bindings. However, since the interfaces are implemented in Python, customization is possible.

Currently, the KVCacheManager uses C++ binding. However, customization in Python is possible, as its interface is implemented in Python.

翻译成可操作的结论：读调度和 KV 管理时，你会看到 Python 接口调用 C++ binding（例如 BindCapacityScheduler(max_num_requests, kv_cache_manager.impl)），逻辑主体在 cpp/tensorrt_llm/batch_manager/ 里；但 Python 侧留了继承点，你可以用 Python 重写算法而不碰 C++——GuaranteedNoEvictScheduler 就是文档给出的例子，它继承 CapacityScheduler 并自己实现 schedule_request。

这个「接口在 Python、实现在 C++」的设计贯穿整个框架，也是它和 vLLM/SGLang 最大的手感差异：后两者基本是纯 Python + 少量自定义 kernel，而 TensorRT-LLM 是「Python 编排层 + 厚重的 C++ 运行时」，两者通过 nanobind（cpp/tensorrt_llm/nanobind/）绑定。

C++ 侧的三个支柱：executor、runtime 与 batch_manager

既然逻辑主体在 C++，就有必要把 cpp/tensorrt_llm/ 这三个目录的边界说清楚。它们的分工是：executor 定义「请求和响应长什么样」，runtime 提供「跑起来需要的内存与通信」，batch_manager 决定「请求怎么被组织成批次」。

1
request.cpp / requestWithId.cpp / response.cpp    请求与响应对象
2
schedulerConfig.cpp                               调度器配置
3
kvCacheConfig.cpp / kvCacheRetentionConfig.cpp    KV Cache 容量与保留策略配置
4
dynamicBatchConfig.cpp                            动态批配置
5
guidedDecodingConfig.cpp / guidedDecodingParams.cpp  结构化输出（引导解码）配置
6
loraConfig.cpp / peftCacheConfig.cpp              LoRA 与 PEFT 缓存配置
7
multimodalInput.cpp                               多模态输入描述
8
mropeConfig.cpp                                   M-RoPE（多模态 RoPE）配置
9
promptTuningConfig.cpp                            提示调优配置
10
cacheTransmissionConfig.cpp                       缓存传输配置
11
contextPhaseParams.cpp                            context 阶段参数
12
tensor.cpp / types.cpp / serialization.cpp        张量与类型、序列化基础设施

1
bufferManager.cpp / iBuffer.cpp / tllmBuffers.cpp     缓冲区管理
2
cudaMemPool.cpp                                        CUDA 内存池
3
virtualMemory.cpp                                      虚拟内存
4
ncclCommunicator.cpp                                    NCCL 通信封装
5
worldConfig.cpp / workerPool.cpp                       世界配置与 worker 池
6
ipcSocket.cpp / ipcNvlsMemory.cu / ipcUtils.cpp        IPC 与 NVLS 内存
7
mcastDeviceMemory.cpp / mcastGroupComm.cpp             多播设备内存与组通信
8
bufferManagerNvls.cpp                                  NVLS 缓冲管理
9
loraCache.cpp / loraModule.cpp / loraUtils.cpp         LoRA 权重缓存
10
memoryCounters.cpp                                     显存计数
11
moeLoadBalancer/                                       MoE 负载均衡
12
locality_domain/                                       局部性域（拓扑感知）
13
tllmBuffers.h / torch.h / torchUtils.h / torchView.h  与 PyTorch 张量的桥接

1
kvCacheManager.cpp / kvCacheManagerV2Utils.cu           KV Cache 管理器（两代）
2
kv_cache_manager_v2/                                    新版分块 KV 管理
3
blockKey.cpp                                            块键（前缀复用寻址）
4
evictionPolicy.cpp                                      淘汰策略
5
capacityScheduler.cpp                                   容量调度
6
microBatchScheduler.cpp                                 微批调度
7
scheduledBlocksManager.h                                已调度块管理
8
cacheTransceiver.cpp / cacheFormatter.cpp               KV 传输与格式化
9
mlaCacheFormatter.cpp / rnnCacheFormatter.cpp           MLA / 循环层专用格式化
10
contextTransferCoordinator.cpp                          context 传输协调
11
contextProgress.cpp                                     上下文进度跟踪
12
dataTransceiver.cpp / cacheTransferLayer.cpp            数据传输层
13
kvCacheTransferManager.cpp / kvCacheEventManager.cpp    KV 传输与事件
14
peftCacheManager.cpp                                    PEFT/LoRA 缓存
15
llmRequest.cpp                                          请求对象
16
agentTree.cpp                                           Agent 树（请求依赖关系）
17
baseTransBuffer.cpp / cacheTransBuffer.cpp              传输缓冲

顶层入口：LLM 对象做了什么

tensorrt_llm/llmapi/llm.py 里的 LLM 类是对外唯一入口，和 vLLM/SGLang 的 LLM 定位一致：

1
from tensorrt_llm import LLM
2

3
llm = LLM(model=<path_to_llama_from_hf>)

官方架构文档对它的职责只给了一句话，但信息量不小：

The interface for PyTorch backend is tensorrt_llm.LLM. The LLM also manages the tokenization and detokenization processes of the input.

也就是说，LLM 至少承担三件事：

1. 配置解析：llmapi/llm_args.py 里的 TorchLlmArgs 是全部参数的载体（取代了旧的 TrtLlmArgs）。
2. 构建 PyExecutor：把参数、模型、KV Cache Manager、调度器组装成执行器。
3. 分词/反分词：llmapi/tokenizer.py 与 sanglang 式的增量解码逻辑——注意这里只是「管理」，真正的增量解码细节在 pyexecutor 侧。

读源码时的实际路径是：

1
LLM.__init__
2
  └─ llm_args.py: TorchLlmArgs          # 参数对象
3
  └─ _torch/pyexecutor/py_executor_creator.py: create_py_executor
4
        ├─ _util.py: KvCacheCreator._create_kv_cache_manager
5
        ├─ BindCapacityScheduler / MicroBatchScheduler
6
        └─ PyTorchModelEngine
7
  └─ _torch/pyexecutor/py_executor.py: PyExecutor

create_py_executor 是整个装配线的中心，下一篇会沿着它展开。这里先记住一点：TensorRT-LLM 的 LLM 对象比 vLLM 的重，因为它要在初始化阶段就把 KV Cache 池、调度器、模型引擎、显存缓冲全部建好，而不是留到第一次请求。

模型层：原生 PyTorch 定义改变了什么

tensorrt_llm/_torch/models/ 是这次重构后最重要的目录，因为它回答了一个根本问题：没有编译期，模型是怎么被描述给引擎的？

答案是：用原生 PyTorch 写。目录里是一长串 modeling_*.py，每个文件定义一个（或一族）模型架构：

1
modeling_auto.py              自动架构分发
2
_arch_index.py                架构索引
3
modeling_llama.py             Llama 系列
4
modeling_qwen.py / modeling_qwen3.py / modeling_qwen3_moe.py / modeling_qwen3_next.py
5
modeling_deepseekv3.py / modeling_deepseekv4.py / modeling_deepseekv41.py
6
modeling_mistral.py / modeling_mixtral.py
7
modeling_gemma3.py / modeling_gemma4.py ...
8
modeling_gpt_oss.py / modeling_glm.py / modeling_kimi_k25.py / modeling_kimi_linear.py
9
modeling_nemotron.py / modeling_nemotron_h.py ...
10
modeling_llava_next.py / modeling_qwen2vl.py / modeling_pixtral.py / modeling_mllama.py ...
11
checkpoints/                  检查点加载相关
12
hf_parameter_utils.py         从 HuggingFace 权重映射到模型参数
13
modeling_multimodal_mixin.py  多模态混入

官方 overview 对这一点的措辞很直接：

Several popular models are also pre-defined and can be customized using [native PyTorch code], making it easy to adapt the system to specific needs.

这段变化带来的三个实际后果，是把 TensorRT-LLM 与「编译型」推理栈彻底区分开的标志：

1. 新模型的支持成本大幅下降。在旧的 engine 时代，支持一个新架构通常要走「写 plugin → 写转换脚本 → 适配 builder」这条长链路；现在只需要写一个 modeling_xxx.py，把 PyTorch 的 nn.Module 前向按规范组织起来。这就是官方反复强调 Day 0 支持的工程基础。
2. 调试路径变短。engine 文件是序列化的编译产物，出问题只能看日志和 profiler；现在模型就是 Python 代码，可以直接打印中间张量、可以在 forward 里打断点、可以逐层对照 HuggingFace 参考实现。
3. 代价从「构建期」转移到了「运行期」。编译期做过的形状特化与算子融合，现在要靠：注意力后端在元数据准备阶段做形状处理、CUDA Graph 在 warmup 阶段固定形状、以及手工融合的 kernel。这也是为什么这套框架对 CUDA Graph 与编译路径（compilation/、breakable_cuda_graph/）的依赖远比其他框架重——它必须把「编译」这件事在运行时补回来。

modeling_multimodal_mixin.py 与 checkpoints/ 里的加载逻辑，则分别解决了两个具体的工程问题：多模态模型的前向需要把视觉编码器的输出插入到文本 token 流中（混入机制），而权重从 HuggingFace 命名到模型内部命名的映射需要一层参数名转换。这两个问题在任何框架里都必须解决，TensorRT-LLM 的做法是把它们放在模型层而不是引擎层。

与 llama.cpp 的对比可以加深理解：llama.cpp 用 ggml 计算图 build_llama 系列函数拼出一次前向，图的形状与算子都由预定义的 C++ 逻辑决定，新架构要手写图构建代码；而 TensorRT-LLM 用 PyTorch 的 nn.Module 表达同一件事，新架构写一个模块即可，灵活度更高但失去了图级别的静态优化机会。可参考 llama.cpp 源码完全拆解（六）：图构建与注意力——llama-graph 如何把模型结构翻译成 ggml 图。

PyExecutor：一次 step 的五个动作

PyExecutor 是 Python 后端的执行核心。官方文档把它的关键组件和单步流程都写得很清楚，这部分值得完整抄下来，因为它是本系列的骨架。

三个关键组件：

• Model Engine：持有语言模型，高效支持单步前向。
• Decoder：根据 Model Engine 的输出生成输出 token。
• Scheduler：决定是否为某个请求分配资源（如 KV Cache），以及当前步是否为该请求跑前向。

单步流程（single-step flow）：

1. 从请求队列取新请求（如果有）。
2. 调度部分请求（scheduling some requests）。
3. 为被调度的请求跑模型前向（running model forward）。
4. 用前向输出为被调度的请求跑 Decoder。
5. 给每个请求追加输出 token，并处理已完成的请求。

这五步和 vLLM 的 EngineCore.step、SGLang 的调度循环在语义上几乎是同构的——这正是「连续批处理」这条主线的同一个骨架，如果你想先补齐这块基础，可以看 连续批处理完全拆解：Orca 的迭代级调度与选择性批处理。差异在于 TensorRT-LLM 把「资源分配」这件事显式拆成了一个 ResourceManager 概念。

1
kv_cache_manager = KVCacheManager(
2
    executor_config.kv_cache_config,
3
    tensorrt_llm.bindings.internal.batch_manager.CacheType.SELF,
4
    num_layers=model_engine.model.config.num_hidden_layers,
5
    num_kv_heads=model_engine.model.config.num_key_value_heads,
6
    head_dim=head_dim,
7
    tokens_per_block=tokens_per_block,
8
    max_seq_len=max_seq_len,
9
    max_batch_size=max_num_requests,
10
    mapping=mapping,
11
    dtype=kv_cache_dtype,
12
)

Scheduler：两级决策与它的两个阶段

调度器的设计是本篇最容易和 vLLM 混淆的地方，因为名字完全不同但语义高度对应。官方文档的定义：

There are two kinds of schedulers:

• CapacityScheduler: This scheduler decides if resources should be allocated for each active request. It considers the KV cache capacity and other resources, if applicable.
• MicroBatchScheduler: This scheduler selects some requests from fitting_requests chosen by CapacityScheduler.

两者串起来的方式也写明了：

SimpleScheduler combines these two schedulers, first using CapacityScheduler and then MicroBatchScheduler, to get the final schedule result.

用一张对照表把三套框架的调度语义对齐，会让你在切换阅读时省很多力气：

CapacityScheduler 的两个输出值得单独说：fitting_requests 和 paused_requests。文档特别指出 paused_requests 是为了支持 C++ runtime 里的请求暂停（request pausing）。也就是说 TensorRT-LLM 把「放不下怎么办」显式建模成了一个「暂停」状态，而不是像 vLLM 那样直接抢占释放。这是一个语义选择：暂停意味着请求保留但本步不执行，抢占意味着释放 KV 要重算，两者的代价模型完全不同。

MicroBatchScheduler 的输入里还有一项 inflight_request_ids，文档说它是为了支持流水线并行（PP）或 C++ runtime 里的重叠执行，并且明确指出：PyTorch flow 不支持流水线并行，所以这个集合是空的。

这句话是本次重构留下的一个清晰边界标记：PyTorch 后端目前不做 PP。读源码时如果你在找 PP 相关逻辑，在 _torch 下是找不到的。

1
available_blocks = max_blocks - reserved_blocks
2
for request in pending_requests:
3
    needed_blocks = self.kv_cache_manager.get_needed_resource_to_completion(request)
4
    if needed_blocks <= available_blocks:
5
        scheduled_requests.append(request)
6
        available_blocks -= needed_blocks
7
    elif needed_blocks > available_blocks:
8
        # If one requests fails to be scheduled, break
9
        break

模型引擎与 Decoder：执行侧的两个角色

PyExecutor 的核心组件里，ModelEngine 承担真正的 GPU 执行：

The core component of PyExecutor is the ModelEngine, responsible for executing the model’s forward pass efficiently on the GPU. The key method of ModelEngine is forward, which handles the forward pass computation.

PyTorch 后端的派生类是 PyTorchModelEngine，声明在 tensorrt_llm/_torch/pyexecutor/model_engine.py。这个文件是本系列后续的重点对象之一，因为「动态请求如何拼成一次静态形状的 GPU 前向」这件最难的事就在这里。

Decoder 的职责文档写得很克制：

The Decoder generates output tokens based on Model Engine outputs and supports greedy search decoding.

「supports greedy search decoding」是一个必要的限定：采样策略（temperature / top-k / top-p / 惩罚项）不在 Decoder 里，而在采样器模块。TensorRT-LLM 把「贪心解码」放在 Decoder、把完整采样管线放在 pyexecutor/sampler/，这个切分意味着 Decoder 只做「取 argmax + 应用停止条件」这种最轻的工作。贪心与采样的分布差异本身值得单独理解，本站 信息论基础：熵、交叉熵与 KL 散度——LLM 推理中无处不在的数学 里有对采样与温度的推导。

注意力后端：三个实现与它们的取舍

注意力是推理框架里最需要特化的部分。官方文档（docs/source/torch/attention.md）把 TensorRT-LLM 的注意力后端讲成了一篇「如何实现新后端」的教程，这个组织方式本身说明了设计取向：注意力后端是一个可插拔的第三方库集成点。

当前有三个可选后端，通过 PyTorchConfig.attn_backend 指定：

这个表格里最值得注意的是 vanilla 后端的存在和它的定位。官方明确说它「designed primarily for inflight batching and linear KV cache support」且「not recommended for production use due to its limited optimizations」。一个成熟框架保留一个明确不推荐生产的参考实现，通常有三个目的：给新模型 bring-up 时提供一个一定能跑通的基线；作为其他后端的正确性对照；给实现新后端的开发者一个最小的模仿对象。

而默认后端选择 TrtllmAttention 而非 FlashInfer，理由在文档里给出了两条具体的融合优化：

1. Fused QKV Input：可以接受单个 QKV 张量作为输入，比分开传 Q/K/V 三个张量更高效。
2. FP8 Output：支持以 FP8 输出注意力结果，把量化融合进注意力计算过程。

这两条都是典型的「减少一次 kernel 边界就是省一次 HBM 往返」的思路：Fused QKV 省掉的是 QKV 投影之后的拼接或多次读写，FP8 Output 省掉的是「注意力输出 → 单独量化 kernel → 后续 GEMM」这一整条链路。FP8 这条路线的整体背景可以看 DeepGEMM 完全拆解：300 行 FP8 GEMM 内核，如何逼近 Hopper 的算力峰值。

1
q: Tensor                 形状 (num_tokens, num_heads * head_dim)
2
k: Tensor                 形状 (num_tokens, num_kv_heads * head_dim)
3
v: Tensor                 形状 (num_tokens, num_kv_heads * head_dim)
4
metadata: AttentionMetadata
5
forward_args: AttentionForwardArgs   # 注意力掩码、输出缓冲与 scale、RoPE/MRoPE 输入、MLA 缓冲、稀疏注意力输入
6
**kwargs                             # 兼容路径；未知字段会报错

Kernel 生态：为什么它「这么杂」

cpp/tensorrt_llm/kernels/ 目录的规模需要单独看，因为它直接回答了一个常见困惑：为什么 TensorRT-LLM 的 kernel 这么散、这么多命名风格？

先看几个代表性目录：

1
cpp/kernels/
2
  fmha_v2/                      Fused Multi-Head Attention（独立版本化目录）
3
  xqa/                          XQA：MultiQuery/GroupQuery Attention kernel（Hopper 优化）
4
  contextFusedMultiHeadAttention/   上下文阶段 FMHA
5
  decoderMaskedMultiheadAttention/  解码阶段 MHA
6
  cutlass_kernels/                   基于 CUTLASS 的 GEMM 集合
7
  flashMLA/                          MLA 专用 kernel
8
  dsv3MinLatencyKernels/            DeepSeek-V3 低延迟 kernel
9
  groupRmsNormKernels/              分组 RMSNorm
10
  fusedQKNormRopeKernel.cu          融合 QK Norm + RoPE
11
  fusedLayernormKernels/            融合 LayerNorm
12
  fusedActivationQuant.cu           激活 + 量化融合
13
  ...
14
cpp/tensorrt_llm/
15
  deep_ep/                      DeepEP（专家并行通信）
16
  deep_gemm/                    DeepGEMM（FP8 GEMM）
17
  flash_mla/                    FlashMLA 集成
18
  nccl_extensions/              NCCL 扩展
19
  cutlass_extensions/           CUTLASS 扩展

以及 tensorrt_llm/_torch/ 下并列存在的多种 kernel 来源：

1
cute_dsl_kernels/       CuTe DSL 写的 kernel
2
cuda_tile_kernels/      CUDA Tile 路径
3
custom_ops/             自定义算子
4
flashinfer_utils.py     FlashInfer 集成
5
fused_relu2_triton.py   Triton 写的融合算子

「杂」的根因有三个，理解了就不会乱：

1. kernel 的来源本就是多元的：有的来自 NVIDIA 内部长期迭代的库（FMHA v2、XQA 都带版本号，说明是独立演进的产品线），有的来自开源（DeepEP、DeepGEMM 是 DeepSeek 开源后被集成），有的来自第三方推理 kernel 库（FlashInfer），有的是用新 DSL 写的（CuTe DSL、TileLang 风格）。
2. 注意力 kernel 必须按「阶段 × 形态」组合特化：context 阶段（长 Q，因果掩码）和 generation 阶段（Q 长度 1，读长 KV）的计算形态完全不同，MHA/MQA/GQA/MLA 的 KV 组织也不同。所以你会看到 contextFusedMultiHeadAttention、decoderMaskedMultiheadAttention、xqa、flashMLA 各自独立——它们不是重复劳动，而是针对不同角落的专门优化。
3. 融合算子的收益极高：目录里大量 fused* 前缀（fusedQKNormRopeKernel、fusedActivationQuant、fusedLayernormKernels、fusedGatedRMSNormQuant）说明这套框架把「减少 HBM 往返」当作核心优化手段。每一次融合都在省一次「读出、计算、写回」。

关于这批 kernel 中相当重要的一个：cpp/kernels/xqa 这个目录名值得记住——XQA 是 NVIDIA 针对 Hopper 架构、面向 MQA/GQA 的解码注意力 kernel，它是「低算术强度场景下如何喂满 Tensor Core」这个问题的一个专门答案。

图：TensorRT-LLM 官方文档给出的 MoE 并行策略示意。TP 下每个专家的权重矩阵被切分到所有 GPU、每个 GPU 看到全部 token；EP 下每个专家的完整权重驻留单卡、每个 GPU 只看到路由到本地专家的 token；Hybrid ETP 则在 EP 基础上再做 TP 切分以平衡负载与 kernel 效率。（来源：NVIDIA/TensorRT-LLM 官方文档 docs/source/media/moe-parallelism.png）

并行策略：六种切法与模块级选择

docs/source/features/parallel-strategy.md 给出的并行策略清单比 vLLM/SGLang 公开的更宽，一共六种：

其中 Wide-EP 是这套框架最有辨识度的设计，文档对它的动机交代得很直接：

Large-scale MoE models like DeepSeek-V3/R1, LLaMA4, and Qwen3 use fine-grained expert designs that introduce new challenges:

• High memory demands for expert weights
• Inherent expert-level workload imbalance due to sparse execution patterns
• Communication overhead in distributed expert parallelism
• Hot expert problem where certain experts receive significantly more tokens than others

而 Wide-EP 的解法核心是把「专家」和「槽位」两个概念解耦：

Wide-EP separates the concepts of experts and slots:

• Expert: The concept from the model’s perspective (e.g., Expert 0, Expert 1, etc.)
• Slot: The concept from the model engine’s perspective (e.g., Slot 0, Slot 1, etc.) The system maintains a routing table that maps Expert IDs to Slot IDs, which can be updated by the load balancing policy.

这个解耦是「专家复制」得以实现的前提：模型视角下 Expert 0 只有一个身份，而引擎视角下可以有多个 Slot 同时承载 Expert 0 的副本，分散在不同 GPU 上。路由表把两者接起来，并由负载均衡策略动态更新。

配套的两个机制：

• Offline EPLB：基于历史负载统计预先计算专家放置。
• Online EPLB：根据实时流量动态调整专家放置，且做逐层权重重分配（layer-wise weight redistribution）以最小化推理中断。

「逐层重分配」这个细节值得注意：重排专家意味着要搬权重，如果一次性全搬，服务会有一个明显的停顿窗口；逐层做则把停顿切成小段，每一层搬完即可继续服务。这与 SGLang 的 EPLB 实现思路可以对照阅读，见 SGLang 源码完全拆解（十七）：DP Attention 与专家并行——注意力数据并行、DeepEP 通信与 EPLB 负载均衡。关于 MoE 路由本身，本站有 DeepSeekMoE 完全拆解：细粒度专家切分与共享专家隔离。

一个绕不开的取舍：Wide-EP 的通信代价藏在哪

Wide-EP 的收益（吞吐、均衡）是显性的，代价是隐藏的：EP 度越大，all-to-all 的通信量越大。文档提到 Wide-EP 配有「Custom EP Communication Kernels」，针对 NVIDIA GB200 的 Multi-Node NVLink（MNNVL）优化，并明确说「Reduced communication overhead compared to traditional EP」。

这句「比传统 EP 通信开销更低」的实现基础是 NVLink 域内的高带宽：在 GB200 这类系统里，MNNVL 让多个节点形成一个大的 NVLink 域，专家 dispatch/combine 不需要走以太网。一旦部署规模超出 MNNVL 域，EP 的通信代价就会急剧上升——这是 Wide-EP 适用的物理边界，也是为什么文档把 max_num_tokens 调优列为最佳实践之一：token 数直接决定 all-to-all 的数据量。

关于 all-to-all 通信本身，本站有 DeepEP 完全拆解：DeepSeek 开源通信库如何把 MoE 推理的 dispatch/combine 压到硬件极限。

图：张量并行的基本形态。注意它与 MoE 示意图的差别——TP 下每张卡都看到全部 token，只是各自持有部分权重；这也是为什么 TensorRT-LLM 文档把注意力模块的 TP 描述为「注意力 kernel 前后的 GEMM 权重均匀切分，注意力的 num_heads 同样切分」。（来源：NVIDIA/TensorRT-LLM 官方文档 docs/source/media/Tensor_Parallelism_Vis.svg）

构建期消失之后，这套框架靠什么取得性能

这是读全新架构时最该问的问题：丢掉了编译期的算子融合与自动调优，性能从哪来？

从前面看到的模块清单，答案大致有五条：

1. 手工融合 kernel（fused\* 系列）：编译期能做的融合，改成人工在设计时就写好融合算子。
2. 专门化的注意力 kernel（FMHA v2 / XQA / FlashMLA / context FMHA / decoder MHA）：按阶段与 KV 组织形态分别提供最优实现。
3. 多种精度路径（FP8 / FP4 / W4A16 / 块量化）：DeepGEMM、Marlin、CUTLASS 扩展与各类量化 kernel 提供低精度算力。
4. 通信与计算的深度重叠（overlap scheduler、Wide-EP 专用通信 kernel、双批重叠）。
5. CUDA Graph + 编译路径（cuda_graph_runner.py、breakable_cuda_graph/、compilation/）：把调度与启动开销压出去。

关于重叠调度，官方文档（features/overlap-scheduler.md）给出了 PyExecutor 里的真实代码形态，这段代码几乎不需要解释：

1
# Schedule and launch GPU work for the current step (n)
2
scheduled_batch, _, _ = self._schedule()
3
batch_outputs = self._forward_step(scheduled_batch, previous_tensors_device)
4
sample_state = self._sample_async(scheduled_batch, batch_outputs)
5

6
# While the GPU is busy, process the CPU-bound results from the previous step (n-1)
7
if self.previous_batch is not None:
8
    self._process_previous_batch()

文档同时给出了代价的明确表述：

The optimization introduces one extra decoding step but significantly improves throughput.

「多一个解码步」换「吞吐显著提升」——这是一笔典型的延迟换吞吐的交易，也是默认开启的原因。对应 vLLM 的同名机制见 vLLM 源码完全拆解（二）：从 add_request 到 EngineCore.step，一次请求如何穿过 V1 引擎；SGLang 的对应实现见 SGLang 源码完全拆解（六）：Overlap Scheduler 如何重叠 CPU 调度与 GPU 执行。

还有哪些值得一提的模块

仓库里还有几个目录，虽然本篇不作深入，但值得在脑子里留下索引，因为它们往往是后续章节的主角：

• _torch/speculative/：投机解码。TensorRT-LLM 支持的算法家族里包括 EAGLE、MTP、NGram，文档在 overview 里明确列出。可参考 EAGLE 完全拆解：特征级草稿模型如何把投机解码推到 3 倍以上 与 MTP 完全拆解：多 token 预测如何让 DeepSeek 自带草稿模型。
• _torch/moe/ 与 _torch/distributed/：MoE 执行与分布式通信。
• _torch/kv_cache_compression/：KV Cache 压缩（对应 features/kv-cache-compression.md）。
• _torch/disaggregation/ 与 cpp/tensorrt_llm/batch_manager/cache_transmission/：P/D 分离与 KV 传输。

图：Medusa 的树式候选结构，用于说明投机解码在「一次前向验证多个候选」这件事上的数据结构形态。TensorRT-LLM 的投机解码模块同样要在批量验证阶段处理这类树形候选与 KV 索引映射——这是 speculative/ 目录里最需要细读的部分。（来源：NVIDIA/TensorRT-LLM 官方文档 docs/source/media/medusa_tree.svg）

图：P/D 分离场景中 KV Cache 的跨实例传输路径。TensorRT-LLM 在 cpp/tensorrt_llm/batch_manager/ 下为此准备了完整的传输设施：cacheTransceiver、cacheFormatter、mlaCacheFormatter、rnnCacheFormatter 与 contextTransferCoordinator——甚至为 MLA 与循环层单独写了格式化器，因为它们的 KV 布局与标准注意力不同。（来源：NVIDIA/TensorRT-LLM 官方文档 docs/source/media/kv_transfer.png）

• _torch/weight_sharing/、shared_tensor/、tensor_lru_cache.py、pinned_weight_staging.py、host_staging.py：显存与权重的分层管理，包括 host 侧暂存与 LRU 缓存。
• _torch/adp_iter_stats.py、perf_metrics_manager.py、hang_detector.py、gpu_keepalive.py：性能观测、hang 检测与保活——这类「生产运维」模块的存在，说明这套框架的设计目标包含长时间稳定服务，而不只是吞吐数字。
• _torch/locality_domain/、_torch/mnnvl_alltoall_workspace.py、_torch/device_mesh.py：拓扑感知与设备网格，是 Wide-EP 与 MNNVL 的基础设施。

还有一件容易被忽略的事：tensorrt_llm/llmapi/ 下有 reasoning_parser.py 和 thinking_budget.py。这说明推理模型（带思维链的模型）的输出解析与思考预算控制已经被当作一等公民写进了 API 层。对于需要区分 reasoning_content 与正式回答的部署场景，这是必须在 API 层处理的问题。

推荐阅读路径（本系列后续篇目）

摸清地形之后，本系列的后续规划按「先结构后细节」推进，大致分为四个阶段：

第一阶段：执行闭环

1. PyExecutor 与 py_executor_creator：create_py_executor 如何把参数、KV Cache Manager、调度器、模型引擎装到一起，以及单步五动作的真实代码形态。
2. Scheduler：CapacityScheduler 与 MicroBatchScheduler：C++ binding 的准入逻辑、paused_requests 的语义、inflight_request_ids 为空的边界。
3. KVCacheManager 与 ResourceManager：块分配、块表构造、prepare/update/free 三个钩子的调用点。

第二阶段：模型执行

4. PyTorchModelEngine：forward 如何把动态请求拼成静态形状输入。
5. Attention Backend 家族：三个后端的实现差异，AttentionMetadata.prepare 的构造细节，CUDA Graph 元数据的约束。
6. KV Cache 压缩与量化路径：kv_cache_compression/ 的设计。

第三阶段：分布式与通信

7. 并行策略落地：TP/DP attention 的 KV 分区、MoE 的 EP/ETP 选择、mapping 如何影响 KV 分配。
8. Wide-EP 与 EPLB：expert/slot 解耦、路由表更新、逐层重分配。
9. P/D 分离与 KV 传输：cache_transmission/ 与 disaggregation/。

第四阶段：kernel 与性能

10. XQA 与 FMHA v2：解码注意力的专门 kernel。
11. DeepGEMM / DeepEP / flash_mla 集成：开源自研 kernel 如何被接进这套框架。
12. CUDA Graph 与编译路径：cuda_graph_runner、breakable_cuda_graph、compilation/。

小结

本篇是 TensorRT-LLM 系列的地形图，把可验证的事实收拢如下：

• TensorRT engine 后端已被彻底移除，PyTorch 是唯一执行后端；trtllm-build、convert_checkpoint.py、tensorrt pip 依赖都不再需要。读源码时不需要理解 TensorRT builder/plugin 机制。
• 框架是「Python 编排层 + 厚重 C++ 运行时」：调度与 KV Cache Manager 的实现在 cpp/tensorrt_llm/batch_manager/，接口在 Python，通过 nanobind 绑定，因此两者都可以用 Python 自定义。
• PyExecutor 单步五动作：取新请求 → 调度 → 前向 → Decoder → 追加输出并处理完成。ResourceManager 用 prepare/update/free 三个钩子把「请求需要的资源」抽象出来，KV Cache Manager 是其中最重要的一个。
• 调度是两级：CapacityScheduler 做容量准入、MicroBatchScheduler 做本步选择，SimpleScheduler 串联；paused_requests 显式建模「暂停」，inflight_request_ids 在 PyTorch flow 下为空（不支持 PP）。
• KV Cache 布局是 [num_blocks, 2, tokens_per_block, num_kv_heads, head_dim]，K/V 共用物理内存、按块寻址、KV 头数决定压缩比。
• 注意力后端三选一：vanilla（参考）、FlashInfer（分页 KV + FP8 + RoPE 融合）、TRT-LLM（默认，另有 Fused QKV 与 FP8 输出）；后端生命周期分模型构建、元数据准备、单步前向三个阶段，CUDA Graph 下元数据张量只能分配一次。
• 并行策略六种，注意力可选 TP 或 DP（GQA/MQA/MLA 在 num_heads < tp_size 时 KV 复制），MoE 可选 TP / EP / Hybrid ETP，且满足 moe_tp × moe_ep == tp。Wide-EP 通过 expert 与 slot 解耦实现专家复制，代价是 all-to-all 通信，收益依赖 MNNVL 高带宽域。
• 性能来自手工融合 kernel、专门化注意力 kernel、多精度路径、通信-计算重叠与 CUDA Graph，而不是编译期自动优化。

下一篇进入第一阶段的核心：create_py_executor 与 PyExecutor 的单步闭环，看这套装配线如何把 LLM 对象的初始化参数变成一台持续运转的推理机器。

参考资料

1. TensorRT LLM 官方架构总览（PyTorch 后端）
2. Migration Guide: TensorRT Backend Removed
3. TensorRT LLM Attention 后端文档
4. TensorRT LLM Scheduler 文档
5. TensorRT LLM KV Cache Manager 文档
6. TensorRT LLM Overview
7. Parallelism in TensorRT LLM
8. Overlap Scheduler
9. NVIDIA/TensorRT-LLM GitHub 仓库
10. Scaling Expert Parallelism in TensorRT LLM（技术博客）
11. DeepSeek-V3 Technical Report（EPLB 与细粒度 MoE 背景）
12. Attention Is All You Need