XB-BOX - 🧠 Wan 模型加载

If you're new to local video gen, the scariest part of a Wan workflow isn't the sampling - it's the loader. XB_WanModelLoader is the XB_ToolBox way of loading a Wan diffusion model into ComfyUI, and its whole job is to make the decisions that used to be buried in a JSON workflow visible and steerable. It's the "XB-BOX - 🧠 Wan 模型加载" node in the XB_ToolBox/Wan category.

The pack is a Wan-heavy utility suite from a Chinese community author (WJLUOXIAO) aimed squarely at beginners - the README's stated goal is "help AI beginners new to ComfyUI quickly master workflows," with a heavy AMD-GPU optimization bent. This loader is the front door to all of that: everything else in the Wan half of the pack consumes its WANVIDEOMODEL output.

How it works

Under the hood it's a thin, honest wrapper around ComfyUI's native Wan model loader - it calls the same WanVideoModelLoader that core ComfyUI uses, so it loads whatever checkpoints you already have in models/diffusion_models. What it adds is a clean surface for the knobs people actually fight over:

• base_precision (bf16 default) - the working precision for the weights.
• quantization - disabled, fp8_e4m3fn, fp8_e4m3fn_fast, or fp8_e5m2. On a 12–16GB card, fp8 is often the difference between OOM and a working 81-frame run.
• load_device - main_device (GPU) or offload_device (system RAM). If you're on a 10GB card, offloading the model to RAM while keeping activations on GPU is the classic trick.
• attention_mode - sdpa or sageattn. SageAttention is a genuine speedup but a notorious install headache on Windows; sdpa is the safe default.
• rms_norm_function - default or pytorch; leave it alone unless you know why you're changing it.

Three optional inputs plug the rest of the pack in: block_swap_args (from the pack's XB_WanBlockSwap, which shoves whole transformer blocks into system RAM), compile_args (from XB_WanCompileSettings, for torch.compile), and lora (WANVIDLORA). The source also quietly defends you: it forces sdpa if a flash mode slips through, and on a HIP build it drops compile args entirely, because torch.compile on ROCm is where fun goes to die.

What to actually set

For a beginner: pick your checkpoint, set base_precision to bf16, leave quantization disabled until you OOM (then try fp8_e4m3fn), and keep attention_mode on sdpa. The output is a single model socket of type WANVIDEOMODEL - feed it to the pack's XB_WanSampler, or into the Wan bus/relay nodes if you're building one of the long-form pipelines.

Install

Two ways, same result. In ComfyUI Manager, search XB_ToolBox and hit install. Or from the terminal:

cd ComfyUI/custom_nodes
git clone https://github.com/wjluoxiao/XB_ToolBox.git

Then restart ComfyUI. The README insists there are "NO extra pip dependencies required," but the shipped pyproject.toml declares opencv-python and easyocr, so Manager will quietly pull those in - the "no deps" claim is optimistic, not a lie. No model files ship with the pack: you bring your own Wan 2.1/2.2 checkpoints, and the Wan T5/CLIP/VAE that go with them.

Gotchas

Where people get burned: the model dropdown only lists files in models/diffusion_models, so a checkpoint sitting somewhere else won't show up. And if you loaded a Wan 2.2 MoE checkpoint, remember the loader is precision- and quantization-aware but not magic - a 27B model at bf16 still needs ~24GB of headroom even with offloading. This node is the easy part; the VRAM math comes later, at sample time.