[perf]: training-free token reduction for MiniMax H3 (#2004)

docs/inference/fasth3-distilled.md

@@ -198,6 +198,57 @@ forwards. With the DiT sharded, peak allocated memory is about 66 GiB per GPU
 (about 95 GiB in use), against 83 GiB (103 GiB) with a full DiT copy on each
 GPU; the output is identical. Model loading and decoding come on top of this.
 
+## Token reduction
+
+`--token-reduction` is an opt-in, training-free speed mode that follows the
+`--token-reduction` mode of [antirez/h3.c](https://github.com/antirez/h3.c).
+Inside DiT blocks 4 to 29, every two horizontally adjacent tokens of the
+generated video are averaged into one, so those blocks see the video at half
+width. During the first 4 of the 8 forwards, where the coarse layout forms,
+the interval extends to block 39. Before the first full-width block, each
+token gets back its own value plus the update its pair received. Text, audio,
+reference and condition tokens are never paired.
+
+FastH3 8-Step V2 and the OmniRef PDD export both support it:
+
+```bash
+python examples/inference/basic/basic_fasth3_8step.py \
+  --prompt 'Two people walk along a beach at sunset, talking and laughing' \
+  --num-gpus 4 --token-reduction
+
+python examples/inference/basic/basic_fasth3_omniref_pdd.py \
+  --model-path <OmniRef export> --image reference.png \
+  --prompt '<Picture 1> ...' --num-gpus 4 --token-reduction
+```
+
+In a recipe, set `pipeline.experimental.h3_token_reduction` to
+`{enabled: true}`. The optional keys `blocks`, `early` and `update_scale`
+match the `--token-reduction-blocks`, `--token-reduction-early` and
+`--token-reduction-scale` flags. Malformed values, and intervals past the
+checkpoint's DiT depth, fail before any weights load.
+
+Measured on one GB200 tray with 4 GPUs, 1344x768, 124 frames and BF16
+weights, after warm-up:
+
+| Checkpoint | Denoising, 8 forwards | Whole request |
+|---|---|---|
+| FastH3 8-Step V2, default profile with regional compile | 5.08 s to 3.53 s, 30.6% less | 9.13 s to 7.58 s, 17.0% less |
+| FastH3 8-Step V2, regional compile off | 6.10 s to 4.26 s, 30.2% less | 10.18 s to 8.41 s, 17.4% less |
+| OmniRef PDD with one image reference, eager | 12.07 s to 9.33 s, 22.7% less | 24.67 s to 21.62 s, 12.3% less |
+
+The saving follows how many rows the middle blocks drop. A V2 request has a
+short text and audio prefix, so the reduced blocks see about half the rows.
+An OmniRef request also carries the reference tokens, which stay unpaired, so
+it saves less. Decoding takes the same time either way.
+
+The reduced video keeps the quality of the unreduced one, but it is not the
+same video. Most scenes keep their overall layout, while details can change,
+such as one of two people in a scene or the venue of a concert. The
+checkpoints were not trained with token reduction, and fine-tuning with it
+enabled is the expected way to keep the original shot. Only the GB200 BF16
+path has been validated so far; the NVFP4 and FP8 consumer profiles have not
+been tested with it.
+
 ## Apple Silicon
 
 `mlx_fasth3.py` stays on FastH3 V1 and its uniform AdaLN cache.