ComfyUI-QwenVL-MultiImage 🧪

A powerful ComfyUI custom node that integrates Qwen2.5-VL and Qwen3-VL vision-language models with multi-image support. Process multiple images simultaneously with advanced AI capabilities for image understanding, comparison, and analysis.

✨ Features

• 🖼️ Multi-Image Support: Process multiple images in a single inference
• 🤖 Latest Models: Support for Qwen2.5-VL and Qwen3-VL series
• 💾 Flexible Quantization: 4-bit, 8-bit, and FP16 options for different VRAM requirements
• ⚡ Model Caching: Keep models loaded in VRAM for faster subsequent runs
• 🎛️ Two Node Variants: Standard and Advanced nodes for different use cases
• 🔧 Full Parameter Control: Temperature, top_p, top_k, beam search, and more (Advanced node)
• 🎯 GPU Optimized: Flash Attention 2 support and efficient memory management

📦 Installation

Method 1: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager
2. Search for "QwenVL Multi-Image"
3. Click Install

Method 2: Manual Installation

1. Navigate to your ComfyUI custom nodes directory:

cd ComfyUI/custom_nodes/

2. Clone this repository:

git clone https://github.com/YOUR_USERNAME/ComfyUI-QwenVL-MultiImage.git

3. Install dependencies:

cd ComfyUI-QwenVL-MultiImage
pip install -r requirements.txt

4. Restart ComfyUI

🎯 Supported Models

Qwen3-VL Series (Latest)

Model	Size	HuggingFace Link
Qwen3-VL-4B-Instruct	4B	Download
Qwen3-VL-8B-Instruct	8B	Download
Qwen3-VL-32B-Instruct	32B	Download
Qwen3-VL-8B-Thinking	8B	Download
Qwen3-VL-32B-Thinking	32B	Download
Qwen3-VL-8B-Instruct-FP8	8B	Download
Qwen3-VL-32B-Instruct-FP8	32B	Download

Qwen2.5-VL Series

Model	Size	HuggingFace Link
Qwen2.5-VL-2B-Instruct	2B	Download
Qwen2.5-VL-3B-Instruct	3B	Download
Qwen2.5-VL-7B-Instruct	7B	Download
Qwen2.5-VL-72B-Instruct	72B	Download

Models will be automatically downloaded from HuggingFace on first use.

📖 Usage

Basic Usage (Standard Node)

1. Add the "🧪 QwenVL Multi-Image" node from the 🧪AILab/QwenVL category
2. Connect one or more image sources to the node:
   • images: Main image input (can be a batch)
   • images_batch_2: Optional second batch
   • images_batch_3: Optional third batch
3. Select your desired model from the dropdown
4. Write your prompts:
   • system_prompt: System instructions for the AI
   • user_prompt: Your question or task
5. Configure quantization and other settings
6. Run the workflow

Advanced Usage (Advanced Node)

Use the "🧪 QwenVL Multi-Image (Advanced)" node for fine-grained control:

• temperature: Controls randomness (0.1-2.0)
• top_p: Nucleus sampling threshold (0.0-1.0)
• top_k: Top-k sampling (1-100)
• num_beams: Beam search width (1-10)
• repetition_penalty: Penalize repeated tokens (1.0-2.0)
• device: Force specific device (auto/cuda/cpu)

⚙️ Parameters

Common Parameters

Parameter	Description	Default	Range
images	Main image input (supports batches)	Required	-
model_name	Qwen-VL model to use	Qwen3-VL-4B-Instruct	See model list
system_prompt	System instructions	"You are a helpful assistant."	Any text
user_prompt	Your question/task	"Describe these images..."	Any text
quantization	Memory optimization mode	8-bit (Balanced)	FP16/8-bit/4-bit
max_tokens	Maximum output length	1024	64-4096
keep_model_loaded	Cache model in VRAM	True	True/False
seed	Random seed	1	1 - 2^32-1

Advanced Parameters (Advanced Node Only)

