Control Qwen Image 2.1 References and Prompt Phrases in ComfyUI

What ComfyUI-qwen_img_2_1_enhancer Does

ComfyUI-qwen_img_2_1_enhancer adds two nodes for native Qwen Image 2.1 workflows in ComfyUI. The nodes let you control the attention priority of individual reference images and emphasize or suppress selected prompt phrases.

Use the nodes independently or combine them in the same workflow. They adjust attention scores inside the native Qwen Image 2.1 transformer rather than rescaling text embeddings, compositing reference pixels, or changing the source images.

• Qwen Image 2.1 Reference Strength: Changes the attention priority of a selected reference image.
• Qwen Image 2.1 Edit — Phrase Weights: Adds weighted phrase syntax to positive and negative prompts and produces conditioning and latent outputs.

Requirements and Installation

You need ComfyUI with native Qwen Image 2.1 support, plus a working Qwen Image 2.1 model, text encoder, and VAE setup. The custom node does not require additional Python packages or edits to ComfyUI core files.

1. Open a terminal and move to ComfyUI's custom-node directory:

cd ComfyUI/custom_nodes

1. Clone the repository:

git clone https://github.com/capitan01R/ComfyUI-qwen_img_2_1_enhancer.git

Restart ComfyUI after installing or updating the node. Once restarted, search the node menu for the two Qwen Image 2.1 enhancer nodes.

Adjust Reference-Image Strength

The Qwen Image 2.1 Reference Strength node controls attention to one connected reference image. Add it after your model and optional LoRA loaders, then connect its MODEL output to the sampler.

Load Diffusion Model -> LoRA loaders (optional) -> Reference Strength -> sampler

Connect the reference images and VAE to the native Text Encode Qwen Image 2.1 node or to the included Phrase Weights encoder. Reference selection follows the encoder's connected-image order. Empty image inputs are skipped.

Reference Strength Inputs

• model: The Qwen Image 2.1 model, including any applied LoRAs.
• reference_index: The reference to adjust. 1 selects the first connected image, 2 selects the second, and so on.
• strength: The attention-odds multiplier. Its default value is 1.2.

Interpreting Strength Values

• 1.0 preserves native reference weighting.
• Values above 1.0 increase the selected reference's priority.
• Values between 0.0 and 1.0 reduce its priority.
• 0.0 blocks direct attention to the selected reference's latent tokens, although information about the image may remain elsewhere in the conditioning.

The adjustment applies to the entire reference image. To control several references, chain multiple Reference Strength nodes. If the same index is repeated, the later setting replaces the earlier strength. Setting an index to 1.0 removes its adjustment.

Apply Weighted Prompt Phrases

Use Qwen Image 2.1 Edit — Phrase Weights instead of the native Text Encode Qwen Image 2.1 node. Connect the native Qwen Image 2.1 CLIP, your reference images, and the VAE. Then send the node's positive, negative, and latent outputs to the sampler.

The encoder does not need a MODEL connection. The model follows its normal path to the sampler.

Phrase-Weight Syntax

Wrap a word or phrase in parentheses, add a colon, and specify a nonnegative weight:

Add (warm lighting:1.3) and (soft shadows:1.1).

• 1.0 uses native phrase weighting.
• Values above 1.0 increase the phrase's priority.
• Values between 0.0 and 1.0 reduce the phrase's priority.
• 0.0 strongly suppresses attention to the selected phrase tokens.

Positive and negative prompts have independent weights. Only the marked occurrence receives the adjustment, so use complete words or phrases in separate, non-nested sections.

Phrase Weights Connections and Outputs

• clip: The native Qwen Image 2.1 text encoder loaded with CLIP type qwen_image.
• prompt: The positive prompt, including optional weighted phrases.
• negative_prompt: The negative prompt, with its own optional weighted phrases.
• vae: The native Qwen Image 2.1 VAE. It is required when combining this node with Reference Strength.
• resolution: The reference resizing target. The default is 1024; setting it to 0 keeps references near their original dimensions, rounded to multiples of 32.
• images: Reference images. Additional image sockets appear as needed.
• positive and negative: Conditioning outputs for the sampler.
• latent: An empty latent sized from the first reference after resizing.
• phrase_report: Optional JSON text showing clean prompts, weights, and selected token rows.

Use Both Nodes Together

For a workflow that controls both image references and prompt phrases, route the model through Reference Strength and route the conditioning and latent outputs from Phrase Weights to the sampler.

MODEL -> Reference Strength -------------------------> sampler MODEL

CLIP + VAE + images -> Phrase Weights
                           |------------------------> sampler positive
                           |------------------------> sampler negative
                           `------------------------> sampler latent_image

When comparing results, change one control at a time while keeping the other settings fixed. This makes it easier to determine whether a visual difference comes from reference priority or phrase priority.

Advanced Tips and Limitations

Both nodes apply a mathematical attention adjustment. For a positive weight w, selected attention scores receive log(w) before softmax. This changes relative attention priority while retaining normalization.

• A strength or phrase weight of 2.0 does not guarantee twice the visible effect.
• Very large values can dominate other instructions or references and reduce editing flexibility.
• Reference Strength selects reference-image keys, while Phrase Weights selects text keys belonging to marked phrases.
• Native prefix caching is preserved.
• Attention backends must support additive masks.
• Phrase mapping requires whole tokenizer pieces and does not support textual-inversion embeddings.
• Changing conditioning token rows after phrase encoding can invalidate the phrase mapping.

For practical tuning, begin at the native value of 1.0, make small changes, and inspect the optional phrase_report when you need to verify which prompt tokens were selected.

Conclusion

ComfyUI-qwen_img_2_1_enhancer provides focused control for Qwen Image 2.1 editing workflows without modifying ComfyUI core files. Install the custom node, use Reference Strength to prioritize individual images, use Phrase Weights to emphasize or suppress prompt phrases, and combine both nodes when you need coordinated control over visual references and text instructions.

The project is released under the MIT License.