[diffusion] MiniMax-H3: tiered AdaLN plan cache (pinned-host tier + per-plan LRU) (#37266)

Co-authored-by: mickqian <mickqian@users.noreply.github.com>

docs/cookbook/diffusion/MiniMax/MiniMax-H3.mdx

@@ -297,6 +297,34 @@ values. SGLang rejects a request outside that coverage instead of silently
 changing conditioning. Cache mode supports the matching unquantized checkpoint
 only.
 
+### Advanced: online AdaLN rebuild with a host cache
+
+`--minimax-h3-adaln-online true` needs no prebuilt artifact: the server drops
+the 24.2 GiB of `adaln_proj` weights from the GPU and computes each request's
+AdaLN outputs from the checkpoint on demand, bit-exact with the resident-weight
+path. Because a rebuild pass streams the whole 24.2 GiB, the first request of
+every new `(task shape, num_inference_steps, flow_shift, audio_flow_shift)`
+combination pays several seconds; after that the plans are served from a
+64-slot GPU slab (LRU per plan) backed by a pinned host cache
+(`--minimax-h3-adaln-host-cache-gb`, LRU per schedule, default 8 GB per
+rank), so mixed-schedule serving does not re-read the checkpoint. Plan sets
+that exceed the host budget are simply recomputed on their next occurrence.
+Expert escape hatches live in environment variables:
+`SGLANG_DIFFUSION_MINIMAX_H3_ADALN_GPU_PLANS` resizes the GPU slab (needed
+only beyond 65 inference steps) and `SGLANG_DIFFUSION_MINIMAX_H3_ADALN_FP32`
+computes the one-time projections in fp32 (experimental; not bit-comparable
+to resident weights, validate end-to-end before production). LoRA adapters
+that modify `adaln_proj` are rejected in both cache modes rather than
+silently ignored.
+
+Both cache modes hold values derived from `adaln_proj`, so a runtime weight
+update is only accepted when the cache can follow it: online mode takes a disk
+update whose target directory carries native `adaln_proj` safetensors, and
+rejects everything else (tensor updates, and directories without those
+tensors) before a single weight is written. A sidecar is built offline and
+cannot be regenerated in the server, so weight updates are rejected outright;
+rebuild the sidecar against the new weights and restart.
+
 ### Serve MiniMax-H3 on Ascend NPUs
 
 For Ascend NPU, follow the

docs/docs/sglang-diffusion/api/cli.mdx

@@ -78,6 +78,9 @@ Use `sglang generate --help` and `sglang serve --help` for the full argument lis
 - `--served-model-name {NAME}`: stable model name exposed by serving APIs. Defaults to `--model-id` when set, otherwise `--model-path`.
 - `--model-variant {NAME}`: semantic checkpoint variant to load when one model repository contains multiple weight partitions. The pipeline maps this stable name to the repository layout before loading; for example, MiniMax-H3 accepts `fl2va` and `ref2va`. This is a server/load-time choice, unlike a request's `task`.
 - `--minimax-h3-adaln-cache-path {FILE}`: advanced MiniMax-H3-only inference cache. It replaces the checkpoint's AdaLN projection weights with precomputed outputs and only accepts requests whose exact FP32 timestep plan is included in the cache. It requires unquantized weights and the matching model variant.
+- `--minimax-h3-adaln-online {true,false}`: rebuild MiniMax-H3 AdaLN outputs from the checkpoint on demand instead of keeping the 24.2 GiB of `adaln_proj` weights resident. Works with any step count or schedule; requires the unquantized native-layout checkpoint. Built plans live in a GPU slab with per-plan LRU eviction and, by default, a pinned-host cache so previously seen schedules swap back in over PCIe instead of re-reading the checkpoint.
+- `--minimax-h3-adaln-plan-width {N}`: widest timestep plan the online slab is sized for (default 4 covers every task; t2va needs 2, fl2va 3).
+- `--minimax-h3-adaln-host-cache-gb {GB}`: pinned host memory per rank caching built AdaLN plans (default 8; 0 disables). A 50-step schedule needs about 0.9 (t2va) / 1.33 (fl2va) / 1.77 (ref2va) GB; over-capacity plan sets simply recompute. Expert escape hatches (GPU slot count, experimental fp32 rebuild) are the `SGLANG_DIFFUSION_MINIMAX_H3_ADALN_*` environment variables.
 - `--model-subfolder {PATH}`: advanced direct override for a component subfolder inside the model repository. Prefer `--model-variant` when the pipeline exposes semantic routing. If both are supplied, they must resolve to the same weight partition.
 - `--lora-path {PATH}` and `--lora-nickname {NAME}`: load a LoRA adapter from a local path, Hugging Face repo/subfolder, or exact Hub file URL
 - `--lora-weight-name {FILE}`: select one adapter file from a repository that contains multiple LoRA revisions. The Hub download is filtered to that file plus JSON metadata, so unused weights are not downloaded.