Donut ZiT Layer-Blend Encode

Most text encoders are icebergs: you only ever use the tip. Z-Image Turbo's stock encode pulls a single hidden layer out of its Qwen3-4B encoder and hands it to the model - everything else is discarded. But transformer layers aren't redundant; shallow layers carry low-level, syntactic features while deep layers carry high-level semantics. DonutZitLayerBlendEncode is a replacement text-encode node that grabs many hidden layers in a single forward pass and blends them together along a shallow→deep curve. That turns "which layer do I keep" into a real, tunable control - the Z-Image analog of the per-layer sliders people love on other models.

How it works

The trick is in how ComfyUI's encoder works: if you set clip.layer_idx to a list of layers, the encoder returns every requested layer stacked as (B, K, seq, 2560). This node requests the full stack, then collapses the K layer axis with a weighted average - not concatenation - so the output stays 2560-dim and drops into the model unchanged.

The weighting is where you get control. Two handles, one curve:

• weight_shallow (default 0) - gain on the shallowest layers: syntax, structure, low-level form.
• weight_deep (default 1) - gain on the deepest layers: actual semantics. The docstring's useful note: stock encode is roughly deep-only, so defaults ≈ stock behavior.
• curve - linear, smoothstep, ease_in, ease_out, or cosine. This shapes how the gain interpolates from shallow to deep across the layers. ease_in biases toward the shallow end; cosine is the gentle middle.
• multiplier - overall gain applied after the depth blend (default 1).

Outputs: CONDITIONING, ready for the sampler.

When to reach for it

The pitch: stock encode is one layer, this is all of them, and the shallow layers carry information stock encode throws away. In practice the wins show up as better adherence on prompts that need both structure and meaning - complex subjects, multi-part compositions - or as a recovery tool when a prompt reads as "right idea, wrong details." Raising weight_shallow a bit tends to firm up the form of what you asked for; leaning on weight_deep keeps the meaning crisp.

Two caveats worth knowing. First, it needs a ZiT/Lumina2-style CLIP (Qwen3-4B); with any other encoder it detects the wrong conditioning shape and falls back to a plain encode - safe, but you get nothing extra. Second, the layer list is captured in one pass, so it's roughly as fast as stock encoding, but the blend math is still a small per-call cost. Not nothing on a batch.

A practical pairing: this node shapes which layers feed the conditioning, and the pack's DonutZitConditioningRebalance shapes how loud the result is (multiplier on the single 2560-dim tensor). Use LayerBlend for the "which features" question and Rebalance for the "how strong" question.

Install

Part of ComfyUI-DonutNodes: ComfyUI Manager → search "DonutNodes" → install → restart. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/DonutsDelivery/ComfyUI-DonutNodes.git donutnodes
cd donutnodes
python -m pip install -r requirements.txt

No model downloads, no GPU-heavy deps - the pack's shared opencv-python-headless, scipy, matplotlib, psutil, tqdm, requests is the whole story.