企业官网建设流程全解析

SGLang 内核融合与流重叠模式目录：Profiler 性能分析的 Triage 参考手册

【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang

本文介绍 SGLang 仓库中内置的融合（fuse）与重叠（overlap）模式目录fuse-overlap-catalog.md：它是.claude/skills/llm-torch-profiler-analysis分析技能在判定"某个 kernel 融合机会是否为新发现"之前必须查阅的源码级查找表。读完本文，你将掌握该目录的收录范围规则、五步 triage 判定协议、按优化家族组织的 19 个章节结构，以及如何结合 SGLang 源码中的开关（server args 与环境变量）验证某条融合路径究竟是缺失、被禁用还是尚未合入。

1. 这个目录是什么：内核级融合的"查重表"

该目录位于 .claude/skills/llm-torch-profiler-analysis/references/fuse-overlap-catalog.md，配套的主文档是同一技能目录下的 SKILL.md。后者定义了统一的torch.profilertrace 分析工作流：对sglang、vLLM、TensorRT-LLM、TokenSpeed四套推理框架，通过统一入口 scripts/analyze_llm_torch_profile.py 产出一张三表报告——kernel 表、overlap-opportunity 表、fuse-pattern 表，默认只渲染累计 GPU 时间占比 ≥1.0% 的行。

在报告中出现"若干分散的小 kernel 或许可以融合"这类线索时，技能规范要求先对照本目录做"查重"，而不是直接把结论说成新的优化机会。目录开头的定位声明明确了这一点：

This catalog is the source-backed lookup table that the profiler skill should consult before labeling a fuse or overlap opportunity as novel.

若分析只涉及 overlap 机会，还需同时加载 overlap-catalog.md（纯重叠视角的查找表）。

1.1 收录范围：严格限定在 kernel 层面

本版本目录刻意采用 kernel 级（kernel-scoped）收录标准，原文规则如下：

• 只保留能映射到一个融合后的 GPU/NPU kernel 家族、一个"集合通信 + kernel"融合家族、或一个 profiler 可见的 GPU kernel 间流重叠的行；
• 明确排除纯 host 侧的调度器（scheduler）、事件循环（event-loop）、executor、offload 与 load-path 模式。

同时，目录按"可复用的优化家族"分组，而不是按某个具体模型分组；其中 vLLM-origin 等章节属于对比参考（comparative references），这些代码不一定存在于当前 checkout 的 sglang 树中，但在判定"是否 novel"之前仍应被视为上游或同族 kernel 家族。文档还带有一次刷新记录（2026-06-26），核对了 SGLang、vLLM、TensorRT-LLM、TokenSpeed 的官方 main 提交，并把 vLLM 的 torch.compile pass 清单拆分到独立的 vllm-torch-compile-fusions.md 中维护。

2. 五步 Triage 判定协议

目录给出的使用方法（即分析一条 trace 发现时的判定流程）：

1. 从 triage 三张表出发，锁定 top 行；
2. 将 top 行与目录各表的Trace keywords和Primary code两列做匹配；
3. 若命中已有行，结论应二选一：
   • 这是一条已存在但缺失 / 被禁用 / 回退 / 当前后端不支持的优化路径；
   • 这是一个已知家族，应当把同样的融合重新应用到当前模型形状上；
4. 同时检查 mainline 对比章节与PR-backed / in-flight章节。若在那里命中，不得称之为 novel，应称为上游（upstream）或在途（in-flight）模式；
5. 只有当发现不符合本目录任何 mainline 或 PR-backed 行时，才能标记为 "new"。

SKILL.md 中对两 trace 工作流的要求与之一致：读表顺序为 kernel 表 → overlap 表 → fuse-pattern 表，且在宣布"新优化想法"之前，必须先对照本目录与 overlap-catalog 的 mainline 行、再看 in-flight 行。若没有精确匹配但整体形状接近某个已知家族，只允许在表后追加一条high/medium/low相似度注释，且要基于完整模式形状（producer-consumer 链、源码位置、CPU op 名、TP 上下文、模型结构）而非单个 kernel 名判断。

