Skip to content

feat(specforge): 改用上游 capture 插件流程,镜像切到标准 CANN 镜像 - #276

Open
Devin-DC-Huang wants to merge 1 commit into
Ascend:mainfrom
Devin-DC-Huang:feat/specforge-plugin-capture-flow
Open

Devin-DC-Huang wants to merge 1 commit into
Ascend:mainfrom
Devin-DC-Huang:feat/specforge-plugin-capture-flow

Conversation

@Devin-DC-Huang

Copy link
Copy Markdown
Contributor

背景

上游 SpecForge 在 2026-11-07 的 capture 重构(#1063~#1066)把 server 端的 hidden-state 采集从「打补丁」改成插件:

  • #1065 删掉了 patches/sglang/v0.5.18/spec-capture.patch 与 scripts/apply_sglang_spec_capture_patch.sh
  • 改由 specforge-sglang-capture 插件接管
  • #1064 把 scripts/prepare_hidden_states.py 改成必须传 --server-urls

于是 specforge-quick-start / specforge-examples 从 2026-11-07 起连续转红:

smoke: FAILED - git apply -p1 --reject failed:
error: can't open patch '.../patches/sglang/v0.5.18/spec-capture.patch': No such file or directory

(examples 侧则是 setup: WARNING - apply_sglang_spec_capture_patch.sh missing → sglang serve: error: unrecognized arguments: --enable-spec-capture ...)

为什么必须换 SGLang

插件要求 SGLang 提供三个扩展点:

  • --enable-return-aux-hidden-states / --return-aux-hidden-state-layer-ids / --return-hidden-states-mode
  • ModelRunner.forward_observer
  • Scheduler.defer_response(req, completion)(sglang.srt.managers.deferred_output:ResponseCompletion)

它们来自 SGLang PR #43449 / #43450(2026-10-26/27 合入 main),任何已发布版本都没有(0.5.23 仍不具备),所以只能从源码构建。本文按上游 SpecForge CI 自己的钉法取 commit(SGLANG_COMMIT,在克隆到的 SpecForge/.github/workflows/test.yaml 里),保证插件与 SGLang 的 API 成对匹配——上游插件就是照着这个 commit 写的。

改动

文档(sources/specforge/quick_start.md):

  • 删掉「打补丁 + apt 依赖」整节
  • 新增「克隆 SpecForge 源码」「安装 SGLang(源码构建)」「安装 specforge 与 capture 插件」
  • capture server 换成插件流程:SPECFORGE_SPEC_CAPTURE=1 + --speculative-algorithm DFLASH --enable-return-aux-hidden-states --return-aux-hidden-state-layer-ids ... --return-hidden-states-mode full,并断言 /server_info 广播 spec_capture_backend=plugin
  • --mamba-ssm-dtype bfloat16:910B4 上 GDN 的 fp32 initial_state 不被 sgl_kernel_npu 支持(FP32 initial_state is only supported on Ascend950 (arch35))

配套的环境补齐(都踩过):

问题 处理
CANN 镜像没有 torch 新增「安装 torch / torch_npu」步骤(torch 2.10.0+cpu / torch_npu 2.10.0.post6,成对版本)
镜像自带的 sgl_kernel_npu 2026.6.1 缺 sgl_kernel_npu.activation.fused_sigmoid_mul 升级到 2026.9.0.post12 的 wheel
社区 triton 没有 triton.language.extra.cann 装昇腾 fork 的 triton-ascend
uv pip install -e . 会把 torch 升到 2.15(与 torch_npu 失配) 用 constraint 钉 torch 系列 2.10.0
mooncake 0.3.13.post1 的 Ascend transport 在 CANN 9.1.0 上装不上 钉 0.3.14
trainer 段没有 MOONCAKE_* → client 拿到 global_segment_size=0 train 段补上环境变量
CANN 镜像没有 unzip 改用 python zipfile 解压
GitHub release / git 抖动(HTTP2 framing error、GnuTLS recv error) git 走 HTTP/1.1 + 5 次重试;curl 加 --http1.1 --retry-all-errors -C -

镜像:SGLang 由文档自己构建,所以两个看护都从 sglang 专用镜像换成标准 CANN 镜像 ascendhub/cann:9.1.0-910b-ubuntu22.04-py3.12(与仓库其它 guard 一致)。

examples 看护同步到插件流程:setup_example.sh 装 torch 栈 + 源码构建 SGLang + 装上游插件,run_example.sh 的 capture server 换新参数并校验 spec_capture_backend=plugin。

验证

用仓库自带的 doc-test harness(tests/doc_test/base.py + tests/specforge/test_quick_start_ascend.py)按文档跑,两个环境各一轮,21 步全部通过:

环境 结果
CANN 9.1.0 / 910b / py3.12(无 torch、无 sglang) Ran 1 test in 1506s OK,step 1: ce_loss=12.7055,capture backend=plugin
sglang 专用镜像(CANN 9.0.0 / py3.11) Ran 1 test in 1420s OK,同样 ce_loss=12.7055

另外附了 scripts/verify_specforge_plugin_flow_on_coder.sh:不依赖 doc-test harness 的独立复现脚本(coder workspace 上直接跑)。

备注

  • 这条路线不打任何补丁,采集完全由上游插件负责
  • sgl-kernel-npu 的 wheel 按 (torch, CANN, 设备, python) 出包,上游目前只发到 CANN 9.1.0 / torch 2.10.0 / py3.12 的 910b;文档里 CANN 版本是运行时探测的,可以用 SGL_KERNEL_CANN_VER 覆盖
  • 等昇腾侧出「基于 sglang main 的 910b 镜像」后,文档里的 SGLang 源码构建步骤可以删掉

github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

📖 文档预览:https://ascend.github.io/docs/pr-preview/pr-276/sources/specforge/

也可打开整站首页。

构建自 3d1aca00a8244e89c3c6ba985e3c4a1b889d5b17。
每次推送后自动更新,PR 关闭时自动清理。

github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
@Devin-DC-Huang

Copy link
Copy Markdown
Contributor Author

状态

PR 已在 CI 上跑了几轮,目前:

  • specforge-quick-start / monitor + test on change:绿(文档 21 步在 CI 里全跑通)
  • specforge-examples:external 的 9 条 recipe 全绿;offline/colocated 与 managed-local 的 3 条还在收敛中

CI 这几轮帮我抓到的、已经修掉的问题(都是这条新流程暴露出来的):

问题 修复
sgl-kernel-npu wheel 404 CANN 版本改成运行时探测(写死 9.0.0 会拼出上游没发过的 cann9.0.0-py312-910b)
capture server 起不来:No module named 'orjson' guard 装 SGLang 改成带依赖安装(之前 --no-deps)
同上 加 triton-ascend(社区 triton 没有 triton.language.extra.cann)
同上 torch 系列用 constraint 钉在 2.10.0(否则解析器把 torch 升到 2.15,与 torch_npu 失配)
pip: no such option: --reinstall pip 用 --force-reinstall(--reinstall 是 uv 的 flag)
offline 腿:prepare_hidden_states.py: error: the following arguments are required: --server-urls 上游 #1064 把 offline 客户端改成 capture server 的客户端,offline 分支也要拉起 mooncake + capture server
managed-local 腿:capture-server-0 exited with status -9 managed-local 把 server / trainer / mooncake master 放同一容器,插件流程下多出来的 mooncake segment/buffer 顶爆主机内存 → manifest 里把 segment / buffer 调小

一点说明

新流程下 examples 的每条腿都要自己装一遍 SGLang(源码构建 + 13 MB wheel + 全量依赖),单腿 20-30 分钟。等昇腾侧出了「基于 sglang main 的 910b 镜像」之后,文档和 guard 里的 SGLang 构建步骤可以删掉,耗时和失败面都会小很多。

Co-Authored-By: opencode noreply@opencode.ai

github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
@Devin-DC-Huang

Copy link
Copy Markdown
Contributor Author

更新:offline/colocated 三条先挪到 unsupported

上游 #1064 把 offline producer(scripts/prepare_hidden_states.py)从「in-proc capture」改成 capture server 的 CPU client worker 集合:--server-urls 必填、多个 worker 用 gloo 进程组、hidden states 经 mooncake 回传。

我们把 guard 的 offline 分支改成「起 mooncake master + capture server,再跑 producer」之后,client 建连时仍拿不到 master 的 segment descriptor:

E transfer_metadata_plugin.cpp:379] GET http://127.0.0.1:35880/metadata?key=mooncake%2Fram%2F127.0.0.1%3A12452 http=404 body: metadata not found

