# PR #33143 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Replace Kimi K3 DeepGEMM patch with 0.1.5.post1
- 合并时间：2026-08-01 13:17
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/33143

---

# 执行摘要

- 一句话：DeepGEMM 0.1.5.post1 取代 Kimi K3 本地 SiTU 补丁
- 推荐动作：值得快速浏览，核心价值在于『上游正式支持后移除本地 hack』的维护模式：140 行补丁被两行 pip 安装替换。建议 K3 镜像维护者在合入后做一次 cu12/cu13 的端到端验证（至少启动与一轮生成），并用数值 / 输出对比确认官方 SiTU 与原补丁行为一致；另可确认 GitHub Releases 资产 URL 的长期可用性。

# 功能与动机

PR body 明确写着 Apply #33066 到 main，即把分支上的同一变更合入主干。此前 Kimi K3 的 MoE 需要 SiTU 激活，而 DeepGEMM 0.1.4.post1 的 MegaMoE JIT 头文件只支持 SwiGLU，仓库为此维护了一个利用 magic sentinel 值（activation_clamp == 0.03125，即 2^-5）在内核模板中触发 SiTU 分支的补丁脚本。脚本注释说明这是『no _C.so rebuild needed』的 runtime-JIT 方案，但本质上是对上游头文件的脆弱改写。DeepGEMM 0.1.5.post1 官方发布后，官方 MegaMoE runtime-JIT header 已内置 Kimi-K3 SiTU 支持，因此可以删除补丁、直接升级依赖。

# 实现拆解

1. 删除 docker/kimi_k3/apply_deepgemm_situ_patch.py（-140 行）。该脚本原先包含三态逻辑：检测到 v2 补丁则跳过、检测到已废弃的 v1 负 sentinel 补丁则迁移到 v2、未打补丁则用 OLD/NEW 字符串对 sm100_fp8_fp4_mega_moe.cuh 做原地替换；头文件布局变化时 raise SystemExit 避免静默打错。删除后镜像构建不再改写 dist-packages 中的头文件。
2. 修改 kimi_k3_cu13.Dockerfile：新增 ARG SGL_DEEP_GEMM_VERSION="0.1.5.post1"，将 RUN python3 apply_deepgemm_situ_patch.py 替换为 pip install --no-deps --force-reinstall sgl-deep-gemm==${SGL_DEEP_GEMM_VERSION}，并把构建说明从『DeepGEMM mega-MoE SiTU patch』更新为『升级到首个官方支持 Kimi-K3 SiTU 的发布版』。
3. 修改 kimi_k3_cu12.Dockerfile：同样新增 ARG 并替换安装命令；差异在于 PyPI 只发布 CUDA 13 构建，CUDA 12.9 环境改为从 sgl-project/whl 的 GitHub Releases 下载 sgl_deep_gemm-0.1.5.post1+cu129 whl 官方资产。
4. 无测试或运行时代码联动：变更仅在 docker/kimi_k3 目录内，属于纯镜像构建流程调整，编译器与运行时逻辑不变。

关键文件：
- `docker/kimi_k3/apply_deepgemm_situ_patch.py`（模块 补丁脚本；类别 infra；类型 deletion）: 本 PR 的核心动作：整文件删除 140 行补丁脚本。该脚本利用 magic sentinel 值在 DeepGEMM MegaMoE JIT 头文件中注入 Kimi-K3 SiTU 分支，并包含 v1->v2 迁移逻辑；删除后镜像构建不再改写上游头文件。
- `docker/kimi_k3/kimi_k3_cu13.Dockerfile`（模块 镜像构建；类别 infra；类型 infrastructure）: CUDA 13 构建线：新增 SGL_DEEP_GEMM_VERSION ARG，用 pip 安装 sgl-deep-gemm==0.1.5.post1 取代补丁脚本执行。
- `docker/kimi_k3/kimi_k3_cu12.Dockerfile`（模块 镜像构建；类别 infra；类型 infrastructure）: CUDA 12.9 构建线：同样替换补丁为官方版本安装，但因 PyPI 只有 CUDA 13 构建，改用 GitHub Releases 的 cu129 whl URL。

关键符号：未识别

## 关键源码片段

### `docker/kimi_k3/apply_deepgemm_situ_patch.py`

本 PR 的核心动作：整文件删除 140 行补丁脚本。该脚本利用 magic sentinel 值在 DeepGEMM MegaMoE JIT 头文件中注入 Kimi-K3 SiTU 分支，并包含 v1->v2 迁移逻辑；删除后镜像构建不再改写上游头文件。

