DiffSynth: Z-Image Loader

Everything about which Z-Image you're running lives in this node's model_configs - there's no "Turbo or Base" dropdown, because the framework doesn't care what you call the file, only what's in it. Point the ModelConfigs at Turbo and you get 8-step CFG-1 behaviour. Point them at Base and the same graph wants 50 steps.

Inputs

Required:

• torch_dtype - bfloat16 (default), float16, float32.
• device - cuda or cpu.
• model_configs - merged from a Merge ModelConfigs node. Required, and this is the whole story of the Loader.

Optional:

• tokenizer_config - ModelConfig for the Qwen3-4B tokenizer directory. Wire it; the text encoder is a language model and needs its tokenizer files.
• enable_npu_patch - on by default, and you should leave it on. It swaps RMSNorm and rotary embeddings for fused Ascend operators, but only when torch_npu is present and an NPU is actually available. On a CUDA box it's inert, which is why nobody notices it.
• vram_limit - from a VRAM Limit node.

Output: pipe → DiffSynth: Z-Image Inference.

The file list

Straight from the pack's Z-Image examples:

| Into | model_id | origin_file_pattern | |---|---|---| | model_configs | Tongyi-MAI/Z-Image-Turbo | transformer/*.safetensors | | model_configs | Tongyi-MAI/Z-Image-Turbo | text_encoder/*.safetensors | | model_configs | Tongyi-MAI/Z-Image-Turbo | vae/diffusion_pytorch_model.safetensors | | tokenizer_config | Tongyi-MAI/Z-Image-Turbo | tokenizer/ |

Swap every Tongyi-MAI/Z-Image-Turbo for Tongyi-MAI/Z-Image and you're on Base. The 6B transformer plus its Qwen3-4B text encoder is the bulk of the download; the VAE is the Flux 1 VAE, which is why Z-Image swaps latents so cleanly with Flux 1 and takes Z-Image Turbo as a refiner in the other direction.

Files land in models/<model_id>/ under ComfyUI's working directory. If you already have a Z-Image GGUF or a ComfyUI-format fp8 in ComfyUI/models, this loader cannot see it - it wants the DiffSynth component layout, resolved by glob. That's the trade every node in this pack makes.

Install

Manager → search DiffSynth-ComfyUI → install → restart. Manual:

pip install git+https://github.com/modelscope/DiffSynth-Studio.git
cd ComfyUI/custom_nodes && git clone https://github.com/modelscope/DiffSynth-ComfyUI.git

One declared dependency, diffsynth>=2.1.9.

Memory, briefly

Z-Image is the one model in this pack that runs comfortably without heroics. The stock VRAM Config defaults - offload to CPU in bfloat16, compute on GPU - will hold 1024×1024 Turbo on a 12GB card without fuss. If you've got the headroom, push onload_device and preparing_device to cuda for fewer round trips across PCIe; if you're tighter than that, a VRAM Limit with a 0.5–1GB buffer keeps ComfyUI's own cache from being the thing that OOMs.

Quantization is not the first lever here. Reach for it when a model genuinely doesn't fit, not when it barely does.

Common issues

• NaNs, black frames, or an instant failure. The text encoder or VAE is missing from model_configs, or you mixed a Turbo transformer with a Base text encoder's files. Keep one model_id across all four nodes.
• 8 steps produces mush. You're on Base weights with Turbo settings, or vice versa. Check which repo the ModelConfigs point at.
• Sage Attention and Base. Reported to break Base output specifically. Turn it off before you debug anything else.
• Moved the model folder and it re-downloads. DIFFSYNTH_MODEL_BASE_PATH has to be exported before ComfyUI starts, and the glob pattern has to match what's on disk exactly.