comfyui-zimage-vl

ComfyUI 插件，为 Z-Image-Turbo 提供 视觉语言模型（VLM）条件编码能力。通过 Qwen3-VL 对文本 + 参考图像进行联合编码，生成多模态条件向量，驱动 Z-Image 生成与参考图像概念/风格一致的图像。

基于 D-OPSD 论文中的 Teacher 条件编码逻辑实现。

功能

• Load CLIP with Visual：加载 Qwen3-4B 语言模型 + Qwen3-VL 视觉编码器，合并为一个完整的 VLM
• CLIP Text Image Encode：通过 VLM 对文本 + 可选参考图像进行编码，输出 KSampler 可直接使用的 positive/negative conditioning

安装

# 将插件目录软链接到 ComfyUI custom_nodes 目录
ln -s /your/path/to/comfyui-zimage-vl /path/to/ComfyUI_data/custom_nodes/comfyui-zimage-vl

前置条件

需要准备以下模型文件，放置在 ComfyUI 的 text_encoders 目录下：

| 文件 | 说明 | |------|------| | qwen_3_4b.safetensors | Qwen3-4B 语言模型权重 | | qwen_3_vl_visual.safetensors | Qwen3-VL 视觉编码器权重（需从 Qwen3-VL-4B-Instruct 提取，见下方说明） |

提取视觉编码器权重

从 Qwen3-VL-4B-Instruct 模型中提取 model.visual.* 前缀的权重：

import json
from safetensors.torch import save_file, load_file
from pathlib import Path

vlm_path = Path("/path/to/Qwen3-VL-4B-Instruct")
with open(vlm_path / "model.safetensors.index.json") as f:
    index = json.load(f)

visual_sd = {}
for k, shard_name in index["weight_map"].items():
    if "visual" in k.lower():
        shard = load_file(str(vlm_path / shard_name), device="cpu")
        visual_sd[k] = shard[k]

save_file(visual_sd, "qwen_3_vl_visual.safetensors")

使用方法

基础工作流

Load CLIP with Visual
  ├── lm_name: qwen_3_4b.safetensors
  └── visual_name: qwen_3_vl_visual.safetensors
        │
        ▼ (vl_model)
CLIP Text Image Encode
  ├── text: 你的文本 prompt
  ├── image1: [可选] 参考图像 1
  ├── image1_mask: [可选] 参考图像 1 的掩码
  ├── image2: [可选] 参考图像 2
  ├── image2_mask: [可选] 参考图像 2 的掩码
  ├── image3: [可选] 参考图像 3
  └── image3_mask: [可选] 参考图像 3 的掩码
        │
        ├── positive → KSampler (positive conditioning)
        └── negative → KSampler (negative conditioning)

节点说明

Load CLIP with Visual

从 safetensors 加载完整的 VLM 模型（视觉编码器 + 语言模型）。

输入：

| 参数 | 类型 | 说明 | |------|------|------| | lm_name | Combo | Qwen3-4B 语言模型 safetensors 文件 | | visual_name | Combo | Qwen3-VL 视觉编码器 safetensors 文件 |

输出：

| 参数 | 类型 | 说明 | |------|------|------| | vl_model | AnyType | VLM 模型包装，传递给 CLIP Text Image Encode 节点 |

CLIP Text Image Encode

通过 VLM 对文本和可选图像进行编码，生成 conditioning。

输入：

| 参数 | 类型 | 说明 | |------|------|------| | vl_model | AnyType | 来自 Load CLIP with Visual 的输出 | | text | String | 文本 prompt，支持动态 prompt | | image1 | Image (可选) | 参考图像 1。不提供时使用纯文本编码 | | image1_mask | Mask (可选) | 参考图像 1 的掩码，掩码区域（值为 0）在 VLM 编码前被置零 | | image2 | Image (可选) | 参考图像 2 | | image2_mask | Mask (可选) | 参考图像 2 的掩码 | | image3 | Image (可选) | 参考图像 3 | | image3_mask | Mask (可选) | 参考图像 3 的掩码 |

输出：

| 参数 | 类型 | 说明 | |------|------|------| | positive | Conditioning | 正向条件向量，连接 KSampler | | negative | Conditioning | 负向条件（空文本编码），连接 KSampler |

编码细节

• 使用 VLM 倒数第二层 hidden state 作为条件嵌入
• 自动移除 padding token，仅保留有效序列
• min_pixels: 512×512, max_pixels: 768×768
• 编码逻辑与 D-OPSD 训练代码中 teacher 条件编码保持一致

典型应用场景

1. 风格迁移：提供参考图风格 + 文本描述，生成新场景中的同风格图像
2. 概念保持：将训练集中的人物/物体概念泛化到全新场景
3. 参考引导生成：基于参考图像的内容结构，按文本描述生成变体

项目结构

comfyui-zimage-vl/
├── __init__.py          # 插件入口，注册 ComfyUI 节点
├── nodes.py             # 节点定义（Load CLIP with Visual + CLIP Text Image Encode）
├── vlm_model.py         # ZImageVL 模型包装与权重加载
├── vlm_encoder.py       # VLM 编码逻辑，生成 conditioning embeddings
├── resources/           # Qwen3-VL 配置文件（tokenizer、config 等）
│   ├── config.json
│   ├── preprocessor_config.json
│   ├── tokenizer_config.json
│   ├── tokenizer.json
│   ├── vocab.json
│   ├── merges.txt
│   └── chat_template.json
└── README.md

注意事项

• VLM 模型较大（~9GB），建议显存 >= 24GB
• 首次加载模型需要一定时间，后续推理速度受 VLM 编码步骤限制
• 插件使用 ComfyUI 的 text_encoders 目录查找模型文件