# PR #26885 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Cookbook renovation
- 合并时间：2026-06-08 13:04
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/26885

---

# 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 等。

```javascript
// _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 和多节点。

```javascript
// _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）将直接使用此模板，形成统一的文档编写范式。