Post

LLM 推理框架的 Autotune 设计指南:各家最佳实践与可落地的设计要点

面向刚入门的推理框架开发者,把 TensorRT-LLM、FlashInfer、vLLM、SGLang、PyTorch、Triton、Helion、TensorRT、XLA、TVM、DeepGEMM、NCCL 等系统里的 autotune 做法放在一起对照,整理成"什么时候选、怎么分桶、怎么测准、怎么保证对、多卡怎么一致、结果怎么存"十个设计问题,并给出新增可调算子与新增调优策略的步骤和检查清单。

LLM 推理框架的 Autotune 设计指南:各家最佳实践与可落地的设计要点

这篇文章写给要设计或维护 LLM 推理框架的开发者,特别是刚接触 kernel 调优的人。目标是让你读完之后能回答三件事:

  1. 现在主流的推理框架和编译器,autotune 各自是怎么做的;
  2. 自己设计一个 autotune 系统,要做哪些决定,每个决定有哪些坑;
  3. 要给框架加一个新的可调算子、或者加一种新的调优策略,具体该怎么动手。

文中关于各框架的结论,凡是能对到源码或官方文档的都给了文件位置或链接。调研时用到的代码版本:

项目版本日期
TensorRT-LLM73ee6b0b192026-08-31
vLLM8e92248f792026-08-31
SGLang8bb776dc482026-08-30
PyTorch66bec7c1d3b2026-08-31
FlashInfer0.6.18(pip 包)—
Triton / Helion / TileLang / DeepGEMMGitHub main2026-10 ~ 2026-11

各项目迭代很快,具体的默认值、函数名、环境变量可能在你读到时已经变了。设计思路比具体数字更值得记住。


0. 先给结论:十条最重要的经验

如果只有五分钟,读这一节就够了。后面每一条都有展开。

  1. 调优的开销要放在服务上线之前。 要么离线调好随代码发布,要么在服务启动阶段调完。不要让第一个真实请求去承担调优时间。
  2. 调优必须在 CUDA Graph 录制之前完成。 CUDA Graph 会把当时选中的 kernel 固化进图里,录完之后再选也改不了。
  3. “测的时候”和”用的时候”必须落到同一个形状桶。 写表和查表要共用同一套折算函数,这是最隐蔽也最常见的错误来源。
  4. 最快的候选不一定是对的。 调优只比较速度,不检查结果。要么提前过滤掉已知会出错的候选,要么在调优时做数值校验。
  5. 某个候选跑崩了,记成”无穷慢”然后继续。 不要因为调优让服务起不来。
  6. 多卡必须选出同一个结果。 测量有噪声,各卡单独选会选出不同的 kernel,轻则性能抖动,重则通信对不上、整个服务卡死。
  7. 缓存键要把所有影响结果的东西都放进去:GPU 型号、库版本、数据类型、量化方式、并行度。加载缓存时要核对,对不上就丢掉。
  8. 输入数据长什么样会影响测量结果。 全零或均匀随机的输入在 MoE、稀疏、提前退出类算子上会测出错误的结论。
  9. 不是所有地方都值得测。 规则或代价模型能算出接近最优答案的地方(DeepGEMM、MLC-LLM 的 DLight),直接用规则更省事、更稳定。
  10. 调优结果要可见、可复现、可关闭。 打日志、能导出、能固定、能一键关掉退回默认实现。

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 还是 XQAInductor 模板选择、FlashInfer 多 runner、TRT-LLM 多 runner
③ 算法变体是否 split-K、是否 swap-AB、AllReduce 用 one-shot 还是 two-shotFlashInfer 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 tacticJSON,加载时核对环境缓存元数据记录 CUDA/cuBLAS/cuDNN 版本,不匹配就拒绝
vLLM离线 JSON + 启动时调 FlashInferTriton config、FlashInfer tactic仓库 JSON + 按完整配置哈希分目录的缓存rank 0 读缓存后广播给所有卡
SGLang同 vLLM同 vLLM按 Triton 版本分目录;缓存路径编码 TP/PP/EP各卡缓存不一致就全部丢掉重调;确定性推理模式下关掉 autotune
PyTorch Inductor编译期ATen / Triton / CUTLASS本地 + 远端缓存CUTLASS 在子进程测;全部失败退回 ATen
TunableOp首次调用或离线cuBLASLt / hipBLASLt solutionCSV,带版本校验行可选数值校验;结果文件人能看懂、能手改
Triton首次调用kernel config内存;可选写盘原地修改输入的 kernel 要在每次测量前复位
Helion开发期离线kernel config写回代码或 JSON默认开启精度检查;最终候选用长时间窗口重测
DeepGEMM不测tile / stage / multicast无(JIT 缓存编译产物)代价模型 + 有序规则
MLC-LLM / DLight不测调度无规则调度替换调优数据库后性能不降反升
TensorRT构建引擎时每层的 tactictiming cache 文件缓存不匹配默认拒绝;可配置”缓存未命中就构建失败”
XLA编译期GEMM / 融合块的实现与 config可导出的结果文件越界写检查 + 和可信实现对比结果
cuDNN frontend调用方决定执行计划由调用方保存有 errata 拒绝列表,可按版本和形状拉黑计划
NCCL每次通信算法与协议无(代价模型)插件可改写代价表
llama.cpp不测量化矩阵乘还是 cuBLAS无全部用规则,简单可预期

