[RFC] Fine-tune DeepSeek-V4-Flash official DSpark speculator in SpecForge

[chengda-wu]

RFC：在 SpecForge 上微调 DeepSeek-V4-Flash 官方 DSpark 投机层

目标

对 DeepSeek 官方发布的 deepseek-ai/DeepSeek-V4-Flash-DSpark 投机层进行微调（fine-tune），复用 SpecForge 现有的 DSpark 训练路径，并最终导出到 SGLang serving。DSv4-Flash 的 DSpark 是 self-drafting（draft 复用 target 自身层），target 层是 MoE，因此 draft 天然含 MoE experts——满足"MoE 投机层"需求。

本 issue 与 chengda-wu/speculators#2 同源，但落地仓库是 SpecForge：框架是 config 驱动（specforge train --config），serving 侧目标是 SGLang（非 vLLM），并行拓扑是 TP+DP+SP（无 EP）。改造点因此与 speculators 版本不同，下面逐条以 SpecForge 代码证据展开。

背景事实（已核实）

DSv4-Flash 与 DSpark

• 模型：deepseek-ai/DeepSeek-V4-Flash，284B 参数 / 13B activated，1M 上下文。基础版原生带 MTP（num_nextn_predict_layers: 1），不自带 DSpark。
• DSpark checkpoint：deepseek-ai/DeepSeek-V4-Flash-DSpark 是"同一 checkpoint 附加了一个投机解码模块"（官方卡片原文）。配置含 dspark_block_size: 5、dspark_target_layer_ids: [40,41,42]、dspark_noise_token_id: 128799。
• DSpark 是 DeepSeek 官方算法（arXiv 2607.05147），官方训练/评估代码库 github.com/deepseek-ai/DeepSpec，含 DSpark/DFlash/Eagle3 三种 draft。DeepSpec README 明确建议 domain-specific 场景"fine-tune the draft model again"。
• 架构：MoE（n_routed_experts: 256、n_shared_experts: 1、num_experts_per_tok: 6，expert FP4）+ mHC（hc_mult: 4）+ MLA（CSA+HCA，num_key_value_heads: 1、q_lora_rank: 1024），hidden_size: 4096，num_hidden_layers: 43。
• self-drafting：draft 复用 target 自身层（vLLM PR [New Model][Nvidia] Add SM12x support for DeepSeek V4 Flash with essential fixes vllm-project/vllm#41834 原文："DSpark is DeepSeek's self-drafting speculative-decode variant, draft weights carried in the target checkpoint, block size 5"）。因 target 层是 MoE，draft 含 MoE experts。SGLang 侧的 DSpark serving 支持以 SGLang 上游实现为准；本 issue 聚焦训练 + 导出侧，不涉及 serving runner 本身。

SpecForge 现状（代码证据，commit 1bfa8ae）

DSpark 在本仓库继承 DFlash，draft 层为 Qwen3 dense，未适配 DSv4 的 MoE / MLA / mHC：

• DSpark 仅是 DFlash + Markov/confidence heads：specforge/modeling/draft/dspark.py:283 —— DSparkDraftModel(DFlashDraftModel)，__init__（dspark.py:288）调 super().__init__，复用 DFlash 的 layer 构造；draft backbone 完全继承 DFlash。
• DFlash draft 层硬编码 dense Qwen3：specforge/modeling/draft/dflash.py:143-157 —— Qwen3DFlashDecoderLayer，self.mlp = kernels.make_mlp(config)（dflash.py:157）；dflash_kernels.py:24-25 —— _make_qwen3_mlp 直接 return Qwen3MLP(config)（dense），Liger 变体（dflash_kernels.py:51）同样是 LigerSwiGLUMLP（dense SwiGLU）。无 layer 注册/分发，无 MoE 分支。
• DFlash attention 是标准 GQA：specforge/modeling/draft/dflash.py:43 —— Qwen3DFlashAttention，基于 num_key_value_heads 的 GQA + RoPE，非 MLA。
• mHC / MLA 在 draft modeling 零命中：grep hc_mult|mhc|mla|q_lora|compress_ratios 在 specforge/modeling/ 无任何命中。MoE/expert/router/aux_loss 在 specforge/modeling/ 也无命中——MoE 仅出现在 target 侧（specforge/offline_capture/sglang_backend/，用于从 SGLang-served MoE target 抽 hidden state，capture.py:64-73 的 moe_ep_rank/moe_ep_size）。
• draft config 是 Qwen3 dense：configs/qwen3-4b-dspark.json —— model_type: qwen3、num_hidden_layers: 5、num_attention_heads: 32、num_key_value_heads: 8（GQA）、hidden_size: 2560、intermediate_size: 9728、dflash_config.target_layer_ids: [1,9,17,25,33]、block_size: 7、markov_rank: 256。configs/ 下有 deepseek-v2-lite-eagle3.json、deepseek-v3-671b-eagle3.json，但无任何 deepseek 的 dflash/dspark config，DSv4 路径完全缺失。

