1. 执行摘要

PR #37293 是一个纯文档站变更：在 DeepSeek-V4 cookbook 页面新增实验性多模态变体 Flash Vision（deepseek-ai/DeepSeek-V4-Flash-Vision-Exp）。改动分两层——配置数据层新增 flash-vision 变体、模型映射、部署格、MMMU-Pro 基准与投机解码门控；文档渲染引擎层把 Docker 镜像解析链扩展出 hw|variant|quant → variant|quant 两级键，使 Flash Vision 格自动命中 preview 镜像 lmsysorg/sglang:dev-dsv4-flash-vision，其余变体解析结果不变。B200 FP4 low-latency 格已端到端验证（MMMU-Pro 74.96%，4×B200 TP=4），其余格为 in-progress / pending。整个变更依赖引擎支持 PR #37253，release 前以 preview 镜像引导用户，并有配套的 cookbook-add-model 技能文档同步。

2. 功能与动机

PR body 明确动机：把 DeepSeek 首个实验性多模态 V4 checkpoint 接入既有页面，而不是新建页面——

Add the experimental multimodal checkpoint deepseek-ai/DeepSeek-V4-Flash-Vision-Exp (engine support: #37253) to the DeepSeek-V4 cookbook as a new Flash Vision variant on the existing page.

该 checkpoint 是 0731 Flash 基座 + vision encoder / aligner（305B 总参数），MDX 正文称其为 DeepSeek's first experimental multimodal V4 checkpoint。文档需要给出：已验证部署命令（B200 FP4 low-latency）、实测精度（MMMU-Pro 74.96%）、以及一组未验证不冒充已验证的状态治理——balanced / high-throughput 标记 verificationStatus: "in-progress"，其它硬件格 pending。同时由于 Flash Vision 与 Flash / Flash Official 共享 hw / quant / strategy 维度值，必须扩展镜像解析键位才能让变体级 preview 镜像生效。

3. 实现拆解

1. 配置数据扩展（deepseek-v4.jsx）：新增 flash-vision 变体（305B · Exp）与 "flash-vision|fp4" 模型映射；在 accuracyLabels 追加 mmmu_pro_pct；在 benchmarkCommands.accuracy 增加按变体键控的 MMMU-Pro 复现命令；dockerImages 增加 "flash-vision|fp4" 指向 preview 镜像；投机解码面板对 flash-vision 隐藏 EAGLE 预设、禁用 DSpark 并附原因。最后追加 B200 FP4 三策略格（low-latency 已验证，其余 in-progress）以及 B300 / GB200 / GB300 / H200 / H100 的 pending 格，所有格带 warn banner。

2. 基准数据（deepseek-v4-benchmarks.jsx）：新增 Flash Vision 基准条目，只有 B200 low-latency 格携带 sglang_version 与实测精度 74.96%（附测量条件），其余占位。注意 h100 只配 balanced 一格，与其它硬件三策略齐全不一致。

3. 共享引擎镜像解析链（_deployment.jsx 与 _playground.jsx）：两处同一逻辑——镜像选择从 hw|quant|strategy → hw|quant → hw 扩展为 hw|variant|quant → variant|quant → hw|quant|strategy → hw|quant → hw。新键插在链首，历史配置（无 variant 键）解析结果逐字节不变。两个引擎必须同步改，因为 Mintlify 剥离共享模块状态，playground 只能复制一份解析逻辑。

4. 页面正文（DeepSeek-V4.mdx）：Deploy 面板上方加 <Note> 预告 preview 镜像；§1 变体表与资源行增加 Flash Vision；#vision-note 锚点章节说明 preview 构建、span 对齐 chunked prefill 与 radix-cache 行为、shared-experts fusion 自动关闭、target-only 投机与评测 max_tokens 提示；§3.4 补 DSpark 说明；§3.5 增加视觉 image-input 示例（输出待补）。

5. 配套技能文档（cookbook-add-model）：config.jsx.tmpl、SKILL.md、authoring-reference.md 同步五级镜像键契约，并重申询问作者实际构建、不要猜 release 标签。

测试与验证配套：无自动化测试文件；PR body 报告 mint validate 与 mint broken-links 通过，并在 mint dev 下手工冒烟 badge 状态、镜像解析、精度卡作用域、playground 门控与锚点链接。

docs/src/snippets/configs/deepseek-ai/deepseek-v4.jsx

本 PR 的核心配置数据文件：新增 flash-vision 变体、模型映射、preview 镜像键、MMMU-Pro 指标与复现命令、投机解码门控，以及 B200 / B300 / GB200 / GB300 / H200 / H100 的部署格。

// ===== Flash Vision (Exp) 相关配置摘录（deepseek-v4.jsx） =====
// 变体表：新增 305B 实验性多模态条目（0731 Flash 基座 + 视觉编码器）。
variants: [
  { id: "flash", label: "Flash", subtitle: "284B" },
  { id: "flash-official", label: "Flash Official", subtitle: "284B · 0731" },
  { id: "flash-vision", label: "Flash Vision", subtitle: "305B · Exp" },
  { id: "pro", label: "Pro", subtitle: "1.6T" },
  { id: "pro-official", label: "Pro Official", subtitle: "1.6T · 0813" },
],
// 模型映射：该变体只发布 FP4 量化，直接指向官方实验 checkpoint。
modelNames: {
  "flash-vision|fp4": "deepseek-ai/DeepSeek-V4-Flash-Vision-Exp",
},
// 专属 preview 镜像：引擎支持尚未进入 release（见 sgl-project/sglang#37253），
// 由镜像解析链保证只有 Flash Vision 格命中它；其余硬件键保持 `:latest`。
dockerImages: {
  "flash-vision|fp4": "lmsysorg/sglang:dev-dsv4-flash-vision",
},
// 投机解码门控：checkpoint 自带 DSpark draft head，但“图像批次 + 投机解码”
// 尚未验证，因此 EAGLE 预设对该变体隐藏、DSpark 禁用，配方一律 target-only。
"mtp-314": { hide: { variant: ["flash-official", "flash-vision", "pro-official"] } },
dspark: {
  disable: [
    { when: { variant: ["flash-vision"] },
      reason: "The Flash Vision checkpoint bundles a DSpark head, but speculative decoding is not yet verified with image inputs — the cookbook recipes run target-only for now." },
  ],
},
// B200 + FP4 low-latency 格：唯一端到端验证的部署形态（4×B200、TP=4）。
{
  match: { hw: "b200", variant: "flash-vision", quant: "fp4", strategy: "low-latency", nodes: "single" },
  verified: true,
  warn: "DeepSeek-V4-Flash-Vision-Exp support has not shipped in an SGLang release yet (sglang PR 37253): Docker mode already points at the preview image; for Python mode install SGLang from that PR. See [Flash Vision notes](#vision-note).",
  flags: ["--model-path {{MODEL_NAME}}", "--tp 4", "--mem-fraction-static 0.85", "--host {{HOST_IP}}", "--port {{PORT}}"],
},

docs/src/snippets/configs/deepseek-ai/deepseek-v4-benchmarks.jsx

基准数据入口：为 Flash Vision 各格新增基准条目，只有已实测的 B200 low-latency 格携带精度与 sglang 版本，其余占位待终验。

// ===== B200 + FP4 — Flash Vision (Exp) 基准条目（deepseek-v4-benchmarks.jsx） =====
// 只有 low-latency 格带实测数据：MMMU-Pro (standard, 10-option) 74.96%，
// 测量条件与 sglang 构建版本一并记录，保证可复现；其余格先占位，待终验后翻转。
{
  match: { hw: "b200", variant: "flash-vision", quant: "fp4", strategy: "low-latency", nodes: "single" },
  sglang_version: "dev-dsv4-flash-vision",
  accuracy: { mmmu_pro_pct: 74.96 },
  notes: "MMMU-Pro (standard, 10-option) measured with sgl-eval on 4×B200 (TP=4) at temperature 1.0, top-p 0.95, --reasoning-effort max.",
},
// balanced / high-throughput 与其它硬件（B300 / GB200 / GB300 / H200 / H100）
// 均为 pending 占位；h100 目前只配 balanced 一格，与其他硬件三策略齐全不一致。
{ match: { hw: "b200", variant: "flash-vision", quant: "fp4", strategy: "balanced", nodes: "single" } },
{ match: { hw: "b200", variant: "flash-vision", quant: "fp4", strategy: "high-throughput", nodes: "single" } },
{ match: { hw: "h100", variant: "flash-vision", quant: "fp4", strategy: "balanced", nodes: "single" } },

docs/src/snippets/_deployment.jsx

共享部署引擎：Docker 镜像解析链扩展出变体级键位，是让 Flash Vision 命中 preview 镜像、同时保持其它 cookbook 向后兼容的关键逻辑改动。

// ===== Docker 镜像解析链（_deployment.jsx；_playground.jsx 为同一逻辑的副本） =====
// 解析优先级从具体到宽泛：命中第一个存在的键即返回。
// 新增的 ``hw|variant|quant`` 与 ``variant|quant`` 两级，用于“同一硬件 / 量化下，
// 某个 checkpoint 变体需要专属镜像”的场景（如 Flash Vision 的 preview 构建）；
// 原有 ``hw|quant|strategy → hw|quant → hw`` 链放在其后，保证不带 variant 键的
// 历史配置解析结果与改动前完全一致。
const di = config.dockerImages || {};
const image = di[`${sel.hw}|${sel.variant}|${sel.quant}`] // 例 : "b200|flash-vision|fp4"
  || di[`${sel.variant}|${sel.quant}`] // 例 : "flash-vision|fp4"（跨硬件共享镜像）
  || di[`${sel.hw}|${sel.quant}|${sel.strategy}`] // 原有策略级键（如 spec-decoding preview 镜像）
  || di[`${sel.hw}|${sel.quant}`] // 原有“硬件 + 量化”键
  || di[sel.hw] // 原有硬件级键
  || "lmsysorg/sglang:dev"; // 兜底 dev 镜像

5. 评论区精华

本 PR 几乎没有形成 review 交锋：review_comments_count = 0，唯一 approval（wisclmy0611）为空正文，唯一 issue 评论是 mintlify[bot] 的预览部署通知。值得提炼的讨论点全部来自 PR body 的自述性设计权衡：

• 镜像解析链为何要动共享引擎：Flash Vision 与 Flash / Flash Official 共享 hw / quant / strategy 维度值，旧键位无法把镜像作用域切到变体级，因此新增两级变体键。
• 双引擎重复维护的架构约束：> Both engines carry the change because the playground duplicates image resolution by design (Mintlify strips shared module state). 这是 Mintlify 平台限制下的刻意取舍，不是冗余代码。
• 验证数据治理纪律：> recorded as per-cell accuracy on the verified low-latency cell only — the in-progress cells stay on the "pending" state. 只有实测格标 verified，其余用 verificationStatus 三态占位，避免未验证数据冒充已验证。

6. 风险与影响

• 共享引擎回归面：_deployment.jsx / _playground.jsx 被所有 cookbook 页面复用。新键插在解析链首，理论上对不带 variant 键的存量配置向后兼容；但若某现存配置恰好定义了 variant|quant 或 hw|variant|quant 键（此前为永不命中的死键），行为会变化，建议对其它 cookbook 页面做一次镜像解析冒烟回归。
• 全局指标行扩容：mmmu_pro_pct 加入 accuracyLabels 后，Flash / Pro 等没有该数据的变体，基准卡也会渲染该行，可能出现空值或 N/A，需要确认渲染层对缺失精度的处理。
• 数据不对称：h100 的 flash-vision 只有 balanced 一格（cells 与 benchmarks 均如此），缺少 low-latency / high-throughput 入口，用户按 h100 查找时入口不完整。
• 依赖未发布引擎：所有 Flash Vision 格依赖 #37253；Python 模式命令要求用户自行安装 PR 分支，若照抄到 release 环境会失败（warn banner 已缓解）。#37253 合入并发布后，需要把 preview 镜像统一替换回 :latest，这是明确的后续维护项。
  • 本 PR 不含任何引擎运行时代码，不影响 SGLang 服务稳定性。

7. 关联脉络

本 PR 与引擎支持 PR #37253 构成“支持 + 指南”的配对关系：文档侧所有 Flash Vision 格与 preview 镜像都指向它，待其合入并发布后需做一轮镜像 tag 替换。测试侧，同仓库近期有 #37214 重新启用 DeepSeek-V4-Flash 的 NPU 夜间性能用例，说明该模型家族在测试与文档两条线上并行铺开。更宏观的演进信号在 .claude/skills/cookbook-add-model：dockerImages 契约从 hw → hw|quant → 五级键链持续扩展，意味着 cookbook 基础设施正从“一页一模型”走向“一页多变体、变体级差异化”，本次新增的 flash-vision 是其第一个变体级 preview 镜像用例。