# glm53_pd_chain：sglang 补丁树 vs 镜像原版差异（2026-09-08 快照）

## 这是什么

生产/实验容器通过 `-v /data/sglang_patch_glm53:/sgl-workspace/sglang` 挂载的补丁源码树
（宿主机 60.1/60.2 均有，无 `.git`）。本目录的 `sglang_patch_vs_image_20260908.patch`
是它与镜像 `lmsysorg/sglang:nightly-dev-20260828-daf63171`（digest
`sha256:28e0d26073161e49ca56eba808d264a4223804a212020f1dfe1b2405b9f8a399`）内置原版源码的
统一 diff，是这套补丁**唯一的版本记录**（宿主机树上没有 git 历史可查）。

生成方式（60.2 上，容器化 diff，pristine 在前保证 patch 语义为"打在原版上"）：

```bash
docker run --rm -v /data/sglang_patch_glm53:/host_patch:ro -v /tmp:/host_tmp \
  lmsysorg/sglang:nightly-dev-20260828-daf63171 bash -c \
  'diff -ruN --exclude=__pycache__ --exclude="._*" --exclude=.git \
   /sgl-workspace/sglang /host_patch > /host_tmp/pd_chain.patch'
```

## 改动清单（11 文件：10 改 + 1 新增）

主题 = **DFlash 家族（DFLASH/DSPARK）+ PP 流水 + PD 分离** 三者组合的解锁与修错。

| 文件（python/sglang/srt/ 下） | 改动 |
|---|---|
| `arg_groups/speculative_hook.py` | 放开 PP 断言：DFLASH/DSPARK 允许 pp>1（限 PD prefill/decode server） |
| `disaggregation/prefill.py` | 草稿 KV 跨机传输 opt-out（env `SGLANG_DFLASH_PD_DRAFT_KV_TRANSFER=0`）；PP 下仅最后一个 rank 持活草稿池、仅它注册 draft buffer；TP 不匹配时（MHA 头分片 → kv_item_lens 不同）会 RDMA 段失败/静默错位——注释里有完整推导 |
| `managers/scheduler_pp_mixin.py` | PP 末 rank 为 DFlash 家族构造 next_draft_input 并经 RelayPayload 中继（topk_p/index/hidden_states）；EAGLE 草稿中继路径；dflash 前后 set/clear pp_proxy_tensors |
| `managers/scheduler.py` | PP 投机分支：仅 pp_size==1 时做 D2H copy_to_cpu（末 rank 结果是 device 张量送 rank 0；非末 stage next_token_ids=None 直接拷会崩） |
| `model_executor/model_runner_components/layer_setup.py` | MTP 层守卫放行 dflash 家族（独立草稿模型不用目标模型原生 MTP 层） |
| `models/deepseek_v2.py` | DFLASH PP prefill：各 stage 原始 aux 捕获打包进 proxy_tensors["dspark_aux_hidden_states"]；`set_dflash_layers_to_capture` 改为按 consumer 入口捕获（+1 偏移，各 rank 只留本地 consumer） |
| `models/dflash.py` | 新增 `project_target_hidden_partial`：各 PP rank 只对自己捕获的特征列做 fc 部分投影，末 stage 求和并只做一次 hidden_norm（数学等价切片） |
| `server_args.py` | PP + 投机断言改写：仅允许 PD prefill server + DFLASH/DSPARK（#33863） |
| `speculative/dflash_pp.py` **新增** | `kimi_pp_capture_layer_ids`：Kimi 后置层流捕获归属下一 stage 的辅助函数 |
| `speculative/dflash_worker_v2.py` | PD-prefill 非末 PP rank = context-only（不做草稿 forward、无草稿 KV，只投影本地捕获特征）；草稿 worker 以 pp_size=1 构建；`_init_pp_context_features` |
| `speculative/spec_info.py` | DFlash PD 冷启动接线：disagg 草稿输入走 `build_dflash_family_disagg_draft_input`——无此项 decode 首请求 400 |

## 如何使用

- **部署**：不 apply patch，直接整树挂载（见 `deploy/PD_CHAIN.md` 基础设施依赖表）。
- **审阅/重建**：把镜像源码导出后 `patch -d <sglang仓根> -p2 < sglang_patch_vs_image_20260908.patch`
  （diff 两侧绝对路径去掉前两段后即仓内相对路径）。
- **漂移检测**：重跑上面的容器化 diff，与库内 patch 比对；不一致说明宿主机补丁树又被人改过，
  需要重新快照入库。