# Qwen-Image-2.1 在 ComfyUI 的部署与实测报告

- **部署日期**：2026-09-21
- **目标机器**：GPU 机 `192.168.31.31`（RTX 5060 Ti 16GB / 32GB RAM / Ubuntu 24.04）
- **参考来源**：<https://blog.comfy.org/p/qwen-image-21-in-comfyui-open-weight>（ComfyUI 官方博客，2026-09-20）
- **权重来源**：HuggingFace `Comfy-Org/Qwen-Image-2.1`（本网走 `hf-mirror.com` 镜像）
- **结论**：✅ 部署完成并通过 5 项实测（文生图 / 图像编辑 / RGBA 透明 / 原生 2K / 预热速度）

---

## 一、模型与能力速览

Qwen-Image-2.1 是阿里 Qwen 团队 2026-09 发布的 7B 开源图像模型（MMDiT 架构），ComfyUI 原生支持：

| 能力 | 说明 |
|---|---|
| **RGBA 输出** | 采样器直接产出 4 通道带 alpha 的图，抠图/图标/商品图无需再走分割模型 |
| **原生 2K** | 2048×2048 直接生成（非放大） |
| **最多 10 张参考图** | `TextEncodeQwenImage21` 的 images 槽可自动增长到 10+，按 VAE latent 拼进序列 |
| **生成 + 编辑同权重** | 一个 checkpoint 兼顾 t2i 与 i2i 编辑 |
| **7B 体量** | 消费级显卡可跑（本机 16GB 实测见第四节） |

---

## 二、部署内容

### 2.1 ComfyUI 升级

原版本 **不支持** Qwen-Image-2.1（代码里搜不到任何 2.1 字样），必须先升级：

| 项 | 升级前 | 升级后 |
|---|---|---|
| 版本 | `v0.35.0-42-gb2da2b42`（2026-09-16） | **`v0.37.0-4-gc194dd00`（2026-09-20）** |
| 新增代码 | — | `comfy/text_encoders/qwen_image21.py`、`comfy/ldm/qwen_image21/`、`comfy/storage.py` |
| 新增节点 | — | `TextEncodeQwenImage21`、`QwenImage21Cache`、`EmptyQwenImageLayeredLatentImage` |

启动参数保持原有稳定档（GPU 机）：`--lowvram --force-fp16 --reserve-vram 1.0 --fast-disk --cache-lru 2 --disable-pinned-memory --preview-method none --enable-manager`，端口 8189。

### 2.2 模型文件（已就位）

下载方式：GPU 机 `aria2c -x8 -s8` 直连 `hf-mirror.com`，实测 **~45 MiB/s**，45 GiB 约 16 分钟下完。

| 目录 | 文件 | 大小 | 用途 |
|---|---|---|---|
| `models/diffusion_models/` | `qwen_image_2.1_int8_convrot.safetensors` | 6.76 GiB | **主干（官方模板默认）** |
| `models/text_encoders/` | `qwen3vl_8b_int8_convrot.safetensors` | 8.71 GiB | **文本编码器（官方模板默认）** |
| `models/vae/` | `qwen_image_2.1_vae_bf16.safetensors` | 0.63 GiB | **VAE** |
| `models/text_encoders/` | `qwen3vl_8b_w4a8.safetensors` | 5.88 GiB | 备选：更省显存（未实测） |
| `models/text_encoders/` | `qwen3.5_9b_qwen_image_2.1_pe_t2i.int8_convrot.safetensors` | 8.82 GiB | ⚠️ 仓库里有，但**官方模板与代码均未引用**，未使用 |
| `models/text_encoders/` | `qwen3.5_9b_qwen_image_2.1_pe_i2i.int8_convrot.safetensors` | 8.82 GiB | 同上 |

- 未下载 bf16 主干（13.25 GiB）：16GB 卡上 int8_convrot 更合适；如要极限画质可后补。
- 机器上原有的 `qwen3vl_8b_fp8_scaled.safetensors`（10.6 GiB）也是可选文本编码器档位。
- 磁盘：`/` 已用 949G/1.2T（**88%**），本次新增约 45 GiB。