训练并行拓扑（决定 ~20B MoE draft 能否跑起来）

• specforge/distributed.py:12-18 —— 全局并行组只有 _TP_GROUP / _DP_GROUP / _DRAFT_DP_GROUP / _DRAFT_SP_GROUP / _SP_ULYSSES_GROUP / _SP_RING_GROUP（TP + DP + 序列并行 Ulysses/Ring）。没有 expert parallel（EP）组，expert 在 distributed.py 零命中。
• 含义：256 个 expert 只能靠 TP（按 expert 切分需 TP≥256，不现实）或 FSDP 全分片摊到每张卡，无法按 expert 并行切分。

导出到 SGLang（SpecForge 相对 speculators 的关键差异）

• specforge/export/to_sglang.py:67-72 —— export_to_sglang 显式校验 state.get("strategy") != "eagle3" 即 raise，专用 SGLang 导出器只支持 EAGLE3；DFlash-family（含 DSpark/Domino）被引导走 --to hf（export/to_hf.py），没有 DSpark → SGLang 的专用导出路径。
• export/to_hf.py:13 —— DFlash-family 导出"reload frozen embeddings from the target"，无 self-drafting 权重抽取/转换：官方 DeepSeek-V4-Flash-DSpark 不是 SpecForge 原生格式，而是 DeepSpec/SGLang 的 self-drafting 格式（draft 权重嵌在 target checkpoint，按 dspark_target_layer_ids 复用 target 层），SpecForge 没有把它转成原生 draft 格式的 converter。

DSpark 训练侧 loss

• specforge/algorithms/common/dflash_family_model.py:871 _compute_dspark_loss、dspark/providers.py:83 minimum_loss_tokens —— 当前 DSpark loss 仅 token-level 加权 + Markov/confidence，无 router aux / load-balance loss（与 DSv4 aux-loss-free 路由是否需要传统 aux loss 相关，需对照 DeepSpec）。

需要的改造

A. 加载官方 DSpark checkpoint（最关键，决定能否微调）

