Cookbook Migrate Model

Cookbook Migrate Model

Convert one legacy cookbook page to the config-driven format, faithfully. The legacy page — its generator widget and its measured benchmark blocks — is the single source of truth. You are transcribing it into the new data model, not improving it.

Reuses the cookbook-add-model skill's assets (read them on demand):

• ../cookbook-add-model/templates/config.jsx.tmpl, page.mdx.tmpl, benchmarks.jsx.tmpl
• ../cookbook-add-model/references/authoring-reference.md (config/cells/playground contract)
• ../cookbook-add-model/references/mintlify-authoring.md (MDX rules)

Migration-specific references in this skill:

• 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).

The round's per-model inventory (scope, batch order, quirks, measured-data survey) is tracked by the migration maintainer outside the repo — expect it in your dispatch prompt, or ask for it.

Hard rules (non-negotiable)

1. Never modernize. Env vars, flags, TP values, docker tags, version strings are copied verbatim from the legacy page — even when today's defaults differ (e.g. a flag whose behavior has since become the default; keep it anyway). The recipe that was verified is the recipe as written. Allowed normalizations are ONLY the five alias rewrites in dimension-mapping.md §2 (launch_server→sglang serve, --model→--model-path, --tp-size→--tp, abbreviated --speculative-algo→--speculative-algorithm, --expert-parallel-size→--ep). Accuracy-degrading flags (--kv-cache-dtype fp8_e4m3, W4A4-style runtime quant) follow a deterministic rule — enforced in migration, no asking: offered as a legacy selectable option → never select it (cells mirror the accuracy-safe side), and the option survives as a Playground axis — an existing one where it fits, else add one via a separate prior engine PR (rule 4); a legacy choice never degrades to a tips mention. Baked into the recipe's default/unconditional command → keep it verbatim (the recipe was measured with it, and fp8 KV halves KV memory — stripping could OOM it). See dimension-mapping.md §2 caveats.
2. Never invent versions or numbers. Benchmark numbers only from the legacy page's measured blocks, and a result migrates ONLY when its sglang_version is a reproducible anchor — the bar is reproducibility, not "must be a release":
   • ✅ release tag/version (v0.5.9 / 0.5.9), commit hash, OR — for Day-0 support (the enabling PR isn't merged and no release is cut yet) — a specific PR (PR #27944) or commit you can gh pr checkout / git checkout <sha>. Commit is most precise; a PR pin is fine for day-0.
   • ❌ a moving ref — "main branch", "main (2026-06-11)", open-ended "0.5.8+" — is NOT reproducible: drop the WHOLE result (speed AND accuracy), not just speed. Keep benchmarkCommands so ⚡Reproduce still guides re-measurement against a pinned build. Never inherit cross-model numbers — measurements the legacy page attributes to a different model (e.g. a K2.6 page carrying K2.5-measured speed) are dropped regardless of version. When kept, sglang_version is the legacy page's string verbatim. Docker tags only the ones the legacy page pinned (unmapped hw falls back to :dev).
3. Verified policy (strictest tier). verified: true ONLY when (a) the legacy page has concrete measured data for that exact 5-dim combo AND (b) the cell's flags equal the deployment command used for that measurement — modulo {{HOST_IP}}/{{PORT}}, the five alias rewrites, and parser flags: --reasoning-parser/--tool-call-parser are stripped from every cell (Playground-only feature; when the measured run had them on, say so in the benchmarks file header). When the measured command diverges from the generator default, the verified cell follows the measured command; the generator default stays as the sibling strategy/cell or a tips note. Everything else is unverified (yellow) — including combos that look memory-infeasible; keep them verbatim and list them in the PR body for the re-verification track.
4. Engines are read-only. _deployment.jsx / _playground.jsx must not change in a migration PR. Model-specific features are config DATA consumed by generic axis handlers (MegaMoE precedent), so they need NO engine change. A titled single-select that strips a flag family — KV Cache DType (--kv-cache-dtype), mamba (--mamba-radix-cache-strategy), … — is already covered by the merged generic flagSelects axis: declare it in the config (a list of { id, title, stripPrefixes, options }; see the Qwen3.5 mamba example), no engine PR. Only a genuinely new control shape that flagSelects can't express would need a one-time generic primitive (never a model-named handler) on a separate prior PR (engine-axis.md).
5. github.cookbookModel must be set (<hf-org>/<page-slug>, e.g. qwen/qwen3.5) and the block never pruned — without it Submit ↗ mislabels as deepseek-v4. The issue template itself needs NO edits (free-form input).
6. Strategy tiers are signal-driven. A cell goes under low-latency / high-throughput ONLY on a signal present in the legacy source (an explicit performance toggle, a named recipe, or prose stating the operating point); no signal → balanced. Never derive a slant from your own hardware intuition — re-tiering on measured evidence is the hardware owner's follow-up PR, not part of a migration (dimension-mapping.md §4).

Workflow (one model = one PR)

1. Inventory the legacy assets

• Read the legacy generator (docs/src/snippets/autoregressive/<slug>-deployment.jsx) end-to-end: every option dimension (radio vs checkbox vs dynamic), every gate/SUPPORT matrix, the full emitted command per reachable combo (env prefixes, # Error pseudo-commands included).
• Read the legacy MDX: §2 install docker tags → dockerImages (pinned, not upgraded); §3.2 tips → new §2; §4 invocation examples → new §3 (keep real Output Examples verbatim); §5 benchmark blocks → transcribe each measured block: deploy command used, bench command (dataset/isl/osl/num-prompts/ concurrency), P50 (median) TTFT/TPOT, output tok/s, hardware, version string.
• Inbound-anchor sweep: grep -rn "<PageName>" docs/ --include='*.mdx' — find links/#fragments into this page (mint broken-links does NOT check fragments). Fix referrers or add <a id="old-anchor" /> shims in the same PR.
• Check the maintainer-provided inventory notes for this model's known quirks — but treat them (and the §4 family table) as a survey snapshot: re-verify every dimension against the live legacy files before mapping. Pages keep receiving updates (precedent: Kimi-K2.6's live generator has a speculative toggle the 2026-06-10 survey notes lack).

2. Design the 5-dim mapping

Apply references/dimension-mapping.md. Key decision — which legacy toggle becomes the strategies dimension: a toggle that changes other parts of the command (TP, mem) must (the Playground can't do coupled changes), and so does a toggle the legacy page itself labels with operating-point words — e.g. a dpattention radio whose options are subtitled "Low Latency" / "High Throughput" (GLM-5.1 / Kimi-K2.6 pattern) — even when its flags are uncoupled (--attn-dp-size N is a pure flag add). Any other toggle that only adds/removes its own flags becomes a Playground axis with the flags baked into cells when the legacy default was ON — EXCEPT parsers: --reasoning-parser/--tool-call-parser are NEVER baked into cells, they are Playground-only (DSv4 convention). Every legacy control survives as an interactive control — a dimension or a Playground axis, never a tips-only mention — and a model-specific control is config data, not engine code (MegaMoE W4A4 is all DSv4 config on the existing moe axis). It's pure config whenever it fits an existing axis's data schema. A titled single-select that strips a flag family (Nemotron3's "KV Cache DType", mamba --mamba-radix-cache-strategy, …) fits the merged generic flagSelects axis — so it too is config-only (declare a flagSelects list). Only a control whose shape flagSelects still can't express would need a ONE-TIME generic primitive (never a model-named handler) on a separate PRIOR engine PR, keeping the migration PR data-only (hard rule 4, engine-axis.md). The strategy count follows the page's operating points: one recipe → a single balanced; two → low-latency + high-throughput; three → the full trio (the ideal). The tiers apply per (hw × variant × quant) combination — a single-recipe combination on a multi-strategy page parks under its semantically honest tier (no latency/throughput slant → balanced; the page's list is the union). When the legacy toggle is MTP / speculative decoding, the direction is a deterministic default — apply without asking: MTP on → low-latency, MTP off → high-throughput (reversed only with maintainer confirmation). Tier placement is signal-driven (hard rule 6). Never invent a recipe just to fill strategy chips (see dimension-mapping.md §4). Record the outcome as a strategy mapping table for the PR body — one row per group of combinations sharing the same legacy signal (e.g. "all GPU combos: MTP toggle → low-latency / high-throughput"; "xeon: (none) → balanced"), with a one-line rationale each; don't enumerate 60 identical rows. The table is what hardware owners sign off on at review.