README: verified usage (cross-repo transformer load, turbo prefix, device move)

README.md

@@ -36,10 +36,17 @@ vae/                         # AutoencoderKLMiniMaxH3, decoder_num_layers=12 (st
 
 Requires `diffusers` with the MiniMax-H3 integration.
 
+Two things to know up front, both inherent to a stand-alone modular index (verified on a live Space):
+1. The LightVAE `vae` loads automatically from this repo. The **pruned transformer is remote code in a different
+   repo**, and `trust_remote_code` is only forwarded to components that live in this index's own repo, so
+   `transformer_ref` has to be loaded explicitly and injected with `update_components`.
+2. Components load on CPU; move the model components to the GPU before calling the pipeline.
+
 ```python
 import torch
 from huggingface_hub import hf_hub_download
-from diffusers import ComponentsManager
+from safetensors.torch import load_file
+from diffusers import ComponentsManager, AutoModel
 from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3Blocks
 from diffusers.modular_pipelines.minimax_h3.references import MiniMaxH3VideoReference
 
@@ -50,23 +57,36 @@ pipe = blocks.init_pipeline(
     components_manager=ComponentsManager(),
     collection="h3",
 )
-pipe.load_components(dtype=torch.bfloat16, trust_remote_code=True)
+pipe.load_components(dtype=torch.bfloat16, trust_remote_code=True)  # LightVAE `vae` loads here
+
+# the remote-code pruned transformer lives in a different repo, so load + inject it explicitly
+if getattr(pipe, "transformer_ref", None) is None:
+    transformer_ref = AutoModel.from_pretrained(
+        "multimodalart/MiniMax-H3-Pruned", subfolder="transformer_ref",
+        trust_remote_code=True, torch_dtype=torch.bfloat16,
+    )
+    pipe.update_components(transformer_ref=transformer_ref)
 
 # both autoencoders stay fp32 on the native attention backend
 pipe.vae.set_attention_backend("native")
 pipe.audio_vae.set_attention_backend("native")
 
-# optional: lightx2v 4-step Ref2V Turbo LoRA (on the transformer; independent of the VAE)
-pipe.load_lora_weights(
-    hf_hub_download("lightx2v/Minimax-h3-Turbo", "minimax_h3_ref2v_turbo_4step_v0.1_bf16.safetensors"),
-    adapter_name="turbo",
-)
-pipe.set_adapters(["turbo"], [1.0])
+# lightx2v 4-step Ref2V Turbo LoRA. Its keys target the transformer submodules with no `transformer.` prefix,
+# so load it onto the component with prefix=None (and drop the PEFT `.default.` adapter segment from the keys).
+turbo = load_file(hf_hub_download("lightx2v/Minimax-h3-Turbo", "minimax_h3_ref2v_turbo_4step_v0.1_bf16.safetensors"))
+turbo = {k.replace(".lora_A.default.weight", ".lora_A.weight").replace(".lora_B.default.weight", ".lora_B.weight"): v
+         for k, v in turbo.items()}
+pipe.transformer_ref.load_lora_adapter(turbo, prefix=None, adapter_name="turbo")
+pipe.transformer_ref.set_adapters(["turbo"], [1.0])
+
+# components load on CPU; move the models to the GPU (VAEs keep fp32)
+for name in ("transformer_ref", "vae", "audio_vae"):
+    getattr(pipe, name).to("cuda")
 
 state = pipe(
     prompt="a red fox walking through snow, cinematic",
     references=[MiniMaxH3VideoReference.from_file("reference.mp4")],
-    height=448,
+    height=768,
     width=768,
     num_frames=124,          # must be 17*n + 5
     num_inference_steps=4,   # 4 with the Turbo LoRA; ~20 without