3. 目录的 19 章结构：按框架来源与融合类型分组

目录共 19 个章节，可归为五类：

每一行统一采用五列格式：Pattern（模式）、Trace keywords（trace 中的特征 kernel 名）、Primary code（主要代码位置）、Existing path（已存在路径描述）、Skill should conclude（技能应给出的结论）。下面挑几个代表性家族展开，并结合 SGLang 当前源码给出验证。

3.1 主干融合家族：从 trace 关键词到源码

§1 是体量最大的章节。选取几行说明其形态与当前代码对应关系：

• Fused residual add + RMSNorm：trace 关键词如fused_add_rmsnorm*、npu_add_rms_norm、gemma_fused_add_rmsnorm。现有路径是 CUDA / ROCm / CPU / NPU 共享的 add-RMSNorm 实现。结论：把拆开的 residual add + RMSNorm 视为"已有跨后端融合缺失"，而不是新想法。
• FlashInfer 统一allreduce_fusion：关键词cross_device_reduce_1stage*、FusedAddRMSNormKernel、rmsnorm*。代码入口为 layernorm.py 中的forward_with_allreduce_fusion（当前源码 L893、L1244 两处定义），配合 flashinfer_comm_fusion.py 的 workspace 创建和allreduce_fusion(..., pattern=AllReduceFusionPattern.kARResidualRMSNorm, ...)调用，以及 communicator.py 的apply_flashinfer_allreduce_fusion。结论：TP 场景下 all-reduce 与 RMSNorm 仍分开时，第一个怀疑对象是 FlashInfer allreduce fusion 缺失/被禁用/不支持，而不是"新的 TP 融合创意"。
• Fused activation-and-mul（SwiGLU/GeGLU）：关键词silu_and_mul、gelu_and_mul，对应 activation.py，单 kernel 覆盖激活 + 逐元素乘。
• Fused QK RMSNorm + RoPE：关键词qknorm*+rope*+rotary*分步出现时，对应 fused_qknorm_rope.py，一个 JIT kernel 对 packed QKV 原地做 QK RMSNorm 和 RoPE。
• Fused MoE dispatch / permute / combine：当 trace 出现 token permutation、dispatch/combine、大量小 MoE 支持 kernel 时，先查是否缺少FusedMoE风格路径或后端专属 dispatcher（DeepEP / FlashInfer / FuseEP 等）。
• Fused sampling temperature + softmax与Fused logit softcap：decode 批大小下分离的 temp 除法 + softmax、cast + softcap 阶梯，分别对应 Triton 单趟/多趟 kernel 与通用 softcap kernel 家族。

目录中部分行的Primary code路径（例如某些 router / sampling / elementwise 文件）在当前 checkout 中可能已移动或改组织，这正体现了"以刷新记录与 PR 状态为准"的维护约定；引用具体行时应当以 §19 刷新命令 重扫确认。

3.2 主干重叠家族：双流模式与 SBO

§2 收集了 SGLang 主干中的 kernel 重叠先例，每一行都给出了"技能应如何定论"：

• Single-batch overlap（SBO）：MoE combine 与 down-gemm、shared-expert 工作的邻近双流窗口，由 single_batch_overlap.py 实现，含显式 SM 分区与事件同步。结论：暴露的 MoE combine 若贴近邻近计算，先按 SBO 分类再谈新重叠。
• Q 与 K norm 分流：Q 留在当前流、K 可走alt_stream（capture 模式下），入口在 models/utils.py 的apply_qk_norm。
• DeepSeek shared-expert / routed-expert 重叠：shared experts 放alt_stream，与 dispatch/combine 及 down-gemm 重叠，Blackwell 上有专门的环境变量门控。
• Llama4 / ExaoneMoE / Grok 分支级重叠：shared expert 分支与 routed 分支、dense MLP 与 block-sparse MoE 分支并行，是"分支级双流重叠"的先例集合。
• MoriEP 异步 dispatch/combine：dispatch 与 combine 提交到专用通信流，仅通过 event 同步。
• Heterogeneous-TP staging scatter 重叠：decode 侧 staging scatter 可在专用scatter_stream上跑，见 staging_buffer.py 与 staging_handler.py。