1. 新建 dspark checkpoint converter：从 DeepSeek-V4-Flash-DSpark 抽取 DSpark draft 权重，转成 SpecForge 原生 draft 格式（configs/*.json + safetensors，architectures=["DSparkDraftModel"]）。需处理 self-drafting 权重布局映射：
   • dspark_target_layer_ids: [40,41,42] → dflash_config.target_layer_ids + num_hidden_layers（draft 层数=3，对齐 qwen3-4b-dspark.json 的 target_layer_ids/num_target_layers 语义）。
   • dspark_block_size: 5 → draft config block_size（qwen3-4b-dspark.json 顶层 block_size）。
   • dspark_noise_token_id: 128799 → dflash_config.mask_token_id。
   • draft 权重在 target checkpoint 里的 key 前缀 → SpecForge DSparkDraftModel 期望布局（dspark.py:283）。参考 export/to_hf.py 的 reload-from-target 模式，但需新增 self-drafting 抽取。
2. warm start 路径：确认 specforge/training/model_loading.py 能加载转换后的 native dspark draft 并续训（对应 speculators 的 from_pretrained 路径）。

B. 让 DSpark draft 层支持 MoE（对齐 DSv4 self-drafting 的 MoE 结构）

3. 新建 MoE DFlash decoder layer：参照 dflash.py:143-157 的 Qwen3DFlashDecoderLayer，把 self.mlp = kernels.make_mlp(config)（dflash.py:157，dense Qwen3MLP）换成 DSv4 的 MoE block（256 routed + 1 shared expert，aux-loss-free 路由，FP4 expert）。DFlashKernels（dflash_kernels.py:13）需扩展 make_mlp 之外支持 MoE 构造。
4. 按 model_type 分发 layer：DFlashDraftModel.__init__（dflash.py:273）当前硬编码 Qwen3DFlashDecoderLayer，需改为按 model_type/architectures 分发（对齐 eagle3 的注册制思路），或 DSpark 覆盖 __init__。

C. 适配 DSv4 的 mHC 与 MLA

5. mHC（hc_mult=4）：DSv4 hidden state 是 hc_mult * hidden_size。需在 DSpark/DFlash 里加 hc_head_project 折叠 hc_mult*hidden_size → hidden_size。Qwen3DFlashAttention（dflash.py:43）与 extract_context_feature（dflash.py）当前都假设 hidden_size 形状的 target_hidden，需对齐。DSpark 的 MarkovHead/AcceptRatePredictor（dspark.py）输入维度也要相应对齐。
6. MLA：Qwen3DFlashAttention（dflash.py:43）假设标准 GQA + hidden_size 形状输入。DSv4 用 MLA（CSA+HCA，q_lora_rank）+ hc_mult*hidden_size，K/V 构造需重写（风险最高）。注意 DFlash attention 的 target_hidden/hidden_states 双路拼接（dflash.py forward 里 k_ctx/k_noise）在 MLA 下需重新设计。

D. 训练侧

7. config 注册 + 新 draft config：新增 configs/deepseek-v4-flash-dspark.json（model_type 走 DSv4，含 n_routed_experts / num_experts_per_tok / hc_mult / q_lora_rank 等）。确认 specforge/algorithms/registry.py / builtin.py:16（dspark() 已注册）无需改动，仅 config。
8. MoE aux loss：dflash_family_model.py:871 的 loss 当前无 router aux loss，DSv4 是 aux-loss-free 路由，需对照 DeepSpec 决定是否加传统 load-balance loss。
9. 数据 / hidden state 抽取：specforge/offline_capture/sglang_backend/capture.py 已能从 SGLang-served MoE target 抽 hidden state（含 moe_ep_rank），但 DSv4 的 mHC hidden state 形状（hc_mult*hidden_size）需在 capture + dataloader 里透传处理。
10. 并行：无 EP 的 ~20B MoE 训练：distributed.py:12-18 无 EP，256 experts 全靠 TP/FSDP 摊。需评估是否在 distributed.py 加 EP 组，或明确以 FSDP 全分片 + 大卡数方案跑（见开放问题）。

E. 导出（SpecForge 特有，speculators 版本无此环节）

11. DSpark → SGLang 导出：export/to_sglang.py:67-72 当前 EAGLE3-only。需为 DSpark（MoE self-drafting）新增导出分支，产出 SGLang loadable draft 目录（含 expert 权重布局、weight_map 扩展）。这是 SpecForge "smoothly port to SGLang" 价值主张的核心一环，也是相对 speculators 版本新增的工作量。

参数规模与训练显存（沿用 speculators#2 的估算口径）

按 deepseek-ai/DeepSeek-V4-Flash-DSpark 配置：draft 复用 3 层 target MoE 层（[40,41,42]），每层 256 routed + 1 shared expert，单 expert ≈ 25.17M（3 × 4096 × 2048）。

• draft 总参数 ≈ 19.9B，其中 routed experts 占 19.33B（≈97%），per-token 激活仅 ≈0.53B（每层 6+1 experts）。
• expert 权重存储（3 层 routed）：FP4 ≈9.66GB / FP8 ≈19.33GB / BF16 ≈38.65GB。
• 无 EP 训练显存（distributed.py 仅 TP+DP+SP，BF16 全参数 + 优化器 ≈4× param bytes，仅 draft）：
  • 8 卡 ≈ 19.9 GB/卡
  • 4 卡 ≈ 39.9 GB/卡
  • 16 卡 ≈ 10.0 GB/卡
    还要加载 284B target 取 hidden state（即便 frozen 也要放显存或 offload）。8 卡以内基本不可行，16 卡起步；保持官方 FP4 expert 训练可减半，但 trainer 当前 dense-only。这正是"是否直接用 DeepSpec 微调"开放问题的现实权重。

开放问题

• 是否应直接用 DeepSpec 微调？ DeepSeek 官方 github.com/deepseek-ai/DeepSpec 已提供 DSpark 训练流水线且原生支持 DSv4-Flash（大概率带 EP）。若目标只是微调 DSv4-Flash-DSpark，DeepSpec 可能比改造 SpecForge 更直接。本 issue 的价值在于：把 DSv4-Flash DSpark 纳入 SpecForge 的统一 draft 训练 + SGLang 导出框架（与 EAGLE3/DFlash/Domino 一致的 config/数据/导出契约）。
• self-drafting vs 独立 draft：DSv4-Flash-DSpark 是 self-drafting（draft=target 层）。SpecForge 的 DSpark 是独立 dense draft。微调时是保持 self-drafting（draft 层=target MoE 层）还是改成独立 MoE draft？前者更贴近官方、改造集中在 converter；后者更通用、改造在 layer 注册。倾向前者。
• EP 是否进 distributed.py：无 EP 下 ~20B MoE 训练需 16 卡起步。是否值得为 DSpark 单独引入 EP 组（改动 distributed.py:12-18 的全局并行拓扑），还是接受 FSDP 全分片 + 大卡数方案？
• DSpark → SGLang 导出契约：export/to_sglang.py EAGLE3-only（to_sglang.py:67-72）。DSpark/MoE 的 SGLang 侧 loadable 布局（expert 分片、weight_map）需与 SGLang 上游 DSpark loader 对齐——若 SGLang 上游尚无 DSpark serving 支持，导出侧工作会受上游阻塞。
• expert FP4 训练：DSv4 expert 是 FP4，微调时是否保持 FP4？SpecForge trainer 当前 dense-only，FP4 MoE 训练需额外支持。
• MoE draft 在 DSv4 上的接受率：self-drafting draft=target 层理论上接受率高，但 mHC+MLA+FP4 expert 的训练稳定性需小规模验证（DSv4-Lite 或减少 expert 数）。

[chengda-wu]

进展更新（2026-07-21）

在 dspark-dsv4-flash-finetune 分支上按 per-module review-then-commit 节奏推进,Slices 1-4 的训练 + 导出侧改造已落地。提交:

• 8fa8b58 Slice 1 — DSv4 DSpark draft layer + backbone(MoE + MLA + mHC)
• c45214c Slice 2 — 官方 DSpark checkpoint converter
• cff2eda Slice 2 — dspark strategy 接受 DSv4 draft backbone
• 539c7d7 rework — 去掉 per-layer target_fold,对齐 SGLang 架构
• 7471e68 Slice 4 — DSpark DSv4 → SGLang 导出

已完成

A. 加载官方 DSpark checkpoint(c45214c)— specforge/convert/dspark/converter.py

• 从官方 DeepSeek-V4-Flash-DSpark checkpoint 抽取 reused target 层(40/41/42),remap model.layers.{N}.* → layers.{i}.*。
• fuse per-expert w1/w2/w3 → HF V4 DeepseekV4Experts 的 3D gate_up_proj/down_proj(gate 在前,up 在后,对齐 HF _apply_gate 的 chunk(2))。
• 由 source config 生成 draft config.json:architectures=["DSparkDeepseekV4DraftModel"],由 compress_ratios 推 layer_types/mlp_layer_types,drop expert_dtype/quantization_config。
• 范围限制:experts 仅在 source 存为浮点时转 BF16。官方 checkpoint 是 FP4 packed,FP4→BF16 dequant 未实现(_check_expert_dtype 会显式 raise);BF16 source / test fixture 可端到端转换。

B/C. DSv4 MoE + MLA + mHC draft layer(8fa8b58 + rework 539c7d7)— specforge/modeling/draft/dflash_deepseek_v4.py

• 新增独立注册类 DFlashDeepseekV4DraftModel(DeepseekV4PreTrainedModel) + DSparkDeepseekV4DraftModel(precedent:LlamaForCausalLMEagle3),不触碰 Qwen3 DFlash 现有路径。
• DeepseekV4DSparkAttention:V4 MLA 投影(q_a_proj/q_a_norm/q_b_proj/kv_proj/kv_norm/o_a_proj=GroupedLinear/o_b_proj/sinks),KV 重建为 [ctx_kv ; noise_kv](ctx 来自 verifier target_hidden,noise 来自 draft hidden,共享 kv_proj),partial interleaved RoPE,conjugate output rotation。compressor 路径 wired 但 sliding 层为 None。
• DeepseekV4DSparkDecoderLayer:mHC(attn_hc/ffn_hc=DeepseekV4HyperConnection)+ MLA + MoE(DeepseekV4SparseMoeBlock,含 shared expert)。残差流走 [B,S,hc_mult,hidden]。
• backbone forward mHC plumbing:noise stream expand 到 mHC,fold_module(=DeepseekV4HyperHead)末尾折叠回 hidden 喂 norm+target lm_head。
• rework(539c7d7):对照 SGLang serving 删掉 per-layer target_fold。SGLang DeepseekV4ForCausalLMDSpark 只用单个 stage-0 main_proj/main_norm 投影 verifier target-hidden,每层直接 ctx_kv = wkv(main_x)——无 per-layer fold。SpecForge 原先的 per-layer HyperHead 是 SGLang 无法消费的孤儿权重,已移除;层内 kv_proj 直接吃 backbone 投影后的 [B,S,hidden]。

D. 训练侧 strategy 接入(cff2eda)

• dspark provider 的 DraftRequirement 用 compatible_architectures={DSparkDraftModel, DSparkDeepseekV4DraftModel}(多架构集合),两个 runtime gate(model_loading.resolve_draft_config、assembly._load_draft)改为 membership 检查而非单值相等。provider.architecture 仍为 "DSparkDraftModel"(auto-gen 默认,被 test_draft_resolution_stays_outside_algorithm_spec 锁定)。
• OnlineDSparkModel 训练 wrapper 已 V4 兼容:调 draft_model(position_ids, noise_embedding, target_hidden, attention_mask) 期望 [B,S,hidden] 返回,用 target lm_head 再 apply_logits_head;无 MoE aux-loss handling,无 Qwen3 假设。spec_generate 不被 trainer 调用(SGLang 导出才是部署路径)。
• _TARGET_ARCHITECTURE_FIELDS warm-start 绕过(无新增 DSv4 target config 字段透传需求)。

E. DSpark → SGLang 导出(7471e68)— specforge/export/to_sglang.py

• export_to_sglang 按 state["strategy"] 分发:dspark → 新路径,eagle3 → 原路径。
• 权重契约对照真实 DeepSeek-V4-Flash checkpoint(~/models/DeepSeek-V4-Flash)和 SGLang _remap_dspark_weight_name 逐条核实。映射:q_a_norm→attn.q_norm、sinks→attn.attn_sink、fused experts 解fuse 回 w1/w2/w3、fc→mtp.0.main_proj、hidden_norm→mtp.0.main_norm、fold_module.hc_*→mtp.{N-1}.hc_head_*、norm→mtp.{N-1}.norm、markov_head/confidence_head→mtp.0.*(remap 剥 stage id)、attn_hc/ffn_hc→hc_attn_*/hc_ffn_*。
• config 补顶层 dspark_target_layer_ids/dspark_block_size/dspark_noise_token_id/dspark_markov_rank/dspark_markov_head_type + enable_confidence_head/confidence_head_with_markov + 由 layer_types 重导 compress_ratios(converter 会 drop 它)。
• 拒绝任何孤儿 SpecForge key(无 silent breakage)、拒绝任何 non-mtp 泄漏。
• confidence head 对齐 SGLang:AcceptRatePredictor.proj 改 bias=False(SGLang DSparkConfidenceHead 是 bias=False,否则 trained bias 会被 load_weights 静默丢弃)。注意 SGLang 总是构建 confidence head 且断言权重加载 → DSpark DSv4 必须 enable_confidence_head=True 训练才能在 SGLang serve。

