QwenVL for ComfyUI

ComfyUI-QwenVL 自定义节点集成了阿里云强大的 Qwen-VL 系列视觉语言模型（LVLM），包括最新的 Qwen3-VL 和 Qwen2.5-VL，同时还支持 GGUF 后端以及纯文本的 Qwen3 模型。这一先进的节点能够在您的 ComfyUI 工作流中实现无缝的多模态 AI 功能，从而高效地进行文本生成、图像理解与视频分析。

📰 新闻与更新

• 2026年2月8日：v2.1.1 修复了与 Transformers 4.x 和 5.x 的兼容性问题 [更新]

• 2026年2月5日：v2.1.0 增加了 SageAttention 支持，并针对每种 GPU 架构进行了优化；改进了 FP8 模型的处理方式，实现了注意力机制模式的自动选择。[更新]

  • SageAttention 支持：全新的注意力机制模式，配备针对不同 GPU 架构优化的内核（SM80、SM89、SM90、SM120）
  • FP8 处理改进：更好地支持预量化 FP8 模型，并可自动回退到 SDPA
  • 智能注意力选择：自动模式会依次尝试 Sage → Flash → SDPA，以获得最佳性能
  • 进度条：为模型加载和生成阶段添加了 ComfyUI 进度条
  • 更优的内存管理：在切换注意力模式或量化设置时，改进了缓存清理机制

• 2025年12月22日：v2.0.0 新增了 GGUF 支持节点和提示增强节点。[更新]

[!重要]
在运行 GGUF 节点之前，请先安装 llama-cpp-python 安装说明

• 2025年11月10日：v1.1.0 对运行时进行了全面重构，加入了注意力模式选择器、flash-attn 自动检测功能、更智能的缓存管理以及在两个节点中均可使用的量化和 torch.compile 控制选项。[更新]
• 2025年10月31日：v1.0.4 支持自定义模型 [更新]
• 2025年10月22日：v1.0.3 更新了模型列表 [更新]
• 2025年10月17日：v1.0.0 初始发布
  • 支持 Qwen3-VL 和 Qwen2.5-VL 系列模型。
  • 可从 Hugging Face 自动下载模型。
  • 支持即时量化（4-bit、8-bit、FP16）。
  • 提供预设和自定义提示系统，使用灵活便捷。
  • 包含标准节点和高级节点，适合各水平用户。
  • 针对硬件特性提供保护措施，确保 FP8 模型的兼容性。
  • 支持图像和视频（帧序列）输入。
  • 提供“保持模型加载”选项，以提升连续运行时的性能。
  • 提供 种子参数，便于生成结果的重复性。

✨ 功能特性

• 标准与高级节点：包含一个用于快速使用的简单 QwenVL 节点，以及一个具备精细生成控制能力的 QwenVL（高级）节点。
• 提示增强器：专为 HF 和 GGUF 后端设计的纯文本提示增强器。
• 预设与自定义提示：您可以从便捷的预设提示列表中选择，也可以自行编写提示，以实现完全控制。
• 多模型支持：轻松切换不同的官方 Qwen-VL 模型。
• 自动模型下载：首次使用时会自动下载所需模型。
• 智能量化：通过 4-bit、8-bit 和 FP16 选项，在显存占用与性能之间取得平衡。
• 硬件感知：自动检测 GPU 性能，并防止使用不兼容模型时出现错误（例如 FP8）。
• 可重复生成：使用种子参数可获得一致的输出。
• 内存管理：提供“保持模型加载”选项，将模型常驻显存以加快处理速度。
• 图像与视频支持：既可接受单张图像输入，也可接受视频帧序列作为输入。
• 健壮的错误处理：针对硬件或内存问题提供清晰的错误信息。
• 简洁的控制台输出：运行过程中仅显示最少且富有信息量的日志。
• SageAttention 支持：基于 GPU 优化的注意力机制，配备针对不同架构的专用内核（Ampere、Ada、Hopper、Blackwell）。
• 进度条：在模型加载和生成阶段提供可视化反馈。
• 智能缓存管理：在切换注意力模式或量化设置时自动释放显存。

