Qwen-Image-2.1 Uncensored · ComfyUI 部署套件

Qwen-Image-2.1 Uncensored (GGUF) — ComfyUI deployment kit 工作流 / 节点补丁 / Q8_0 修复工具 / 踩坑记录，一站式。 ComfyUI workflow · GGUF · text-to-image · image editing · 8 GB VRAM · low-VRAM · quantization fix

_{实测直出 · 512×512 / 20 步 / cfg 1.0 · RTX 5060 Laptop 8 GB · 32.3 秒 · 未经后期}

---

⚠️ 重要：本仓库不含模型权重

模型权重合计 32.74 GB，远超 GitHub 的单文件 100 MB 硬限制（Release 上限 2 GB、Git LFS 免费额度仅 1 GB），技术上无法托管。

本仓库只提供权重之外的整套配套，权重请从 Hugging Face 原仓库获取 → 模型下载

---

📖 这是什么

在 ComfyUI 上跑 Qwen-Image-2.1 Uncensored GGUF 的完整配套。原模型发布包开箱即用会撞上三个坑，本仓库把坑和补丁一并解决：

坑 3 是发布方的量化缺陷：64 个 RMSNorm 权重（128 维）被压成 Q8_0 的 136 字节。本仓库提供一个 14 秒、无损、零额外下载的修复器。

---

🖥 环境要求

⚠️ 内存比显存更容易成为瓶颈。加载阶段 TE（8.9 GB staged）+ DiT（7 GB Q8_0 → bf16 ≈ 13 GB）会同时驻留，内存不足会导致进程被杀且日志无 traceback。

---

📁 文件结构

qwen-image2.1-uncensored-comfyui/
├── README.md                                  # 本文件
├── NOTICE.md                                  # 来源、许可与免责声明
├── LICENSE                                    # MIT
├── .gitignore                                 # 排除 *.gguf / *.safetensors 等权重
│
├── assets/
│   └── sample_t2i_512x512.png                 # 实测出图（8 GB 显卡直出）
│
├── workflows/                                 # 可直接载入 ComfyUI 的工作流
│   ├── qwen_image_2.1_t2i_gguf.json           # 文生图（GGUF）
│   └── qwen_image_2.1_multi_image_edit.json   # 多图片编辑（参考图输入）
│
├── patches/                                   # ComfyUI-GGUF 节点补丁
│   ├── qwen_image21_arch.patch                # 架构识别（tools/convert.py）
│   ├── qwen_image21_loader.patch              # IMG_ARCH_LIST（loader.py）
│   └── README.md                              # 补丁应用与多副本处理说明
│
├── tools/                                     # 模型修复与校验工具
│   ├── gguf_1d_repair.py                      # 【推荐】通用修复器 scan / fix / verify
│   ├── fix_q8_0_gguf.py                       # 专用修复脚本（本模型一键版）
│   └── verify_gguf_rewrite.py                 # 逐张量字节级无损校验
│
├── scripts/                                   # 权重获取
│   ├── download_models.py                     # 断点续传下载（HF 主站 → hf-mirror 回退）
│   └── download_models.bat                    # 一键双击版（Windows）
│
└── docs/
    ├── FILE_STRUCTURE.md                      # 模型目录落位详解（含路径表）
    ├── TROUBLESHOOTING.md                     # 三个坑的完整排查过程
    └── VERIFICATION.md                        # 实测数据与无损校验报告

---

🚀 快速开始

第 0 步 · 准备 ComfyUI

需要一个 ≥ 0.37.0 的 ComfyUI（Windows 便携版 / 源码版均可）。低于此版本没有 TextEncodeQwenImage21 等原生节点，工作流会满屏红节点。

第 1 步 · 安装 GGUF 节点并打补丁

# 进入 ComfyUI 的 custom_nodes 目录
cd <ComfyUI>/custom_nodes

# 克隆 GGUF 节点（二选一，leejet 分支已原生支持 qwen_image21，可跳过补丁）
git clone https://github.com/city96/ComfyUI-GGUF
# git clone https://github.com/leejet/ComfyUI-GGUF

如果用的是 city96 原版，需要打上本仓库的补丁：