Parameter	Description	Default	Range
temperature	Sampling randomness	0.7	0.1-2.0
top_p	Nucleus sampling	0.9	0.0-1.0
top_k	Top-k sampling	50	1-100
repetition_penalty	Penalize repeats	1.1	1.0-2.0
num_beams	Beam search width	1	1-10
device	Device selection	auto	auto/cuda/cpu

💡 Quantization Guide

Mode	Precision	VRAM Usage	Speed	Quality	Recommended For
None (FP16)	16-bit	High	Fastest	Best	16GB+ VRAM
8-bit (Balanced)	8-bit	Medium	Fast	Very Good	8GB+ VRAM
4-bit (VRAM-friendly)	4-bit	Low	Slower	Good	<8GB VRAM

Note: FP8 models (pre-quantized) automatically use optimized precision and ignore the quantization setting.

🎨 Example Use Cases

1. Multi-Image Comparison

Compare multiple product photos, analyze differences, or identify similarities.

Prompt: "Compare these images and describe the key differences between them."

2. Sequential Analysis

Analyze a sequence of images showing a process or timeline.

Prompt: "Describe the progression shown across these images."

3. Multi-View Understanding

Process multiple angles or views of the same object.

Prompt: "Based on these different views, provide a comprehensive description of the object."

4. Batch Description

Generate captions or descriptions for multiple images simultaneously.

Prompt: "Provide a detailed caption for each image."

🔧 Troubleshooting

Out of Memory Errors

1. Switch to a smaller model (e.g., 2B or 3B)
2. Enable more aggressive quantization (4-bit)
3. Reduce max_tokens
4. Process fewer images at once
5. Set keep_model_loaded to False

Slow Performance

1. Use FP8 models on supported hardware (RTX 40 series)
2. Enable keep_model_loaded for repeated inference
3. Use FP16 quantization on high-VRAM systems
4. Ensure CUDA is properly installed

Model Download Issues

Models are downloaded from HuggingFace on first use. If you encounter issues:

1. Check your internet connection
2. Verify HuggingFace is accessible
3. Manually download models to your HuggingFace cache directory
4. Check available disk space (models can be 2-150GB)

Import Errors

If you get import errors after installation:

cd ComfyUI/custom_nodes/ComfyUI-QwenVL-MultiImage
pip install -r requirements.txt --upgrade

🎯 Tips & Best Practices

Model Selection

• For most users: Start with Qwen3-VL-4B-Instruct (balanced performance)
• Low VRAM (<8GB): Use Qwen2.5-VL-2B-Instruct with 4-bit quantization
• Best quality: Use Qwen3-VL-32B-Instruct with FP16 (requires 24GB+ VRAM)
• RTX 40 series: Use FP8 variants for optimal speed

Memory Management

• Enable keep_model_loaded if running multiple inferences
• Disable it if you need to switch between different models
• Use 8-bit quantization as a good balance between quality and VRAM

Prompt Engineering

• Be specific about what you want from multiple images
• Use system prompts to set the context and behavior
• For comparisons, explicitly ask to compare or contrast
• Number your images in the prompt if order matters

Performance

• First load is always slower (downloading/caching)
• Subsequent runs with cached models are much faster
• Batch multiple images when possible instead of separate inferences

🛠️ Development

Requirements

• Python 3.8+
• PyTorch 2.0+
• CUDA 11.8+ (for GPU acceleration)
• 8GB+ VRAM recommended (4GB minimum with quantization)

Building from Source

git clone https://github.com/YOUR_USERNAME/ComfyUI-QwenVL-MultiImage.git
cd ComfyUI-QwenVL-MultiImage
pip install -r requirements.txt

🙏 Credits

• Qwen Team (Alibaba Cloud): For developing the Qwen-VL models
• ComfyUI: For the excellent node-based interface
• 1038lab/ComfyUI-QwenVL: For the original QwenVL node implementation that inspired this project

📜 License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📮 Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section
2. Search existing Issues
3. Open a new issue with detailed information

⭐ Star History

If you find this project useful, please consider giving it a star!

---

Note: Replace YOUR_USERNAME with your actual GitHub username before publishing.