cookbook-migrate-model

1---2name: cookbook-migrate-model3description: Migrate a legacy-template SGLang cookbook page (monolithic per-model generator under docs/src/snippets/autoregressive/) onto the config-driven template (shared _deployment.jsx / _playground.jsx engines + per-model config). Use when asked to migrate, convert, or port an existing cookbook page — NOT for brand-new models (use cookbook-add-model for those). Run with /cookbook-migrate-model <Model page name, e.g. GLM-5.1>.4---5 6# Cookbook Migrate Model7 8Convert one legacy cookbook page to the config-driven format, faithfully. The9legacy page — its generator widget and its measured benchmark blocks — is the10**single source of truth**. You are transcribing it into the new data model,11not improving it.12 13Reuses the `cookbook-add-model` skill's assets (read them on demand):14- `../cookbook-add-model/templates/config.jsx.tmpl`, `page.mdx.tmpl`, `benchmarks.jsx.tmpl`15- `../cookbook-add-model/references/authoring-reference.md` (config/cells/playground contract)16- `../cookbook-add-model/references/mintlify-authoring.md` (MDX rules)17 18Migration-specific references in this skill:19- [references/dimension-mapping.md](references/dimension-mapping.md) — legacy-control → new-dimension mapping rules, command rewrite table, per-family strategy sets, and the Qwen3.5 pilot as a worked example (PR #27848).20 21The round's per-model inventory (scope, batch order, quirks, measured-data22survey) is tracked by the migration maintainer outside the repo — expect it in23your dispatch prompt, or ask for it.24 25## Hard rules (non-negotiable)26 271. **Never modernize.** Env vars, flags, TP values, docker tags, version strings28   are copied verbatim from the legacy page — even when today's defaults differ29   (e.g. a flag whose behavior has since become the default; keep it anyway). The recipe30   that was verified is the recipe as written. Allowed normalizations are ONLY31   the five alias rewrites in dimension-mapping.md §2 (`launch_server`→`sglang32   serve`, `--model`→`--model-path`, `--tp-size`→`--tp`, abbreviated33   `--speculative-algo`→`--speculative-algorithm`,34   `--expert-parallel-size`→`--ep`). **Accuracy-degrading flags**35   (`--kv-cache-dtype fp8_e4m3`, W4A4-style runtime quant) follow a36   deterministic rule — enforced in migration, no asking: offered as a37   legacy **selectable option** → never select it (cells mirror the38   accuracy-safe side), and the option **survives as a Playground axis** —39   an existing one where it fits, else add one via a separate prior engine40   PR (rule 4); a legacy choice never degrades to a tips mention. Baked41   into the recipe's **default/unconditional command** → keep it verbatim42   (the recipe was measured with it, and fp8 KV halves KV memory —43   stripping could OOM it). See dimension-mapping.md §2 caveats.442. **Never invent versions or numbers.** Benchmark numbers only from the45   legacy page's measured blocks, and a result migrates ONLY when its46   `sglang_version` is a **reproducible anchor** — the bar is reproducibility,47   not "must be a release":48   - ✅ release tag/version (`v0.5.9` / `0.5.9`), commit hash, OR — for49     **Day-0 support** (the enabling PR isn't merged and no release is cut50     yet) — a specific **PR (`PR #27944`) or commit** you can `gh pr checkout`51     / `git checkout <sha>`. Commit is most precise; a PR pin is fine for day-0.52   - ❌ a moving ref — `"main branch"`, `"main (2026-06-11)"`, open-ended53     `"0.5.8+"` — is NOT reproducible: **drop the WHOLE result (speed AND54     accuracy)**, not just speed. Keep `benchmarkCommands` so ⚡Reproduce still55     guides re-measurement against a pinned build.56   **Never inherit cross-model numbers** — measurements the legacy page57   attributes to a *different model* (e.g. a K2.6 page carrying K2.5-measured58   speed) are dropped regardless of version. When kept, `sglang_version` is the59   legacy page's string verbatim. Docker tags only the ones the legacy page60   pinned (unmapped hw falls back to `:dev`).613. **Verified policy (strictest tier).** `verified: true` ONLY when (a) the62   legacy page has concrete measured data for that exact 5-dim combo AND63   (b) the cell's flags equal the deployment command used for that measurement64   — modulo `{{HOST_IP}}`/`{{PORT}}`, the five alias rewrites, and **parser65   flags**: `--reasoning-parser`/`--tool-call-parser` are stripped from every66   cell (Playground-only feature; when the measured run had them on, say so in67   the benchmarks file header). When the measured command diverges from the68   generator default, **the verified cell follows the measured command**; the69   generator default stays as the sibling strategy/cell or a tips note. Everything else is unverified (yellow) —70   including combos that look memory-infeasible; keep them verbatim and list71   them in the PR body for the re-verification track.724. **Engines are read-only.** `_deployment.jsx` / `_playground.jsx` must not73   change in a migration PR. Model-specific features are config DATA consumed74   by generic axis handlers (MegaMoE precedent), so they need NO engine change.75   A **titled single-select that strips a flag family** — KV Cache DType76   (`--kv-cache-dtype`), mamba (`--mamba-radix-cache-strategy`), … — is already77   covered by the merged generic **`flagSelects`** axis: declare it in the78   config (a list of `{ id, title, stripPrefixes, options }`; see the Qwen3.579   mamba example), **no engine PR**. Only a genuinely new control *shape* that80   `flagSelects` can't express would need a one-time generic primitive (never a81   model-named handler) on a separate prior PR (engine-axis.md).825. **`github.cookbookModel` must be set** (`<hf-org>/<page-slug>`, e.g.83   `qwen/qwen3.5`) and the block never pruned — without it Submit ↗ mislabels84   as deepseek-v4. The issue template itself needs NO edits (free-form input).856. **Strategy tiers are signal-driven.** A cell goes under `low-latency` /86   `high-throughput` ONLY on a signal present in the legacy source (an87   explicit performance toggle, a named recipe, or prose stating the88   operating point); **no signal → `balanced`**. Never derive a slant from89   your own hardware intuition — re-tiering on measured evidence is the90   hardware owner's follow-up PR, not part of a migration91   (dimension-mapping.md §4).92 93## Workflow (one model = one PR)94 95### 1. Inventory the legacy assets96- Read the legacy generator (`docs/src/snippets/autoregressive/<slug>-deployment.jsx`)97  end-to-end: every option dimension (radio vs checkbox vs dynamic), every98  gate/SUPPORT matrix, the full emitted command per reachable combo (env99  prefixes, `# Error` pseudo-commands included).100- Read the legacy MDX: §2 install docker tags → `dockerImages` (pinned, not101  upgraded); §3.2 tips → new §2; §4 invocation examples → new §3 (keep real102  Output Examples verbatim); §5 benchmark blocks → transcribe each measured103  block: deploy command used, bench command (dataset/isl/osl/num-prompts/104  concurrency), P50 (median) TTFT/TPOT, output tok/s, hardware, version string.105- Inbound-anchor sweep: `grep -rn "<PageName>" docs/ --include='*.mdx'` —106  find links/`#fragments` into this page (`mint broken-links` does NOT check107  fragments). Fix referrers or add `<a id="old-anchor" />` shims in the same PR.108- Check the maintainer-provided inventory notes for this model's known quirks —109  but treat them (and the §4 family table) as a **survey snapshot**: re-verify110  every dimension against the live legacy files before mapping. Pages keep111  receiving updates (precedent: Kimi-K2.6's live generator has a speculative112  toggle the 2026-06-10 survey notes lack).113 114### 2. Design the 5-dim mapping115Apply [references/dimension-mapping.md](references/dimension-mapping.md). Key116decision — which legacy toggle becomes the `strategies` dimension: a toggle117that **changes other parts of the command** (TP, mem) must (the Playground118can't do coupled changes), and so does a toggle the legacy page itself labels119with operating-point words — e.g. a `dpattention` radio whose options are120subtitled "Low Latency" / "High Throughput" (GLM-5.1 / Kimi-K2.6 pattern) —121even when its flags are uncoupled (`--dp N --enable-dp-attention` is a pure122flag add). Any other toggle that only adds/removes its own flags becomes a123Playground axis with the flags baked into cells when the legacy default was124ON — EXCEPT parsers:125`--reasoning-parser`/`--tool-call-parser` are NEVER baked into cells, they are126Playground-only (DSv4 convention). **Every legacy control survives as an127interactive control** — a dimension or a Playground axis, never a tips-only128mention — and a model-specific control is **config data, not engine code**129(MegaMoE W4A4 is all DSv4 config on the existing `moe` axis). It's pure130config whenever it fits an existing axis's data schema. A **titled131single-select that strips a flag family** (Nemotron3's "KV Cache DType",132mamba `--mamba-radix-cache-strategy`, …) fits the merged generic **`flagSelects`**133axis — so it too is config-only (declare a `flagSelects` list). Only a control134whose *shape* `flagSelects` still can't express would need a ONE-TIME generic135primitive (never a model-named handler) on a separate PRIOR engine PR, keeping136the migration PR data-only (hard rule 4, engine-axis.md). The strategy count follows the page's137operating points: **one recipe → a single `balanced`; two → `low-latency` +138`high-throughput`; three → the full trio (the ideal)**. The tiers apply per139(hw × variant × quant) combination — a single-recipe combination on a140multi-strategy page parks under its semantically honest tier (no141latency/throughput slant → `balanced`; the page's list is the union). When the142legacy toggle is MTP / speculative decoding, the direction is a deterministic143default — apply without asking: **MTP on → `low-latency`, MTP off →144`high-throughput`** (reversed only with maintainer confirmation). Tier145placement is signal-driven (hard rule 6). Never invent a recipe just to fill146strategy chips (see dimension-mapping.md §4). Record the outcome as a147**strategy mapping table** for the PR body — one row per group of148combinations sharing the same legacy signal (e.g. "all GPU combos: MTP149toggle → low-latency / high-throughput"; "xeon: (none) → balanced"), with a150one-line rationale each; don't enumerate 60 identical rows. The table is what151hardware owners sign off on at review.152 153### 3. Generate the config (codegen, then audit)154- For >~30 cells, port the legacy `generateCommand()` into a throwaway Node155  script that enumerates combos and emits the `cells:[...]` literal (output156  must stay a pure literal — Mintlify forbids runtime spreads/calls). Apply the157  verified-cell override in the script. See the pilot scripts embedded in the158  worked example of dimension-mapping.md §5.159- **Independent equivalence audit (required):** extract the ORIGINAL generator160  from git (`git show main:<path>` — NOT `HEAD:`, the migration branch deletes161  the file, see dimension-mapping.md §5 item 7), stub React hooks, run it for162  every combo, and diff token-by-token against the new cells. Expected deltas163  only: the appended `--host {{HOST_IP}}`/`--port {{PORT}}`, the164  engine-injected multi-node trio, the §2 alias rewrites (the entrypoint165  rewrite doesn't appear in cell tokens — cells hold flags only; the audit166  script normalizes it on the legacy side), and the intentional verified-cell167  override. Paste the PASS count + the audit script in the PR body168  (collapsed `<details>`).169- Hand-author the non-cells fields per authoring-reference.md. Structural170  self-checks: every cell resolves a `modelNames` key; no `--nnodes/--node-rank/171  --dist-init-addr/--host/--port` literals; every `{{KEY}}` declared; every172  `supportedHardware` id has ≥1 cell.173 174### 4. Benchmarks file175One entry per measured block only (cells without entries already render176"pending" — bare `{match}` stubs are unnecessary). `tokens_per_sec_per_gpu` =177total (in+out) tok/s/GPU = `output tok/s ÷ (tp × nnodes) ×178(isl+osl)/osl` — stored directly (the card shows it as-is). TTFT/TPOT179take the P50 (median) rows; set `config.latencyPercentile` (default `"P50"`; use180`"Mean"` only for legacy Mean-recorded data — temporary, being migrated to P50; an181entry-level `latencyPercentile` overrides the page value per cell).182Put the workload's183`num_prompts` into `workload`. **`config.accuracyLabels` is required whenever184the benchmarks carry accuracy data** — the engine ships no default eval set185(#27842), so missing labels means the accuracy rows silently don't render;186extra context (sample counts, suites that don't fit) goes in the entry's187`notes`. Zero-measured-data pages: skip the file and the `benchmarks` prop188entirely, but keep `benchmarkCommands` so ⚡Reproduce still guides users.189 190### 5. Rewrite the MDX191From `page.mdx.tmpl`: keep the original `title` (nav identity), write a fresh192SEO `description` (top-level — delete any legacy `metatags.description`), **no193`tag: NEW`** (a migration is not a launch), **no `mode:`**. Install accordion194carries the legacy install content + pinned images. Keep the template's195DSv4-style strategy bullets — serving semantics first (single-user chat /196typical multi-user / batch throughput), trimmed to the strategies the page197ships, plus at most a one-line note on what each strategy changes on this198model; do NOT rewrite them as toggle-/migration-centric explanations.199Legacy §5 benchmark prose is deleted (numbers → benchmark card, commands →200⚡Reproduce); legacy prose deploy commands are deleted (doc↔config parity —201fold their unique flags into §2 tips). Invocation examples + real outputs carry202over verbatim, but **wrapped in Accordions** — §3 commands and outputs are203collapsible (required, DeepSeek-V4 pattern): code in an204`<Accordion title="… (Python)">`, output in a following205`<Accordion title="Example Output">`; legacy pages kept them inline.206 207### 6. Delete the legacy generator208Remove `docs/src/snippets/autoregressive/<slug>-deployment.jsx` and its209import. `grep -rn "<slug>-deployment" docs/` must return nothing (config210provenance comments must not name the deleted path). Site wiring needs **no211changes**: docs.json path/title unchanged, vendor card + logo already exist.212 213### 7. Validate214- `grep -rn '__[A-Z_]*__'` on the new files (no template tokens).215- `cd docs && mint validate && mint broken-links` (pre-existing breaks on216  main are not yours — say so in the PR).217- `mint dev` browser smoke: initial selection = the verified cell (first in218  `cells[]`) with green badge; multi-node cells show the injected trio +219  header; AMD cells show env prefixes; Docker mode wraps with the pinned image220  and passes cell env as `--env`; condition-hidden combos grey out; benchmark221  card values; NO parser flags in any Deploy command; Playground parser222  toggles ADD the parser flags (green additions) while spec toggles strike223  the baked spec flags (red); Submit ↗ prefills this model. **Probe pitfall:** drive at most224  ONE programmatic click per evaluation and wait for React to settle —225  multiple clicks in one synchronous script batch and read stale DOM.226- Token-level audit from step 3 passes.227 228### 8. PR + review229One PR per model. PR body: migration framing, verified policy applied, the230strategy mapping table (step 2), the audit PASS count + script, any231inherited-infeasible combos flagged for re-verification. Then run `/cookbook-review-pr <N>` and fix findings.232FYI: docs previews only build for in-repo (`sgl-project/sglang`) branches —233a fork-headed PR is perfectly fine but renders no preview; a maintainer can234re-push the branch in-repo if a preview is wanted for review.235 236### 9. Keep this skill current237Any new convention, engine behavior, or pitfall you discover while migrating238(naming decisions, audit-script gotchas, review-rule conflicts, …) MUST be fed239back into this skill — same PR if it's skill-file-only, or an immediate240follow-up commit on the skill's branch/PR. The next agent runs on what's241written here, not on your session's context.242