4. 设计一个 autotuner 要回答的十个问题

这一节是本文的核心。每个问题先说”要决定什么”,再说各家怎么做,最后给建议。

4.1 搜索空间:选什么

要决定的事:候选有哪些?怎么把明显不行的提前去掉?

常见做法:

  1. 先过滤不合法的。 tile 大小不能整除、shared memory 不够、对齐不满足的候选,在测量之前就去掉。Triton 的 prune_configs_by={'early_config_prune': fn} 就是干这个的;FlashInfer 的 get_valid_tactics() 也要求实现者只返回当前形状下能跑的候选。
  2. 去掉已知有问题的。 FlashInfer 有一个 tactics_blocklist.py,记录已知会崩溃或结果错误的 CUTLASS tactic,测量前直接过滤。
  3. 用便宜的指标先砍一刀。 Inductor 发现某个 config 寄存器溢出超过阈值,直接判为无穷慢,不用测(对用户手写的 Triton kernel 不做这个剪枝,因为实测有反例)。Triton 的 perf_model + top_k 用解析模型预排序;AutoHeuristic 用学到的决策树先挑 top-10。
  4. 组合太多时分阶段。 MoE 有两段 GEMM,如果对 (tactic1, tactic2) 做笛卡尔积,可能有几百上千个组合。FlashInfer 的做法是先分别给两段 GEMM 排序各取前 K 个,再只对 K × K 组合测(rank_tactics())。
  5. 空间太大时换搜索算法。 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-LLMattention 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 数可以是任何值,不可能每个都测。分桶就是把它们归到少数几个代表值上。

要决定三件事:

  1. 桶怎么分布。 小 M(decode)性能对 M 很敏感,要分得密;大 M(prefill)已经是计算密集,分得稀一点就够。FlashInfer MoE 用的是三段式:[1, 256] 用 2 的幂,(256, 2048] 步长 256,(2048, 4096] 步长 512。只用 2 的幂的话,2048 到 4096 之间会有一个很大的空档。
  2. 真实值怎么映射到桶。 向下取整(floor)、向上取整(ceil)、最近邻三种:
    • floor(TRT-LLM、FlashInfer 默认):用比实际略小的形状调出来的配置,通常在略大的形状上也能用。
    • ceil(FlashInfer make_bucket_mapper(..., round_map=True)):适合”tile 必须盖住整个形状”的 kernel。
    • 最近邻(vLLM、SGLang 的 MoE JSON):直观,但调优脚本和查表规则要配套。
  3. 超出范围怎么办。 小于最小桶、大于最大桶的形状要落到边界桶,不能”查不到”。

最容易出错的地方:写表和查表用的规则不一致。 调优时以桶的代表值去测、写入缓存;推理时把真实形状映射到桶、去查缓存。这两步必须用同一个映射函数,否则会出现”调了但永远查不到”或者”查到的是另一个桶的结果”。这种错通常没有报错,只表现为性能不如预期。

两个和 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 对称内存的分配对不上,导致死锁。

三种解决办法,通常要组合使用:

  1. 测量时间跨卡汇总再选。FlashInfer 的 set_autotune_process_group(group) 让每个候选的耗时在组内取平均,然后每张卡都用同一组数字选最小的。TRT-LLM 的 DistributedTuningStrategy.MERGE 也是跨卡合并时间。vLLM、SGLang 都用 CPU(gloo)组来做这个汇总,避免和 GPU 上的 NCCL 通信混在一起。
  2. 一个人测,广播给大家(TRT-LLM BROADCAST)。或者把候选分给各卡并行测再汇总(TRT-LLM PARALLEL),候选很多时能缩短调优时间。
  3. 进入调优前让缓存一致。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 按顺序查:

  1. 进程内缓存(本次调优的结果);
  2. 用户显式加载的文件(load_configs() 或 autotune(cache=...));
  3. 随包发布的预调结果(需要设置 FLASHINFER_AUTOTUNER_LOAD_FROM_FILE=1,默认不开);
  4. 兜底(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 来提高测量精度,这是另一回事。


参考资料

源码

文档与讨论

论文

This post is licensed under CC BY 4.0 by the author.