KernelAgent Fuser 流水线解析:extract、dispatch、compose 三阶段 GPU 内核融合生成
KernelAgent Fuser 流水线解析:extract、dispatch、compose 三阶段 GPU 内核融合生成
KernelAgent 是一款面向 GPU 内核自动生成的开源多智能体框架,其中 Fuser 流水线 是它的核心。本文将带你看懂 Fuser 如何通过 extract → dispatch → compose 三个阶段,把一个 PyTorch 模型拆成可融合子图,再为每个子图生成经验证的 Triton 内核,最后合成端到端程序。无需深入 GPU 细节,跟随三张"工件图"即可掌握全流程。
一、Fuser 流水线是什么?为什么要分三阶段?
Fuser 是 KernelAgent 中负责"端到端内核融合生成"的子系统,入口在 Fuser/pipeline.py。它解决一个核心矛盾:手写高性能 GPU 内核(Triton/CUDA)门槛极高,而 LLM 一次性写完整个大模型的推理内核又容易出错、难验证。
Fuser 的思路是把"大问题"拆成"小问题":
- extract(提取):把原始 PyTorch 模型重写并识别出所有可融合子图,标注精确的输入/输出形状。
- dispatch(分发):把每个子图交给 KernelAgent,并行生成、编译并跑测试验证对应的 Triton 内核。
- compose(合成):用一个 LLM 把所有已验证的子图内核"拼"回一个完整程序,使其与原模型数值等价。
💡 关键设计:每个子图内核都是独立验证过的,最后合成时只做"组装 + 适配",大幅降低一次性生成失败的概率。
三阶段由 run_pipeline() 顺序串联,最终工件全部落在 .fuse/<run_id>/ 目录下。
二、整体架构:一次运行会产出哪些工件?
理解三阶段,先看它们的"交接物"。每次运行会创建一个 run 目录,逐阶段往里写文件:
.fuse/<run_id>/
orchestrator/ # 阶段①:Fuser 编排器 + 融合后的 PyTorch 代码
result.tar.gz # 内含 code.py(融合后的模型)
subgraphs.json # 阶段①:去重后的"形状特化"子图描述
kernels_out/ # 阶段②:每个子图一个目录
<subgraph_id>/
problem.txt # 该子图的精确任务描述
kernel.py # 生成并通过测试的 Triton 内核
summary.json # 每个子图的成败汇总
compose_out/ # 阶段③:最终合成产物
composed_kernel.py # 端到端 Triton 程序 + 自检
composition_summary.json
这套"每个阶段都落盘"的设计带来两大好处:可复现(可单独重跑某个内核会话)和可调试(能翻阅每个环节的 prompt 与 response)。
三、阶段一:extract 提取子图
extract 是整个流水线里最"重"的一步,它内部又分两小步:
第 1 小步:用 Fuser 编排器改写模型
调用 extract_subgraphs_to_json() 会先拉起 Orchestrator。它并行启动多个 Worker(进程池,见 Fuser/worker.py),每个 Worker 反复让 LLM 把 PyTorch 模块重构成"可融合的子图模块",并实际运行来验证数值正确性。第一个跑通测试的 Worker 成为"胜者",其融合代码被打包成 result.tar.gz。
🎯 这里采用"多路竞速"策略:4 个 Worker 各带不同变体(
variant_index)同时尝试,谁先PASS谁赢,其余立即取消——既提速又提高成功率。
第 2 小步:让 LLM 吐出"子图 + 形状"的 JSON
拿到融合代码后,流水线再用一次 LLM 调用(prompt 构造见 _build_llm_prompt_for_shapes()),让它输出一个 JSON 数组,每个元素描述一个唯一子图,包含:ops(算子序列)、input_shape/output_shape、weights_fused、dtype、data_layout 等。
随后 _dedup_by_shape_signature() 按"形状签名"去重:只要输入/权重/输出形状相同,就归为同一子图并累加 count。这一步至关重要——它让 dispatch 阶段只为"形状不同"的子图各生成一个内核,避免重复劳动。
subgraphs.json 长什么样?
每个子图大致如下(字段已精简):
{
"id": "sg_0001",
"type": "conv_bn_relu",
"data_layout": "NCHW",
"dtype": "float32",
"ops": [
{ "op": "conv2d", "stride": [1,1], "padding": [0,0], "groups": 1 },
{ "op": "batch_norm" },
{ "op": "relu" }
],
"input_shape": [B, 64, 56, 56],
"output_shape": [B, 64, 56, 56],
"weights_fused": { "weight": [64, 3, 3, 3], "bias": [64] },
"count": 5
}
count: 5 表示这种形状的子图在模型里出现了 5 次——dispatch 阶段只需要生成一份内核复用。
四、阶段二:dispatch 分发并生成内核
dispatch 读取 subgraphs.json,对每个子图做两件事,核心函数是 run():
1. 把 JSON 转成"精确的生成任务"
_synthesize_problem_description() 会把子图 JSON 翻译成一段人话任务描述,并自动生成一段 PyTorch 参考实现(由 _build_reference_code() 完成)。它内置了对常见算子的处理:conv2d、conv_transpose2d、relu/tanh/sigmoid、max_pool2d、avg_pool2d、batch_norm、group_norm、add、gemm 等。
📌 任务描述里强制写明了容差策略(默认
rtol=1e-3, atol=1e-3,上限1e-2)和设备要求(如device='cuda'),从源头约束生成内核的数值行为。
2. 并行启动 KernelAgent 生成 + 验证
每个子图独立实例化一个 TritonKernelAgent(4 个 Worker、多轮迭代),调用 generate_kernel()。该内核会经过编译、单元测试,只有测试打印 PASS 且退出码为 0 才算成功,结果内核写入 <subgraph_id>/kernel.py。
并发由 --dispatch-jobs 控制:
| 取值 | 行为 |
|---|---|
数字(默认 2) |
最多同时处理 N 个子图 |
auto |
并发数 = 子图数量(全量并行) |
最终汇总到 kernels_out/summary.json,记录每个子图的 success / kernel_path / 失败原因。
五、阶段三:compose 合成端到端内核
compose 是"把积木拼回大楼"的一步,入口是 compose()。它的输入是三样东西:原始问题文件、subgraphs.json、kernels_out/summary.json(从中只挑出 success: true 的内核)。
1. 构造合成 prompt
_build_composition_prompt() 把以下内容喂给 LLM:
- 子图摘要(形状、算子)
- 原始 PyTorch 问题文件
- 每个子图内核的完整源码
并给出硬性要求:输出单个 Python 文件,内含至少一个 @triton.jit 内核 + 顶层 kernel_function(...) 包装器 + 一个自检(用 PyTorch 参考对比,成功打印 PASS 并退出 0)。它强调"优先把子图尽量融合成更少的内核启动,且不得回退到 torch.nn 等 PyTorch 算子"。
2. 自动修补 + 验证迭代
拿到代码后,_auto_patch_common_triton_issues() 会先做几个保守的文本修补(例如把 tl.broadcast(0.0, ...) 替换成标量 0.0,并剥离平台相关的 CUDA hack)。
若开启 --verify,每次尝试都会真实执行(走 Fuser/runner.py),失败则用 _build_refinement_prompt() 把 stderr 尾部 + 上次代码一起回喂给 LLM 继续修,最多迭代 --max-iters 轮。最终产物是 compose_out/composed_kernel.py 与 composition_summary.json。
六、一条命令跑完全流程
三阶段也可以手动分别跑(便于调试),但日常使用推荐一键式:
python -m Fuser.pipeline \
--problem /abs/path/to/problem.py \
--extract-model gpt-5 \
--dispatch-model o4-mini \
--dispatch-jobs auto \
--compose-model o4-mini \
--workers 4 \
--max-iters 5 \
--verify
常用参数速查:
| 参数 | 作用 | 默认值 |
|---|---|---|
--problem |
KernelBench 问题文件路径(必填) | — |
--extract-model |
阶段①提取模型 | gpt-5 |
--dispatch-model |
阶段②内核生成模型 | 按级别自动选 |
--dispatch-jobs |
子图并发数,auto=全量并行 |
2 |
--compose-model |
阶段③合成模型 | o4-mini |
--workers |
阶段①并行 Worker 数 | 4 |
--verify |
对最终合成内核执行验证 | 关闭 |
🔄 自动路由:如果不确定该走哪条路,可用 Fuser/auto_agent.py 做静态分析(解析 AST、检测 attention / 转置卷积 / 控制流等),自动选择"直接走 KernelAgent"或"完整 Fuser 流水线",并在首条路径失败时回退到另一条。
七、三阶段职责速览
| 阶段 | 核心文件 | 输入 | 输出工件 | 一句话职责 |
|---|---|---|---|---|
| extract | subgraph_extractor.py | PyTorch 模型 | subgraphs.json |
拆出唯一子图 + 形状签名去重 |
| dispatch | dispatch_kernel_agent.py | subgraphs.json |
kernels_out/*.py |
并行生成并验证每个子图内核 |
| compose | compose_end_to_end.py | 模型 + 子图 + 内核 | composed_kernel.py |
合成端到端 Triton 程序并自检 |
八、小结:Fuser 流水线的设计精髓
- 分而治之:把"写一个大内核"拆成"写很多个小内核再拼装",每块独立可验证。
- 形状特化 + 去重:用形状签名合并重复子图,生成更少的内核却能复用到模型所有同形位置。
- 多路竞速验证:extract 与 dispatch 阶段都用多 Worker 竞速,先
PASS者胜,提速又稳。 - 全程落盘可复现:每个阶段的 prompt、response、内核、日志都写入
.fuse/<run_id>/,便于复现与调试。
掌握这三阶段后,你既能一键跑 pipeline.py,也能用 auto_agent.py 让框架自己挑最优路径,把 PyTorch 模型真正"变成"高性能 Triton 内核。