ComfyUI-Captionator-Qwen35

ComfyUI Captionator Qwen3.5

Simple ComfyUI custom node for running multimodal Qwen3.5 image captioning.

Node

• Name: CaptionatorQwen35
• Description: ComfyUI Qwen 3.5 Prompting nodes
• Category: Captionator
• Optional input image: IMAGE
• Output caption: STRING
• Output full_output: STRING

Features

• Scans models/text_encoders, models/llm, and models/LLM using folder_paths
• Loads local Qwen3.5 checkpoints
• Offers one-click download options for Qwen3.5 2B, 4B, and 9B when no local models are found
• Sends prompt plus optional image to the model
• Supports text-only generation when no image is connected
• Supports seed
• Supports think mode
• Supports optional resize via resize_to
• Supports configurable output length via max_new_tokens
• Splits visible caption from full reasoning output when think is enabled
• Includes a prompt improver node with optional image input

Installation

Place this folder into your ComfyUI custom_nodes directory.

Install dependencies in the same Python environment used by ComfyUI:

pip install -r requirements.txt

You also need a transformers build with Qwen3.5 support, plus the model files themselves. If you run on CUDA with automatic device mapping, install accelerate in the same environment as ComfyUI.

Model placement

Put your Qwen3.5 model in one of these folders:

• ComfyUI/models/text_encoders
• ComfyUI/models/llm
• ComfyUI/models/LLM

The model directory should include the checkpoint and the usual Hugging Face files such as config, tokenizer, and processor files. Text-only generation can work without processor files if the selected model directory includes config.json and tokenizer files. Standalone .safetensors files without the surrounding Hugging Face model files are not enough for Transformers loading.

Inputs

• image: optional input image; leave disconnected for text-only generation from prompt
• model: model selected from discovered Qwen 3 .safetensors files or their Hugging Face model directories
• If no matching local model is found, the dropdown shows download actions for Qwen3.5 2B, 4B, and 9B into models/llm
• prompt: multiline instruction for the model
• resize_to: longest image side before inference; 0 disables resizing
• max_new_tokens: maximum number of generated output tokens
• seed: random seed for reproducible sampling
• think: enables thinking mode when supported by the installed processor

Outputs

• caption: final caption text; if think is enabled and the model returns </think>, everything up to and including that tag is removed
• full_output: raw model output without trimming

Usage Examples

Simple workflow:

Image -> prompt -> image workflow for Z-Image:

Caption Improver

• Name: Caption Improver Qwen 3.5
• Optional input image: IMAGE
• Output prompt: STRING
• Output full_output: STRING
• Output instructions_prompt: STRING
• Reuses the same model, prompt, resize, token limit, seed, and think settings
• Includes a mode dropdown to choose whether details/style come mainly from the prompt, the image, or both
• Builds an instruction that improves the original prompt, optionally using the attached image for style/detail guidance
• If both prompt and image are provided, the selected mode controls which source has priority for details and style
• Returns a single-paragraph English prompt and the raw model output

Prompt Improver workflow example:

Notes

• Restart ComfyUI after changing code or installing dependencies.
• If think is not supported by your installed processor version, the node falls back automatically.
• Large images and large token counts can increase VRAM use.
• Model discovery only shows .safetensors paths containing qwen and 3 (case-insensitive).

Development

Run the unit tests without a ComfyUI installation or model checkpoint:

python -m unittest discover -s tests -v

The tests use a mocked folder_paths module and do not perform model inference or downloads. GitHub Actions runs the same suite for Python 3.10, 3.12, and 3.13 on every push and pull request.

The ComfyUI node layer is separated from model inference through a small backend contract. The current TransformersBackend owns model loading, preprocessing, generation, and its model cache; this boundary is intended to allow additional model formats without duplicating the node UI and prompt-building logic.