测试

• tests/test_modeling/test_dflash_deepseek_v4.py(layer forward/grad/no-compressor + backbone forward/loss-backward/confidence)。
• tests/test_convert/test_dspark_converter.py(converter round-trip)。
• tests/test_runtime/test_export_dspark_sglang.py:CPU 上复制 SGLang _remap_dspark_weight_name 做守门——每个 key round-trip 非 None、experts 解fuse bit-identical、required key 齐全无孤儿、config 字段正确(SGLang DSpark model import 需 deep_gemm/CUDA,CPU 跑不了真 serving load)。
• tests/test_runtime/test_model_loading.py 新增 DSv4 architecture 接受/拒绝测试。

遗留问题 / 开放项

1. Slice 3 converter 移植:当前 c45214c 的 converter 是 SpecForge 原生格式产出。speculators fork 的 ddb79ea converter 还需对照确认 training_state.pt 格式对齐(resume contract + remapped draft_state_dict)。
2. FP4 → BF16 expert dequant 未实现:官方 checkpoint experts 是 FP4 packed,converter 现在显式 raise。微调真实官方 checkpoint 前需补 dequant 路径,或用 BF16 source。
3. 真实 GPU SGLang serving 集成测试缺失:CPU venv 无法 import SGLang DSpark model(deep_gemm 需 CUDA)。导出契约已对照 remap 逻辑守门,但未做端到端 DeepseekV4ForCausalLMDSpark.load_weights 实测——需在 H200/CUDA box 上验证。
4. MoE aux loss:DSv4 是 aux-loss-free 路由,dflash_family_model._compute_dspark_loss 当前无 router aux/load-balance loss。未加,与 aux-loss-free 设计一致,但训练稳定性需小规模实测确认。
5. 无 EP 的 ~20B MoE 训练显存:仍未解决,distributed.py 无 EP 组,256 experts 全靠 TP/FSDP 摊,16 卡起步。test_dspark_disagg_launch.py / 部分 test_export.py::TestExporters 因缺 yunchang(Ulysses SP 可选依赖)在当前 venv 跑不了——预先存在的环境缺口,非本次回归。
6. self-drafting 保持:draft 复用 target 层 40/41/42(原 RFC 倾向项),已落地。