3.3 VLM 与 Diffusion 章节：跨模态也受同一规则约束

§3 只有三行但很关键：vision 侧 QK norm 可以走共享的apply_qk_norm(...)并让 K 侧工作在aux_stream上（layers/attention/vision.py）；但当SGLANG_VIT_ENABLE_CUDA_GRAPH打开时，visionaux_stream是有意禁用的——因此 ViT CUDA graph 下"看不到视觉重叠"可能是设计如此，而不是回退。

§4–5 覆盖 diffusion 侧：fused_scale_residual_norm_scale_shift/fused_norm_scale_shift等 DiT 调制融合、Z-Image 的norm(x) * tanh(scale) + shift与 residual-gate 融合、LTX2 的 Ada values 物化融合（PR#29390）与residual + update * gate（PR#29361）、Nunchaku 的 fused GELU MLP；重叠侧则包括 Ulysses 序列并行 all-to-all、USP（all-to-all + ring attention）、Turbo-layer 的 pipelined A2A（async_op=True+ 通信流分阶段后处理）、TorchInductor 的reorder_for_compute_comm_overlap编译期重排，以及 dual-stream DiT 模型。

3.4 PR-backed / in-flight 行：上游在途工作的"状态快照"

§6、§7 是状态敏感的章节，目录明确规定"stable 条目应折叠回 mainline 行"。例如：

• PR#21877：grouped down-GEMM + DeepEP combine 融合。该路径一旦打开会有意禁用 SBO（因为 combine 窗口已被折叠进 down-GEMM），所以讨论"combine 重叠"时应先按这个上游 fused-overlap 家族分类；
• PR#22005：add + RMSNorm + per-token FP8 quant 的 CUDA JIT kernel，normed 值留在寄存器内同时输出 BF16 + FP8 与 per-token scale；
• PR#20667：Qwen3.5 ROCm/AITER 路径的 QK norm + RoPE + KV cache 写融合；
• PR#24150：把 torch.compile 覆盖扩展到 local decode 区域，Inductor 生成的融合可能取代手写小 kernel——因此 decode trace 中出现编译器生成 kernel 时，应先检查这条在途 compile 路径再下"该形状不支持"的结论。

§14–17 的 vLLM / TokenSpeed 来源行则回答了跨框架的问题：当 trace 形状像某个上游家族但当前 sglang 树里没有同样实现时（例如 vLLM 的fused_qk_norm_ropecompile pass、DSV3 专用 router GEMM、TokenSpeed 的 CuTe DSL MLA prefill/decode 与 MLA KV pack + FP8 quantize），结论应是"上游已存在该家族"，而不是本地新想法。

4. 开关与注意事项：为什么 trace 里的 kernel 形状会"不一样"

§18 是整份目录中实操价值最高的部分：同一个模型，仅因开关不同，trace 中的 kernel 形状会显著变化。阅读 trace 前必须先核对这些开关，否则会把"配置差异"误判为"融合缺失"。以下是与当前 SGLang 源码核对后的要点（完整列表以目录原文为准）：

此外目录还列出了 FlashInfer 侧（enable_pdl/launch_with_pdl、trigger_completion_at_end、use_cuda_graph、split_device_green_ctx*）、TensorRT-LLM 侧（rmsnorm_backend、insert_cached_attention.backend、TRTLLM_GEN_FUSED_MOE_USE_FLASHINFER、multi_stream_moe/multi_stream_mla_attn/multi_stream_gemm、mlir_elementwise_fusion）以及 vLLM 侧（PassConfig.fuse_allreduce_rms、fuse_norm_quant、fuse_act_quant、fuse_attn_quant、enable_qk_norm_rope_fusion、enable_sp、fuse_gemm_comms等）的对应开关。其中两条尤其值得记住：

