QwenImage-WebUI · 图像工坊

别再对着 ComfyUI 搓节点了：专为 Qwen-Image 2.1 打造的现代生图与图像编辑工作台。
无需折腾 ComfyUI 环境，丢给 AI 助手全自动部署；大白话对话直接出图，无需苦憋提示词；告别蜘蛛网连线，看片选图更舒适。

---

✨ 核心亮点

阿里开源的 Qwen-Image 2.1 是目前最惊艳的 7B 视觉开源大模型之一：原生支持 文生图与复杂指令编辑、支持最多 10 张参考图、具备顶尖的 中英文文字排版能力 与 原生 RGBA 透明背景直出。

但面对 ComfyUI 满屏蜘蛛网般的节点图、繁琐的环境依赖与断流报错，很多创作者和开发者望而却步。QwenImage-WebUI 就是为了解决这一痛点而打造的解决方案：

1. 🚀 完全零折腾 ComfyUI：下载后直接丢给 AI，全自动搞定
   • 仓库内置 setup-comfyui Agent Skill，支持 Cursor、Claude Code、Antigravity、Windsurf、Aider 等主流 AI 编程助手。
   • 对 AI 说一句部署指令，AI 会自动调用诊断脚本，核验版本并从 ModelScope（魔搭社区）千兆高速通道 下载 INT8 优化三件套（~17GB，无需外网/梯子，防放错目录），一键拉起全套服务。
2. 💬 AI 助手对话即出图：告别苦憋提示词，大白话直接出片
   • 内置 qwen-image Agent Skill。AI 助手直接成为你的专属生图美工。
   • 写代码或写文档时，在聊天框直接说：“生成一张 16:9 赛博朋克雨夜封面”、“把 cat.jpg 里的猫戴上一顶小巫师帽，其他保持不变”。
   • AI 自动转化为结构化自然语言、自动计算 32 像素倍数对齐、自动注入局部修改保留条款，成图直接保存到项目目录。
3. 🎨 高颜值暗房工作台：告别节点盘丝洞，沉浸式看图选图
   • 文生图 / 图像编辑合一：底部撰写坞空着就是文生图，随手拖入参考图自动变编辑模式，没有多余的模式切换按钮。
   • @ 图片引用交互：提示词里敲一个 @，直接用缩略图胶囊指定哪张图是修改目标，提交时自动映射占位符。
   • 原图前后实时对比滑块：编辑生成的图片，内置双层对比滑块，拖动中线即可直观比对改动细节。
   • 真·透明底输出识别：后台真实逐像素统计 Alpha 通道，真正透空的素材自动打标分类，贴纸、Logo、立绘一键筛选导出。
4. ⚡ 极致轻量与纯粹设计
   • WebUI 采用纯原生 HTML5/CSS3/Vanilla JS，秒开无白屏。
   • 服务层仅依赖 Python 3.10+ 标准库，零额外 pip 依赖，极速启动。
   • 画廊缩略图按需 WebP 缓存与强缓存机制，上千张图片瀑布流翻阅丝滑不卡顿。

---

🚀 极速上手

方式 A：Agent 全自动托管（推荐，最省心）

克隆本项目到本地后，在支持 Agent 的编程助手（Cursor / Claude Code / Antigravity 等）对话框中直接输入：

@setup-comfyui 帮我检查并配置好 ComfyUI 和 Qwen-Image 2.1 模型，并一键启动服务

AI 助手会自动执行依赖诊断、魔搭千兆极速下载权重（约 17.4GB）并拉起服务，完成后访问浏览器 http://127.0.0.1:8907 即可！

---

方式 B：手动快速安装与启动

1. 启动 ComfyUI 后端

确保你已经安装了 ComfyUI ≥ v0.37.0（官方原生内置核心节点 TextEncodeQwenImage21 与 QwenImage21Cache，无需安装任何第三方插件）：

# 进入 ComfyUI 根目录启动
python3 main.py --listen 127.0.0.1 --port 8188

2. 下载模型三件套（必须放对目录）

你可以使用本项目内置脚本从 魔搭社区 (ModelScope) 千兆直连高速下载：

# 安装可选下载依赖
pip install modelscope

# 执行一键下载 (INT8 推荐版，适合 16G/24G 显存)
python3 .agents/skills/setup-comfyui/scripts/download_models.py \
  --comfy-dir /path/to/ComfyUI \
  --source modelscope \
  --precision int8

模型存放目录对照表：

模型类别	目标存放目录	推荐文件名 (INT8)	大小	全精度文件名 (BF16)	大小
主扩散模型	ComfyUI/models/diffusion_models/	qwen_image_2.1_int8_convrot.safetensors	7.3 GB	qwen_image_2.1_bf16.safetensors	14.0 GB
文本编码器	ComfyUI/models/text_encoders/	qwen3vl_8b_int8_convrot.safetensors	9.4 GB	qwen3vl_8b_bf16.safetensors	17.5 GB
VAE	ComfyUI/models/vae/	qwen_image_2.1_vae_bf16.safetensors	0.7 GB	qwen_image_2.1_vae_bf16.safetensors	0.7 GB

