Cookbook config reference (fields · cells · playground · MDX)

Loaded on demand by the cookbook-add-model skill. This is the field-by-field contract for when the clone needs more than a rename. The two engine files are the canonical specs — read their headers first:

• _deployment.jsx — the matrix widget; its header lists every config field. Dimensions are the legacy fixed five by default, or config-declared via matchDims / overlayDims (§2.1b).
• _playground.jsx — the diff-based override widget; lists the playgroundFeatures axes + the AXIS_HANDLERS interface.

Engine extension (adding a new playground axis) lives in engine-axis.md.

---

2.1 Create the config file

Path: docs/src/snippets/configs/<vendor>/<model>.jsx. The vendor folder is the HuggingFace org (deepseek-ai, Qwen, moonshotai, ...); the file name is a short hyphenated model id (deepseek-v4, qwen3.5, ...).

Shape: must be a single export const config = { ... } literal. Do not use function calls, spreads, fragment refs, or IIFE — Mintlify re-evaluates this export at hydration time with module-level identifiers out of scope, and any non-literal value crashes with ReferenceError.

Required fields (engine reads these — see the _deployment.jsx header for the full contract):

Optional fields:

2.1b Custom dimensions (matchDims / overlayDims)

The legacy shape above is a fixed five dimensions. A model whose axes don't fit (no variant axis, a deployment-shape axis, an orthogonal feature toggle) declares its own instead. Declaring matchDims replaces variants/quantizations/ strategies/nodesOptions wholesale; omitting it keeps the legacy behaviour, so existing pages need no change.

Option shape, both kinds:

Overlay options additionally take flags, env and hints — each a literal array or a function of the whole selection (so an "auto" value can resolve against another row). hints render as # ... comment lines above the command, for setup the launch line cannot express on its own.

_playground.jsx sees the overlay dims in its base, so a playground axis can gate on them with its own showWhen(base) — an axis whose feature the Deploy panel never switched on is not rendered at all. Changing the Deploy selection resets every playground axis back to inherit-from-base.

The overlay resolution rule is written in BOTH engines (snippets can't import each other); each copy is marked MIRROR. Change both or neither, or the Deploy command and the playground base silently disagree.

2.2 Author the matrix (cells[])

Each cell describes one verified (or auto-estimated) launch recipe.

{
  match: { hw: "b200", variant: "flash", quant: "fp4",
           strategy: "low-latency", nodes: "single" },
  verified: true,                  // green "Verified" badge; absence = yellow
  env: [
    "SGLANG_DEEPEP_NUM_MAX_DISPATCH_TOKENS_PER_RANK=1024",
  ],
  flags: [
    "--trust-remote-code",
    "--model-path {{MODEL_NAME}}", // {{MODEL_NAME}} resolves from modelNames
    "--tp 4",
    "--moe-runner-backend flashinfer_mxfp4",
    "--host {{HOST_IP}}",
    "--port {{PORT}}",
  ],
},

Rules:

• match MUST contain exactly the 5 keys: hw, variant, quant, strategy, nodes. The engine looks up cells by tuple equality.
• verified is the badge baseline (true → green Verified, absent → yellow Not Verified). verificationStatus overrides it with a third state — "verified" | "in-progress" | "unverified" — for a recipe whose verification round is OPEN rather than absent. It may also be a FUNCTION of the selection, which is how a cell reports a per-pick state: e.g. verificationStatus: (sel) => sel.spec === "dflash" ? "in-progress" : "verified" marks one speculative option as still being validated while the cell's other picks stay Verified. An unrecognized string falls back to unverified, so a typo can never render as a green badge — and check_cookbook_configs.mjs probes the function over every reachable selection, so a typo or a crash fails the check instead of reaching the page.
• env and flags are FLAT literals. The engine does NOT expand fragments, aliases, or templates — it consumes them verbatim (only {{PLACEHOLDER}} substitutions happen at render time).
• DO NOT include --nnodes / --node-rank / --dist-init-addr in cell.flags for multi-node cells. The renderer injects them automatically from match.nodes (multi-N → N nodes).
• DO NOT include --host / --port literally — use {{HOST_IP}} / {{PORT}} placeholders so users can override through the Env modal.
• Order flags as: --model-path first (after any --trust-remote-code), then parallelism (--tp, --dp, --enable-dp-attention), then MoE flags, then tuning knobs, with --host / --port last. The playground engine assumes this ordering when inserting overrides (its anchors target --model-path / --tp / etc., and inserts before the --host tail).
• Accuracy-degrading flags don't belong in cells by default: a cell's output quality should be exactly what its quantization chip declares. Runtime quant below the checkpoint's precision (e.g. MegaMoE W4A4 — DSv4 gates it behind the Playground's megamoeQuant opt-in) and lossy KV-cache dtypes (--kv-cache-dtype fp8_e4m3 over a higher-precision-KV checkpoint) default to Playground opt-ins or §2-tips material. If the model's recipe genuinely needs one in a cell, flag it to the user and get explicit confirmation — never ship it silently. (Migrations are the sanctioned exception: a flag baked into the legacy recipe's default command keeps verbatim — see the migrate skill.)

Cells are denormalized on purpose — common flags repeat across cells. This makes each cell self-contained and easy to verify. When sweeping a common change, edit every cell.

Avoid premature cells: only add a cell for a (hw × variant × quant × strategy × nodes) combination if you have a recipe that has been tested or at least sanity-checked. The engine greys out un-listed combinations automatically.

2.3 Configure playgroundFeatures (optional)

The Playground is opt-out, not opt-in: 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 (e.g. MegaMoE for DeepSeek-V4) and deletes ONLY the axes this model genuinely cannot use (e.g. hisparse on non-DSA models, moe on a pure-dense model). Knobs that don't apply to a subset of variants/hw get disable + disableReason, not removal. Recognised axis keys and their schemas (full reference in the _playground.jsx header):

Per-chip constraints: any chip entry in any axis can be wrapped with hide / disable constraint objects:

{ value: 16, disable: { nodes: ["single"] },
  disableReason: "TP=16 requires 16 ranks — switch the Deploy panel's Nodes to Multi-Nodes first." }

• hide — chip omitted entirely (use for hard impossibilities).
• disable — chip greyed out with tooltip (soft warning).
• Constraints are AND across keys, OR within each key's array.
• Bare disabled: true / disable: true is a static always-disabled form (used for "Coming soon" chips).
• disable may also be an ARRAY of {when: constraint, reason} items (OR across items, first match wins and supplies its own tooltip) — for conditions that need OR across keys or per-condition reasons, e.g. the GLM-5.2 CP knob (grayed on non-Hopper hw OR multi-node, different reasons).
• Constraint keys are the 5 cell dims (hw/variant/quant/strategy/ nodes) plus cross-axis live facts: dpAttnOn (effective DP-Attention on), cpOn (effective prefill-CP on), cpStrategy (effective CP layout), cpSizeTarget (the only enable-able CP size — see below), effTp (effective TP degree — override else derived), and pdMode (live PD-Disagg role).
• On the attention axis, knob-level hide/disable (on the knob object, not a value entry) hides/grays the whole select; apply() skips knobs/values that are disabled under the live facts, so stale picks never emit a blocked combination. Interleave prefill-CP + DP-Attention is deliberately NOT grayed (combined support is planned upstream even though current releases assert dp_size == 1 for interleave) — the engine shows a warning hint below the command box instead.
• The CP knob emits --attn-cp-size N --enable-prefill-cp --cp-strategy S, where S is: an optional { id: "cpStrategy", values: [null, "interleave", "zigzag"] } knob's pick > the strategy already baked in the base cell (legacy mode flags map in: in-seq-split → zigzag, round-robin-split → interleave) > "interleave". Declare the cpStrategy knob only on models whose runtime accepts both layouts (DeepSeek-V4 rejects zigzag; DSA zigzag forces deepep + ep=tp + batch_size=1 — label it experimental).
• CP sizes auto-gate in the engine to the runtime derivation attn_cp_size = tp/dp (both in the grayed options and in apply), so configs list plain size values — no per-value effTp constraints needed. A model whose runtime honors arbitrary --attn-cp-size opts out with freeSize: true on the cp knob.
• Only expose a CP knob on models with model-side CP integration in SGLang (DeepSeek-family / Qwen-MoE / Mellum); on others the emitted flags do nothing or crash (that's why Hy3 and MiniMax-M3 have no CP knob).

2.4 Create the MDX page

Path: docs/cookbook/<category>/<Vendor>/<Model>.mdx. Import both widgets and the per-model config, render them inside the relevant sections:

## Deployment

import { Deployment } from "/src/snippets/_deployment.jsx";
import { config }     from "/src/snippets/configs/<vendor>/<model>.jsx";
import { benchmarks } from "/src/snippets/configs/<vendor>/<model>-benchmarks.jsx";

{/* Install is a PREREQUISITE — keep it compact + collapsed at the top of the
    Deploy section (NOT a numbered section). Tabs mirror the widget's
    Python/Docker toggle. */}
<a id="install" />
<Accordion title="Install SGLang">
  <Tabs>
    <Tab title="Python (pip / uv)">…pip / uv install…</Tab>
    <Tab title="Docker">…docker pull + a `docker run … sglang serve` example…</Tab>
  </Tabs>
</Accordion>

<Deployment config={config} benchmarks={benchmarks} />

[model-specific tuning notes, caveats, links]

## Playground

import { Playground } from "/src/snippets/_playground.jsx";

<Playground config={config} />

Heading slugs matter — the two widgets cross-link by scrolling to each other's section id (Mintlify auto-slugs headings: lowercase, spaces → hyphens, punctuation dropped). The engines look up:

• the Deploy panel by id deployment (falls back to deploy) — used by the Playground's "↑ Switch base" button and by deep-link scroll-on- load. Title the section ## Deployment (or ## Deploy).
• the Playground by id playground — used by _deployment.jsx's "Open the Playground →" link. Title the section ## Playground.

Avoid numbered headings like ## 3. Model Deployment (slug 3-model-deployment) for these two sections — the cross-links would break. The Playground reads the Deploy selection live via the URL hash + the sglang-deploy-sel custom event, so the two can live in different parts of the page.

The benchmarks prop is optional. It points at a sibling <model>-benchmarks.jsx file (one entry per cell, keyed by the same match tuple) that renders an accuracy + speed sub-card under the command box; omit the import and the prop if the cookbook has no measured numbers yet. See the _deployment.jsx header and deepseek-v4-benchmarks.jsx for the full speed/accuracy schema.

Each entry's sglang_version must be a reproducible anchor — a release tag/version (v0.5.9), a commit hash, or (for Day-0 support, before the enabling PR merges or a release is cut) a specific PR (PR #27944) or commit you can gh pr checkout / git checkout. Never a moving ref like "main" / "main (2026-06-11)" (not reproducible). A spec-decoding model whose cell carries --speculative-algorithm but no --max-running-requests auto-shows an amber Deploy + Playground callout (SGLang otherwise caps it at 48) — it is flag-driven, so no per-page prose is needed.

To let users reproduce those numbers, add a benchmarkCommands block to the config (§2.1, next to curl). When present alongside benchmarks, the benchmark card grows a "⚡ Reproduce" button that opens a modal listing the runnable commands for the current cell — one bench_serving command for Speed (with concurrency chips that rewrite --max-concurrency) plus an Accuracy command with a chip per eval. No separate benchmark section needed.

---

Pitfalls (authoring)

Stale URL hash hydration — If a user shares a link from an old cell catalog and the hash names an impossible combination, _deployment.jsx's validateSelection snaps to the nearest real cell. The Playground reads the hash too — make sure cookbook removals don't leave dangling shared links pointing at hardware/quant combos that no longer exist.

Mintlify constraints — Module-level statements are stripped. The config MUST be a single export const config = { ... } literal — no function calls, spreads, fragment refs, or IIFE (Mintlify re-evaluates the export at hydration with module-level identifiers out of scope; any non-literal crashes with ReferenceError). In MDX, capitalized JSX tags get rebound — use the built-in Mintlify components (<Accordion>, <Tabs>, <Card>, ...) as documented. Avoid !(x in y) anywhere (Mintlify's AST walker crashes on it) — use obj.key === undefined.

Per-cell denormalization — Cells repeat common flags on purpose. Do not factor them into a shared commonFlags array — Mintlify will fail to inline the reference. If you need to sweep a flag across cells, do it with a global find-replace in the config file.