🚀 安装步骤

1. 将本仓库克隆到您的 ComfyUI/custom_nodes 目录下：

   cd ComfyUI/custom_nodes  
   git clone https://github.com/1038lab/ComfyUI-QwenVL.git
   

2. 安装所需的依赖项：

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

3. 重启 ComfyUI。

可选：SageAttention 支持

为了在支持的 GPU 上获得最佳性能，您需要安装 SageAttention：

pip install sageattention

🧭 节点概览

Transformers（HF）节点

• QwenVL：快速的视觉语言推理（图像/视频 + 预设/自定义提示）。
• QwenVL（高级）：可全面控制采样、设备及性能设置。
• QwenVL 提示增强器：纯文本提示增强（同时支持 Qwen3 文本模型和 QwenVL 模型的文本模式）。

GGUF（llama.cpp）节点

• QwenVL（GGUF）：基于 GGUF 的视觉语言推理。
• QwenVL（GGUF 高级）：扩展的 GGUF 控制选项（上下文长度、GPU 层数等）。
• QwenVL 提示增强器（GGUF）：GGUF 版本的纯文本提示增强。

🧩 GGUF 节点（llama.cpp 后端）

本仓库包含由 llama-cpp-python 提供支持的 GGUF 节点（与基于 Transformers 的节点分开）。

• 节点：QwenVL（GGUF）、QwenVL（GGUF 高级）、QwenVL 提示增强器（GGUF）
• 模型文件夹（默认路径）：ComfyUI/models/llm/GGUF/（可通过 gguf_models.json 进行配置）
• 视觉要求：需安装具备视觉功能的 llama-cpp-python 轮子，该轮子应提供 Qwen3VLChatHandler 或 Qwen25VLChatHandler
  请参阅 docs/LLAMA_CPP_PYTHON_VISION_INSTALL.md

🗂️ 配置文件

• HF 模型：hf_models.json
  • hf_vl_models：视觉语言模型（供 QwenVL 节点使用）。
  • hf_text_models：纯文本模型（供提示增强器使用）。
• GGUF 模型：gguf_models.json
• 系统提示：AILab_System_Prompts.json（包含 VL 提示及提示增强风格）。

📥 下载模型

首次使用时，模型将自动下载。如果您希望手动下载，请将其放置在 ComfyUI/models/LLM/Qwen-VL/ 目录下。

HF 视觉模型（Qwen-VL）

模型	链接
Qwen3-VL-2B-Instruct	下载
Qwen3-VL-2B-Thinking	下载
Qwen3-VL-2B-Instruct-FP8	下载
Qwen3-VL-2B-Thinking-FP8	下载
Qwen3-VL-4B-Instruct	下载
Qwen3-VL-4B-Thinking	下载
Qwen3-VL-4B-Instruct-FP8	下载
Qwen3-VL-4B-Thinking-FP8	下载
Qwen3-VL-8B-Instruct	下载
Qwen3-VL-8B-Thinking	下载
Qwen3-VL-8B-Instruct-FP8	下载
Qwen3-VL-8B-Thinking-FP8	下载
Qwen3-VL-32B-Instruct	下载
Qwen3-VL-32B-Thinking	下载
Qwen3-VL-32B-Instruct-FP8	下载
Qwen3-VL-32B-Thinking-FP8	下载
Qwen2.5-VL-3B-Instruct	下载
Qwen2.5-VL-7B-Instruct	下载

HF 文本模型（Qwen3）

模型	链接
Qwen3-0.6B	下载
Qwen3-4B-Instruct-2507	下载
qwen3-4b-Z-Image-Engineer	下载

GGUF 模型（手动下载）