• trigger_completion_at_end=False时，FlashInfer allreduce fusion 之后的下游 PDL-aware kernel 才能在同流上提前重叠；设为True会把 completion 推迟到 kernel 末尾，直接抹掉这个重叠窗口；
• PDL（Programmatic Dependent Launch）开启后，启动分组与同流重叠的 trace 形状会显著变化，因此跨 PDL 开关对比 trace 时必须先归一化。

5. 刷新与维护：目录不是静态的

§19 给出了维护者重扫本地源码树以刷新目录的命令清单（triage 脚本运行时不使用），核心模式是：

# 对 SGLang 主干按 trace 关键词重扫 rg -n "fused_add_rmsnorm|gemma_fused_add_rmsnorm|silu_and_mul|gelu_and_mul|fused_qk_rope_reshape_and_cache|fused_set_kv_buffer|fused_metadata_copy|normal_decode_set_metadata" python/sglang rg -n "FusedMoeRouter|fused_topk_deepseek|moe_fused_gate|fused_rms_fp8_group_quant|fast_topk_transform_fused|fused_temperature_softmax|fused_softcap" python/sglang # 对兄弟仓库做对比扫描（FlashInfer / TensorRT-LLM / vLLM） rg -n "AllReduceFusionPattern|allreduce_fusion|trigger_completion_at_end|rope_quantize_fp8|cutlass_fused_moe|trtllm_.*_moe" "$FLASHINFER_REPO/flashinfer" rg -n "multi_stream_moe|multi_stream_mla_attn|multi_stream_gemm|record_event_passthrough" "$TRTLLM_REPO/tensorrt_llm/_torch" rg -n "fuse_allreduce_rms|fuse_norm_quant|fuse_act_quant|fuse_attn_quant|enable_qk_norm_rope_fusion|fuse_rope_kvcache" "$VLLM_REPO/vllm" # 提交历史与 PR 扫描 git log --all --format='%h %s' | rg -i 'fused|fusion|overlap|cutedsl|triton|cuda|rope|topk|quant|combine|allreduce'

配合目录开头的刷新记录（记录各框架的 main 提交哈希与新增条目，例如 2026-06-26 刷新新增了 TokenSpeed-origin 的 CuTe DSL MLA、MLA KV pack+FP8 quantize、sampling、lm_head GEMM、NVFP4 GEMM+SwiGLU+quant 行，以及 LTX2 Ada-value diffusion 融合），可以推断出该目录的维护节奏：每次上游 main 前进后重扫、把已稳定的 in-flight 行折叠进 mainline 行、并更新刷新记录。对使用者而言，这意味着引用 in-flight 行前必须先重查 PR 状态，不能把在途工作当作已合入事实。

6. 小结：把它当作"先例库"而非"待办清单"

这份目录的设计意图可以概括为一句话：在宣称任何融合或重叠机会之前，先证明它不在本目录的任何 mainline 或 PR-backed 行里。它的价值来自三点：

1. 可验证的匹配依据——每行给出 trace 关键词与源码位置，可以直接用rg在当前树中复核（本文核对过forward_with_allreduce_fusion位于 layernorm.py，SGLANG_DSA_FUSE_TOPK（旧名SGLANG_NSA_FUSE_TOPK）定义于 environ.py 等）；
2. 开关感知的 trace 解读——§18 保证"看不到融合 kernel"这一观察在被下结论前先排除配置、确定性模式与后端选择因素；
3. 跨框架的 prior 覆盖——通过 FlashInfer / TensorRT-LLM / vLLM / TokenSpeed 对比行，避免在本地"重新发明"上游已有的 kernel 家族。

配合 SKILL.md 的单/双 trace 工作流与 overlap-catalog.md（overlap 专属表）、vllm-torch-compile-fusions.md（vLLM compile pass 清单），这份目录构成了对 SGLang 及其周边生态做 kernel 级性能 triage 时的完整"先例库"。

【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang