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

[chengda-wu]

RFC：在 speculators 上微调 DeepSeek-V4-Flash 的 DSpark 投机层

目标

对 DeepSeek 官方发布的 deepseek-ai/DeepSeek-V4-Flash-DSpark 投机层进行微调（fine-tune），使用 speculators 的 DSpark 算法路径。DSv4-Flash 的 DSpark 是 self-drafting（draft 复用 target 自身层），target 层是 MoE，因此 draft 天然含 MoE experts——满足"MoE 投机层"需求。

背景事实（已核实）

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（vLLM PR [Bugfix][Spec Decode] DSpark: build draft under its own model/quant config (NVFP4 target corrupts MXFP4 draft experts) vllm-project/vllm#49133 提到 "MXFP4 draft experts"）。
• vLLM 推理侧已支持：[Spec Decode] DSpark vllm-project/vllm#46995（DSpark 主合并，2026-07-01）；服务命令 vllm serve deepseek-ai/DeepSeek-V4-Flash-DSpark --speculative_config '{"method":"dspark","num_speculative_tokens":5}'。本 issue 不涉及推理侧。

speculators 现状（代码证据，commit f8cf626）

DSpark 在本仓库继承 DFlash，draft 层硬编码 dense，未适配 DSv4：

• src/speculators/models/dspark/core.py:21-22 —— DSparkDraftModel(DFlashDraftModel)，__init__ 调 super().__init__（core.py:33），复用 DFlash 的 layer 构造。
• src/speculators/models/dflash/core.py:78-83 —— draft 层硬编码 Qwen3DFlashDecoderLayer，无 layer 注册/分发。
• src/speculators/models/dflash/model_definitions.py:158,163 —— Qwen3DFlashDecoderLayer.mlp = Qwen3MLP（dense），attention 为 Qwen3DFlashAttention（标准 GQA，非 MLA）。
• DSpark 相比 DFlash 仅多 MarkovHead（dspark/model_definitions.py:12-81）+ ConfidenceHead（model_definitions.py:83-91），draft 层结构完全相同，dense。
• src/speculators/models/dspark/ 与 dflash/ 下 hc_mult|hc_head|mHC|dsv4|deepseek 零代码命中（仅 dspark/config.py:36 一句无关注释）。DSv4 的 mHC 未适配。
• scripts/train.py:50-53 —— DRAFT_ARCH_CONFIGS = {"llama": LlamaConfig, "qwen3": Qwen3Config}，from-scratch 路径只产出 dense。
• src/speculators/convert/ 下只有 dflash / eagle / mtp，无 dspark converter（entrypoints.py:22-24, 140-142）。

微调已有 checkpoint 的现有路径

• scripts/train.py:446-459 的 --from-pretrained（非 config-only、非 mtp）分支 → SpeculatorModel.from_pretrained（src/speculators/model.py:232-388）：可加载 speculators 原生格式（config.json 含 speculators_model_type="dspark" + safetensors）的 DSpark checkpoint 并继续训练。
• 但官方 DeepSeek-V4-Flash-DSpark 不是 speculators 原生格式，而是 DeepSpec/vLLM 的 self-drafting 格式（draft 权重嵌在 target checkpoint 里，按 dspark_target_layer_ids 复用 target 层）。speculators 没有把它转成原生格式的 converter。

需要的改造

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

1. 新建 dspark converter：在 src/speculators/convert/dspark/ 新增 converter（注册到 entrypoints.py:22-24, 32, 140-142），从 DeepSeek-V4-Flash-DSpark checkpoint 抽取 DSpark draft 权重，转成 speculators 原生格式。需处理：
   • self-drafting 的权重布局：draft 权重在 target checkpoint 里的 key 前缀与 speculators 的 DSparkSpeculator 期望布局（dspark/config.py:23-26 的 architectures=["DSparkSpeculator"]）之间的映射。
   • dspark_target_layer_ids: [40,41,42] → speculators DSpark 的 layer 数（DFlash/DSpark 的 num_draft_layers，见 dflash/core.py:78-83）。
   • dspark_block_size: 5 → DSpark config 的 block_size（dspark/config.py 继承 DFlash 的 block_size）。
   • dspark_noise_token_id → DSpark 的 noise/mask token。
   • 参考 convert/mtp/converter.py 的抽取+fuse 模式，但 DSpark 无 mtp.* 前缀，权重来自 target 层复用。

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

2. 新建 MoE DFlash decoder layer：参照 dflash/model_definitions.py:158-207 的 Qwen3DFlashDecoderLayer，把 self.mlp = Qwen3MLP（第 163 行）换成 DSv4 的 MoE block（256 routed + 1 shared expert，aux-loss-free 路由，FP4 expert）。attention 部分需从 Qwen3DFlashAttention（GQA）换成 DSv4 MLA（CSA+HCA） 的 DFlash 变体。
3. 让 DSpark 用该 layer：DFlashDraftModel.__init__（dflash/core.py:78-83）当前硬编码 Qwen3DFlashDecoderLayer，需改为按 model_type 分发（对齐 eagle3/model_definitions.py:131-137 的注册制），或 DSpark 覆盖 __init__。同步更新 _no_split_modules（dflash/core.py:36）。

C. 适配 DSv4 的 mHC 与 MLA

4. mHC（hc_mult=4）：DSv4 hidden state 是 hc_mult * hidden_size。需在 DSpark/DFlash 里加 hc_head_project 折叠 hc_mult*hidden_size → hidden_size（参考 Add hc_mult support to DFlash for DeepSeek-V4-Flash vllm-project/speculators#524 给 dense DFlash 的 mHC 适配，但 Add hc_mult support to DFlash for DeepSeek-V4-Flash vllm-project/speculators#524 尚未合入 main）。DSpark 的 MarkovHead/ConfidenceHead 输入维度也要相应对齐。
5. MLA：Qwen3DFlashAttention 假设标准 GQA + hidden_size 形状的 target_hidden。DSv4 用 MLA + hc_mult*hidden_size，K/V 构造需重写（风险最高）。

D. 训练侧

6. config 注册：DRAFT_ARCH_CONFIGS（scripts/train.py:50-53）加 DSv4 条目；create_transformer_layer_config（train.py:178-194）支持构造含 n_routed_experts / num_experts_per_tok / hc_mult / q_lora_rank 等字段的 config。
7. MoE aux loss：dspark/metrics.py / dspark/core.py:187-199 的 loss 当前无 router aux loss，需加入（DSv4 是 aux-loss-free 路由，可能不需要传统 load-balance loss，需对照 DeepSpec 实现）。
8. 数据生成：src/speculators/train/data.py hidden state 抽取架构无关，但 DSv4 的 mHC hidden state 形状（hc_mult*hidden_size）需在 dataloader 里处理（参考 Add hc_mult support to DFlash for DeepSeek-V4-Flash vllm-project/speculators#524 的 hc_mult 透传到 collate/sample 形状）。

与 vllm-project#524 的关系

vllm-project#524 给 dense DFlash 加 DSv4 mHC 适配（hc_mult 透传、hc_head_project、load_verifier_weights override），尚未合入 main。本 issue 的 DSpark MoE 路径应建立在 vllm-project#524 的 mHC 适配之上，但额外需要：MoE layer、MLA attention、dspark converter、self-drafting 权重抽取——范围远大于 vllm-project#524。

开放问题

• 是否应直接用 DeepSpec 微调？ DeepSeek 官方 github.com/deepseek-ai/DeepSpec 已提供 DSpark 训练流水线且原生支持 DSv4-Flash。若目标只是微调 DSv4-Flash-DSpark，DeepSpec 可能比改造 speculators 更直接。本 issue 的价值在于：把 DSv4-Flash DSpark 纳入 speculators 的统一 draft 训练框架（与 EAGLE-3/DFlash/MTP 一致的 config/数据/部署契约）。需讨论是否值得。
• self-drafting vs 独立 draft：DSv4-Flash-DSpark 是 self-drafting（draft=target 层）。speculators 的 DSpark 是独立 dense draft。微调时是保持 self-drafting（draft 层=target MoE 层）还是改成独立 MoE draft？前者更贴近官方、改造在 converter；后者更通用、改造在 layer 注册。倾向前者。
• MoE draft 在 DSv4 上的接受率：self-drafting draft=target 层理论上接受率高（与 target 同构），但 mHC+MLA+FP4 expert 的训练稳定性需小规模验证（DSv4-Lite 或减少 expert 数）。
• expert FP4 训练：DSv4 expert 是 FP4，微调时是否保持 FP4？speculators 的 trainer（src/speculators/train/trainer.py）当前 dense-only，FP4 MoE 训练需额外支持。

[chengda-wu]

DSv4-Flash DSpark 投机层参数规模估算

按 deepseek-ai/DeepSeek-V4-Flash-DSpark 的 config.json 实际字段估算 draft（self-drafting，复用 target 第 40/41/42 层 + DSpark heads）的可训练参数量。

关键配置（已核实）

字段	值
hidden_size	4096
dspark_target_layer_ids	[40, 41, 42] → draft 复用 3 层 target MoE 层
n_routed_experts / n_shared_experts	256 / 1
num_experts_per_tok	6
moe_intermediate_size	2048
expert_dtype	fp4
hc_mult	4
dspark_markov_rank / vocab_size	256 / 129280
MLA	num_attention_heads=64、head_dim=512、qk_rope_head_dim=64、q_lora_rank=1024、o_lora_rank=1024、num_key_value_heads=1（CSA/HCA hybrid，compress_ratios 交替 4/128）

逐项计算

单个 routed expert（SwiGLU：gate + up + down）
3 × hidden_size × moe_intermediate_size = 3 × 4096 × 2048 ≈ 25.17M

单层 MoE 层

子项	参数量
routed experts（256 × 25.17M）	6.442B
shared expert（1，intermediate=2048）	25.17M
router（4096 × 256）	1.05M
MLA attention（q_lora/o_lora=1024，量级估算）	~84M
RMSNorm ×2	8K
单层合计	≈ 6.55B

DSpark draft 总参数

部分	参数量
[1] draft backbone = 3 层复用 MoE 层	19.66B
[2] DSpark heads：MarkovHead（vocab×256 + 256×vocab ≈ 66M）+ FC（hc_mult=4，3 层 → 12×H×H ≈ 201M）+ ConfidenceHead	0.27B
draft 总计	≈ 19.9B

其中 routed experts 占 19.33B（≈ 97%），是绝对主体；attention/router/head 合计 < 3%。

两个关键数字

1. 总参数 ≈ 20B，但 per-token 激活仅 ≈ 0.53B（每层 6 routed + 1 shared = 7 experts × 25.17M × 3 层）。稀疏度 2.7%——draft 很"宽"但很"稀疏"，与 target 同构正是 self-drafting 接受率高的原因。

2. expert 权重存储（仅 3 层 routed experts）

精度	显存
FP4（官方 expert_dtype）	9.66 GB
FP8	19.33 GB
BF16	38.65 GB

对本 issue 改造工作量的直接影响

• 规模锚点：~20B 的 draft 已不是"小 drafter"。A 组（dspark converter）要抽取/映射的 expert 权重就 19.3B，converter 的 fuse/unfuse 与 key 重映射是主要工作量，不能照搬 MTP converter（MTP 是单层，这里是 3 层 × 256 experts）。
• B/C 组（MoE + MLA + mHC layer）：参数大头在 expert MLP，但训练稳定性风险在 MLA attention + mHC hidden（hc_mult*hidden_size）的 K/V 构造——参数小但最难写对。
• D 组（训练侧，无 EP）：speculators 训练并行只有 FSDP2 + SP + DP，没有 expert parallel（EP）（src/speculators/train/distributed.py:88-131 仅 SP+DP process group）。这意味着 256 个 expert 全靠 FSDP 全分片摊到每张卡，无法按 expert 切分。BF16 全参数 + 优化器（≈4× param bytes）下，仅 draft：
  • 8 卡 ≈ 19.9 GB/卡（draft only，不含 target 与激活）
  • 4 卡 ≈ 39.9 GB/卡
  • 16 卡 ≈ 10.0 GB/卡
    考虑还要加载 284B 的 target 取 hidden state（即便 frozen 也要放显存或 offload），8 卡以内基本不可行，16 卡起步。若保持官方 FP4 expert 训练（需 trainer 支持 FP4 MoE），显存可减半，但 speculators trainer 当前 dense-only（见 issue 正文章节 D-8）。这正是"是否直接用 DeepSpec 微调"开放问题的现实权重——DeepSpec 原生支持 DSv4 且大概率带 EP，speculators 改造需把无-EP 的 ~20B MoE 训练跑通。

假设与不确定性（透明列出）

• n_shared_experts=1 时 shared expert intermediate 按 moe_intermediate_size=2048 计（即 1 个 expert 大小）；若 DeepSpec 实现按 moe_intermediate_size × num_experts_per_tok 计，shared 每层升至 ~151M，对 20B 总量影响 < 1.5%，结论不变。
• MLA attention 为量级估算（DSv4 的 CSA/HCA hybrid 用 compress_ratios + index_head_dim/index_n_heads，比 V3 MLA 更复杂），但 attention/router/head 合计 < 3%，不改变总规模量级。
• 未计入 embed_tokens/lm_head（self-drafting 下复用 target，非 draft 新增可训练参数）。
• 假设第 40/41/42 层均为 MoE（DSv4-Flash 主体 MoE；compress_ratios 在这三层为 0 指的是 attention 无压缩，不影响 FFN 是否 MoE）。若实际这三层含 dense FFN，routed experts 项需下调，需对照 DeepSpec 权重布局核实。

[chengda-wu]

阶段性进展（A + B/C + D 已落地，端到端训练待数据生成路径）

分支 dspark-dsv4-flash-finetune（off upstream main f8cf626），按"每完成一部分 review + commit"推进。计划见 ~/.claude/plans/immutable-purring-pearl.md。issue 正文 A/B/C/D 四组的实现状态：

已完成（4 个 commit，8 个新单测全过，ruff 全清）

组	commit	内容
B+C 层 + backbone	8c9bc92	DeepseekV4DSparkDecoderLayer（MoE + MLA + mHC），DSpark target-hidden KV 注入范式：KV = [ctx_kv (verifier target_hidden) ; noise_kv (draft hidden)]，复用 V4 的 HyperConnection / SparseMoeBlock / MLA projections；每层 target_fold（HyperHead）折叠 verifier 的 mHC 流。backbone 侧 dflash/components.py 按 model_type 分发 layer/norm/rotary/fold，dflash/core.py 走 mHC [B,S,hc_mult,hidden] 残差流 + V4 {"main","compress"} rotary dict + expand/fold + V4-aware _init_weights（PreTrainedModel._init_weights 会让 V4 的 HyperConnection/Experts/Router/HyperHead 留作 torch.empty 垃圾）。RoPE 按 [ctx;noise] 全长对齐（ctx 用前 S_ctx、noise 用后 S_q）。draft 层（target 40/41/42）是 sliding_attention（compress_ratio=0），无 CSA/HCA compressor——这正是实际跑的路径。
A converter	ddb79ea	convert/dspark/converter.py：官方 DeepseekV4ForCausalLM（完整 43 层 self-drafting checkpoint）→ speculators DSpark。抽取 target 层 [40,41,42] 权重，model.layers.{N}.* → layers.{i}.* 重映射；fuse 官方 per-expert w1/w2/w3（key 带双点 experts..{N}.）成 3D gate_up_proj/down_proj（speculators DeepseekV4Experts 的布局）；从 compress_ratios 推导 3 层 layer_types/mlp_layer_types；verifier 填充 embed/lm_head/verifier_norm；DSpark heads（fc / hidden_norm / fold_module / target_fold / markov_head / confidence_head）fresh-init 留给微调。注册到 convert/entrypoints.py（algorithm="dspark" + 自动检测 dspark_target_layer_ids）。
D 训练侧	c887741	scripts/train.py：DRAFT_ARCH_CONFIGS 加 deepseek_v4；create_transformer_layer_config 守卫 deepseek_v4（MoE/mHC/MLA config 无法从 verifier 现场合成，必须走 --from-pretrained（converted）或 --draft-config）。DSv4 路由是 aux-loss-free，trainer 无需改；DSpark 无 batch-shift preprocess。

测试：test_dspark_dsv4_layer.py(3) + test_dspark_dsv4_backbone.py(2) + test_dspark_converter.py(3，含 convert→reload 权重 round-trip 与 FP4 守卫) + test_draft_config_init.py 加 1 个守卫用例。

关键技术发现（实现中确认）

1. 官方 checkpoint 是完整 DeepseekV4ForCausalLM（43 层），DSpark 是 self-drafting，draft 复用 target 40/41/42；compress_ratios[40:43]=[0,0,0] → sliding，无 compressor。converter 抽子集即可，无需重训。
2. V4 save_pretrained 把 fused experts 拆回官方 per-expert w1/w2/w3 布局（key experts..{N}.，双点），converter 必须重新 fuse——这点和 MTP converter 的 experts.{N}.gate_proj 布局不同，不能照搬。
3. 训练侧 --from-pretrained 直接加载 converter 产出的完整 V4 config，绕过 create_transformer_layer_config，所以 D 组改动很小（只注册 + 守卫）。
4. V4 的 apply_rotary_pos_emb 是单 tensor 版、不按 q_len 切片（不像 Qwen3 DFlash），ctx/noise 的 RoPE 位置对齐需手动切 cos[:, :ctx_len] / cos[:, -q_len:]。

遗留问题 / 未完成

1. FP4→BF16 expert 反量化（A 组缺口）：converter 目前对非浮点 expert 张量抛 NotImplementedError（在 fuse 之前检查，避免 torch.cat 把 uint8 提升回 float 而掩盖 FP4）。需对照真实 checkpoint 的 FP4 packing 布局写反量化。本轮按计划 BF16-first，FP4 列为后续。→ 真实官方 checkpoint 转换被此阻塞，目前用 BF16 小规模 fixture 验证。
2. V4 数据生成路径（D 组缺口，端到端训练的硬阻塞）：draft 的 fc 输入是 num_target_layers * hidden_size，而 V4 verifier 每层隐状态是 hc_mult * hidden_size 的 mHC 流。必须在数据生成阶段用 verifier 的 hc_head 把每层 mHC 流折叠到 hidden 再存储，否则 collate 的 per-layer 宽度对不上。src/speculators/data_generation/ 当前无 V4 分支。
3. CSA/HCA compressor causality + target_fold 经验验证：draft 层是 sliding，compressor 路径未实际跑到（已 wired 但对 ctx/noise mask 对齐标了 TODO）；target_fold 用独立 HyperHead（不复用 draft 的 attn_hc）是设计假设，需对照真实 checkpoint 数值验证。
4. 端到端 scripts/train.py 单步 + BF16 显存：依赖 [RFC] Fine-tune DeepSeek-V4-Flash official DSpark speculator in speculators #2 数据生成路径 + ≥16 卡（issue 上一条 comment 已估算）。

下一步计划

优先级按"解锁端到端"排序：

1. V4 数据生成路径（最高优先，解锁端到端训练）：在 data_generation/ 加 V4 verifier 的 mHC 隐状态折叠（hc_head：hc_mult*hidden → hidden per layer），让 train/data.py collate 见到 num_target_layers*hidden_size。然后跑 scripts/train.py --speculator-type dspark --from-pretrained <converted> --dry-run 验证 config/权重落盘，再单步 forward+backward。
2. FP4 反量化（解锁真实官方 checkpoint）：对照 DeepSeek-V4-Flash-DSpark 的 expert FP4 packing 写 dequant，接到 converter 的 _check_expert_dtype 之后。可与 1 并行（1 用 BF16 fixture 即可）。
3. 数值验证：用真实 checkpoint 跑 converter→reload，校验关键权重 round-trip；在 sliding 路径上对照 V4 原层在 target_hidden==hidden 退化情形的输出近似；compressor 路径 causality 对齐。
4. BF16 显存实测：8/16 卡 draft-only 显存，确认 ≥16 卡可行（对齐上一条 comment 估算）。

征求方向：1 和 2 先做哪个？我个人倾向先做 1（数据生成路径），因为它直接解锁端到端 dry-run/单步验证，且能用 BF16 fixture 跑通整条链路；FP4 反量化更多是"对接真实 checkpoint"的工程项，可在链路验证后再接。

[chengda-wu]

代码审查与修复进展（commit 3126a6f）

在分支 dspark-dsv4-flash-finetune 上对 A/B/C/D 已落地代码做了正确性审查，并提交修复：

3126a6f — [DSpark/DSv4] Fix V4 DSpark attention path and dense target-hidden contract

发现并修复的问题

严重度	问题	修复
P0	V4 attention 缺 num_key_value_groups，eager 路径会炸	对齐上游 DeepseekV4Attention，设为 num_attention_heads
P0	默认 simple_flex_attention；V4 的 AttentionInterface 未注册 flex，且 sinks 仅 eager 实现	deepseek_v4 强制 eager；显式 sdpa/flex 直接 ValueError
P0	CSA/HCA compressor 假接线：docstring 说会 raise，实际会用错位的 position_ids/block_bias 执行	非 sliding_attention 在构造期 NotImplementedError（正式 draft 层 40/41/42 本就是 sliding）
P1	sinks 留作 torch.empty，from-scratch / fresh-init 时 logits 垃圾	_init_weights 对齐上游 zeros_(sinks)
P1	backbone 把 dense fc_output expand 成假 mHC，再经 fresh-init target_fold 折回——与「数据生成用 hc_head 预折叠」契约矛盾	去掉 target_fold；verifier context 保持 dense，与 Qwen3 DFlash 注入范式一致
P1	converter 只拦非浮点 expert 张量；expert_dtype=fp4 可能绕过	同时拦 config 的 expert_dtype ∈ {fp4,mxfp4,nvfp4} + 非浮点张量；fuse 缺 w1/w2/w3 时报清晰错误
nit	未知 model_type 静默落到 Qwen3	get_components 明确 ValueError

测试

• DSv4 相关：test_dspark_dsv4_layer / test_dspark_dsv4_backbone / test_dspark_converter — 12 passed
• 新增覆盖：eager 强制、sdpa 拒绝、sinks zero-init + grad、CSA 拒绝、expert_dtype=fp4 拒绝
• 相关回归（draft config + dflash/dspark）：90 passed

仍未完成（优先级不变）

1. V4 数据生成路径（端到端硬阻塞）：data_generation/ 需用 verifier hc_head 把每层 mHC 流折成 hidden 再存储，否则 collate 宽度对不上 fc。
2. FP4→BF16 反量化：真实官方 DeepSeek-V4-Flash-DSpark checkpoint 转换仍被挡；目前只能 BF16 fixture。
3. 端到端 scripts/train.py 单步 + ≥16 卡显存实测：依赖 [Survey] Draft-side MoE support across speculators and SpecForge #1。

下一步建议

仍倾向先做 V4 数据生成路径（解锁 dry-run / 单步），FP4 反量化可并行。本轮修复已把 sliding + eager + dense target-hidden 这条实际训练路径理顺，适合在此基础上接数据生成。

[chengda-wu]

遗留项推进：V4 数据生成 mHC 折叠（无 GPU 环境，仅 CPU 单测验证）

按阻塞优先级推进了 #1 V4 数据生成路径。本机没有训练/vLLM 运行环境，未做端到端抽取验证；CPU 单测与代码审查通过。

做了什么

1. 本地 vLLM（真正的抽取路径） — 仓库 chengda-wu/vllm

• 原行为：aux mHC 流用 mean(dim=1) 压成 [T, H]（临时近似）
• 现行为：nvidia / amd 路径改为走 verifier hc_head 折叠（与 HF DeepseekV4HyperHead / 训练侧 dense 契约一致）
• 文件：vllm/models/deepseek_v4/nvidia/model.py、amd/model.py
• 需在该 vLLM 仓库单独 commit / 部署后，用 extract_hidden_states 重跑数据生成

2. speculators — commit b2b3e20

• 新增 src/speculators/data_generation/mhc.py：
  • fold_mhc_stream / fold_stacked_mhc_hidden_states（对齐 HyperHead 数学，可供 offline 补折叠）
  • validate_dense_hidden_states（拒收 [S,N,hc_mult,H] 未折叠导出）
  • load_hc_head_from_verifier_state
• offline.check_hidden_states / ArrowDataset._get_raw_data 接入校验，避免错误宽度静默 flatten 进 fc
• CPU 单测：tests/unit/data_generation/test_mhc.py（对照 transformers DeepseekV4HyperHead）— 8 passed

仍未完成

项	状态
FP4→BF16 反量化	未做：无真实官方 packing 样例，盲写容易静默写错权重；converter 继续硬拒 expert_dtype=fp4
端到端 dry-run / 单步 / ≥16 卡显存	未做：依赖可用 GPU + 上述 vLLM 部署 +（最好）BF16/反量化后的 converted ckpt
vLLM 侧 GPU 数值回归	未做：改完需在有卡环境对 aux 输出对照 hc_head reference

建议验证清单（有环境时）

1. 用改过的 vLLM 起 launch_vllm.py + extract_hidden_states，确认写出的 hs_*.safetensors 为 dense [S, N, H]（H=4096，不是 hc_mult*H）
2. check_hidden_states / 训练 dataloader 不再因 rank-4 报错
3. scripts/train.py --speculator-type dspark --from-pretrained <converted> --dry-run 再单步
4. 真要接官方 ckpt：对照 FP4 packing 实现 converter 反量化

[chengda-wu]

阶段性暂停：代码已全部清理、提交并推送

任务暂停,同步当前状态。两个仓工作树均干净,全部已 push,无未提交残留。

speculators — chengda-wu/speculators 分支 dspark-dsv4-flash-finetune

自上次更新(b2b3e20)后新增 8 个 commit(均已推送):

commit	内容
3126a6f	修正 V4 DSpark attention path,确立 dense target-hidden 契约(对齐 vLLM pre-folded target,移除 per-layer target_fold 退化路径)
b2b3e20	mHC fold helpers + 拒收未折叠的 V4 hidden states(data_generation/mhc.py)
c5dd575	V4 datagen smoke 脚本 + dense HS shape 校验
24475f0	prepare_data 改用 DeepSeek-V4 encode_messages(deepseek_v4_chat.py)
e1f9aae	datagen vLLM 启动参数对齐已知可用的 H200 serve 配置
02ec30a	硬编码本地 V4-Flash 路径,去掉 trust-remote-code
890d96f	datagen serve 对齐 chunked-prefill,启用 Triton indexer
04d5a9b	撤回 Triton indexer workaround(CuteDSL 待 cutlass-dsl 修复)

vLLM fork — chengda-wu/vllm 分支 main

确认已修改 vLLM 代码(4 commit,均已推送):

commit	内容
50d1ed3	aux hidden states 改用 hc_head 折叠(替代原先 mean(dim=1))
4c3ff9a	打磨 aux hc_head fold:抽 helper + 复用 last-layer fold
811c678	加 VLLM_USE_TRITON_INDEXER_Q escape hatch 绕 CuteDSL JIT
94b7718	revert 上一条(CuteDSL 待上游 cutlass-dsl 修复)

说明:vLLM 的改动只针对数据生成的 hidden-state 抽取路径(aux mHC 流折叠),不是 serving/部署侧。speculators-native DSv4 DSpark checkpoint 的 vLLM 部署路径尚未开始(见下)。

仍未完成 / 下一步

项	状态
FP4→BF16 反量化	未做:无真实官方 packing 样例,converter 继续硬拒 expert_dtype=fp4
端到端 dry-run / 单步 / ≥16 卡显存	未做:依赖可用 GPU + 上述 vLLM 抽取验证 + (最好)反量化后的 converted ckpt
vLLM 侧 GPU 数值回归	未做:改完需在有卡环境对 aux 输出对照 hc_head reference
vLLM serving 部署路径	未开始:已确认 vLLM 注册了 "DSparkDraftModel" → DSparkDeepseekV4ForCausalLM(registry.py:599),但 update_dspark 写死走 qwen3 loader。两条路待定——(A) 改 fork 的 update_dspark 按 model_type 分发到 DSparkDraftModel + 对齐 speculators key 布局;(B) 写反向 converter(speculators-native → 官方 self-drafting mtp.{i}.* 格式)走已有官方 loader。两条路都要先去掉 speculators 侧 target_fold(3126a6f 已做)。倾向 A(训完直接 serve,免离线转换 + FP4 量化)。

CPU 单测与代码审查通过;本机无 GPU,未做端到端验证。恢复任务时从"serving 部署路径"或"GPU 端到端验证"继续。