[Video] Bound H3 host weight residency on memory-constrained hosts

[yangzhuxinyzx]

Purpose

H3 TP4 loading exhausted the four-V100 host's 64 GiB system RAM after GPU selection and collectives succeeded. Store DiT and encoder CPU masters in reclaimable file mappings on smaller hosts, while preserving weight bytes, tensor aliases, GPU kernels and sampling. Reserve disk before mapping and immediately unlink mapped files so worker crashes cannot leave large offload files behind. Explicit pinned/mmap options remain available.

The source-wheel extraction path also retains all three H3 native operators, allowing this Python-only change to reuse the exact native libraries compiled from the current source during the same deployment.

Base: a9cfe620127f04888400f7fba91c23699174832f. Head: 9f111147204b55d35eb11b3c188842af55ed01bb.

Test Plan and Result

• Host-memory and FastH3 CPU suites: 35 passed, 1 GPU test skipped, 1 CUDA case deselected.
• Staged pre-commit hooks passed, including mypy and documentation lint.
• Covers byte-exact storage aliases/strides, fused checkpoint writes, buffer preservation, disk reservation failure/cleanup, and packaging of H3 native operators.
• Isolated candidate wheel installed; all 13 native libraries are SHA256-identical to the campaign’s full SM70 source build. python -m pip check passed.
• Actual V100 test: python -m pytest src/tests/video/test_h3_host_memory.py -q — 7 passed, including three byte-exact GPU load/offload cycles.
• Studio-managed H3 Turbo4, TP4 / 4×V100-SXM2-32GB / 64 GiB host: loading and generation completed without a new kernel OOM. ModelScope FL2VA INT8 plus original Turbo4 adapter, FP16 staging, Flash-V100, seed 42, 107 frames, 1344×768, 4 denoiser updates.
• Saved MP4 verified: 107 frames, 24 FPS, 4.458333 seconds, AAC stereo. Four-frame visual check shows coherent boat/duck/water imagery; this is an operational smoke, not a full temporal or prompt-adherence quality benchmark.
• Generation-to-save elapsed 147.93 s; native denoising 67.5 s. No same-contract pinned baseline exists on this 64 GiB host because it OOMs, so no speedup is claimed. The runtime keeps H3 experimental.

Original OOM and raw deployment evidence are retained in /home/ymzx/1cat-vllm-deploy/studio-main-20260909/; candidate evidence is retained in /home/ymzx/1cat-vllm-deploy/h3-host-memory-20260909/.

Scope and Limitations

Open-PR checks found kernel/workflow changes (#571/#578), but no duplicate host-weight residency fix. This scope does not change those kernels. File-backed staging needs local disk capacity and can slow CPU→GPU transfers; transient activations still require RAM. Automatic mode uses physical host RAM, with an explicit override for constrained containers.

AI assistance: implementation and tests prepared with OpenAI Codex at the maintainer's request.