PR 分析报告 #26885

执行摘要

本 PR 对 SGLang 文档中的部署 cookbook 进行了架构级重构，将每个模型独立编写的 React 组件替换为两个共享的配置驱动引擎（_deployment.jsx 和 _playground.jsx）。以 DeepSeek-V4 作为示范，新增了交互式 Playground、深链接、可重现基准等能力，并提供了 Claude Code 技能以引导新增模型。这是文档基础设施向配置驱动方向的重要演进。

功能与动机

原有 cookbook 中每个模型都有一份自包含的部署代码生成器（<model>-deployment.jsx），重复实现硬件选择、变体、量化、命令构建、暗色模式等 UI 逻辑，维护代价高且易出错。PR 旨在通过配置驱动模板实现一次编写、全局共享，使得新增模型仅需提供配置文件和简短 MDX 页面，无需编写引擎代码。具体描述见 PR body。

实现拆解

1. 配置数据契约：在 docs_new/src/snippets/configs/deepseek-ai/deepseek-v4.jsx 定义 5 维验证矩阵（hw × variant × quant × strategy × nodes），包括 modelNames、placeholders、benchmarkCommands 等纯数据字段。
2. 共享部署引擎：_deployment.jsx 读取配置，通过 findCell 定位匹配组合并生成 sglang serve / cURL 命令，支持 Docker 模式、多节点注入、环境变量持久化、基准重现弹窗。
3. 交互式 Playground 引擎：_playground.jsx 实现差分覆盖沙箱，用户可在已验证基础上调整并行策略、MoE 等轴，利用 findMatchingCell 检测覆盖后是否命中其他已验证组合，并展示即时 diff。
4. 旧组件删除：移除 deepseek-v4-deployment.jsx（-1263 行），该组件承载了 DeepSeek-V4 的完整选择逻辑和渲染。
5. Claude Code 技能与模板：新增 .claude/skills/cookbook-add-model/ 和 cookbook-review-pr/，包含配置模板、MDX 模板、作者指南和引擎轴参考，支持 /cookbook-add-model 等指令。
6. 文档页面适配：修改 DeepSeek-V4.mdx，由直接引用旧组件改为导入新引擎并传递配置。

docs_new/src/snippets/_playground.jsx

新增 Playground 引擎，实现交互式差分覆盖沙箱，核心逻辑包括 findMatchingCell、resolveModelName 等。

// _playground.jsx — 引擎内部的纯数据辅助函数，负责根据配置查找已验证组合
// 这些函数与视图完全分离，便于测试和推理
​
const DIMENSIONS = ["hw", "variant", "quant", "strategy", "nodes"];
​
// 在 cells 数组中精确查找匹配当前选择的 cell
const findCell = (cells, sel) =>
  cells.find((c) => DIMENSIONS.every((d) => c.match[d] === sel[d]));
​
// 比较 flags 数组（有序）
const flagsEq = (a, b) =>
  a.length === b.length && a.every((x, i) => x === b[i]);
​
// 比较 env 数组（无序集合）
const envEq = (a, b) => {
  if (a.length !== b.length) return false;
  const set = new Set(a);
  for (const x of b) if (!set.has(x)) return false;
  return true;
};
​
// 在应用覆盖后，查找是否存在另一个已验证的 cell 与当前 (env, flags) 相同
const findMatchingCell = (cells, sel, pgEnv, pgFlags) => {
  for (const c of cells) {
    if (c.match.hw !== sel.hw) continue;
    if (c.match.variant !== sel.variant) continue;
    if (c.match.quant !== sel.quant) continue;
    if (c.match.nodes !== sel.nodes) continue;
    if (flagsEq(c.flags || [], pgFlags || []) && envEq(c.env || [], pgEnv || [])) {
      return c;
    }
  }
  return null;
};
​
// 解析模型 HF slug：优先 hw|variant|quant，其次 variant|quant
const resolveModelName = (sel) => {
  const triple = `${sel.hw}|${sel.variant}|${sel.quant}`;
  const pair = `${sel.variant}|${sel.quant}`;
  return config.modelNames[triple] ?? config.modelNames[pair] ?? "";
};
​
// 在命令模板中替换 {{PLACEHOLDER}}（MODEL_NAME 特殊处理）
const interpolate = (text, env, modelName) =>
  text.replace(/{{(\w+)}}/g, (_, key) =>
    key === "MODEL_NAME" ? modelName : (env[key] ?? `{{${key}}}`));
​
// 解析节点选项 id，如 "multi-2" -> 2
const parseNnodes = (id) => {
  if (id === "single") return 1;
  const m = /^multi-(\d+)$/.exec(id);
  return m ? parseInt(m[1], 10) : 1;
};

docs_new/src/snippets/_deployment.jsx

新增部署引擎，读取配置生成命令行和cURL命令，支持Docker和多节点。

// _deployment.jsx — 部署命令生成引擎，无模型特定代码
​
export const Deployment = ({ config, benchmarks }) => {
  if (!config) {
    return <div style={{padding: 12, color: "#b91c1c", }}>Deployment: missing <code>config</code> prop</div>;
  }
​
  // 硬件目录（跨 cookbook 共享），config.hardware 在运行时合并
  const HARDWARE_CATALOG = {
    nvidia: [
      { id: "h100", label: "H100", vram: "80GB" },
      { id: "h200", label: "H200", vram: "141GB" },
      { id: "b200", label: "B200", vram: "192GB" },
      { id: "b300", label: "B300", vram: "288GB" },
      { id: "gb200", label: "GB200", vram: "192GB" },
      { id: "gb300", label: "GB300", vram: "288GB" },
    ],
    amd: [
      { id: "mi300x", label: "MI300X", vram: "192GB" },
      { id: "mi325x", label: "MI325X", vram: "256GB" },
      { id: "mi350x", label: "MI350X", vram: "288GB" },
      { id: "mi355x", label: "MI355X", vram: "288GB" },
    ],
  };
​
  // 暗色模式感知的样式工厂
  const makeStyles = (isDark) => ({
    container: { maxWidth: "900px", margin: "0 auto", display: "flex", flexDirection: "column", gap: "3px" },
    card: {
      padding: "5px 10px",
      border: `1px solid ${isDark ? "#374151" : "#e5e7eb"}`,
      borderLeft: `3px solid ${isDark ? "#E85D4D" : "#D45D44"}`,
      borderRadius: "4px",
      display: "flex", alignItems: "center", gap: "10px",
      background: isDark ? "#1f2937" : "#fff",
    },
    itemsGrid: () => ({
      display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(72px, 1fr))",
      gap: "4px", flex: 1,
    }),
  });
​
  // 在 cells 数组中查找匹配当前 5 维选择的 cell
  const DIMENSIONS = ["hw", "variant", "quant", "strategy", "nodes"];
  const findCell = (cells, sel) =>
    cells.find((c) => DIMENSIONS.every((d) => c.match[d] === sel[d]));
​
  // ... 剩余渲染逻辑（生成命令、渲染矩阵等）
};

评论区精华

• JustinTong0323: “Make PD mode inject role-specific serving and distributed-init ports. The decode role currently inherits --port {{PORT}} defaulting to 30000 while the router sends decode traffic to http://<decode-host>:30001; multi-node PD also gives both independent role servers the same --dist-init-addr {{NODE0_IP}}:20000.” → 作者修复了角色特定端口，但 Docker 映射问题遗留。
• JustinTong0323: “Strip all MegaMoE-owned env keys before adding the selected option env. As written, switching from a verified W4A4 base cell to W4A8 only strips fc.stripEnv, so SGLANG_OPT_DEEPGEMM_MEGA_MOE_USE_FP4_ACTS … can remain and make the W4A8 command still run with W4A4 activation settings.” → 已修复。
• JustinTong0323: “Add an explicit Docker image for rtx6000 or remove the RTX PRO 6000 cell from this PR.” → 作者解释 SM120 未在 release cut 中，暂时使用 dev 镜像。

风险与影响

• 命令生成正确性：引擎自动注入多节点参数，若配置遗漏或处理有误可能生成无效命令，review 已发现 PD 端口问题。
• 配置 schema 耦合：引擎与配置数据契约强绑定，新增轴需同步更新引擎和文档，缺乏版本校验。
• 基准数据维护：硬编码的基准数字需随版本手动更新。
• 影响范围：本质是文档前端重构，不影响运行时稳定性，但未来所有 cookbook 将依赖此模式。

关联脉络

本 PR 是 cookbook 架构的独立重构，暂无跨 PR 依赖。后续新增模型（如 DeepSeek-V5）将直接使用此模板，形成统一的文档编写范式。