cd ComfyUI-GGUF
patch -p1 < <本仓库>/patches/qwen_image21_arch.patch
patch -p1 < <本仓库>/patches/qwen_image21_loader.patch

🚨 如果你的环境里存在多份 ComfyUI-GGUF 副本（例如同时被 extra_model_paths.yaml 外挂注册），ComfyUI 会并行加载且注册顺序不确定 —— 必须每一份都打补丁，否则改了也不生效。详见 patches/README.md。

第 2 步 · 下载权重

python scripts/download_models.py --dir <ComfyUI>/models
# 或 Windows 直接双击 scripts/download_models.bat

下载后按 docs/FILE_STRUCTURE.md 核对落位。

第 3 步 · 修复 Q8_0 量化缺陷 ⭐

这一步不能跳，否则采样时必然报 [136] vs [128]：

# 用 ComfyUI 便携版自带的 python（内含 gguf + numpy）
<ComfyUI>/../python_embeded/python.exe tools/gguf_1d_repair.py scan   <models>/diffusion_models/qwen-image-2.1-Q8_0.gguf
<ComfyUI>/../python_embeded/python.exe tools/gguf_1d_repair.py fix    <models>/diffusion_models/qwen-image-2.1-Q8_0.gguf <models>/diffusion_models/qwen-image-2.1-Q8_0_fixed.gguf --arch qwen_image21
<ComfyUI>/../python_embeded/python.exe tools/gguf_1d_repair.py verify <models>/diffusion_models/qwen-image-2.1-Q8_0.gguf <models>/diffusion_models/qwen-image-2.1-Q8_0_fixed.gguf

预期：scan 报 65 个待修张量 → fix 约 14 秒完成、体积仅 +31.5 KB → verify 输出 === PASS ===。

不想折腾也可以用 Q6_K / Q5_K_M / Q4_K_M 档位（这些档位 1D 张量通常正确保留 F32），把工作流里 UnetLoaderGGUF 的下拉换掉即可。

第 4 步 · 载入工作流出图

把 workflows/*.json 拖进 ComfyUI 窗口。检查三个加载器指向的文件名与实际落位逐字一致：

首次加载会比较慢（要反量化 7 GB GGUF 并转 bf16）。

---

⚙️ 参数建议

基于 RTX 5060 Laptop 8 GB 显存的实测：

• 分辨率必须是 32 的倍数；8 GB 卡建议从 512×512 起步验证链路。
• Qwen-Image 系列使用 cfg = 1.0（TextEncodeQwenImage21 的负面词留空即可）。
• 内存紧张时可先降低分辨率验证链路，再逐步上调。
• 若日志出现 loaded partially; ... MB offloaded，说明已触发 CPU offload，速度会明显下降但可跑完。

---

🧪 实测数据

完整报告见 docs/VERIFICATION.md。

---

🔧 已知问题速查

详见 docs/TROUBLESHOOTING.md。

---

📦 模型下载

# 国内网络建议走镜像
python scripts/download_models.py --dir <ComfyUI>/models --mirror

8 GB 显存请优先用 int8_convrot 文本编码器（8.71 GB），不要用 bf16（16.33 GB）。

---

📄 许可与来源

• 本仓库内容（工作流、脚本、文档、补丁）：MIT。该许可仅覆盖本仓库原创内容；模型权重、TE/VAE 重打包件、ComfyUI-GGUF 节点均为第三方资产，各有其上游许可，详见 NOTICE.md
• 模型权重：版权归原作者，未包含在本仓库中，请遵循上游仓库的许可条款
• Qwen-Image-2.1 基座：Qwen/Qwen-Image-2.1
• GGUF 量化版：abenzerps/Qwen-Image-2.1-Uncensored-GGUF
• ComfyUI-GGUF 节点：city96/ComfyUI-GGUF / leejet/ComfyUI-GGUF

免责声明：Uncensored 指上游移除了内容过滤，可生成更宽泛的题材。使用者需自行确保生成内容符合所在地法律法规及使用平台的政策。本仓库仅提供技术配套，不对生成内容承担责任，与上游模型作者及 ComfyUI 官方均无隶属关系。

---

_{整理自一次真实的 8 GB 显存部署实战 · 2026-09}