Legacy → config-driven dimension mapping

Loaded on demand by the cookbook-migrate-model skill. How to translate a legacy generator's option space into the 5-dim matrix + Playground axes. Field schemas live in ../../cookbook-add-model/references/authoring-reference.md; this file is about the mapping decisions.

1. Legacy control → new home

2. Command rewrite table (the ONLY allowed normalizations)

Caveats discovered in the pilot:

• The Playground moe.ep knob only understands --ep — normalize a legacy --expert-parallel-size N to --ep N (alias, see table above) so the knob can recognize/strip it.

• multiNodeHints only for hw whose fabric needs manual NIC env (gb200-class); standard-IB H100 multi-node needs none. Hints show on both run modes, so docker run flags go in the hardware entry's multiNodeDockerFlags instead.

• dockerImages: only the tags the legacy page pinned. CPU/Xeon stays unmapped (:dev fallback) with a "install from source" tip.

• Accuracy-degrading flags (--kv-cache-dtype fp8_e4m3, W4A4-style runtime quant) — deterministic rule, enforced in migration without asking:

  • offered as a legacy selectable option/toggle → never select it; cells mirror the accuracy-safe side (even if the legacy default was the lossy side). The option itself must survive as a Playground control — the user's choice may not degrade to a tips mention. Express it as config data on the fitting axis (DSv4 gates W4A4 behind megamoeQuant; a single-select like Nemotron3-Ultra's "KV Cache DType" radio None/fp8_e4m3/bf16 rides the merged generic flagSelects axis — declare a flagSelects block, config-only, no engine PR);
  • baked into the recipe's unconditional/default command → keep it verbatim. The legacy measurements ran with it, and fp8 KV halves KV memory — stripping could OOM the recipe. Expect this pattern: legacy AMD recipes routinely append --kv-cache-dtype fp8_e4m3 ("for memory efficiency"), and GLM-5's NVFP4 path ships it too — all keep.

  (Only migration gets this auto-keep — faithfulness wins here. On new pages the same flags are flag-and-confirm with the maintainer: authoring-reference §2.2 / review checklist.)

2b. Playground axes: opt-out, not opt-in

The legacy page's silence about a feature does NOT mean the axis is dropped. Every cookbook ships the general axes by default — attention (TP/CP/DP-Attn), moe (backend + EP) for MoE models, parsers, speculative, pdDisagg, hicache — then adds model-specific axes, and deletes ONLY axes the model genuinely cannot use (hisparse is DSA-only; MegaMoE is DeepSeek-V4 Blackwell-only). Knobs meaningless for a subset of variants/hw get disable + disableReason (per-chip constraints), not removal — e.g. MoE backend/EP greyed out on dense variants.

speculative presets must include every algorithm that actually appears on the page (otherwise a stripped cell's baseline can't be re-applied) — but collapse aliases: NEXTN is an alias of EAGLE (§2 rewrite table), so a page benchmarked with NEXTN ships a single eagle preset, not both. (Pilot history: Qwen3.5 once shipped both; corrected to EAGLE-only.)

MTP --max-running-requests hint (engine, automatic): when a cell's command turns speculative decoding on (--speculative-algorithm present) without --max-running-requests, the Deploy panel + Playground auto-render an amber callout (SGLang otherwise caps it at 48). It is FLAG-driven, not strategy-driven — nothing to author per page; do NOT duplicate it in §2 prose.

The parsers axis is add-only: --reasoning-parser / --tool-call-parser are never part of any Deployment cell (see §1) — the axis adds them on top of the base command, so toggling a parser renders a green addition, never a strikethrough.

3. Verified policy mechanics

• Green requires measured data + flag equality with the measured command (see SKILL.md hard rule 3). Order cells[] so the verified flagship cell is first — cells[0] is the page's initial selection.
• When the measured command and the generator default disagree (Qwen3.5: bench ran NEXTN + SGLANG_USE_CUDA_IPC_TRANSPORT=1, generator emitted EAGLE + fusion flags), the verified cell mirrors the measurement; the generator default lives on as the not-verified sibling cells. Offer BOTH as Playground speculative presets and explain the split in §2 tips.
• config.accuracyLabels is REQUIRED whenever benchmarks carry accuracy data — the engine ships no default eval set (#27842); without it the accuracy rows silently don't render. defaultAccuracy paints every entry-bearing cell of a variant — under the strict policy prefer per-entry accuracy on the measured cell only.

4. Per-family strategy sets (survey sketches — re-derive from the live page)

The family table below was sketched from the 2026-06-10 survey at PAGE level. At migration time re-derive it from the live generator: pages drift (precedent: Kimi-K2.6's live page has a speculative toggle the survey notes lack), and the per-combination rule means gated/hidden toggles — typically on Xeon, AMD, or a single-recipe quant like NVFP4 — produce balanced combos the page-level sketch doesn't show.

Strategy-set rule — the count follows the page's operating points (ids always from the DeepSeek-V4 vocabulary, never model-specific ids like mtp/no-mtp):

• 1 operating point (a single recipe, no performance toggle) → a single balanced strategy. Never invent a second recipe just to fill chips.
• 2 operating points → low-latency + high-throughput. When the legacy toggle is MTP / speculative decoding, the mapping is a deterministic default — apply it without asking: MTP on → low-latency, MTP off → high-throughput. (Why it's near-certain: speculative decoding cuts per-token latency at low concurrency, but at saturation the draft+verify overhead costs more than it saves — DSv4's high-throughput recipes disable MTP for the same reason.) Other toggles map by the same serving semantics — the two recurring high-throughput markers are dp-attention ON (MLA-attention models) and EP / DP+EP ON (MoE models): both shard work across ranks for saturated throughput at some per-request latency cost. These directions apply to the toggle CHOSEN as the strategy dimension (§1); a flag-only spec toggle riding alongside a named operating-point toggle stays a Playground axis and bakes per its legacy default — GLM-5.1's spec defaults ON, so its flags bake into BOTH tiers there. Only if a legacy page documents the OPPOSITE slant (e.g. "enable MTP for high throughput") stop and confirm with the maintainer.
• 3 operating points → the full trio (the ideal — e.g. GPU-budget tiers 2/4/8).

Signal-driven tiers (hard rule). A cell goes under low-latency / high-throughput ONLY on a signal present in the legacy source: an explicit performance toggle (MTP/speculative, dp-attention, EP, gpuCount, …), a named recipe/strategy checkbox, option subtitles ("Low Latency" / "High Throughput"), or prose stating the operating point. Reading such a signal is SGLang-level serving semantics (MTP favors latency on any vendor's silicon), so any migrator can tier any vendor's cells without hardware-specific judgment. No signal → balanced — legacy silence is itself information: the page offered that command as the hardware's general-purpose operating point, and balanced transcribes exactly that. Never derive a slant from your own hardware intuition ("this flag combo feels throughput-tuned"); re-tiering on measured evidence is the hardware owner's follow-up PR, not part of a migration. A toggle that maps to no dimension, or a suspected undocumented slant → stop and ask the maintainer.

The tiers apply per (hw × variant × quant) combination, not just per page: a combination with fewer operating points than the page parks its cells in the semantically honest tier. A single recipe with a signal-evidenced slant goes to that tier (DSv4's RTX PRO 6000 → low-latency: workstation card, low-batch Marlin recipe — the recipe's own SGLang-legible content is the evidence); a general-purpose recipe with no latency/throughput slant goes to balanced (Qwen3.5's Xeon → balanced). Never park a no-slant recipe under low-latency/high-throughput just because the page's toggle mapping lands there — that reads as a semantic lie ("CPU = high-throughput?"). The page's strategies list is the union of tiers actually used (a mixed [low-latency, balanced, high-throughput] page where GPUs use the two ends and CPU uses the middle is fine); the engine greys unused chips per selection and auto-snaps, no extra config needed.

Deviations (e.g. how to name pure GPU-budget tiers) need maintainer sign-off. The MDX strategy bullets describe serving semantics in the DSv4 style (single-user chat / typical multi-user / batch jobs), with at most a one-line model-specific note — never toggle-/migration-centric explanations.

Qwen3 variant fan-out: variants = deployable checkpoints size-ordered (235b-instruct, 235b-thinking, 235b, 30b-*, 32b, …); do NOT abuse strategies for the instruct/thinking category. Trim original-hybrid chips to the ones the legacy page actually measured.

5. Worked example — the Qwen3.5 pilot (PR #27848)

Decisions log, in the order they came up:

1. Strategy split over Playground toggle because MTP couples with TP on three H100 combos (35B/27B BF16: tp2↔tp1+mem0.88; 122B FP8: tp4↔tp2). Canonical naming: low-latency = MTP on (legacy default), high-throughput = MTP off. Xeon has a single operating point (the legacy widget hid the MTP toggle there) and its recipe has no latency/throughput slant → its 12 cells park under balanced (per-combination placement; parking them under high-throughput as a toggle-mapping side effect read as a semantic lie). Result: 186 cells = 87 low-latency + 87 high-throughput + 12 balanced; the page ships the full trio and the engine greys unused chips per selection.
2. Verified cell follows the measurement: H200/397B/BF16/low-latency = SGLANG_USE_CUDA_IPC_TRANSPORT=1 env + --speculative-algorithm EAGLE (the bench reported NEXTN, an alias of EAGLE — normalized to EAGLE, §2) + measured flag set minus the parser flags (the measured run had both parsers on; cells never carry them — noted in the benchmarks header). All other cells = the generator's parsers-OFF output verbatim. A single eagle spec preset on the speculative axis (the duplicate NEXTN preset was dropped).
3. FP4 single quant id with hw|variant|quant modelNames keys → nvidia/...NVFP4 (b200/b300) vs amd/...MXFP4 (mi355x).
4. Xeon as config.hardware vendor:"intel"; cells carry --device cpu --disable-overlap-schedule; no docker mapping.
5. Playground axes: the full general set per §2b — attention (TP/CP/DP-Attn), moe (DeepEP backend + EP knob, disable+reason on the dense variants), parsers, speculative (NEXTN + EAGLE — both algorithms appear on the page), pdDisagg, hicache. Excluded as inapplicable: hisparse (DSA-only), MegaMoE (DSv4 Blackwell-only). The legacy --expert-parallel-size 8 flag is normalized to --ep 8 for the EP knob.
6. Benchmarks: one entry (the measured cell) only — entry-less cells render "pending" without stubs. The legacy speed numbers were DROPPED: they were measured on a drifting "main branch" build, which is no version anchor (speed migrates only under an exact release tag / commit hash — hard rule 2), so the entry carries accuracy only (GSM8K + MMMU via accuracyLabels, sample counts in notes) and no sglang_version.
7. Codegen + audit scripts (adapt per model): a generator-port script that emits the cells literal, and an independent audit that git shows the ORIGINAL generator, stubs useState/useEffect, calls its generateCommand(values) per combo via indirect eval, and token-diffs against the new cells (expected deltas only). Read the legacy source via git show main:<path> — NOT HEAD: (the migration branch's HEAD has already deleted the file, so the audit breaks after the deletion commit). Re-run the audit after ANY later cells revision (renames included). Pilot result: 185/185 identical + 1 intentional override. Scripts are archived in PR #27848's description (collapsed details block).
8. Inherited-infeasible combos kept verbatim (e.g. 122B BF16 tp1 on mi325x: 244 GB weights vs 256 GB VRAM with mem-fraction 0.8) — they stay yellow and are listed in the PR body for the re-verification track.
9. Browser-smoke probe pitfall: multiple programmatic .click() calls in one synchronous eval batch under React 18 — the DOM reads between them are stale and look like snap-logic bugs. One click per eval, then settle.