(顺带修掉了前一轮的两个真问题:Default process group has not been initialized → producer 要按上游 README 用 torchrun --standalone --nproc_per_node=4 起多个 client worker。)

这条链还没跟上游的新形态对齐,所以先把这 3 条挪到 manifest 的 unsupported(那里就是记「暂时跑不了 + 原因」的地方),等对齐后再放回 supported。其余 9 条 external + 1 条 managed-local 都已跑绿。

目前 CI 状态

  • specforge-quick-start / monitor + test on change:绿(文档 21 步在 CI 里全跑通)
  • specforge-examples:external 9 条 + managed-local 1 条 绿

这一轮 CI 还帮我抓到并已修掉的问题:

问题 修复
sgl-kernel-npu wheel 404 CANN 版本改成运行时探测
capture server 起不来:No module named 'orjson' guard 装 SGLang 改成带依赖安装
同上 加 triton-ascend(社区 triton 没有 triton.language.extra.cann)
同上 torch 系列用 constraint 钉 2.10.0
pip: no such option: --reinstall pip 用 --force-reinstall
managed-local:capture-server-0 exited with status -9 managed-local 的 capture server 由 launch plan 起,命令行不含 --mamba-ssm-dtype bfloat16 → Qwen3.5-4B 的 GDN fp32 state 在 910B4 上把 server 打挂;用 model.sglang_extra_args 透传该 flag

说明

