TwinFlow Model Patcher

TwinFlow is a distillation that hangs an extra piece of machinery on an existing DiT: a second time-embedding branch that the base Qwen-Image / Z-Image architecture doesn't have. That branch lives in a separate patch file, not in the full checkpoint, and the standard ComfyUI loader doesn't know it exists. The TwinFlow Model Patcher is the node that loads those patch weights and re-stitches the branch onto your model. Its output is a patched MODEL that now knows how to be a 1-step generator.

This is the pack's reason to exist. The author is blunt about it: the entire TwinFlow workflow hinges on this node, because without the restored embedder the model silently runs as a slower, unpatched version of itself. If you skip it, everything downstream is wasted effort.

How it works

Which weights the patch file carries depends on the model family. On Z-Image the extra branch is t_embedder_2; on Qwen-Image it's time_text_embed_2. The patcher reads the file, pulls out only those keys, builds a small MLP embedder from them, and wraps the model's original time embedder in a proxy. From then on, every forward pass adds the TwinFlow term - scaled by how far the current step is from a target timestep that the TwinFlow sampler hands it through ComfyUI's transformer options. That target-timestep conditioning is the entire secret sauce of TwinFlow, and it only exists because this node put it there.

The patch_file dropdown scans ComfyUI/models/diffusion_models/ (and unet/), and it'll happily list .gguf patch files too - the loader dequantizes F32/F16/BF16/Q8_0 tensors on the fly. If the keys don't match, it warns and passes the model through untouched. That silent pass-through is the failure mode you'll actually hit.

The inputs that matter

Just two:

• model - your TwinFlow-tuned DiT, loaded normally (Qwen-Image, Z-Image-Turbo). You can load the base model as GGUF via city96's ComfyUI-GGUF loader; the patcher doesn't care how the model got into memory.
• patch_file - the matching TwinFlow patch weights, e.g. TwinFlow_Z_Image_Turbo_bf16.safetensors. "Matching" means the same model family - a Qwen patch on a Z-Image model has no compatible keys, and the patcher will just shrug and pass through.

Output: a single MODEL, wired into the TwinFlow KSampler or a custom-sampling chain.

Installing it

Standard pack install - ComfyUI Manager, search "TwinFlow", or:

cd ComfyUI/custom_nodes
git clone https://github.com/mengqin/ComfyUI-TwinFlow.git
pip install -r requirements.txt

The gguf>=0.6.0 dependency is what powers GGUF patch loading; stick with safetensors patches and you don't strictly need it, but it's in requirements for a reason. Drop patch files in ComfyUI/models/unet/ (GGUF can live there too) and restart.

When it goes wrong

This is where most TwinFlow pain lives, and it's mostly real-world baggage rather than theory:

• Output looks like ordinary, unpatched Z-Image/Qwen - the classic sign the patch keys didn't match and the patcher passed through. Third-party conversions have shipped with wrong prefixes; one popular "exp" safetensors had none of the expected names, and a user only got it working by feeding the .gguf version in as the patch file instead.
• GGUF patch and metadata problems - the z-image-turbo GGUF from wbruna has incomplete metadata and malformed tensors and won't load with ComfyUI-GGUF without a one-line header fix (arch=lumina2); some Qwen GGUFs on HuggingFace carry "qwen" instead of "qwen_image" as their architecture. Corrected conversions exist - Arunk25's Qwen GGUF is the one the README points at.
• Low-bit quant patch files - only F32/F16/BF16/Q8_0 tensors are dequantized; anything quantized lower is silently skipped, leaving the patch effectively dead.

Honest caveat: the author has said the repo's had thin upkeep lately, and a competing pack (smthemex/ComfyUI_TwinFlow) implements TwinFlow with a self-contained loader and sampler that doesn't interoperate with standard nodes. This patcher's whole pitch is that it plays nice with the rest of ComfyUI - LoRAs included.