Z-Image Diffusers Loader

A lot of the most interesting Z-Image weights ship as diffusers folders, not single safetensors. Community merges, re-turbo'd variants, fine-tunes trained in AI Toolkit - they come down as transformer/, text_encoder/, vae/ subdirectories, and ComfyUI's stock loaders want one flat file. ZImageDiffusersLoader is the node that bridges that gap: point it at a diffusers folder and it loads the transformer, text encoder, and VAE, converting the keys to ComfyUI naming on the fly. People are actually running it - one of the higher-profile community Z-Image showcase workflows names this exact node for its diffusers-based models.

How it works

Three sub-loaders behind one interface:

• Transformer: looks for transformer/ or unet/ inside the folder (falling back to the folder root), handles sharded models via *.index.json, and runs the converted keys through a two-pass remapper. The clever part is QKV fusion: the node scans for attention.to_q weights, merges Q/K/V into a single fused attention.qkv weight (with bias handling), then cleans up the rest of the keys - stripping transformer./unet./diffusion_model. prefixes and fixing renames like to_out.0 → out.
• Text encoder: loads text_encoder/ (or text_encoder_2/), strips text_model. prefixes.
• VAE: loads the vae/ subfolder and hands it to ComfyUI's standard VAE loader.

Outputs are RAW_MODEL, RAW_CLIP, and a real VAE. As always in this pack, the raw pair goes through an injector (ZImageComfyInjector) to become sampleable MODEL/CLIP - the VAE is already usable directly.

The inputs

• folder_path - the diffusers folder on disk. Quotes are stripped automatically.
• load_transformer, load_text_encoder, load_vae - three booleans, all defaulting to true. Turn one off to skip a component; handy when a folder is missing a piece or you're only after the VAE.

Install

ComfyUI Manager (search ComfyUI-Zlycoris) or:

cd ComfyUI/custom_nodes
git clone https://github.com/TripleHeadedMonkey/ComfyUI-Zlycoris.git

Restart ComfyUI. The heavy dependency list (diffusers, transformers, accelerate, optimum) is what makes folder loading possible, so don't skip the install step. No bundled model downloads - bring the diffusers folder yourself.

Where people get burned

• It raises FileNotFoundError if a requested component is missing - e.g. no weights found in transformer/ or unet/. If a folder legitimately lacks a piece, flip the matching boolean off.
• Key conversion isn't magic. QKV fusion only fires when all three of to_q, to_k, to_v exist; when fusion fails it logs a warning and keeps the keys as-is. Merges that come out subtly wrong usually trace back to a partially-fused state dict, so watch for those warnings in the console.
• It's a raw pipeline node. The RAW_MODEL/RAW_CLIP outputs won't sample until they pass through an injector. Forgetting that step is the classic first-run stumble with this whole pack.
• Quantized Qwen encoder caveat applies here too: this loads full-precision diffusers folders; if your text encoder is a GGUF to save VRAM, use the GGUF loader path instead.