新流程下 examples 的每条腿都要自己装一遍 SGLang(源码构建 + 13 MB wheel + 全量依赖),单腿 20-30 分钟。等昇腾侧出了「基于 sglang main 的 910b 镜像」后,文档和 guard 里的 SGLang 构建步骤可以删掉,耗时和失败面都会小很多。

Co-Authored-By: opencode noreply@opencode.ai

github-actions Bot pushed a commit that referenced this pull request Nov 13, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 14, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 14, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 14, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 14, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 16, 2026
github-actions Bot pushed a commit that referenced this pull request Nov 16, 2026
@Devin-DC-Huang
Devin-DC-Huang force-pushed the feat/specforge-plugin-capture-flow branch from b963804 to b543114 Compare November 16, 2026 03:20
github-actions Bot pushed a commit that referenced this pull request Nov 16, 2026
@Devin-DC-Huang
Devin-DC-Huang force-pushed the feat/specforge-plugin-capture-flow branch from b543114 to 96fdeb1 Compare November 16, 2026 03:42
github-actions Bot pushed a commit that referenced this pull request Nov 16, 2026
@Devin-DC-Huang
Devin-DC-Huang force-pushed the feat/specforge-plugin-capture-flow branch 2 times, most recently from a526942 to 28213d2 Compare November 16, 2026 03:56
上游 SpecForge 2026-11-07 的 capture 重构(#1063~#1066)把 server 端的
hidden-state 采集从「打补丁」改成插件:#1065 删掉了
patches/sglang/v0.5.18/spec-capture.patch 与
scripts/apply_sglang_spec_capture_patch.sh,改由 specforge-sglang-capture
插件接管;#1064 把 scripts/prepare_hidden_states.py 改成必须传 --server-urls。

插件要求的三个扩展点(--enable-return-aux-hidden-states /
--return-aux-hidden-state-layer-ids / --return-hidden-states-mode、
ModelRunner.forward_observer、Scheduler.defer_response)来自 SGLang PR
#43449 / #43450(2026-10-26/27 合入 main),任何已发布版本都没有
(0.5.23 仍不具备),所以 SGLang 从源码构建,commit 取上游 SpecForge CI
钉的 SGLANG_COMMIT,保证插件与 SGLang 的 API 成对匹配。

文档(sources/specforge/quick_start.md):

- 删「打补丁」整节;新增「克隆 SpecForge 源码」「安装 SGLang(源码构建)」
  「安装 specforge 与 capture 插件」
- capture server 换插件参数(SPECFORGE_SPEC_CAPTURE=1 + 新 flag),并断言
  /server_info 广播 spec_capture_backend=plugin
- --mamba-ssm-dtype bfloat16:910B4 上 GDN 的 fp32 initial_state 不被
  sgl_kernel_npu 支持(只在 Ascend950 上支持)
- torch / torch_npu / triton-ascend / mooncake 按需安装:CANN 镜像不带
  torch;社区 triton 缺 triton.language.extra.cann 要装 triton-ascend;
  mooncake 钉 0.3.14(0.3.13.post1 的 Ascend transport 在 CANN 9.1.0 上
  初始化失败);torch 系列用 constraint 钉 2.10.0(否则被 uv 升到 2.15
  与 torch_npu 失配)
- trainer 段补 MOONCAKE_* 环境变量(specforge 从 env 读 segment size,
  缺了 store setup 直接失败)
- 镜像换成标准 CANN 镜像(ascendhub/cann:9.1.0-910b-ubuntu22.04-py3.12),
  不再依赖 sglang 专用镜像

看护(specforge-quick-start.yml / specforge-examples.yml / examples
guard):

- 解除 fixed_ref 钉版,ref 解析回到引擎默认(最新 release → 无 release
  落默认分支 main),即每次跑上游最新
- setup_example.sh:装 torch 栈 + 源码构建 SGLang(CANN 版本运行时探测)
  + 装上游插件;run_example.sh:capture server 换插件参数并校验
  spec_capture_backend=plugin;offline 分支按上游 #1064 的新形态起
  mooncake + capture server 后用 torchrun --standalone 跑多进程 producer
- managed-local:mooncake segment/buffer 调小(与 server、trainer 同容器
  会顶爆主机内存);model.sglang_extra_args 透传 --mamba-ssm-dtype
  bfloat16(launch plan 起的 capture server 命令行里没有它)
- offline/colocated 三条暂挪 unsupported:上游 #1064 改了 producer 形态,
  现有编排接不上(client 拿不到 master 的 segment descriptor,metadata
  404),对齐后放回

验证:specforge-quick-start 的 21 个文档步骤在 CI 与 coder(CANN 9.1.0
/910b 镜像)上全跑通,1 步训练 ce_loss=12.7055;specforge-examples 的
9 条 supported recipe 全绿。
@Devin-DC-Huang
Devin-DC-Huang force-pushed the feat/specforge-plugin-capture-flow branch from 28213d2 to 3d1aca0 Compare November 16, 2026 04:03
github-actions Bot pushed a commit that referenced this pull request Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant