[Diffusion] Integrate no-AllGather DLO with Host Weight Runtime (#6486)

Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>
Signed-off-by: hsliuustc0106 <hsliuustc0106@users.noreply.github.com>
Co-authored-by: hsliuustc0106 <hsliuustc0106@users.noreply.github.com>

docs/user_guide/diffusion/offloader/distributed_layerwise_offload.md

@@ -63,6 +63,8 @@ omni = Omni(
 | `--dlo-use-allgather` | Shard host weights and reconstruct with AllGather | `true` |
 | `--dlo-no-use-allgather` | Stream complete rank-local blocks without a DLO weight collective | `false` |
 | `--dlo-resident-layers N` | Keep N leading main-DiT blocks on device; requires no-AllGather and model-declared resident paths | `0` |
+| `--host-weight-runtime-mode {disabled,preferred,required}` | HWR policy: no interaction, populate on a miss, or require an exact hit | `disabled` |
+| `--host-weight-runtime-root PATH` | Writable node-local HWR store shared by workers in one storage domain; required for `preferred` and `required` | unset |
 
 ## Host-weight loading
 
@@ -104,6 +106,88 @@ process.
 When the effective DLO group size is one, `dlo_use_allgather=True` does not
 perform a collective and uses the same rank-local transfer behavior.
 
+### Final-layout Host Weight Runtime
+
+HWR is an opt-in startup optimization for models that declare the final-layout
+BF16 restore contract. Use it only with no-AllGather DLO:
+
+```bash
+vllm serve /path/to/model --omni \
+  --enable-distributed-layerwise-offload \
+  --dlo-no-use-allgather \
+  --host-weight-runtime-mode preferred \
+  --host-weight-runtime-root /var/cache/vllm-omni/hwr
+```
+
+#### Choosing a mode
+
+| Mode | Exact local artifact hit | Miss or recoverable artifact/store problem | Intended use |
+| --- | --- | --- | --- |
+| `disabled` | HWR is not consulted | Use the existing checkpoint-mmap or ordinary-loader path | Default compatibility path |
+| `preferred` | Restore the final-layout artifact | Load canonically, serve with those tensors, and attempt to publish an artifact for the next startup | Normal deployment and store population |
+| `required` | Restore the final-layout artifact | Fail startup without canonical DiT fallback or publication | Enforce a pre-populated store in controlled rollouts or CI |
+
+Both enabled modes still fail on non-retryable configuration, identity, or
+compatibility errors. `preferred` is a fallback policy for a cache miss or a
+recoverable cache problem; it does not hide an invalid deployment.
+
+#### Populating a store for `required` mode
+
+`required` is deliberately consume-only. PR2 does not include a separate
+prewarm command, so populate each node-local storage domain with one matching
+`preferred` producer cohort:
+
+1. Choose a persistent, writable root visible to every diffusion worker in the
+   storage domain. Do not use a process-private temporary directory.
+2. Start the deployment with `preferred`, using the exact model revision,
+   dtype, TP size, SP configuration, and other weight-layout settings intended
+   for serving. No inference request is needed; publication happens during
+   model startup. Wait for the engine to become healthy, then shut it down
+   cleanly.
+3. Restart with the same arguments and root, changing only the mode to
+   `required`. A successful startup proves that every worker acquired a valid
+   artifact; a miss, corrupt artifact, or incompatible identity fails startup.
+4. Repeat the population start on every node or storage domain because this
+   store is node-local.
+
+For example:
+
+```bash
+# First startup: canonically load and populate the exact artifacts.
+vllm serve /path/to/model --omni \
+  --enable-distributed-layerwise-offload \
+  --dlo-no-use-allgather \
+  --host-weight-runtime-mode preferred \
+  --host-weight-runtime-root /var/cache/vllm-omni/hwr
+
+# After a healthy startup and clean shutdown, enforce cache hits.
+vllm serve /path/to/model --omni \
+  --enable-distributed-layerwise-offload \
+  --dlo-no-use-allgather \
+  --host-weight-runtime-mode required \
+  --host-weight-runtime-root /var/cache/vllm-omni/hwr
+```
+
+Include the same TP and SP layout flags in both commands. DP rank and DP size
+are excluded from artifact identity, so the population and serving DP sizes may
+differ and equivalent DP replicas share artifacts. TP rank is included, so a
+TP-N deployment normally needs N rank-specific artifacts in each storage
+domain; launching the matching TP cohort creates that set. If the model
+revision or layout changes, run `preferred` again for the new identity before
+returning to `required`.
+
+On a cold start, the canonical loader remains authoritative and publishes a
+validated final-layout artifact for later workers. A warm start restores the
+DiT final tensors without ordinary DiT materialization, then DLO streams them
+through the same two bounded host staging slots. The artifact identity includes
+the TP rank/size and SP layout, so TP1, TP2 rank-local shards, and distinct SP
+layouts do not alias one another. Publication failure remains separate from a
+`preferred` serving startup; the next `required` startup provides the explicit
+artifact-availability check.
+
+When HWR is disabled, DLO is disabled, or AllGather is enabled, the loader does
+not resolve HWR sources or construct its store.
+
 ## Declarative topology
 
 Models may declare an `OffloadPlan` instead of embedding offload logic:
@@ -135,7 +219,9 @@ must enter each collective.
 - Direct checkpoint mmap currently requires TP1. TP greater than one is
   outside the Phase A shared-mmap support scope and falls back before model
   mutation to the ordinary TP-aware loader. DLO can stream that runtime layout,
-  but it provides no shared-mmap host-memory benefit or guarantee.
+  and eligible no-AllGather configurations may use HWR final-layout artifacts,
+  but direct checkpoint mmap provides no shared-mmap host-memory guarantee for
+  TP greater than one.
 - HSDP plus AllGather is rejected to avoid double sharding. HSDP without
   AllGather has limited end-to-end validation.
 - Per-tensor online FP8 linears use the ordinary loader and can run with either
@@ -147,10 +233,10 @@ must enter each collective.
   `OffloadPlan` that declares eligible `resident_dit_paths`.
 - DP concurrency requires an explicit, identical inference-step count.
 
-Sharing transformed TP or quantized runtime layouts through a normalized mmap
-cache is a follow-up design in
+Sharing quantized or otherwise unvalidated transformed layouts through a
+normalized HWR producer is a follow-up design in
 [RFC #6195](https://github.com/vllm-project/vllm-omni/issues/6195), not part of
-the direct-checkpoint path.
+the current BF16 final-layout path.
 
 See the [Cosmos3 DistOffload recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/cosmos3/Cosmos3-DistOffload.md)
 for an end-to-end example.