组别	模型	仓库	替代仓库	模型文件	MMProj
Qwen 文本（GGUF）	Qwen3-4B-GGUF	Qwen/Qwen3-4B-GGUF		Qwen3-4B-Q4_K_M.gguf, Qwen3-4B-Q5_0.gguf, Qwen3-4B-Q5_K_M.gguf, Qwen3-4B-Q6_K.gguf, Qwen3-4B-Q8_0.gguf
Qwen-VL（GGUF）	Qwen3-VL-4B-Instruct-GGUF	Qwen/Qwen3-VL-4B-Instruct-GGUF		Qwen3VL-4B-Instruct-F16.gguf, Qwen3VL-4B-Instruct-Q4_K_M.gguf, Qwen3VL-4B-Instruct-Q8_0.gguf	mmproj-Qwen3VL-4B-Instruct-F16.gguf
Qwen-VL（GGUF）	Qwen3-VL-8B-Instruct-GGUF	Qwen/Qwen3-VL-8B-Instruct-GGUF		Qwen3VL-8B-Instruct-F16.gguf, Qwen3VL-8B-Instruct-Q4_K_M.gguf, Qwen3VL-8B-Instruct-Q8_0.gguf	mmproj-Qwen3VL-8B-Instruct-F16.gguf
Qwen-VL（GGUF）	Qwen3-VL-4B-Thinking-GGUF	Qwen/Qwen3-VL-4B-Thinking-GGUF		Qwen3VL-4B-Thinking-F16.gguf, Qwen3VL-4B-Thinking-Q4_K_M.gguf, Qwen3VL-4B-Thinking-Q8_0.gguf	mmproj-Qwen3VL-4B-Thinking-F16.gguf
Qwen-VL（GGUF）	Qwen3-VL-8B-Thinking-GGUF	Qwen/Qwen3-VL-8B-Thinking-GGUF		Qwen3VL-8B-Thinking-F16.gguf, Qwen3VL-8B-Thinking-Q4_K_M.gguf, Qwen3VL-8B-Thinking-Q8_0.gguf	mmproj-Qwen3VL-8B-Thinking-F16.gguf

📖 使用方法

基本用法

1. 从 🧪AILab/QwenVL 类别中添加 “QwenVL” 节点。
2. 选择您想要使用的 model_name。
3. 将图像或视频（图像序列）源连接到节点。
4. 使用预设或自定义字段编写您的提示。
5. 运行工作流。

高级用法

为了获得更多的控制，可以使用 “QwenVL (Advanced)” 节点。这使您可以访问详细的生成参数，如温度、top_p、束搜索和设备选择。

⚙️ 参数

参数	描述	默认值	范围	节点
model_name	要使用的 Qwen-VL 模型。	Qwen3-VL-4B-Instruct	-	标准版与高级版
quantization	即时量化。对于预先量化的模型（例如 FP8）则忽略此选项。	8 位（平衡）	4 位、8 位、无	标准版与高级版
attention_mode	注意力机制：自动（Sage→Flash→SDPA）、sage、flash_attention_2、sdpa	自动	自动、sage、flash_attention_2、sdpa	标准版与高级版
preset_prompt	常见任务的预定义提示选择。	“描述一下这个……”	任意文本	标准版与高级版
custom_prompt	如果提供，则会覆盖预设提示。		任意文本	标准版与高级版
max_tokens	最大生成新标记数。	1024	64-2048	标准版与高级版
keep_model_loaded	将模型保留在 VRAM 中，以便后续运行更快。	真	真/假	标准版与高级版
seed	用于可重复结果的种子。	1	1 - 2^64-1	标准版与高级版
temperature	控制随机性。数值越高，越具创造性。（当 num_beams 为 1 时使用）。	0.6	0.1-1.0	仅高级版
top_p	核采样阈值。（当 num_beams 为 1 时使用）。	0.9	0.0-1.0	仅高级版
num_beams	束搜索的束数。大于 1 会禁用温度/top_p 采样。	1	1-10	仅高级版
repetition_penalty	不鼓励重复标记。	1.2	0.0-2.0	仅高级版
frame_count	从视频输入中采样的帧数。	16	1-64	仅高级版
device	覆盖自动设备选择。	自动	自动、cuda、cpu	仅高级版
use_torch_compile	启用 torch.compile 优化以加快推理速度。	假	真/假	仅高级版