### 2.3 工作流（已装入 GUI 工作流浏览器）

位置（GPU 机）：`ComfyUI/user/default/workflows/Qwen-Image-2.1/`

- `image_qwen_image_2_1_t2i.json` — 文生图
- `image_qwen_image_2_1_image_edit.json` — 图像编辑（最多 10 张参考图）
- `image_qwen_image_2_1_background_removal.json` — 背景移除（同样用上述三个模型，无需额外下载）

同时 pip 包 `comfyui-workflow-templates` 已升到 0.11.66，**Templates 面板里也能直接搜到 Qwen-Image-2.1**。

### 2.4 关键接口（自己拼 API 工作流时用）

```
UNETLoader  : qwen_image_2.1_int8_convrot.safetensors | weight_dtype=default
CLIPLoader  : qwen3vl_8b_int8_convrot.safetensors     | type=qwen_image   ← 注意仍是 "qwen_image"（2.0/2.1 共用），由权重自动分流
VAELoader   : qwen_image_2.1_vae_bf16.safetensors
TextEncodeQwenImage21 : clip / prompt / negative_prompt / resolution(默认1024) / images.image_1..10 / vae(可选)
                        → 输出 positive(0) / negative(1) / latent(2)   ← latent = 按 image_1 尺寸的空 latent
KSampler    : euler + simple, steps 25, cfg 1.0, denoise 1.0
```

⚠️ **官方模板是 subgraph 结构**，`/prompt` API **不能直接吃模板 JSON**，需要展平——本报告附带展平后的脚本 `qwen21_run.py`。

---

## 三、实测结果

统一参数：25 步 / euler + simple / cfg 1.0 / 固定 seed / int8_convrot 权重。

| 用例 | 分辨率 | 耗时 | 每步 | 显存峰值 | 结果 |
|---|---|---|---|---|---|
| 文生图（首跑，含模型加载） | 1024×1024 | 63.1 s | 2.5 s | 15220 MiB | ✅ 玻璃锦鲤茶壶，细节/光影优秀 |
| 文生图（预热后） | 1024×1024 | **18.0 s** | **0.72 s** | 15286 MiB | ✅ 同机连续跑，权重已缓存 |
| 图像编辑（人物换装） | 896×1152 | 69.1 s | 2.8 s | 15254 MiB | ✅ 官方模板素材：人物/姿态/背景保持，仅换牛仔衬衫 |
| RGBA 透明 | 1024×1024 | 18.0 s | 0.72 s | 15286 MiB | ✅ 真 4 通道，alpha 实测 0–255 |
| 原生 2K 直出 | 2048×2048 | 129.1 s | 5.2 s | 15294 MiB | ✅ 16GB 卡可跑（余量极小） |

- 显存峰值稳定在 **15.2–15.3 GiB / 15.9 GiB**，`--lowvram` 是必须的；2K 能跑但没有余量。
- 首次运行慢是因为加载 8.7GiB 文本编码器 + 6.8GiB 主干；**预热后 1024² 只要 18 秒**（0.72 s/step）。
- 四张验证图见本目录 `qwen21_*.png`，并已入相册（family = `Qwen-Image-2.1`）。

### 复现命令（GPU 机）

```bash
# 文生图
/home/zyw/ComfyUI/venv/bin/python /home/zyw/qwen21_run.py t2i /home/zyw/prompt_t2i.txt qwen21_t2i 25 1024 1024 424242
# 原生 2K
/home/zyw/ComfyUI/venv/bin/python /home/zyw/qwen21_run.py t2i /home/zyw/prompt_t2i.txt qwen21_2k 25 2048 2048 555
# 图像编辑（图片需已在 ComfyUI/input/ 下）
/home/zyw/ComfyUI/venv/bin/python /home/zyw/qwen21_run.py edit /home/zyw/prompt_edit.txt qwen21_edit 25 1024 1024 777 \
    portrait_model_denim.png clothing_light_blue_denim_shirt.png
```