下一步优先级建议:sgl-project#3(真实 GPU serving 实测,验证导出契约)> sgl-project#2(FP4 dequant,解锁官方 checkpoint 微调)> #1(converter training_state.pt 格式)。

[chengda-wu]

状态:暂时搁置(2026-07-23)

本任务暂停推进。当前进展已全部落地到 dspark-dsv4-flash-finetune 分支并 push(见上一条进展评论),训练 + 导出侧代码可用,但尚未在真实硬件上端到端验证。

已交付(5 commit,已 push):

• DSv4 DSpark draft layer(MoE + MLA + mHC)
• 官方 DSpark checkpoint converter
• dspark strategy 接受 DSv4 backbone
• 对齐 SGLang 架构(去掉 per-layer target_fold)
• DSpark DSv4 → SGLang 导出

未解决,恢复时需先做:

1. 真实 GPU SGLang serving 端到端实测(导出目录能否被 DeepseekV4ForCausalLMDSpark 加载)——这是验证整条链路是否通的关键,目前只做了 CPU 守门。
2. FP4 → BF16 expert dequant(解锁官方 checkpoint 微调)。
3. 无 EP 的 ~20B MoE 训练显存方案(H200 卡数需按实际 disaggregated/非 disaggregated + 实测 MoE all-gather 峰值确定,先前 RFC 的数字是 envelope 估算,不可直接采信)。

如需恢复,重开此 issue 或新开即可。

[chengda-wu]

进展更新（2026-07-25）：serving-shape 重工完成

对比 XPengZhao/SpecForge dsv4-dspark 后，发现原先方案有根本性冗余：复用 transformers 融合模块 → HF 风格参数名 → 被迫造两层变换（converter + to_sglang DSpark 分支）+ 无法加载 FP4 官方 checkpoint。

本次按"整体方案最优"重构成 serving-shape（mtp.* 布局）：draft 参数一开始就是 SGLang 期望的命名，加载官方 ckpt 和保存训练后的 draft 都是 identity 操作，零变换。已 push（43c5fbc + 42c5537）。

已完成

• 重写 draft model（specforge/modeling/draft/dflash_deepseek_v4.py）：单类 DeepseekV4DSparkDraftModel，手写 MLA / MoE（per-expert w1/w2/w3，不融合）/ mHC / attn sink，参数全是 serving 名。
• attn sink 两条路径都有：flex 用原生 return_lse，sdpa 兜底用 torch.logsumexp 手算 lse 做相同 sigmoid(lse - sink) 缩放（CPU 测试可跑）。
• FP4/FP8 dequant + 官方 ckpt warm-start（load_deepseek_v4_dspark_hf_weights）：stream mtp.* tensor，遇 int8+scale 走 FP4、float8_e4m3fn+scale 走 FP8，in-flight dequant —— 解决之前"遇 FP4 直接 raise"的遗留。
• 砍掉两层变换：删 converter（specforge/convert/dspark/）+ to_sglang.py DSpark 分支（回退 EAGLE3-only）。DSpark 现在走 --to hf，save_pretrained 是 identity，SGLang 直接加载。
• AcceptRatePredictor 参数化 bias：DSv4 用 bias=False 对齐 SGLang DSparkConfidenceHead，Qwen3 路径保持 bias=True 不变。
• providers / mock config / warm-start 接线全部迁到新架构名 DeepseekV4DSparkDraftModel。
• 测试重写：stage/backbone forward+grad、DSpark loss backward、serving-shape key 守门（全 mtp.* 无 HF 残留）、FP4 dequant 单测、sdpa sink 生效测试。

验证

• 27 测试通过（draft + model_loading）；ruff 在改动文件上 clean。
• test_automodel（网络）与 test_export.py::TestExporters（yunchang/CUDA）为既有环境缺口，非回归。

遗留（下一轮）

• capture 数据管线：XPengZhao capture.py DSv4 改动（fused mHC unfuse + forward hook + .mean(dim=1) fold）+ offline data provider + prepare_hidden_states.py —— 端到端跑通的前提，独立于本轮架构返工。
• 真实 GPU SGLang serving 端到端实测（CPU venv 无法 import deep_gemm）。
• 无 EP ~20B MoE 训练显存方案（H200 141GB/card）。

Branch: dspark-dsv4-flash-finetune。Issue 重新打开，继续推进 capture 数据管线。

[chengda-wu]

进展更新（2026-07-29）：DSv4 离线 capture 管线完成

本轮补齐 serving-shape 重工留下的 capture 数据管线（之前标为"端到端跑通的前提"）。决定采用 dingyibin fork（dpsk-v4-dspark-0723）的实现并移植到我们 base。3 个 commit，已 push：313d044 + 37529c4 + 552d6eb，branch dspark-dsv4-flash-finetune。

已完成

A. DSv4 capture 逻辑（commit 313d044） — specforge/offline_capture/sglang_backend/

• capture.py 新增 _set_deepseek_v4_capture_layers：unfuse mHC（use_fused_mhc_post_pre=False）→ forward hook 抓目标层输出 → 断言 3D [tokens, hc_mult, hidden] → .mean(dim=1) 折叠 → monkeypatch decoder.forward 返回 (output, aux_hidden_states) → 置 model.capture_aux_hidden_states=True。set_eagle3_capture_layers 按模型类名分发。
• FP4 expert 强制 moe_runner_backend=flashinfer_mxfp4 + initialize_moe_config。
• utils.py 加 prefer_aux_hidden_states：DSv4 的 hidden_states_before_norm 是拍平的 mHC 流 [tokens, 4H]，不是配置的目标层 capture，必须优先 aux（torch.cat(aux_pruned_states, dim=-1)）。
• sglang.py 加 _force_cuda_norm：绕过 FlashInfer CuTe RMSNorm 在 DSv4 pinned CUDA 栈的编译失败。

B. DSpark OFFLINE 特征契约（commit 37529c4） — DSpark 之前是 streaming-only