💡 量化选项

模式	精度	内存占用	速度	质量	推荐场景
无（FP16）	16 位浮点	高	最快	最佳	高 VRAM 显卡（16GB+）
8 位（平衡）	8 位整数	中	快	非常好	平衡性能（8GB+）
4 位（节省 VRAM）	4 位整数	低	较慢*	良好	低 VRAM 显卡（<8GB）

* 关于 4 位速度的说明：4 位量化显著减少了 VRAM 的使用，但由于实时反量化带来的计算开销，在某些系统上可能会导致性能下降。

🎯 注意力模式指南

模式	描述	适用场景
auto	自动选择最佳可用模式：Sage → Flash → SDPA	大多数用户（推荐）
sage	基于 GPU 优化内核的 SageAttention	在现代 GPU（RTX 40 系列、Hopper、Blackwell）上速度更快
flash_attention_2	Flash Attention 2	当 Sage 不可用时提供速度优势
sdpa	PyTorch SDPA（默认）	兼容性好，适用于 FP8 和 BitsAndBytes 模型

注意：无论选择哪种模式，FP8 模型和 BitsAndBytes 量化都会自动使用 SDPA。

🤔 设置建议

设置	建议
模型选择	对于大多数用户来说，Qwen3-VL-4B-Instruct 是一个很好的起点。如果你有 40 系列 GPU，可以尝试 -FP8 版本以获得更好的性能。
内存模式	如果计划多次运行该节点，建议保持 keep_model_loaded 开启（True），以获得最佳性能。仅在其他节点内存不足时才关闭它。
量化	首先使用默认的 8 位量化。如果显存充足（>16GB），可切换到无量化（FP16），以获得最快的速度和最佳质量。若显存紧张，则使用 4 位量化。
注意力模式	使用“auto”模式以获得最佳性能。在支持的 GPU 上，SageAttention 能提供最快的推理速度。
性能	第一次加载特定量化级别的模型时，可能会比较慢。但后续运行（保持 keep_model_loaded 开启）会快得多。

🧠 关于模型

该节点使用由阿里云通义实验室团队开发的 Qwen-VL 系列模型。这些是功能强大的开源大型视觉语言模型（LVLM），旨在理解和处理视觉与文本信息，非常适合用于详细描述图像和视频等任务。

🗺️ 路线图

✅ 已完成（v2.1.0）

• ✅ 支持基于每 GPU 架构优化的 SageAttention
• ✅ 改进了 FP8 模型的处理，自动回退到 SDPA
• ✅ 智能注意力选择（auto：Sage → Flash → SDPA）
• ✅ 模型加载和生成进度条
• ✅ 更好的内存管理和缓存清理

✅ 已完成（v2.0.0）

• ✅ 通过 llama.cpp 后端支持 GGUF 模型
• ✅ 文本优化增强节点

✅ 已完成（v1.0.0）

• ✅ 支持 Qwen3-VL 和 Qwen2.5-VL 模型。
• ✅ 自动下载和管理模型。
• ✅ 实时进行 4 位、8 位和 FP16 量化。
• ✅ 对 FP8 模型进行硬件兼容性检查。
• ✅ 支持图像和视频（帧序列）输入。

🙏 致谢