3. 启动 QwenImage-WebUI

克隆本项目并直接启动（Python 标准库零依赖）：

git clone https://github.com/bailutingyu/QwenImage-WebUI-OpenSource.git
cd QwenImage-WebUI-OpenSource

# 直接启动
python3 run.py

打开浏览器访问：http://127.0.0.1:8907 开启生图！

---

🤖 AI 助手与命令行生图（CLI）

除了打开网页，你还可以直接在终端或让 AI Agent 调用内置脚本快速出图：

# 1. 基础文生图 (16:9 高清)
python3 .agents/skills/qwen-image/scripts/generate.py \
  -p "A close-up cinematic photo of a cup of artisan cappuccino on a rustic wooden table, morning soft light" \
  -a "16:9" \
  -o "outputs/coffee.png"

# 2. 图像局部精准编辑 (原图比例保持不变)
python3 .agents/skills/qwen-image/scripts/generate.py \
  -r "outputs/cat.jpg" \
  -a "orig" \
  -p "In <image1>, add a tiny red wizard hat on the cat's head. Keep lighting, pose, and background completely unchanged." \
  -o "outputs/magic_cat.png"

# 3. 生成原生透明背景素材 (Alpha 通道)
python3 .agents/skills/qwen-image/scripts/generate.py \
  --alpha \
  -p "A 3D glossy isometric red magic potion bottle with swirling blue liquid, golden stopper, game asset icon" \
  -o "outputs/potion.png"

# 4. 原图自适应等比 2K 放大
python3 .agents/skills/qwen-image/scripts/generate.py \
  -r "draft.png" \
  -a "orig" \
  --scale "2k" \
  -p "High-definition enhanced version of <image1>, rich texture details, preserve composition completely." \
  -o "outputs/upscaled.png"

---

⚙️ 配置说明

项目根目录下 config.json 包含基础运行参数：

{
  "comfyui_url": "http://127.0.0.1:8188",
  "port": 8907,
  "bind": "127.0.0.1",
  "models": {
    "unet": "qwen_image_2.1_int8_convrot.safetensors",
    "clip": "qwen3vl_8b_int8_convrot.safetensors",
    "vae": "qwen_image_2.1_vae_bf16.safetensors"
  }
}

• 若 ComfyUI 运行在局域网另一台独立显卡服务器上，将 comfyui_url 修改为对应 IP 与端口即可。
• 也可以通过环境变量覆盖：export QWEN_IMAGE_URL="http://127.0.0.1:8907"。

---

🔌 REST API 参考

接口	方法	说明
/api/meta	GET	查询 ComfyUI 连通状态、三件套是否就绪、可选模型列表
/api/generate	POST	提交异步生图/修图任务（支持 width, height, aspect, steps, cfg, seed, refs）
/api/status	GET	轮询当前运行进度、队列位次与最新生成结果
/api/upload	POST	上传参考图到 ComfyUI 输入目录并生成缩略图
/api/gallery	GET	获取画廊历史列表（支持根据索引版本与 ETag 进行 gzip 增量缓存）
/api/thumb	GET	请求成图或参考图的高性能 WebP 缩略图
/api/free	POST	请求 ComfyUI 卸载模型并清空显存/内存缓存

---

💡 官方参数实用建议

• CFG 引导值：Qwen-Image 2.1 推荐保持 cfg = 1.0（官方默认路径）。负向提示词只在 cfg > 1.0 时产生过滤效果。
• 步数推荐：官方管线推荐 25~40 步 Euler 采样。默认 25 步已能在速度与成片质量上取得极佳平衡。
• 编辑分辨率：图像编辑时，尺寸代表参考图的总像素预算（默认 0 代表沿用原图尺寸，仅自动对齐 32 整数倍）。
• 显存与量化选择：
  • 16GB ~ 24GB 显卡（如 RTX 4080 / 4090）：强烈推荐 INT8 优化组合（约 17.4GB），生成迅速且不易 OOM；
  • 24GB+ 显卡或内存充裕机器：可在网页右上角环境面板随时切换为全量 BF16 组合（约 32.2GB）。

---

🛠️ 生产常驻与服务部署

如需将本 WebUI 在 Linux 或 WSL2 服务器中作为 systemd 守护进程常驻：

1. 参考 scripts/qwenimage-webui.service.example 创建服务单元文件并放入 /etc/systemd/system/；
2. 执行 sudo systemctl daemon-reload && sudo systemctl enable --now qwenimage-webui；
3. 参考 scripts/deploy.sh.example 编写个人自动化同步部署脚本。

---

📄 开源许可证与致谢

• 本项目基于 Apache License 2.0 开源。
• 核心模型基于阿里巴巴 Qwen-Image 2.1 系列研究成果。
• 推理后端基于强大的开源生态 ComfyUI。