```python
# docker/kimi_k3/apply_deepgemm_situ_patch.py —— 本 PR 中整个文件被删除（-140 行）
# 背景：DeepGEMM 0.1.4 的 MegaMoE JIT 头文件只支持 SwiGLU，
# Kimi-K3 需要 SiTU 激活，原脚本用 magic sentinel 值触发官方 JIT 模板：
# 宿主传入 activation_clamp = 0.03125（2^-5，可精确表示，合法 swiglu 的 clamp >= 0 不会误用），
# 内核侧 kActivationClamp == 0.03125f 时走 K3 常量（beta = 4.0, linear_beta = 25.0）的 SiTU 分支。

P = "/usr/local/lib/python3.12/dist-packages/deep_gemm/include/deep_gemm/impls/sm100_fp8_fp4_mega_moe.cuh"

# OLD / NEW 分别是原始 SwiGLU 块与注入 SiTU 分支后的新块（完整字符串被省略）
# V1_LINES / V2_LINES 是两代 sentinel 写法：v1 用负 clamp 作 sentinel，v2 改为 +0.03125 magic 值

s = open(P).read()
if V2_LINES in s:
    print("already patched (v2)")            # 幂等：已是最新补丁则跳过
elif V1_LINES in s:
    # 迁移已废弃的负 sentinel v1 -> magic value v2
    assert s.count(V1_LINES) == 1
    s = s.replace(V1_LINES, V2_LINES)
    open(P, "w").write(s)
    print("migrated v1 -> v2")
elif OLD in s:
    assert s.count(OLD) == 1                 # 防重入：确保只替换一次
    open(P, "w").write(s.replace(OLD, NEW))
    print("patched")
else:
    # 头文件布局变化时宁可失败退出，避免静默打错补丁导致运行时数值异常
    raise SystemExit("ERROR: expected SwiGLU epilogue block not found — header layout changed")

```

### `docker/kimi_k3/kimi_k3_cu13.Dockerfile`

CUDA 13 构建线：新增 SGL_DEEP_GEMM_VERSION ARG，用 pip 安装 sgl-deep-gemm==0.1.5.post1 取代补丁脚本执行。

```dockerfile
# docker/kimi_k3/kimi_k3_cu13.Dockerfile（重构后的相关段落）
# 基础镜像 sglang:v0.5.16 自带 DeepGEMM 0.1.4.post1，需显式升级

FROM lmsysorg/sglang:v0.5.16 AS base

# 新增可覆盖参数：DeepGEMM 升级到首个官方支持 Kimi-K3 SiTU 的版本 0.1.5.post1
ARG SGL_DEEP_GEMM_VERSION="0.1.5.post1"

# ... 中间省略 DeepEP patch 与 FlashInfer cubin 等无关步骤 ...

# --- 3. DeepGEMM：升级到首个官方支持 Kimi-K3 SiTU 的发布版 ---
# 原 apply_deepgemm_situ_patch.py 通过改写 JIT 头文件注入 SiTU 分支（sentinel 方式）；
# 现在 0.1.5.post1 的 MegaMoE runtime-JIT header 已官方支持，直接 pip 安装并删除补丁脚本。
RUN python3 -m pip install --no-deps --force-reinstall \
    "sgl-deep-gemm==${SGL_DEEP_GEMM_VERSION}"

```

# 评论区精华

该 PR 没有实质性的 review 讨论：Fridge003 直接批准（approved），唯一的评论是 gemini-code-assist[bot] 的停服公告，说明其代码审查活动已停止。因此没有关于数值等价性、URL 稳定性等话题的公开交锋。

- Gemini Code Assist bot 停服说明 (other): 无技术结论；Fridge003 已直接批准该 PR。

# 风险与影响

- 风险：
 1. 行为等价性风险：官方 0.1.5.post1 的 SiTU 实现（beta=4.0、linear_beta=25.0、fast-math 分支）与原补丁的数学形式是否完全一致，PR 内没有给出对拍证据，需在真实 Kimi K3 镜像上做解码质量或数值对比。
 2. 外部制品依赖：cu12 镜像从 GitHub Releases 拉取固定 whl URL，该 URL 由 sgl-project/whl 仓库托管，存在外部可用性与版本生命周期风险；pip 安装也依赖 PyPI 可用性。
 3. 缓存残留：原补丁脚本曾提示 /root/.cache/deep_gemm 会缓存 JIT 模板实例，若旧镜像层未清理，升级后的模板会因 sentinel 值不同而重新实例化，一般不会冲突，但脏缓存可能干扰排查。
 4. 影响面有限：改动全部集中在 docker/kimi_k3，不触碰 Python 运行时、调度或 kernel 代码，回归风险主要限制在 K3 镜像构建环节。
 - 影响：对用户：无直接运行时影响，Kimi K3 推理路径保持不变；对系统：K3 Docker 镜像构建从『安装后改头文件』变为『直接装官方发布』，减少 140 行补丁维护成本，也降低多节点镜像构建时补丁脚本执行失败的风险；对团队：后续升级 DeepGEMM 无需再同步补丁逻辑，且 cu13 与 cu12 两条构建线行为对齐（cu12 用官方 cu129 wheel）。影响程度为中等偏低，局限于部署 / 基础设施范畴。
 - 风险标记：依赖上游行为等价性未验证 , 外部制品下载依赖 , 镜像缓存需清理

# 关联脉络

- PR #33066 Replace Kimi K3 DeepGEMM patch with 0.1.5.post1（推断，原始标题未提供）: PR body 明确写有 Apply #33066 到 main，说明本 PR 是把 #33066 的同一变更从分支合入主干；原始 PR 的完整标题在提供材料中未列出。
- PR #32828 [Kimi] Support DCP + DSpark (ported from kimi-k3 branch): 同为 Kimi K3 相关支持 PR，说明 kimi-k3 分支有一系列特性通过独立 PR 向 main 迁移；本 PR 是其中纯构建 / 依赖的一环。