---

## 四、踩坑记录

1. **`pkill -f` 会杀掉自己**：远端命令行里含 `qwen21_run.py` 字样，`pkill -f qwen21_run.py` 匹配到当前 `bash -c` 进程，整条命令自杀（与备忘里 `llmster` 同一个坑）。→ 改用 `pgrep -af "qwen21_[r]un.py"` 这类括号写法。
2. **新依赖 `comfy-aimdo==0.5.5` 缺失会直接起不来**：报 `ModuleNotFoundError: No module named 'comfy_aimdo.storage'`。本次是 `pip install -r requirements.txt` 因另一个包解析失败整体中止导致漏装，单独 `pip install -U comfy-aimdo==0.5.5` 解决。
3. **清华 pip 镜像滞后**：`comfyui-workflow-templates-media-assets-02==0.1.3` 在清华源找不到（`from versions: none`）→ 用 `--index-url https://pypi.org/simple` 直连装成功（pypi.org 本机可达，HTTP 200）。
4. **本机 `comfy/ops.py` 有不可丢的本地修复**：2026-09-09 为 Blackwell 禁掉 cuDNN SDPA（`enable_cudnn_sdp(False)`），升级前必须备份补丁。注意 `git apply --3way` 会**同时写入 index**，此时 `git checkout --` 无效，必须 `git restore --source=HEAD --staged --worktree comfy/ops.py` 才能让 merge 过去；升级后补丁重放成功。
5. **下载满速时 git 会握手失败**：aria2c 跑满带宽时 `git pull` 报 `GnuTLS recv error (-110)`。→ 先 `pkill -STOP aria2c`，拉完再 `pkill -CONT aria2c`。
6. **官方模板不能直接喂 API**：模板节点是 subgraph（UUID 类型），`/prompt` 只认扁平图 → 已提供 `qwen21_run.py` 展平版。
7. **显存吃紧**：int8 档峰值 15.2–15.3 GiB。若后续上更大分辨率或多参考图 OOM，优先换 `qwen3vl_8b_w4a8` 文本编码器（省 2.8 GiB）。
8. **未使用的 `pe_*` 文本编码器占了 17.6 GiB 磁盘**（当前无模板/代码引用）。若要回收磁盘可删，但不影响本部署运行。

---

## 五、如何使用

- **网页**：<http://192.168.31.31:8189> → 工作流浏览器 → `Qwen-Image-2.1/`，或在 Templates 面板搜 “Qwen-Image-2.1”。
- **透明图写法**（官方提示词模板）：
  > `This is an RGBA format image with transparency. [主体描述]. The image has an alpha channel and a transparent background.`
  保存为 PNG 即可保留 alpha。
- **2K 写法**：分辨率设为 2048×2048（原生），步数官方建议 40–50（模板默认 25 也能用）。
- **启停 ComfyUI**（GPU 机）：`bash ~/restart_comfy.sh`。
- ⚠️ **与 LLM 服务互斥显存**：跑图前先 `bash ~/stop-ridge.sh`（或 `lms unload --all`），否则 27B 常驻会直接 OOM。

---

## 六、附件

| 文件 | 说明 |
|---|---|
| `qwen21_run.py` | 展平后的 API 实测脚本（t2i / edit，含显存采样与计时） |
| `prompt_t2i.txt` / `prompt_rgba.txt` / `prompt_edit.txt` | 本次实测用提示词 |
| `image_qwen_image_2_1_*.json` | 三个官方工作流模板备份 |
| `qwen21_t2i_test_00001_.png` | 文生图 1024² |
| `qwen21_edit_test_00001_.png` | 图像编辑（换装） |
| `qwen21_rgba_00001_.png` | RGBA 透明输出 |
| `qwen21_2k_00001_.png` | 原生 2K 2048² |