vllm-omni/docs/design/module/diffusion/offloader.md

title, kind, status, owners, primary_code_paths, related_code_paths, depends_on, validation_paths, upstream_refs, last_reviewed

title	kind	status	owners	primary_code_paths	related_code_paths	depends_on	validation_paths	upstream_refs	last_reviewed
Diffusion Offloader	module	draft	@yuanheng-zhao @david6666666 @lishunyang12	vllm_omni/diffusion/offloader/**	vllm_omni/diffusion/models/** vllm_omni/diffusion/worker/**	diffusion_runtime.md ../execution_platforms.md	tests/diffusion/offloader/**	torch.nn.Module.to	2026-08-25

Diffusion offloader

The offloader owns component residency, transfer scheduling, memory accounting, prefetch, and teardown for diffusion execution.

Candidate invariants

OFFLOAD-INV-001: Residency is explicit

Rule: Each managed component MUST have one known residency state and one owner responsible for transitions.

OFFLOAD-INV-002: Use follows readiness

Rule: Runtime execution MUST NOT consume a component until its transfer to the required device is complete.

OFFLOAD-INV-003: Transfers preserve model state

Rule: Offloading MUST preserve parameter and buffer identity, dtype, device, and correctness required by the selected execution mode.

OFFLOAD-INV-004: Memory is bounded and released

Rule: Retained host and device copies MUST respect configured limits and provide deterministic teardown.

Allocator-cache retention MUST remain local to an explicit component owner, declare both cache and physical-free-memory bounds, release conservatively when telemetry is unavailable, and force release on failure or memory pressure. It MUST NOT replace unconditional executor shutdown cleanup.

Safe-change guide

Test enabled and disabled paths, repeated execution, asynchronous transfer, memory limits, failure, teardown, and numerical equivalence.