• Qwen 团队：阿里云 —— 感谢他们开发并开源了强大的 Qwen-VL 模型。
• ComfyUI：comfyanonymous —— 感谢其强大且可扩展的 ComfyUI 平台。
• llama-cpp-python：JamePeng/llama-cpp-python —— 提供了 GGUF 节点使用的具有视觉支持的 GGUF 后端。
• SageAttention：SageAttention —— 提供了高效的注意力实现及 GPU 优化的内核。
• ComfyUI 集成：1038lab —— 该自定义节点的开发者。

📜 许可证

本仓库的代码采用 GPL-3.0 许可证 发布。

ComfyUI-QwenVL 快速上手指南

ComfyUI-QwenVL 是专为 ComfyUI 设计的自定义节点，集成了阿里云强大的 Qwen-VL 系列视觉语言模型（包括最新的 Qwen3-VL、Qwen2.5-VL），支持图像理解、视频分析及文本生成。该工具提供标准与高级两种节点模式，并支持 GGUF 量化后端，能够灵活适配不同显存配置。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统: Windows, Linux 或 macOS
• Python: 建议 Python 3.10 或更高版本
• ComfyUI: 已安装并可正常运行的最新稳定版 ComfyUI
• GPU: 推荐 NVIDIA GPU (支持 CUDA)，显存建议 8GB 以上（根据模型大小而定，小模型如 2B/4B 可在较低显存运行）
• 依赖库:
  • transformers (自动安装)
  • torch (需匹配你的 CUDA 版本)
  • 可选 (高性能): 若使用 SageAttention 加速，需额外安装 sageattention
  • 可选 (GGUF 模式): 若使用 GGUF 节点，需预先安装支持 Vision 的 llama-cpp-python

安装步骤

1. 克隆仓库

进入 ComfyUI 的 custom_nodes 目录并克隆本插件：

cd ComfyUI/custom_nodes
git clone https://github.com/1038lab/ComfyUI-QwenVL.git

国内加速提示：如果 GitHub 连接缓慢，可使用镜像源： git clone https://ghp.ci/https://github.com/1038lab/ComfyUI-QwenVL.git

2. 安装依赖

进入插件目录并安装所需 Python 包：

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

国内加速提示：建议使用国内镜像源加速 pip 安装： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. (可选) 安装高性能组件

• SageAttention 加速 (推荐 NVIDIA Ampere/Ada/Hopper 架构用户):

  pip install sageattention
  

• GGUF 支持 (如需使用 GGUF 节点): 请参考项目文档 docs/LLAMA_CPP_PYTHON_VISION_INSTALL.md 安装带有 Qwen3VLChatHandler 支持的 llama-cpp-python 版本。

4. 重启 ComfyUI

安装完成后，完全重启 ComfyUI 以加载新节点。

基本使用

以下是使用 标准节点 进行图像描述的最简工作流：

1. 添加节点: 在 ComfyUI 右键菜单中，找到 🧪AILab/QwenVL 分类，选择 QwenVL 节点添加到画布。

2. 连接输入:

   • 将 图像加载器 (Load Image) 的输出连接到 QwenVL 节点的 image 输入端。
   • (可选) 支持视频帧序列输入。

3. 配置参数:

   • model_name: 选择要使用的模型（例如 Qwen3-VL-4B-Instruct）。首次运行时会自动从 Hugging Face 下载模型。
   • preset_prompt: 选择预设提示词（如 "Describe this image in detail"），或在 custom_prompt 中输入自定义指令。
   • quantization: 根据显存选择量化等级（默认 8-bit，显存紧张可选 4-bit）。

4. 运行工作流: 点击 "Queue Prompt" 运行。节点将输出模型生成的文本描述。

进阶提示

• 模型存储: 自动下载的模型默认存储在 ComfyUI/models/LLM/Qwen-VL/。如需手动下载，可从 Hugging Face 获取后放入该目录。
• 保持模型加载: 启用 keep_model_loaded 选项可避免重复加载模型，显著提升连续生成的速度。
• 高级控制: 如需调整 Temperature、Top_P 或指定 Attention 模式，请使用 QwenVL (Advanced) 节点。