LLM 推理框架的 Autotune 设计指南:各家最佳实践与可落地的设计要点
面向刚入门的推理框架开发者,把 TensorRT-LLM、FlashInfer、vLLM、SGLang、PyTorch、Triton、Helion、TensorRT、XLA、TVM、DeepGEMM、NCCL 等系统里的 autotune 做法放在一起对照,整理成"什么时候选、怎么分桶、怎么测准、怎么保证对、多卡怎么一致、结果怎么存"十个设计问题,并给出新增可调算子与新增调优策略的步骤和检查清单。
这篇文章写给要设计或维护 LLM 推理框架的开发者,特别是刚接触 kernel 调优的人。目标是让你读完之后能回答三件事:
- 现在主流的推理框架和编译器,autotune 各自是怎么做的;
- 自己设计一个 autotune 系统,要做哪些决定,每个决定有哪些坑;
- 要给框架加一个新的可调算子、或者加一种新的调优策略,具体该怎么动手。
文中关于各框架的结论,凡是能对到源码或官方文档的都给了文件位置或链接。调研时用到的代码版本:
| 项目 | 版本 | 日期 |
|---|---|---|
| TensorRT-LLM | 73ee6b0b19 | 2026-08-31 |
| vLLM | 8e92248f79 | 2026-08-31 |
| SGLang | 8bb776dc48 | 2026-08-30 |
| PyTorch | 66bec7c1d3b | 2026-08-31 |
| FlashInfer | 0.6.18(pip 包) | — |
| Triton / Helion / TileLang / DeepGEMM | GitHub main | 2026-10 ~ 2026-11 |
各项目迭代很快,具体的默认值、函数名、环境变量可能在你读到时已经变了。设计思路比具体数字更值得记住。
0. 先给结论:十条最重要的经验
如果只有五分钟,读这一节就够了。后面每一条都有展开。
- 调优的开销要放在服务上线之前。 要么离线调好随代码发布,要么在服务启动阶段调完。不要让第一个真实请求去承担调优时间。
- 调优必须在 CUDA Graph 录制之前完成。 CUDA Graph 会把当时选中的 kernel 固化进图里,录完之后再选也改不了。
- “测的时候”和”用的时候”必须落到同一个形状桶。 写表和查表要共用同一套折算函数,这是最隐蔽也最常见的错误来源。
- 最快的候选不一定是对的。 调优只比较速度,不检查结果。要么提前过滤掉已知会出错的候选,要么在调优时做数值校验。
- 某个候选跑崩了,记成”无穷慢”然后继续。 不要因为调优让服务起不来。
- 多卡必须选出同一个结果。 测量有噪声,各卡单独选会选出不同的 kernel,轻则性能抖动,重则通信对不上、整个服务卡死。
- 缓存键要把所有影响结果的东西都放进去:GPU 型号、库版本、数据类型、量化方式、并行度。加载缓存时要核对,对不上就丢掉。
- 输入数据长什么样会影响测量结果。 全零或均匀随机的输入在 MoE、稀疏、提前退出类算子上会测出错误的结论。
- 不是所有地方都值得测。 规则或代价模型能算出接近最优答案的地方(DeepGEMM、MLC-LLM 的 DLight),直接用规则更省事、更稳定。
- 调优结果要可见、可复现、可关闭。 打日志、能导出、能固定、能一键关掉退回默认实现。
1. Autotune 在解决什么问题
1.1 一个具体的例子
假设模型里有一个线性层,权重形状是 [7168, 2048],输入有 M 个 token。
- decode 阶段,
M可能只有 1 到 64。这时计算量很小,瓶颈在”把权重从显存读进来”。适合用小 tile、甚至把 K 维拆开多个 block 并行算(split-K),尽量让更多 SM 同时读权重。 - prefill 阶段,
M可能是 8192。这时计算量很大,适合用大 tile、多级流水,把 Tensor Core 喂满。
CUTLASS、cuBLASLt、Triton 这类库会为同一个矩阵乘生成几十到上百个不同配置的 kernel。哪一个最快,取决于形状、数据类型、GPU 型号、甚至前后 kernel 留在 L2 里的数据。理论上可以建模估算,但模型很难做到处处准确。
最朴素的办法是写一堆 if:
1
2
3
4
5
6
if m <= 16:
kernel = small_tile_splitk
elif m <= 256:
kernel = medium_tile
else:
kernel = large_tile
问题在于:这些阈值是在某一张卡、某一个版本上拍出来的。换一张卡、换一个 CUDA 版本、换一个模型尺寸,阈值就可能不对,而且没人会发现。
Autotune 的思路是:在真实硬件上把候选都跑一遍,记下”什么形状用哪个最快”,之后查表。
1.2 名词表
不同框架对同一个概念叫法不同,本文统一用下面这些词:
| 本文用词 | 意思 | 各框架里的叫法 |
|---|---|---|
| 候选 | 一个可以被选中的具体实现或配置 | tactic(TRT-LLM / FlashInfer / TensorRT)、config(Triton / Helion)、algo(cuBLASLt)、solution(TunableOp)、choice(Inductor) |
| 实现者 | 能执行某一族候选的对象 | runner(TRT-LLM / FlashInfer)、ChoiceCaller(Inductor) |
| 搜索空间 | 所有候选的集合 | valid tactics、configs |
| 形状桶 | 把无穷多个真实形状归到有限几个代表值 | bucket、profile、key(Triton) |
| 缓存键 | 用来查”上次选了谁”的索引 | cache key、file key |
| 测量 | 在 GPU 上实际计时 | profiling、benchmark、timing |
| 兜底 | 查不到结果时用的默认实现 | fallback、tactic=-1、default config |
1.3 Autotune 选的到底是什么
可以分成四类,难度和影响逐级变大:
| 类别 | 例子 | 典型系统 |
|---|---|---|
| ① kernel 内部参数 | tile 大小、流水级数、warp 数、cluster 形状 | Triton config、CUTLASS tactic、Helion config |
| ② 同一算子的不同实现 | cuBLAS vs CUTLASS vs Triton;MLA decode 用 trtllm-gen 还是 XQA | Inductor 模板选择、FlashInfer 多 runner、TRT-LLM 多 runner |
| ③ 算法变体 | 是否 split-K、是否 swap-AB、AllReduce 用 one-shot 还是 two-shot | FlashInfer low-M GEMM、TRT-LLM AllReduce |
| ④ 系统级参数 | TP/EP 怎么切、batch 上限、prefill/decode 是否分离 | vLLM auto_tune、NVIDIA AIConfigurator |
本文主要讲 ①~③,也就是”算子级 autotune”。④ 在第 3.6 节简单介绍,它的性质很不一样:一次测量是跑一整段压测,以分钟计。
2. 推理框架里 autotune 发生在哪几层
一个现代推理框架通常同时有好几套 autotune,彼此独立:
flowchart TB
A["服务参数层<br/>TP / EP / batch 上限 / P-D 分离<br/>vLLM auto_tune, AIConfigurator"] --> B
B["框架调度层<br/>选哪个 attention / MoE / GEMM 后端<br/>TRT-LLM AutoTuner, FlashInfer AutoTuner"] --> C
C["kernel 库层<br/>CUTLASS tactic / cuBLASLt algo / Triton config<br/>Triton autotune, TunableOp, Inductor"] --> D
D["通信库层<br/>NCCL 的 algorithm / protocol<br/>NCCL 内部代价模型 + tuner plugin"]
E["编译器层<br/>TensorRT builder, XLA, Inductor, TVM"] -.-> C
几点说明:
- 层与层之间基本不协调。 比如 Inductor 在编译期调出来的 Triton config,和 FlashInfer 在启动期调出来的 GEMM tactic,各管各的,不会联合优化。
- 越往上,一次测量越贵。 kernel 级一次测量是微秒到毫秒;服务参数级一次测量是一轮几分钟的压测。所以越往上越依赖离线搜索和代价模型。
- 每一层都应该能单独关掉。 出问题时,你需要能确认”是不是 autotune 选错了”。
3. 业界做法速览
按”什么时候选”把各家做法分成五类。这个分类比按框架分更有用:同一类做法面对的问题和坑基本一样。
3.1 离线调好,结果随代码发布
做法:开发者在目标 GPU 上跑调优脚本(几小时到几天),把结果写成 JSON/CSV 提交进仓库。用户安装后直接查表。
代表:
- vLLM / SGLang 的 Triton fused MoE。文件名就是缓存键,例如
E=256,N=128,device_name=NVIDIA_H200,dtype=fp8_w8a8,block_shape=[128,128].json,文件内容是{M: config}。vLLM 主目录里有 332 个这样的文件(vllm/model_executor/layers/fused_moe/configs/)。生成脚本是benchmarks/kernels/benchmark_moe.py。 - SGLang 按 Triton 版本分目录:
configs/triton_3_1_0/到configs/triton_3_7_1/共 8 个目录。原因是不同 Triton 版本对同一个 config 生成的机器码可能差很多,最优选择也会变。代价是每个版本目录里的覆盖率被稀释,没覆盖到的形状退回启发式默认值。 - vLLM 的 Helion kernel。预调好的配置放在
vllm/kernels/helion/configs/<kernel>/<platform>.json(如nvidia_h100.json),运行时用一个PresetConfigSearch替换掉 Helion 的搜索器,直接返回预调配置。形状桶和 CUDA Graph 的录制尺寸对齐。 - PyTorch TunableOp 的离线模式:第一遍只记录遇到了哪些 GEMM(
PYTORCH_TUNABLEOP_RECORD_UNTUNED=1),第二遍离线调优,产出tunableop_results*.csv。 - AMD 的 AITER 与 hipBLASLt。AITER(ROCm/aiter)用成对的 CSV 管理结果:先设
AITER_TUNE_GEMM=1把遇到的形状记进*_untuned_*.csv,再跑调优脚本产出*_tuned_*.csv,例如bf16_tuned_gemm.csv以gfx、CU 数、M/N/K等为键,记录用哪个库(libtype)、哪个 solution、是否 split-K。hipBLASLt 自己也有一套”记录形状 → 离线 bench → 运行时用HIPBLASLT_TUNING_OVERRIDE_FILE覆盖”的流程,并且明确说明 solution 编号不能跨库版本或跨 GPU 架构复用(文档)。 - AllReduce 的阈值表。vLLM 和 SGLang 选 AllReduce 实现时不在运行时测量,而是用离线测好的固定阈值。例如 vLLM 的
CUSTOM_ALL_REDUCE_MAX_SIZES(vllm/distributed/device_communicators/all_reduce_utils.py)按 SM 版本和 TP 大小给出自定义 AllReduce 能用到多大的消息:SM90 上 TP2/4/6/8 分别是 64MiB / 32MiB / 512KiB / 256KiB,SM100 上是 2 / 2 / 1 / 1 MiB。SGLang 用一个统一的_MAX_CAR_SIZE(CUDA 上 8MiB)。TRT-LLM 的 C++ 侧也有一张AllReduceBestStrategyTable(按 SM × TP × 融合类型 × hidden size × token 数索引),由tests/scripts/allreduce_perf/allreduce_heuristic_code_gen.py离线测出来后生成代码。
优点:用户零启动开销;结果可审查、可 diff;调优可以花很长时间做得很彻底。
缺点:只覆盖开发者调过的 (模型, GPU, 版本) 组合。没覆盖到的情况会悄悄退回默认值,性能可能差很多,用户却不知道。
查表方式要注意:vLLM 和 SGLang 查 M 用的是”最近邻”(min(configs.keys(), key=lambda x: abs(x - M)),fused_moe.py:1447),TRT-LLM / FlashInfer 用的是”向下取整到桶”。同样 M=200、桶是 {128, 256},前者选 256,后者选 128。两种都有道理,但你的框架要明确选一种,并且调优脚本要按同一种规则来产出数据。
3.2 服务启动时现场测
做法:服务加载完模型后,用假输入跑几遍前向,过程中每个可调算子都把候选测一遍,结果写进进程内缓存(可选写盘)。之后的真实请求只查表。
代表:
- TensorRT-LLM
AutoTuner(tensorrt_llm/_torch/autotuner.py,2079 行)。启动时在with self.no_cuda_graph(), autotune(cache_path=...)里跑 warmup(pyexecutor/model_engine.py:2042),环境变量TLLM_AUTOTUNER_CACHE_PATH指定缓存文件。推理时缓存没命中就返回(runners[0], -1),-1表示”让底层库自己选”。 - FlashInfer
AutoTuner:最初从 TRT-LLM 分叉出来,接口几乎一样(TunableRunner/TuningConfig/choose_one),后来加了不少实用功能,见第 4 节。 - vLLM 和 SGLang 调用 FlashInfer 的 autotuner:vLLM 在
vllm/model_executor/warmup/kernel_warmup.py的flashinfer_autotune();SGLang 在python/sglang/srt/model_executor/runner/flashinfer_autotune.py。两者都在外面补了多卡一致、缓存路径、是否启用的策略。
优点:自动适配当前的 GPU、模型、并行配置,不需要提前覆盖所有组合。
缺点:启动变慢(几十秒到几分钟);假输入不一定像真输入;多卡要额外处理一致性。
3.3 编译期测
做法:模型被编译成执行计划时,编译器为每个算子/融合块测候选,结果存进编译产物或单独的缓存文件。
代表:
- TensorRT builder。构建引擎时,对每一层把可用的 tactic 计时,选最快的,结果存进 timing cache。
builderOptimizationLevel取 0~5,默认 3:0 级直接用”第一个能跑通的 tactic”,且不使用 timing cache;1~2 级先用启发式排序,只测前几个;4~5 级会编译动态 kernel 并和静态 kernel 比较。timing cache 的使用规则写得很严:头部记录 CUDA 设备属性,不匹配就失败(除非显式忽略);合并两个 cache 要求”完全相同的 TensorRT 版本”;官方建议把 cache 文件当作”可执行的构建输入”来管理,并保持ignore_mismatch=False(NvInfer.h、优化指南)。另有kERROR_ON_TIMING_CACHE_MISS:缓存里没有就让构建失败,用来保证”线上构建一定复用离线结果”。原来用来手工干预选择的IAlgorithmSelector在 10.8 被废弃,替代品是可编辑的 timing cache(kEDITABLE_TIMING_CACHE),直接改缓存条目来固定某一层用哪个 tactic。TensorRT 11 的 trtexec 还新增了”全局性能调优”(--tuneBuildRoutes),在单层 tactic 之上再搜索构建器的内部选项组合,并支持用--loadRefOutputs+--accuracyThreshold做精度门槛(trtexec README)。 XLA GPU(JAX 的后端)。
xla_gpu_autotune_level默认 4,帮助文本是 “0 = off; 1 = on; 2 = on+init; 3 = on+init+reinit; 4 = on+init+reinit+check”,第 4 级会做结果校验。缓存键是”设备描述字符串 + 规范化后的 HLO + 版本号”,设备描述里包含算力版本、SM 数、GPU 时钟、显存带宽、L2 大小和 cuDNN 版本(autotune_cache_key.cc)。结果可以用xla_gpu_dump_autotune_results_to/xla_gpu_load_autotune_results_from导出导入;JAX 打开持久化编译缓存后,默认也会把 autotune 结果一起存下来。- PyTorch Inductor(
torch.compile(mode="max-autotune"))。对 mm/bmm/conv 等,在 ATen(cuBLAS)、Triton 模板、CUTLASS 模板之间比较。默认 Triton GEMM 搜索空间是二十来个手选 config,EXHAUSTIVE模式是上千个,编译时间到小时级。测量用InductorBenchmarker,默认返回最小值(return_mode="min",torch/_inductor/runtime/benchmarking.py)。CUTLASS 候选可能把 CUDA context 弄坏,所以放在子进程里测,并且全部失败时退回 ATen。 - TVM MetaSchedule:用进化搜索加 XGBoost 代价模型来减少真实测量次数,官方建议每个任务 200~500 次试验,结果存 JSON 数据库。
优点:编译一次,多次使用;能和算子融合一起考虑(融合会改变最优 tile)。
缺点:编译时间长;形状必须在编译期大致已知,动态形状要额外处理。
3.4 第一次调用时测
做法:某个形状第一次出现时,当场测所有候选,记下结果。
代表:
- Triton
@triton.autotune。缓存键是key=[...]里列出的参数值,加上所有张量参数的 dtype。默认只存在进程内存里;打开cache_results=True或TRITON_CACHE_AUTOTUNING=1才写盘(缓存键包含 Triton 版本、目标硬件、kernel 源码、所有候选 config)。注意:只要任何一个 config 带了pre_hook,写盘就会被关掉,因为钩子函数没法序列化。 torch.backends.cudnn.benchmark = True:卷积第一次遇到新形状时试所有 cuDNN 算法。- TunableOp 在线模式:
PYTORCH_TUNABLEOP_ENABLED=1且TUNING=1。
优点:实现最简单,只测真正用到的形状。
缺点:对在线服务是反面教材。 推理服务的 batch 大小一直在变,每遇到一个新形状就有一个请求被卡几十到几百毫秒。所以 vLLM 提供了 VLLM_TRITON_FORCE_FIRST_CONFIG=1,直接用第一个 config、跳过测量,以换取启动快和结果确定。
3.5 不测,用规则或代价模型直接算
做法:根据硬件参数(SM 数、shared memory 大小、L2 带宽)和形状,用公式或规则直接给出配置。
代表:
- DeepGEMM:完全不做运行时测量。
get_best_config枚举候选布局,用代价模型比较。SM90 上的模型大致是num_cycles = max(L1_cycles, L2_cycles) / wave_efficiency,其中wave_efficiency = num_blocks / (num_waves * num_sms);源码注释说 HBM 带宽和总计算量对所有候选都一样,所以只建模 L1/L2。SM100 上则是一串有序规则:”单 wave 总是更好” → “能 multicast 更好” → wave 数更少 → 最后一个 wave 利用率更高 → tile 更小。(heuristics/sm90.hpp、sm100.hpp) - MLC-LLM 从调优数据库切到规则调度。MLC-LLM 早期给每个模型存一份 MetaSchedule 调优数据库(
log_db/)。2023 年 8 月的 PR #670 删掉了所有数据库,改用 TVM 的 DLight 规则调度,PR 里写:在 Llama2-7B 和 RedPajama-3B、RTX 4090 和 M1 Max 上确认没有性能倒退,RedPajama-3B 反而更快,因为数据库里有些条目本身不是最优的。TVM 文档对 DLight 的描述是”编译几秒完成,对 LLM 里常见的 GEMM、GEMV 性能很好,其余的一般”。 - PyTorch AutoHeuristic:把 autotune 的结果拿去训练一棵决策树,生成 Python 代码随编译器发布(
torch/_inductor/autoheuristic/artifacts/)。例如用来决定要不要 pad 矩阵,以及在 max-autotune 之前先把 Triton 候选砍到 top-10。模型置信度不够时退回默认行为。收集训练数据”可能要一天”。 - cuBLASLt 启发式:
cublasLtMatmulAlgoGetHeuristic返回的候选”按预估耗时从小到大排序”,大多数调用方直接用第一个。NVIDIA 官方示例里的”autotuning”做法是要 8 个候选、每个测 5 次、取中位数最小的(示例),也就是”启发式先排序,再实测前几名”。CUTLASS 用 nvMatmulHeuristics 做同样的事:先用解析模型给 kernel 排序,只编译和测量其中一部分(heuristics.md)。 - cuDNN 启发式:
HEUR_MODE_A是一棵决策树;HEUR_MODE_B用一个小神经网络,CPU 开销高 10~100 倍;FALLBACK只保证能跑、不保证快(文档)。 - NCCL:选 AllReduce 等集合通信的算法(Ring / Tree / NVLS / CollNet / PAT)和协议(LL / LL128 / Simple)时,用的是内部代价模型而不是实测。每个候选的预估时间大致是
延迟 × 步数 + 字节数 / 带宽,选最小的(src/tuning/)。NCCL 允许用 tuner 插件(NCCL_TUNER_PLUGIN,接口见plugins/tuner/)改写这张代价表:插件拿到每个 (算法, 协议) 组合的预估代价,可以改数值或标记为不可用。这是”内置代价模型 + 外部可覆盖”的典型设计:集群运维可以根据自己网络的实测数据修正模型,而不用改 NCCL 本身。NCCL 文档同时提醒,NCCL_PROTO除了临时禁用疑似有问题的协议外不建议手动设置,在不支持的平台强制用 LL128 “可能导致数据损坏”。 - llama.cpp:整个仓库没有运行时 autotune。CUDA 后端选 kernel 全靠规则,例如
ggml_cuda_should_use_mmq(ggml/src/ggml-cuda/mmq.cu)根据 GPU 架构、是否有 int8 Tensor Core、batch 大小(以 64 为界)决定用自己的量化矩阵乘还是 cuBLAS;tile 宽度用”让 tile 数最少”的公式算出来。
优点:零调优时间,结果完全确定,跨机器可复现。
缺点:规则只对”见过的模式”好;新硬件、新形状上可能明显不是最优。
什么时候应该选这条路:kernel 的性能主要由几个可以算出来的量决定(wave 数、shared memory 占用、是否单 wave),并且你能接受偶尔损失几个百分点。MLC-LLM 的经历说明,一个好的规则系统可能比一份过期的调优数据库更好。
3.6 系统级参数搜索
这一层选的不是 kernel,而是整个服务怎么部署:TP/EP 怎么切、batch 上限多少、prefill 和 decode 要不要分开、各需要几张卡。一次测量就是一次完整压测,所以做法和 kernel 级很不一样。
- vLLM
benchmarks/auto_tune/auto_tune.sh:只搜max-num-seqs×max-num-batched-tokens两个参数,可以加 P99 端到端延迟上限和前缀缓存命中率下限作为约束。gpu-memory-utilization不在搜索范围内,脚本从 0.98 开始每次降 0.01,直到服务不 OOM 能启动为止。更通用的继任者是vllm bench sweep。 - NVIDIA AIConfigurator(ai-dynamo/aiconfigurator):先在真实硬件上把 GEMM、attention、通信等算子的耗时测一遍存成数据库,然后用插值把这些算子耗时拼成端到端耗时,在几千种部署配置(包括 P/D 分离)里搜索,最后输出 Dynamo 等框架的启动配置。也就是”算子级实测 + 系统级建模搜索”。
- Dynamo profiler:提供两档:
rapid用 AIConfigurator 模拟,约 30 秒、不需要 GPU;thorough真的把候选配置部署起来压测,要 2~4 小时。
这一层给 kernel 级 autotune 的启示是:当一次测量非常贵时,就用”测零件、拼整体”的代价模型来缩小范围,只对最后几个候选做真实测量。
3.7 一张对比表
| 系统 | 什么时候选 | 选什么 | 结果存在哪 | 最值得学的一点 |
|---|---|---|---|---|
| TensorRT-LLM | 服务启动 | CUTLASS tactic、后端、AllReduce 策略 | 进程内 + 可选 JSON | 多卡策略做成 4 种枚举,算子作者只选不写 |
| FlashInfer | 服务启动(被上层调用) | GEMM / MoE / attention tactic | JSON,加载时核对环境 | 缓存元数据记录 CUDA/cuBLAS/cuDNN 版本,不匹配就拒绝 |
| vLLM | 离线 JSON + 启动时调 FlashInfer | Triton config、FlashInfer tactic | 仓库 JSON + 按完整配置哈希分目录的缓存 | rank 0 读缓存后广播给所有卡 |
| SGLang | 同 vLLM | 同 vLLM | 按 Triton 版本分目录;缓存路径编码 TP/PP/EP | 各卡缓存不一致就全部丢掉重调;确定性推理模式下关掉 autotune |
| PyTorch Inductor | 编译期 | ATen / Triton / CUTLASS | 本地 + 远端缓存 | CUTLASS 在子进程测;全部失败退回 ATen |
| TunableOp | 首次调用或离线 | cuBLASLt / hipBLASLt solution | CSV,带版本校验行 | 可选数值校验;结果文件人能看懂、能手改 |
| Triton | 首次调用 | kernel config | 内存;可选写盘 | 原地修改输入的 kernel 要在每次测量前复位 |
| Helion | 开发期离线 | kernel config | 写回代码或 JSON | 默认开启精度检查;最终候选用长时间窗口重测 |
| DeepGEMM | 不测 | tile / stage / multicast | 无(JIT 缓存编译产物) | 代价模型 + 有序规则 |
| MLC-LLM / DLight | 不测 | 调度 | 无 | 规则调度替换调优数据库后性能不降反升 |
| TensorRT | 构建引擎时 | 每层的 tactic | timing cache 文件 | 缓存不匹配默认拒绝;可配置”缓存未命中就构建失败” |
| XLA | 编译期 | GEMM / 融合块的实现与 config | 可导出的结果文件 | 越界写检查 + 和可信实现对比结果 |
| cuDNN frontend | 调用方决定 | 执行计划 | 由调用方保存 | 有 errata 拒绝列表,可按版本和形状拉黑计划 |
| NCCL | 每次通信 | 算法与协议 | 无(代价模型) | 插件可改写代价表 |
| llama.cpp | 不测 | 量化矩阵乘还是 cuBLAS | 无 | 全部用规则,简单可预期 |
4. 设计一个 autotuner 要回答的十个问题
这一节是本文的核心。每个问题先说”要决定什么”,再说各家怎么做,最后给建议。
4.1 搜索空间:选什么
要决定的事:候选有哪些?怎么把明显不行的提前去掉?
常见做法:
- 先过滤不合法的。 tile 大小不能整除、shared memory 不够、对齐不满足的候选,在测量之前就去掉。Triton 的
prune_configs_by={'early_config_prune': fn}就是干这个的;FlashInfer 的get_valid_tactics()也要求实现者只返回当前形状下能跑的候选。 - 去掉已知有问题的。 FlashInfer 有一个
tactics_blocklist.py,记录已知会崩溃或结果错误的 CUTLASS tactic,测量前直接过滤。 - 用便宜的指标先砍一刀。 Inductor 发现某个 config 寄存器溢出超过阈值,直接判为无穷慢,不用测(对用户手写的 Triton kernel 不做这个剪枝,因为实测有反例)。Triton 的
perf_model+top_k用解析模型预排序;AutoHeuristic 用学到的决策树先挑 top-10。 - 组合太多时分阶段。 MoE 有两段 GEMM,如果对
(tactic1, tactic2)做笛卡尔积,可能有几百上千个组合。FlashInfer 的做法是先分别给两段 GEMM 排序各取前 K 个,再只对K × K组合测(rank_tactics())。 - 空间太大时换搜索算法。 Inductor 用坐标下降(每次只改一个参数,block 大小翻倍或减半);Helion 默认用一种基于分类器的贝叶斯优化(LFBO),能从”超时”和”精度不达标”的候选里也学到信息;TVM 用进化搜索 + 代价模型。
建议:
- 搜索空间的定义和算子实现放在一起,由算子作者负责。框架不要猜。
- 候选数量要有上限意识。在线(启动期)调优建议每个形状几十个候选以内;几百上千个只适合离线。
- 一定要保留一个”不指定”的兜底候选(TRT-LLM 和 FlashInfer 里是
tactic = -1),它必须对所有形状都能跑。
4.2 时机:什么时候选
| 时机 | 适合 | 不适合 |
|---|---|---|
| 离线,结果进仓库 | 模型和硬件组合固定、追求零启动开销 | 组合太多、更新太快 |
| 服务启动 | 通用框架默认方案 | 对冷启动时间极度敏感(如弹性扩缩容) |
| 编译期 | 静态形状或可预知形状的编译栈 | 强动态形状 |
| 首次调用 | 离线脚本、训练 | 在线推理服务 |
| 不测,用规则 | 性能能被几个量解释清楚的 kernel | 新硬件、规则没覆盖的形状 |
有一条硬约束:调优必须在 CUDA Graph 录制之前完成。
CUDA Graph 会把录制时实际发出的 kernel 和参数整个固化下来。如果录制时 autotuner 还在调优模式,图里录进去的可能是测量用的某个候选;如果录制时缓存还是空的,图里录进去的就是兜底实现。之后缓存怎么更新,图里的 kernel 都不会变。
三个主流框架都遵守这个顺序:
| 框架 | 顺序 | 位置 |
|---|---|---|
| vLLM | 编译尺寸 dummy run → kernel_warmup()(注释:”Warmup and tune the kernels … before cuda graph capture”)→ capture_model() | vllm/v1/worker/gpu_worker.py 的 compile_or_warm_up_model |
| SGLang | 每次 capture() 之前先跑 BaseRunner.warmup(),FlashInfer autotune 在其中 | python/sglang/srt/model_executor/runner/base_runner.py |
| TRT-LLM | attention warmup → 普通 / torch.compile warmup → _run_autotuner_warmup(with self.no_cuda_graph(), autotune(...))→ CUDA Graph warmup 两遍(第一遍把 workspace 撑到最大,第二遍录制) | tensorrt_llm/_torch/pyexecutor/model_engine.py 的 warmup |
库层面也有同样的限制:cuBLAS 的实验性 CUBLAS_GEMM_AUTOTUNE 在 stream capture 期间不能做测量,文档建议先调好再录图。
建议:
- 默认用”启动时调 + 写盘缓存”,第二次启动直接复用。
- 对高频部署的组合,额外提供离线预调结果。
- 启动流程的顺序固定为:加载模型 → 加载并核对缓存 → 调优 warmup → 保存缓存 → 录制 CUDA Graph → 开始服务。
4.3 分桶:形状怎么归类
真实请求的 token 数可以是任何值,不可能每个都测。分桶就是把它们归到少数几个代表值上。
要决定三件事:
- 桶怎么分布。 小 M(decode)性能对 M 很敏感,要分得密;大 M(prefill)已经是计算密集,分得稀一点就够。FlashInfer MoE 用的是三段式:
[1, 256]用 2 的幂,(256, 2048]步长 256,(2048, 4096]步长 512。只用 2 的幂的话,2048 到 4096 之间会有一个很大的空档。 - 真实值怎么映射到桶。 向下取整(floor)、向上取整(ceil)、最近邻三种:
- floor(TRT-LLM、FlashInfer 默认):用比实际略小的形状调出来的配置,通常在略大的形状上也能用。
- ceil(FlashInfer
make_bucket_mapper(..., round_map=True)):适合”tile 必须盖住整个形状”的 kernel。 - 最近邻(vLLM、SGLang 的 MoE JSON):直观,但调优脚本和查表规则要配套。
- 超出范围怎么办。 小于最小桶、大于最大桶的形状要落到边界桶,不能”查不到”。
最容易出错的地方:写表和查表用的规则不一致。 调优时以桶的代表值去测、写入缓存;推理时把真实形状映射到桶、去查缓存。这两步必须用同一个映射函数,否则会出现”调了但永远查不到”或者”查到的是另一个桶的结果”。这种错通常没有报错,只表现为性能不如预期。
两个和 LLM 相关的细节:
- 并行切分后的真实形状。 TRT-LLM 的 trtllm-gen MoE 在开启 attention DP 时,先把全局 token 数除以 EP size,再映射到桶。漏掉这一步,所有形状都会被系统性地映射到偏大的桶。
- 和 CUDA Graph 的 batch 尺寸对齐。 CUDA Graph 只会在若干个固定 batch 尺寸上录制。把调优桶设成和这些尺寸一致(vLLM 的 Helion 配置就是这样做的),可以保证每张图里用的都是专门为它调过的配置。
建议:
- 把分桶函数做成公共工具(FlashInfer 的
make_bucket_mapper是个好例子),不要让每个算子自己手写。 - 给分桶函数写单元测试:对每个桶代表值
b,map(b) == b;对桶之间的值,映射结果符合预期。
4.4 测量:怎么测才准
这是最需要细心的一步。kernel 越短,测量误差占比越大,越容易选错。
① 预热(warmup)。前几次运行包含 JIT 编译、内存分配、cache 冷启动,不能计时。TRT-LLM 默认 warmup 2 次、计时 10 次;FlashInfer 是 3 次 / 10 次;Triton do_bench 是按时间算,warmup 25 ms、计时 100 ms。
② 去掉 CPU 发射开销。微秒级的 kernel,CPU 发射时间可能比 kernel 本身还长。两种办法:
- 延迟 kernel:计时前先在 stream 上放一个空转 kernel(TRT-LLM 默认 1000 μs,FlashInfer 5000 μs),让 CPU 在它运行期间把后面所有 kernel 都排好队。这样起止 event 之间只有 GPU 时间。
- CUDA Graph:把 N 次运行录进一张图再回放。TRT-LLM 默认开,FlashInfer 默认关。注意是”录 N 次、回放一次”,不是”录一次、回放 N 次”。
③ L2 缓存是冷还是热。连续跑同一个 kernel,第二次开始输入数据已经在 L2 里,测出来会偏快。两种取舍:
- 冷 L2:每次运行前清掉 L2(Triton
do_bench每次清一个 256 MB 的 buffer;Inductor 按实际 L2 大小清),或者准备多份输入轮流用(TRT-LLM 的use_cold_l2_cache,TunableOp 的PYTORCH_TUNABLEOP_ROTATING_BUFFER_SIZE)。 - 热 L2:不清。TRT-LLM、FlashInfer 默认如此,部分原因是冷 L2 要额外占显存。
两种会选出不同的结果:冷 L2 偏向数据复用好的大 tile,热 L2 偏向小 tile。该用哪种取决于这个算子在真实模型里前面跑的是什么。 比如 decode 阶段权重通常远大于 L2,权重读取基本是”冷”的;而激活值可能刚被上一个 kernel 写进 L2,是”热”的。没有一个通用答案,但你的框架应该让算子作者能选,并且在文档里写清楚默认值是哪种。
④ 多次测量怎么汇总。
| 系统 | 汇总方式 |
|---|---|
| Triton autotune | 中位数(调用 do_bench 时取 0.5 分位) |
| Inductor | 最小值 |
| TRT-LLM / FlashInfer | 平均值 |
| TensorRT builder | 多组平均值里取最小 |
cuDNN frontend autotune() | 最小值;一次运行没能比当前最小值快 5% 以上就提前停止 |
| cuBLASLt 官方示例 | 中位数 |
| XLA | 每个候选只计时一次 |
| NVBench(NVIDIA 的 benchmark 库) | 平均值,相对标准差低于 0.5% 才停止(默认至少 10 个样本、至少 0.5 秒) |
可以看到没有统一答案。最小值对偶发干扰(别的进程、时钟波动)最不敏感,但偏乐观;中位数比较稳;平均值容易被一次异常拉偏。候选之间差距在 2% 以内时,选谁基本是噪声决定的,这时应该用一个和速度无关的标准来打破平局:
- Inductor 有
min_speedup_threshold:非默认实现必须比 ATen 快到一定比例才会被采用; - XLA 在与最快者相差 2 μs 以内的候选里,选用临时显存最少的那个。
⑤ GPU 频率和温度。GPU 会根据功耗和温度调整频率。Helion 的文档提到,在 B200 这类功耗受限的 GPU 上,用 50~200 ms 的短时间窗口测量,会把最终候选的排名搞错 3%~6%。所以 Helion 在最终选择阶段先做 5 秒的热身,再用 4 轮、每轮 500+500 ms 的窗口交替测量。
TensorRT 的优化指南给出了另一种办法:锁定 GPU 频率(sudo nvidia-smi -lgc <频率>,用完 -rgc 恢复),并增加计时次数,可以让 tactic 选择更稳定。NVBench 会检测降频:实测频率低于默认频率的 75% 时丢弃这个样本。锁频适合离线调优和 benchmark;在线服务一般不锁频,这时离线和在线的频率条件不同,结果可能有偏差,这一点要心里有数。
⑥ 测得短一点。启动期调优的总时间直接影响服务启动。TRT-LLM 的做法:先跑 2 次试探,单次超过 1 ms 就不再跑满 10 次(慢 kernel 噪声占比小,多测意义不大),可用 TLLM_AUTOTUNER_DISABLE_SHORT_PROFILE=1 关掉。Inductor 先估一次耗时,再反推迭代次数,把每个候选的测量控制在 25 ms 左右。TileLang 的 early_stop 在预估时间已经超过当前最优的若干倍时直接跳过。
⑦ 假输入要像真输入。启动期调优时真实请求还没来,只能造假数据。大部分 GEMM 对数据内容不敏感,但以下几类算子很敏感:
- MoE:均匀随机的路由会让每个专家拿到差不多的 token,真实分布却是严重倾斜的。负载不同,最优 tile 也不同。FlashInfer 的
TuningConfig有inputs_pre_hook和tensor_initializers让算子作者注入更真实的分布,还有value_aware_input_indices标记”内容会影响性能”的输入。 - 全零输入:某些 kernel 遇到零会走快速路径,测出来不真实。TRT-LLM 源码注释明确写了不能用全零张量。
- EP 下的路由:vLLM 在 autotune warmup 时特意随机化输入,注释说如果所有 token 都选同一批专家,有的 EP rank 收不到 token、直接跳过 MoE kernel,就会和其他 rank 的同步计时对不上而卡死。
建议:
- 测量函数做成一个公共实现,所有算子共用。不要让每个算子自己写计时代码。
- 默认值:warmup ≥ 2 次,延迟 kernel 或 CUDA Graph 二选一去掉 CPU 开销,至少 10 次计时,用中位数或最小值。
- 允许算子作者按算子选择冷/热 L2 和输入构造方式,并要求他们在数据敏感的算子上显式提供输入钩子。
4.5 正确性:最快的不一定是对的
autotune 的目标只有”快”,它不会检查结果对不对。这在以下情况会出事:
- 某个 CUTLASS tactic 在特定形状下有 bug,算出来的数是错的;
- 某种 AllReduce 策略在特定 buffer 大小下会读到旧数据,跑得飞快但结果错误(FlashInfer 的 PCIe IPC AllReduce 在返回候选列表之前会先跑一遍正确性检查,就是为了这个);
- 原地修改输入的 kernel 被连续跑了很多次,后面几次的输入已经被前面改坏了。
各家的做法:
| 手段 | 例子 |
|---|---|
| 调优时做数值校验 | TunableOp PYTORCH_TUNABLEOP_NUMERICAL_CHECK="1e-5_1e-5"(默认关);Helion autotune_accuracy_check=True(默认开,atol/rtol=1e-2);TileLang 给了 ref_prog 就先校验再计时 |
| 提前拉黑 | FlashInfer tactics_blocklist.py |
| 隔离崩溃 | Inductor 的 CUTLASS 候选、Helion 的 benchmark 都在子进程里跑 |
| 失败记无穷慢 | TRT-LLM、FlashInfer、Triton 都把抛异常或资源不足的候选记为 inf 继续 |
| 复位被修改的输入 | Triton 的 reset_to_zero / restore_value |
| 越界写检查 | XLA 在输出 buffer 前后各留一段”红区”(默认 8 MiB),候选写到红区就判为不合格 |
| 和可信实现对比 | XLA 把所有候选的输出按误差容限分组,最大的那组里必须包含一个”可信”实现(比如 cuBLAS),组外的候选标记为 WRONG_RESULTS;cutlass_profiler 可以用 cuBLAS / cuDNN 作参考做校验 |
| 按版本拉黑 | cuDNN frontend 的 errata 文件(CUDNN_ERRATA_JSON_FILE)按算子、引擎、cuDNN 版本范围、形状屏蔽某些执行计划 |
| 精度门槛 | TensorRT 11 trtexec 的 --loadRefOutputs + --accuracyThreshold |
XLA 的做法值得多说一句:它不是简单地拿”第一个实现”当参考,而是要求参考实现本身是可信的。如果你的兜底实现也可能有 bug,用它当参考就会把错误当正确。
一个容易漏掉的细节:CUDA 的”粘性错误”。 有些错误(比如非法内存访问)会让整个 CUDA context 进入不可用状态,之后所有调用都失败。在同一个进程里测一个会越界的候选,可能把后面所有候选连同服务本身一起拖垮。这是 Inductor 把 CUTLASS 放进子进程测的原因。如果你的框架不方便用子进程,至少要做到:一个候选出错后立刻同步并检查 context 是否还可用,不可用就终止调优、退回兜底实现。
建议:
- 框架提供一个可选的”调优时数值校验”开关,参考输出用兜底实现算。新增 kernel 时打开,CI 里也打开。
- 已知有问题的候选用拉黑表管理,拉黑表进仓库、带原因注释。
- 对通信类、原地修改类算子,算子作者必须在
get_valid_tactics或测量钩子里自己保证正确性。
4.6 多卡一致:每张卡必须选同一个
为什么会不一致:每张卡独立测量,测量有噪声。两个候选差距很小时,卡 0 可能选 A,卡 1 选 B。
不一致的后果:
- 对纯本地算子(普通 GEMM),通常只是各卡性能略有差异;
- 对通信算子(AllReduce),各卡用的通信方式不同,结果可能直接错,或者卡死;
- FlashInfer 的源码注释给了一个更隐蔽的例子:tactic 不一致会让 NCCL 对称内存的分配对不上,导致死锁。
三种解决办法,通常要组合使用:
- 测量时间跨卡汇总再选。FlashInfer 的
set_autotune_process_group(group)让每个候选的耗时在组内取平均,然后每张卡都用同一组数字选最小的。TRT-LLM 的DistributedTuningStrategy.MERGE也是跨卡合并时间。vLLM、SGLang 都用 CPU(gloo)组来做这个汇总,避免和 GPU 上的 NCCL 通信混在一起。 - 一个人测,广播给大家(TRT-LLM
BROADCAST)。或者把候选分给各卡并行测再汇总(TRT-LLMPARALLEL),候选很多时能缩短调优时间。 - 进入调优前让缓存一致。vLLM 由 rank 0 读缓存文件,
broadcast_object发给所有 rank。SGLang 先在各卡上算缓存摘要做all_gather,只要有一张卡不一样就全部删掉从头调(_drop_diverged_autotune_cache)。
跨卡汇总有一个必须遵守的约定(FlashInfer set_autotune_process_group 的注释写得很清楚):每张卡必须以相同的顺序、相同的次数进入测量函数。这意味着:
- 每张卡上的候选列表、形状桶、跳过的算子必须完全相同;
- 每张卡进入调优时的缓存必须相同(一张卡命中缓存跳过了测量,其他卡还在等它的汇总,就卡死了);
- 出错路径也要参与汇总:某张卡上某个候选崩了,不能直接
continue,要带着inf去参加这一轮汇总; - 不能有”某张卡因为 kernel 很慢就少测几次”的分支。TRT-LLM 在
MERGE模式下专门关掉了”慢 kernel 少测几次”的优化(代码里的and strategy != MERGE),就是为了避免各卡走进不同分支。
汇总用平均值还是最小值:通信算子的真实耗时由最慢的那张卡决定。取平均比取最小保守;取最大最贴近真实但对噪声敏感。卡之间互联不均匀时(跨 NUMA、跨节点),这个选择会影响结果。
建议:
- 把多卡策略做成有限的几种,让算子作者选,而不是让他们自己写通信(TRT-LLM 的思路)。
- 默认对所有算子做”时间跨卡汇总”,用 CPU 组。代价很小,能避免一整类问题。
- 加一个启动期断言:调优结束后,各卡对每个缓存条目的选择做一次哈希比对,不一致就报错。
4.7 持久化:结果怎么存
缓存键里应该有什么。原则是:任何会让”最优候选”或”候选编号的含义”发生变化的东西都要放进去。
| 类别 | 内容 | 不放会怎样 |
|---|---|---|
| 算子身份 | 算子名、实现者类名、实现者的关键属性(dtype、是否 gated、量化布局) | 不同配置的算子命中同一条缓存 |
| 形状 | 映射后的桶,不是原始形状 | 缓存命中率极低 |
| 硬件 | GPU 型号或 SM 版本 | H100 的结果被用在 B200 上 |
| 软件版本 | 框架版本、CUDA、cuBLAS、cuDNN、Triton 版本 | 升级后候选编号含义变了,选到了另一个 kernel |
| 并行配置 | TP / PP / EP / DP size | 每张卡上的 GEMM 形状、专家数不同 |
| 模型与量化 | 模型路径或结构、量化方式 | 同一个算子名对应不同的实际计算 |
几个做得好的例子:
- FlashInfer 的缓存文件带
_metadata,记录 FlashInfer、CUDA、cuBLAS、cuDNN、cuDNN frontend 版本和 GPU 名称。源码注释解释了为什么要记 cuDNN frontend 版本:tactic 存的是 cuDNN 计划列表里的下标,而 frontend 单独升级也可能改变列表顺序。load_configs发现不匹配就拒绝加载。 - SGLang 的缓存路径是
<cache>/flashinfer/autotune/<flashinfer版本>/<sm架构>/<哈希>/rank_tp{}_pp{}_dp{}.json,哈希里包含模型路径、dtype、量化、MoE 后端、TP/PP/attention-DP/EP size、模型类名、跳过的算子列表。 - vLLM 直接用整个 vLLM 配置的编译哈希(
aot_compile_hash_factors)做目录名,配置有任何变化就换目录。 - Triton 写盘时的键是 Triton 版本、目标硬件、kernel 源码、相关环境变量、调优键和所有候选的哈希。
- TunableOp 的 CSV 文件开头有
Validator行,记录 PyTorch、ROCm、hipBLASLt 等版本,任何一个变了整个文件作废。 - TensorRT 官方文档说 timing cache 和”设备、CUDA 版本、TensorRT 版本、BuilderConfig 参数”都绑定。
- XLA 的设备描述里连 SM 数、GPU 时钟、显存带宽、L2 大小都放进去了,比只记 GPU 型号更细:同一型号不同功耗/频率版本的卡也会被区分开。
一个反例:TRT-LLM 的缓存文件里记录了 device_name、device_capability、lib_version,但加载时 _deserialize_metadata 只是把它们读出来覆盖到自身,没有比较。把一台 H200 上生成的缓存拷到 B200 上,它会照常使用。
文件写入要安全:
- 原子写:先写临时文件,再
os.replace改名。vLLM 的write_flashinfer_autotune_cache就是这样做的。写到一半进程被杀,也不会留下半个文件。 - 多进程同时写同一个文件要加锁。TRT-LLM 用
fcntl文件锁,并且是”读出来 → 合并 → 写回”,而不是直接覆盖。 - 或者干脆按 rank 分文件(SGLang 的做法),从根上避免并发写。
结果从哪里来,可以分层查。FlashInfer 的 search_cache 按顺序查:
- 进程内缓存(本次调优的结果);
- 用户显式加载的文件(
load_configs()或autotune(cache=...)); - 随包发布的预调结果(需要设置
FLASHINFER_AUTOTUNER_LOAD_FROM_FILE=1,默认不开); - 兜底(
tactic=-1)。
建议:
- 缓存键宁可多放,不要少放。多放的代价是命中率下降、多调几次;少放的代价是悄悄用错。
- 加载时必须核对元数据。不匹配时默认丢弃并打日志,而不是报错退出。
- 缓存文件用人能读懂的格式(JSON / CSV),方便排查和手工修改。
4.8 成本:怎么控制调优时间
启动期调优太慢,会直接影响服务的冷启动和扩容速度。常用手段:
| 手段 | 例子 |
|---|---|
| 缓存复用 | 所有框架都支持写盘,第二次启动直接加载 |
| 只测需要的形状 | TRT-LLM skip_dynamic_tuning_buckets 只测 warmup 中实际出现的形状 |
| 慢 kernel 少测几次 | TRT-LLM 单次 > 1 ms 时只测 2 次 |
| 按时间预算定次数 | Inductor 每个候选约 25 ms;TunableOp PYTORCH_TUNABLEOP_MAX_TUNING_DURATION_MS 默认 30 ms |
| 提前放弃明显慢的 | TileLang early_stop |
| 跳过某些算子 | FlashInfer autotune(skip_ops=...);vLLM 在用 CuTe-DSL FP4 GEMM 时默认跳过 fp4_gemm,注释说它会给每个候选都做一次 JIT 编译,而它的兜底本来就是启发式 |
| 并行编译候选 | Inductor 在 worker 进程里并行编译;TileLang 用 90% 的 CPU 核并行编译 |
| 多卡分摊 | TRT-LLM PARALLEL 把候选分给各卡 |
| 不同调优强度 | Helion 的 autotune_effort:none / quick(文档说简单 kernel 约 3 秒)/ full(文档说通常约 10 分钟) |
建议:
- 打印每个算子的调优耗时和总耗时,先知道时间花在哪。
- 给整个启动期调优设一个总预算(例如 120 秒),超时的算子直接用兜底,并在日志里写清楚。
- 对需要 JIT 编译的候选格外小心,编译时间往往远大于测量时间。
4.9 确定性与复现
问题:autotune 的结果依赖测量噪声,同一个模型在同一台机器上启动两次,可能选出不同的 kernel。不同 kernel 的浮点累加顺序不同,输出可能有细微差别。对需要逐位复现的场景(对拍、调试、某些评测)这是不可接受的。
SGLang 的做法:开启确定性推理(enable_deterministic_inference)时直接关掉 FlashInfer autotune。源码注释说得很直白:调出来的配置是按问题形状分的,所以累加顺序会跟着 batch 形状变。
PyTorch 的做法:AutoHeuristic 的 pad_mm 判断在 config.deterministic 打开时启用学到的规则,代替依赖测量的路径。
XLA 的做法(determinism 文档):先调一次并把结果存下来,之后打开 --xla_gpu_require_complete_aot_autotune_results,缓存里查不到就直接报错,而不是现场再调。这保证了”每次运行用的 kernel 都来自同一份文件”。
TensorRT 的提醒:即使用同一个 timing cache,在某些模式下”选出的 tactic 和格式仍可能不同”;TensorRT 11 的全局调优 README 也明确说构建结果”不是逐位确定的”,应该发布构建好的引擎,而不是指望重新构建能得到同样的结果。也就是说,真正可复现的是产物,不是过程。
建议:
- 提供”确定性模式”:关掉在线调优,只用固定的缓存文件或规则。
- 提供”固定结果”的方式:把一次调优的结果导出,以后指定这个文件启动,不再重调。
- 在日志里记录每个算子最终选了谁,复现问题时能对上。
4.10 可观测性与可调试性
autotune 选错了,往往没有任何报错,只是”性能不如预期”。所以可观测性很重要:
| 需要 | 例子 |
|---|---|
| 打印选择结果 | TRITON_PRINT_AUTOTUNING=1;DeepGEMM DG_PRINT_CONFIGS=1 |
| 命中/未命中统计 | 推理时缓存未命中多少次、落在哪些形状上 |
| 一键关闭 | TRT-LLM enable_autotuner=False;SGLang --disable-flashinfer-autotune;vLLM VLLM_TRITON_FORCE_FIRST_CONFIG=1 |
| 强制指定候选 | 调试时绕过调优,强制用某个 tactic,排除”是不是选错了” |
| 录制与重放 | TRT-LLM 的 capture/replay 可以把一次调优中遇到的所有 (算子, 形状, 候选) 记下来,之后逐个重放做正确性测试 |
| 监听回调 | Triton knobs.autotuning.listener |
建议:至少做到前三项。推理时缓存未命中尤其要统计,它通常意味着分桶范围没覆盖到真实流量。
5. 实操:给框架新增一个可调算子
下面以一个通用的 runner 接口为例(形式上接近 TRT-LLM / FlashInfer),说明加一个新算子要做哪几步。
第 1 步:实现 runner
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
class MyGemmRunner(TunableRunner):
def __init__(self, dtype, use_bias):
self.dtype = dtype
self.use_bias = use_bias
def get_valid_tactics(self, inputs, profile):
"""只返回在当前形状下合法、且不在拉黑表里的候选。"""
m, k = inputs[0].shape
n = inputs[1].shape[0]
tactics = [t for t in ALL_TACTICS
if t.fits_smem() and n % t.tile_n == 0]
tactics = [t for t in tactics if t.id not in BLOCKLIST]
return tactics + [-1] # -1 兜底,必须始终可用
def forward(self, inputs, tactic=-1):
if tactic == -1:
return default_gemm(*inputs)
return launch_gemm(*inputs, config=tactic)
def cache_key_extras(self, inputs):
"""所有影响 kernel 选择、但不体现在形状上的信息。"""
return (str(self.dtype), self.use_bias)
要点:
get_valid_tactics只做便宜的静态过滤,不要在这里跑 kernel(通信类算子的正确性筛选除外)。-1兜底必须对所有形状都能跑。- 缓存键里的”runner 身份”要手动列出。不要把对象的所有属性都塞进去:像 rank 编号、对象地址这类东西混进去,会导致多卡之间、多次启动之间键不一样。FlashInfer 的
ProfilingCacheKey明确把runner_hash排除在写盘的键之外,就是因为它可能含对象地址。
第 2 步:描述调优配置
1
2
3
4
5
6
7
8
9
10
11
12
13
GEMM_TUNING = TuningConfig(
dynamic_tensor_specs=(
# 第 0 个输入的第 0 维(token 数)是动态的
DynamicTensorSpec(
input_idx=0, dim_idx=0,
buckets=(1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192),
map_to_bucket=floor_to_bucket, # 写表和查表共用
),
),
use_cold_l2_cache=False, # 想清楚:真实模型里这个算子前面是什么
inputs_pre_hook=None, # 数据敏感的算子必须提供
distributed_strategy="merge_time",
)
要点:
- 桶的上限要覆盖
max_num_tokens,下限是 1。 - 如果这个算子的耗时和数据内容有关,必须提供
inputs_pre_hook。 - 如果并行切分会改变单卡上的真实形状,要把切分逻辑写进映射函数。
第 3 步:在算子调用处接入
1
2
3
4
5
def my_gemm(a, b, bias=None):
runner = MyGemmRunner(a.dtype, bias is not None)
runner, tactic = AutoTuner.get().choose_one(
"mylib::gemm", [runner], GEMM_TUNING, [a, b])
return runner.forward([a, b], tactic=tactic)
推理时 choose_one 只做一次查表;调优模式下才会真的去测。
第 4 步:确认 warmup 能覆盖到这个算子
启动期调优只会调到 warmup 前向里实际走过的算子。确认:
- warmup 的 dummy 输入能走到这个算子(比如 MoE 的某个分支、speculative decoding 的 draft 模型);
- warmup 的形状能触发所有桶(或者调优框架会根据桶自动生成形状)。
第 5 步:写测试
| 测试 | 内容 |
|---|---|
| 所有候选的正确性 | 对每个桶、每个候选,和兜底实现对比输出 |
| 分桶一致性 | 对每个桶代表值 b,map(b) == b;调优写入的键和推理查表的键相同 |
| 缓存往返 | 写盘 → 新进程加载 → 选择结果相同 |
| 多卡一致 | 多卡调优后各卡选择相同 |
| 兜底可用 | 关掉 autotune 后结果正确 |
| 端到端性能 | 开/关 autotune 的端到端吞吐和延迟对比 |
第 6 步:文档
在算子旁边写清楚:搜索空间从哪来、为什么用 floor/ceil、冷还是热 L2、是否数据敏感、多卡策略是什么。这些决定在代码里很难看出来,但出问题时第一个要查的就是它们。
6. 实操:新增一种调优策略
“策略”指的是框架层面的通用能力,比如新的搜索算法、新的分桶方式、新的多卡同步方式、新的测量方法。新增时建议按下面的问题自查。
6.1 新的搜索算法
例如从”全部测一遍”改成坐标下降、进化搜索、贝叶斯优化。
- 它解决的是什么规模的问题? 候选在一百以内,全测通常最好;上千才值得换算法。
- 每次测量的成本? 如果测一次要先 JIT 编译(Helion、TileLang、CuTe DSL),减少测量次数的价值很大。
- 结果的稳定性? 带随机性的搜索算法,两次跑可能结果不同。要固定随机种子,或者在最后对前几名重测。
- 能不能从失败里学? Helion 选 LFBO 的一个原因是:它是分类器,能利用”超时”和”精度不达标”的候选。
- 多卡下怎么办? 搜索路径依赖测量结果,各卡的搜索路径可能分叉。要么只在一张卡上搜然后广播,要么每步都同步测量结果。
6.2 新的分桶方式
- 写表和查表是否用同一个函数?
- 边界外的值落到哪?
- 是否和 CUDA Graph 的录制尺寸对齐?
- 并行切分后的形状是否正确?
- 改动后已有缓存是否需要作废?(分桶方式变了,缓存键的含义也变了,应该把分桶版本写进元数据。)
6.3 新的多卡策略
- 异常路径上,所有卡是否仍然参与同样次数的集合通信?
- 是否有依赖本卡测量结果的分支(比如”慢就少测”)?如果有,多卡下要关掉。
- 用 CPU 组还是 GPU 组通信?启动期一般用 CPU(gloo)组,避免和模型自己的 NCCL 通信冲突。
- 汇总用平均、最小还是最大?对通信算子要想清楚。
6.4 新的测量方法
- 冷 L2 还是热 L2?
- 如何去掉 CPU 发射开销?
- 汇总方式?
- 和旧方法比,在一组代表性算子上选出的结果有多大差别?差别大的地方要人工确认哪个更贴近端到端表现。
最终的验收标准永远是端到端性能,不是单算子的测量结果。一个新策略在单算子测量上更”准”,不代表端到端更快。
7. 一个最小的参考实现
下面把前面的要点组合成一个大约 120 行的骨架,用来说明各部分怎么连起来。它省略了很多工程细节,不能直接用。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
import os, json, tempfile, torch, torch.distributed as dist
INF = float("inf")
class AutoTuner:
def __init__(self, warmup=3, repeat=10):
self.warmup, self.repeat = warmup, repeat
self.cache = {} # key -> (runner_idx, tactic)
self.tuning = False
self.group = None # CPU 组,用于跨卡汇总时间
self.stats = {"hit": 0, "miss": 0}
# ---------- 缓存键 ----------
def _key(self, op, runner, inputs, cfg):
bucketed = tuple(cfg.bucketize(inputs)) # 写表、查表共用
return (op, type(runner).__name__,
runner.cache_key_extras(inputs), bucketed)
# ---------- 唯一入口 ----------
def choose_one(self, op, runners, cfg, inputs):
keys = [self._key(op, r, inputs, cfg) for r in runners]
for i, k in enumerate(keys):
if k in self.cache:
self.stats["hit"] += 1
r_idx, tactic = self.cache[k]
return runners[r_idx], tactic
if not self.tuning:
self.stats["miss"] += 1
return runners[0], -1 # 兜底
return self._tune(op, runners, cfg, inputs, keys)
# ---------- 调优 ----------
def _tune(self, op, runners, cfg, inputs, keys):
best = (INF, 0, -1)
for profile_inputs in cfg.make_inputs_for_buckets(inputs):
for r_idx, r in enumerate(runners):
for tactic in r.get_valid_tactics(profile_inputs):
t = self._measure(r, tactic, profile_inputs, cfg)
t = self._sync_time(t) # 失败的 inf 也要参与
if t < best[0]:
best = (t, r_idx, tactic)
k = self._key(op, runners[best[1]], profile_inputs, cfg)
self.cache[k] = (best[1], best[2])
r_idx, tactic = self.cache.get(keys[0], (0, -1))
return runners[r_idx], tactic
def _measure(self, runner, tactic, inputs, cfg):
try:
if cfg.check_numerics:
ref = runner.forward(inputs, tactic=-1)
out = runner.forward(inputs, tactic=tactic)
if not torch.allclose(out, ref, atol=cfg.atol, rtol=cfg.rtol):
return INF
for _ in range(self.warmup):
runner.forward(inputs, tactic=tactic)
batches = cfg.rotate_inputs(inputs) if cfg.cold_l2 else [inputs]
start = torch.cuda.Event(enable_timing=True)
end = torch.cuda.Event(enable_timing=True)
times = []
for i in range(self.repeat):
delay_kernel(1000) # 让 CPU 先排好队
start.record()
runner.forward(batches[i % len(batches)], tactic=tactic)
end.record()
times.append((start, end))
torch.cuda.synchronize()
ts = sorted(s.elapsed_time(e) for s, e in times)
return ts[len(ts) // 2] # 中位数
except Exception as e:
torch.cuda.synchronize() # 清掉错误状态
log_warning(f"tactic {tactic} failed: {e}")
return INF
def _sync_time(self, t):
if self.group is None:
return t
x = torch.tensor([t], dtype=torch.float64)
dist.all_reduce(x, op=dist.ReduceOp.MAX, group=self.group)
return x.item()
# ---------- 持久化 ----------
def save(self, path, metadata):
data = {"_metadata": metadata,
"entries": [[list(k), v] for k, v in self.cache.items()]}
fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path))
with os.fdopen(fd, "w") as f:
json.dump(data, f, default=str)
os.replace(tmp, path) # 原子写
def load(self, path, metadata):
with open(path) as f:
data = json.load(f)
if data.get("_metadata") != metadata:
log_warning("autotune cache metadata mismatch, ignored")
return
self.cache.update({tuple(k): tuple(v) for k, v in data["entries"]})
服务启动流程:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
def start_server(model, cfg):
tuner = AutoTuner.get()
meta = collect_metadata() # GPU、框架/CUDA/cuBLAS 版本、TP/EP、量化……
# 1. rank 0 读缓存,广播给所有卡,保证进入调优时缓存一致
blob = read_file(cfg.cache_path) if rank == 0 else None
blob = broadcast_object(blob, src=0)
if blob:
tuner.load_from_bytes(blob, meta)
# 2. 调优(必须在 CUDA Graph 录制之前,且关掉 CUDA Graph)
if cfg.enable_autotune and not cfg.deterministic:
tuner.group = cpu_world_group()
tuner.tuning = True
with no_cuda_graph(), torch.inference_mode():
model.dummy_forward(num_tokens=cfg.max_num_tokens, randomize=True)
tuner.tuning = False
tuner.group = None
assert_same_across_ranks(hash(tuple(sorted(tuner.cache.items()))))
if rank == 0:
tuner.save(cfg.cache_path, meta)
# 3. 录制 CUDA Graph
model.capture_cuda_graphs(cfg.graph_batch_sizes)
# 4. 开始服务;定期上报 tuner.stats["miss"]
serve(model)
这里多卡汇总用了 MAX(以最慢的那张卡为准),这是为了在骨架里说明”汇总方式是一个要选的东西”。FlashInfer 用平均值,TRT-LLM 的 MERGE 是另一种合并方式,各有道理。
8. 上线前检查清单
新增或修改 autotune 相关代码时,可以逐条对照:
时机
- 调优在 CUDA Graph 录制之前完成,并且调优期间关掉了 CUDA Graph
- 推理路径上没有”首次遇到新形状就现场测”的逻辑
- warmup 前向能走到所有可调算子(包括 draft 模型、MoE 各分支)
分桶
- 写表和查表用的是同一个映射函数
- 桶覆盖
[1, max_num_tokens],边界外的值有明确去处 - 并行切分(EP/DP)后的真实形状被正确计算
- 桶和 CUDA Graph 录制尺寸的关系是清楚的
测量
- 有 warmup;用延迟 kernel 或 CUDA Graph 去掉了 CPU 开销
- 冷/热 L2 的选择有理由,并写进了注释
- 数据敏感的算子提供了贴近真实的输入
- 不用全零输入
正确性
- 所有候选在所有桶上的正确性测试通过(CI 里打开数值校验)
- 失败的候选记为
inf,不会让调优中断 - 原地修改输入的算子在每次测量前复位输入
多卡
- 各卡进入调优时缓存相同
- 测量时间跨卡汇总,异常路径也参与汇总
- 没有依赖本卡测量结果的分支
- 调优结束后各卡的选择做了一致性检查
持久化
- 缓存键包含:算子、runner 身份、桶、GPU、软件版本、并行配置、量化
- 加载时核对元数据,不匹配就丢弃
- 原子写;多进程写同一文件有锁或按 rank 分文件
可运维
- 能一键关闭 autotune 回到兜底
- 有确定性模式
- 日志里能看到每个算子选了谁、调优花了多久
- 推理时缓存未命中有统计
9. 常见问题
Q:开了 autotune,性能反而变差了?
先关掉 autotune 对比确认。常见原因:① 写表和查表的分桶不一致,实际一直在用兜底;② 测量用的是热 L2,真实场景是冷的(或反过来);③ 假输入和真实分布差太多(MoE 最常见);④ 用了别的 GPU 或别的版本生成的缓存。
Q:多卡启动时卡死在 autotune 阶段?
几乎都是”各卡进入集合通信的次数不一样”。检查:各卡的缓存是否一致、跳过的算子是否一致、某张卡上某个候选是否抛了异常后直接跳过了汇总、EP 下是否有卡收不到 token 而跳过了 kernel。
Q:每次启动选出的 kernel 不一样?
两个候选性能接近时这很正常。如果需要稳定,固定使用缓存文件,或者在选择时加一个”必须快出 X% 才换掉默认”的阈值。
Q:要不要把调优结果提交进仓库?
对少数高频部署组合(主力模型 × 主力 GPU)值得做,并在文件名或元数据里写清楚版本。其余情况用启动期调优 + 本地缓存。记住 SGLang 的教训:按版本分目录能保证正确,但每次升级都要重调,人力跟不上就会留下大量空洞。
Q:规则和调优怎么选?
先看能不能写出一个”大体对”的规则。如果性能主要由 wave 数、shared memory、是否单 wave 这类可计算的量决定,规则通常足够(DeepGEMM、DLight)。调优适合规则难以覆盖的情况:多种后端互相比较、通信算法选择、新硬件上还没有经验的时候。两者也可以结合:用规则把候选砍到个位数,再实测(Inductor + AutoHeuristic、cuBLASLt 启发式 + 实测前几名)。
Q:autotune 和 CUDA Graph 是什么关系?
CUDA Graph 把 kernel 的选择固化了。所以调优必须在录制前完成,录制后再调没有意义。另外调优本身也可以用 CUDA Graph 来提高测量精度,这是另一回事。
参考资料
源码
- TensorRT-LLM AutoTuner:
tensorrt_llm/_torch/autotuner.py;warmup 触发点tensorrt_llm/_torch/pyexecutor/model_engine.py - FlashInfer AutoTuner:
flashinfer/autotuner/autotuner.py;flashinfer/tactics_blocklist.py - vLLM:
vllm/model_executor/warmup/kernel_warmup.py、vllm/model_executor/warmup/flashinfer_autotune_cache.py、vllm/model_executor/layers/fused_moe/fused_moe.py、benchmarks/kernels/benchmark_moe.py、vllm/kernels/helion/ - SGLang:
python/sglang/srt/model_executor/runner/flashinfer_autotune.py、python/sglang/srt/layers/moe/moe_runner/triton_utils/configs/ - PyTorch Inductor:
torch/_inductor/select_algorithm.py、torch/_inductor/runtime/benchmarking.py、torch/_inductor/runtime/coordinate_descent_tuner.py - PyTorch TunableOp:
aten/src/ATen/cuda/tunable/README.md - PyTorch AutoHeuristic:
torchgen/_autoheuristic/README.md - Triton:
python/triton/runtime/autotuner.py、python/triton/testing.py - Helion:
helion/autotuner/、docs/deployment_autotuning.md - TileLang:
tilelang/autotuner/tuner.py - DeepGEMM:
csrc/jit_kernels/heuristics/ - TensorRT:
include/NvInfer.h、samples/trtexec/README.md - XLA:
xla/debug_options_flags.cc、autotune_cache_key.h - cuDNN frontend:
graph_interface.h、cudnn_frontend_Errata.h - NCCL:
src/tuning/、plugins/tuner/ - CUTLASS:
heuristics.md、profiler.md - AITER:https://github.com/ROCm/aiter
- AIConfigurator:https://github.com/ai-dynamo/aiconfigurator
- llama.cpp:
ggml/src/ggml-cuda/mmq.cu - NVBench:
docs/cli_help.md
文档与讨论
- TVM MetaSchedule:https://tvm.apache.org/docs/deep_dive/tensor_ir/tutorials/meta_schedule.html
- TVM DLight:https://tvm.apache.org/docs/deep_dive/tensor_ir/tutorials/dlight_gpu_scheduling.html
- MLC-LLM 移除 MetaSchedule 数据库:https://github.com/mlc-ai/mlc-llm/pull/670
- Triton autotune 结果写盘:https://github.com/triton-lang/triton/pull/6261
论文
- AutoTVM:https://arxiv.org/abs/1805.08166
- Ansor:https://arxiv.org/abs/2006.06762
- MetaSchedule:https://arxiv.org/abs/2205.13603
- LFBO(Helion 默认搜索算法的基础):https://arxiv.org/abs/2206.13035
- KernelBench:https://arxiv.org/abs/2502.10517