• dflash_family_data.py：DSPARK_NORMALIZER_ID + normalize_offline_dspark_sample（存储的 aux_hidden_state→hidden_states、hidden_state→target_last_hidden_states，3D/2D 归一 + 序列长度对齐）+ build_offline_dspark_{reader,normalizer}（OfflineManifestReader，feature_keys=input_ids/loss_mask/aux_hidden_state/hidden_state）。
• dspark/providers.py：在 STREAMING 契约前加 OFFLINE FeatureContract（OfflineStorageContract(format=specforge_hidden_states_v1, …)）+ OfflineDataProvider。resume_contract 的 dspark_draft_num_hidden_layers 改 len(draft_model.mtp) 回退 config.num_hidden_layers（DSv4 的 num_hidden_layers ≠ mtp stage 数，真实 bugfix）。
• base 分歧处理：dingyibin 的 providers.py/capture_contract.py diff 基于不同 base（它假设 DraftConfigProvider 有 compatible_architectures 属性、draft_config_dict 不收该参数）。我们 base 从 algorithm.spec.draft.compatible_architectures 显式传参，因此不引入 DSparkDraftConfigProvider、不动 capture_contract.py。

C. prepare_hidden_states 脚本 + 测试（commit 552d6eb）

• scripts/prepare_hidden_states.py：加 --strategy {eagle3,dspark} + --draft-model-config（必填，本地 JSON，其 draft_vocab_size 决定 eagle3 vocab 映射）。_resolve_capture_layers 加 strategy/draft_model_config：dspark 默认从 dflash_config.target_layer_ids 取，eagle3 仍 1,middle-1,final-4。build_target_model 对 DSv4 注入 kv_cache_dtype=fp8_e4m3 / swa_full_tokens_ratio=1.0 / _force_cuda_norm，fp4 expert → flashinfer_mxfp4。eagle3 才在 rank0 生成共享 vocab_mapping.pt，dspark 跳过。
• 8 个 hermetic 测试（vocab size 解析 / rank0 映射生成 / dspark 默认 capture layers）+ build_target_model 测试 pin model_type 避免触网。

验证

• ruff 全绿；90 个 algorithms+config 测试通过；8 个 prepare_hidden_states 测试通过。
• 全量回归 49 failed + 10 collection errors 全部预存环境缺口（yunchang / accelerate / CUDA / distributed）—— 在 baseline 393df81 worktree 上跑同样失败，确认零回归。

附带澄清

先前调查结论"upstream 无 MoE draft PR"不准确。upstream sgl-project/SpecForge 有 open PR sgl-project#468「(feat)Draft model supports Qwen3 MoE」——但它在 EAGLE3 / llama3_eagle 路径（非 dflash）、是 placeholder + 含 debug 垃圾、未合并。DSv4 仍是 DSpark/DFlash 框架里的第一个 MoE draft。

遗留（未验证 / 未做）

1. 真实 DSv4 离线 capture 实跑（核心缺口）：_set_deepseek_v4_capture_layers / _force_cuda_norm / flashinfer_mxfp4 本轮仅验证 import + 参数解析 + 单测，从未在真实 GPU + DSv4 模型上跑过。需 ~/models/DeepSeek-V4-Flash + GPU，跑 prepare_hidden_states.py --strategy dspark 抓 hidden states 再喂训练才算端到端通。CPU venv 无 sglang/flashinfer/deep_gemm。
2. DSpark 训练端到端：capture 特征 → OfflineManifestReader → dspark offline 契约 → 训一个 step，整链路未实跑（同样卡 GPU/sglang）。
3. SGLang serving 端到端：训练 draft（--to hf 导出）在 DeepseekV4ForCausalLMDSpark 加载 + 推理验证，未做（CPU venv 跑不了 deep_gemm）。
4. 无 EP MoE 训练显存方案：已移植 expert_groups FSDP 分片 + attention_chunk_size + activation_checkpointing 三个旋钮（前轮 commit 393df81），但未实测峰值。需先给硬件再算（不自行估算）。

1 是 2/3 的前置，4 独立。1/2/3 都需 GPU 环境。