技术教程
很多人部署 ComfyUI，卡住的并不是模型下载，而是最后那一步：模型明明在目录里，节点也能拖出来，运行时却接连报错。
上次的文章是在云端部署Qwen-Image-2.1模式，经1周的本地摸索，我将本地低成本生图流程分享出来，在这次我在 Windows + RTX 3080 上部署 Qwen-Image-2.1 Q4，先后遇到了模型架构识别失败、文本编码器走错分支、4096/12288 维度冲突，以及“补丁已经改了，程序却像什么都没发生”的问题。
最后跑通的路线是：
Windows ComfyUI portable + ComfyUI-GGUF + 本地兼容补丁 + 两份 Q4 GGUF + BF16 VAE
本文记录的是一套实际重启、实际出图验证过的配置。它适合复现，也适合排错。但要先说清楚：下面的结论只针对本文列出的实际文件和版本，并不是对所有同名 GGUF 的通用承诺。
先说结论：这次到底跑通了什么
图片
本次已经验证成功的是：文生图，768×768，单张，8 步采样。
没有验证图生图，也没有验证参考图编辑。当前环境没有配置参考图编辑所需的视觉/mmproj 权重。不要因为工作流里出现了 images 输入，就以为这套模型已经具备完整的视觉编辑能力。
本次没有使用 WSL、stable-diffusion.cpp、Ollama，也没有继续编译 sd-cli。Ubuntu 中原来装过的 CUDA Toolkit 和 CMake 可以保留，但它们不是这条 Windows ComfyUI 路线的启动条件。
我的测试环境
| 项目 | 实际配置 | |---|---| | 主显卡 | NVIDIA GeForce RTX 3080，20GB 显存 | | 第二显卡 | NVIDIA T400，2GB，不参与本次生成 | | 内存 | 约 80GB | | ComfyUI | 0.42.0 | | 内嵌 Python | 3.13.12 | | PyTorch | 2.11.0+cu130 | | ComfyUI-GGUF | 基础提交 6ea2651e7df66d7585f6ffee804b20e92fb38b8a，另有本地补丁 | | 已验证配置 | 768×768、单张、8 步 |
本文使用的是本机报告的 20GB RTX 3080。常见的 10GB 版本不能直接照搬显存预期。显卡编号也以启动日志为准，本机通过 --cuda-device 0 选择显卡。
PowerShell 检查命令：
nvidia-smi
Set-Location 'C:\Users\Vincent\Project\AI\ComfyUI_windows_portable'
.\python_embeded\python.exe -s -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
注意目录名是便携包自带的 python_embeded。不要改拼写，也不要拿系统 Python 替代它。
模型文件：名字会骗人，架构不会
便携包根目录：
C:\Users\Vincent\Project\AI\ComfyUI_windows_portable
实际目录：
ComfyUI_windows_portable\
├─ python_embeded\
└─ ComfyUI\
├─ main.py
├─ custom_nodes\ComfyUI-GGUF\
├─ models\
│ ├─ unet\Qwen-Image-2.1-Turbo-AD-Q4_K.gguf
│ ├─ text_encoders\Qwen-Image-2.1-Turbo-Uncensored-AD-Q4_K.gguf
│ └─ vae\qwen_image_2.1_vae_bf16.safetensors
└─ output\
| 文件 | 实际用途 | 文件大小 | |---|---|---:| | Qwen-Image-2.1-Turbo-AD-Q4_K.gguf | 去噪模型，由 Unet Loader (GGUF) 加载 | 4,201,694,944 字节 | | Qwen-Image-2.1-Turbo-Uncensored-AD-Q4_K.gguf | 本机识别为 Qwen3-VL 文本编码器，由 CLIPLoader (GGUF) 加载 | 5,287,517,120 字节 | | qwen_image_2.1_vae_bf16.safetensors | 将潜变量解码成图片，由 VAELoader 加载 | 675,509,688 字节 |
最值得强调的一点是：文件名不能证明模型用途。
第二个文件的名字看起来像图像模型，但本机实际读取到的 GGUF 架构是 qwen3vl。如果只看文件名、只看下拉框，后面很容易把文本编码器塞进错误的加载路径。
文件字节数可以帮助判断下载是否明显不完整，但它不是加密校验值。更不能把别的模型改个名字，就套用这份配置。
如果模型在 WSL 里，怎么复制到 Windows
资源管理器地址栏可以尝试：
\\wsl.localhost\Ubuntu\home\vincent\AI\qwen-image-2.1\models
发行版名称不确定时，先执行：
wsl -l -v
从 PowerShell 进入 Ubuntu：
wsl -d Ubuntu -u vincent
进入后提示符变成 vincent@...，此时已经是 Linux shell。不要再次输入 wsl -d Ubuntu，也不要根据提示安装同名的 wsl 软件包。输入 exit 返回 PowerShell。
Ubuntu 中的 Windows C 盘对应 /mnt/c：
mkdir -p /home/vincent/AI/qwen-image-2.1/models
cp '/mnt/c/Users/Vincent/Downloads/Qwen-Image-2.1-Turbo-AD-Q4_K.gguf' /home/vincent/AI/qwen-image-2.1/models/
带有 :Zone.Identifier 后缀的旁文件不是模型，不要放进加载列表。
真正的难点：插件不是“装上就兼容”
这次实际遇到两个独立问题。
问题一：去噪模型架构识别失败
图片
原插件报：
Unknown model architecture!
原因是插件没有按这份权重的真实张量键识别 qwen_image21 架构。
修复内容：
- 在
tools/convert.py中，根据真实张量键识别qwen_image21； - 在
loader.py的图像架构列表中加入该架构。
问题二：文本编码器走进了错误分支
文本 GGUF 没有用于自动识别的视觉张量，原加载路径把它当成普通 Qwen3/Flux 文本编码器处理。日志出现：
Flux2TEModel_
随后输出维度是 12288，但去噪模型需要 4096，最终报维度不匹配。
修复方式是在 nodes.py 中读取 GGUF 声明的 qwen3vl 架构，并在单编码器、qwen_image 类型的加载请求下，选择 ComfyUI 原生的 QwenImage21 文本编码器，同时校验隐藏维度为 4096。
这次补丁只修改了插件的三个 Python 文件，没有重新量化模型，也没有改动 GGUF 权重。
补丁怎么保存，怎么重新应用
本机备份目录：
C:\Users\Vincent\Project\AI\local_llm\gguf-backup-20261025
其中包含修改前的 loader.py、nodes.py、convert.py，以及 qwen-image21-compat.patch。
注意：备份目录里的原文件是“修改前”的版本。把它们覆盖回插件目录后，兼容能力也会一起被覆盖掉。
本机已经应用过补丁，日常不需要重复执行。恢复到基础版本后，先检查：
$pluginDir = 'C:\Users\Vincent\Project\AI\ComfyUI_windows_portable\ComfyUI\custom_nodes\ComfyUI-GGUF'
$compatPatch = 'C:\Users\Vincent\Project\AI\local_llm\gguf-backup-20261025\qwen-image21-compat.patch'
git -C $pluginDir status --short
git -C $pluginDir apply --check $compatPatch
只有 --check 成功后，才执行：
git -C $pluginDir apply $compatPatch
如果检查失败，不要马上强制覆盖。可能是补丁已经应用，也可能是插件新版代码发生了变化。可以反向检查：
git -C $pluginDir apply --reverse --check $compatPatch
最容易被忽略的一步：重启后端，不是刷新网页
修改 Python 插件以后，必须退出 ComfyUI 后端进程，再重新启动。
新建工作流、重新导入 JSON、刷新浏览器，都不会重新加载已经运行中的 Python 插件代码。
这次最后一个错误就来自这里：补丁在 20:02–20:08 写入，但旧进程从 18:52 一直没退出，所以它当然还在执行旧代码。看起来像“补丁没用”，其实是程序根本没读到补丁。
正确操作：
- 保存工作流。
- 回到启动 ComfyUI 的终端，按
Ctrl+C，等待后端退出。 - 在 Windows PowerShell 启动：
Set-Location 'C:\Users\Vincent\Project\AI\ComfyUI_windows_portable'
.\python_embeded\python.exe -s .\ComfyUI\main.py --windows-standalone-build --cuda-device 0
- 等待终端出现：
To see the GUI go to: http://127.0.0.1:8188
- 打开或刷新 ComfyUI，运行期间不要关闭终端窗口。
如果 8188 端口被占用，先查看，不要结束所有 Python 进程：
Get-NetTCPConnection -LocalPort 8188 -State Listen | Select-Object LocalAddress,LocalPort,OwningProcess
Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'python.exe' -and $_.CommandLine -like '*ComfyUI*main.py*' } | Select-Object ProcessId,CreationDate,CommandLine
已验证工作流怎么配
图片
将工作流 JSON 拖入 ComfyUI 画布，然后逐项确认加载节点使用的是前面列出的真实文件。
| 节点 | 关键设置 | |---|---| | Unet Loader (GGUF) | Qwen-Image-2.1-Turbo-AD-Q4_K.gguf | | CLIPLoader (GGUF) | Qwen-Image-2.1-Turbo-Uncensored-AD-Q4_K.gguf，type = qwen_image | | VAELoader | qwen_image_2.1_vae_bf16.safetensors | | TextEncodeQwenImage21 | 分辨率 768；负面提示词为空；images 和 vae 不连接 | | KSamplerSelect | euler | | SamplerCustom | add_noise 开启；seed 24092026；fixed；CFG 1.0 | | ManualSigmas | 使用下方完整序列 | | SaveImage | 文件名前缀 Qwen-Image-2.1-Turbo-Q4 |
1.0,0.978453,0.95418,0.926626,0.89508,0.845148,0.704534,0.414568,0.0
9 个 sigma 值定义了 8 个采样区间，也就是本次的 8 步采样。它是本机验证过的配置，不要把它当成所有 Turbo 模型的通用参数。
测试提示词：
一只可爱的橘色小猫坐在雨后的上海老弄堂窗台上，窗外是温暖的霓虹灯和湿润石板路，电影感摄影，自然柔光，细腻毛发，真实质感，无文字，无水印
必须使用插件提供的 CLIPLoader (GGUF)，不是普通 CLIPLoader。模型出现在下拉框里，只能说明路径被扫描到了，不能证明加载架构正确。
节点连接关系
| 输出 | 输入 | |---|---| | Unet Loader (GGUF) → MODEL | SamplerCustom → model | | CLIPLoader (GGUF) → CLIP | TextEncodeQwenImage21 → clip | | TextEncodeQwenImage21 → positive | SamplerCustom → positive | | TextEncodeQwenImage21 → negative | SamplerCustom → negative | | TextEncodeQwenImage21 → latent | SamplerCustom → latent_image | | KSamplerSelect → SAMPLER | SamplerCustom → sampler | | ManualSigmas → SIGMAS | SamplerCustom → sigmas | | SamplerCustom → output | VAEDecode → samples | | VAELoader → VAE | VAEDecode → vae | | VAEDecode → IMAGE | SaveImage → images |
关键点只有一个，但很容易接错：直接使用 TextEncodeQwenImage21 的 latent 输出。
本次没有使用早期示例里的 EmptyLatentImage，也没有使用普通 KSampler 的“20 steps + simple”配置。旧教程的节点不要拆一半混进来。
运行时看什么，才算真的成功
首次运行会加载和处理模型，通常比缓存命中后的运行慢。不要只看显存占用，也不要看到模型加载完成就宣布成功。
本次成功日志：
Loading Qwen3-VL GGUF with native QwenImage21 text encoder (text-to-image)
Requested to load QwenImage21TEModel_
... compatibility mode 'sd.cpp' [arch:qwen_image21]
Requested to load QwenImage21
... 8/8 ...
Prompt executed in 53.36 seconds
其中 compatibility mode 'sd.cpp' 在这套配置里表示兼容加载路径，不是失败提示。日志里出现 model_type FLUX 也不能单独证明模型错误。真正需要警惕的是修复前的 Flux2TEModel_，以及 12288/4096 维度冲突。
完整成功标准是：采样完成、VAE 解码完成、SaveImage 保存成功，而且图片内容正常。
输出目录：
C:\Users\Vincent\Project\AI\ComfyUI_windows_portable\ComfyUI\output
测试图片是 Qwen-Q4-compat-test_00001_.png。日常工作流使用 Qwen-Image-2.1-Turbo-Q4 前缀，文件名不同不代表工作流异常。
本次 53.36 秒包含一次加载和生成，不能当作固定速度。之后重启原服务再次测试，也确认成功。
常见错误，别只盯着最后一行
| 现象 | 更可能的原因 | 处理方式 | |---|---|---| | Unknown model architecture! | 插件没有识别 QwenImage21，或仍在运行旧代码 | 检查补丁，完整退出后端再重启 | | 导入新 workflow 后仍报相同错误 | 导入不会重载 Python 插件 | 重启 ComfyUI 后端 | | CLIP 下拉框没有 GGUF | 用了普通 CLIPLoader，或模型目录不对 | 使用 CLIPLoader (GGUF)，检查 text_encoders | | expected ...4096，got ...12288 | 文本编码器走了普通 Qwen3/Flux 路径 | 检查 nodes.py 补丁及 QwenImage21TEModel_ 日志 | | 找不到 TextEncodeQwenImage21 | 核心版本、导入状态或插件加载异常 | 对照已验证版本，检查启动日志 | | clip missing: visual.* | 当前 GGUF 没有视觉权重 | 保持纯文本工作流，不要直接做参考图编辑 | | CUDA out of memory | 显存不足，或其他程序占用显存 | 确认 RTX 3080，关闭其他 GPU 任务，回到 768 测试 | | Git fetch 操作超时 | 更新时远程请求失败 | 处理网络后重新更新，并核对更新结果 | | Ubuntu 提示 wsl: command not found | 在 Linux shell 里执行了 Windows 命令 | exit 回到 PowerShell |
visual.* 缺失在本次纯文本测试中可以解释，但不等于所有缺失权重都可以忽略。遇到新的权重缺失、张量形状错误或其他异常，仍要单独判断。
日常使用，先别急着改参数
跑通以后，流程很简单：
启动 ComfyUI → 打开工作流 → 修改提示词 → 运行 → 到 output 目录取图。
建议先保留 768、CFG 1、Euler 和固定 sigma 序列。想换构图，先只改 seed；想提高分辨率，也一次只改一个参数，同时观察耗时、显存和画面质量。1024 或更高分辨率不属于本次验证范围。
至少备份：
- 已验证的 JSON 工作流和本教程；
gguf-backup-20261025整个目录；- 三份权重，以及每份权重的真实用途；
- 成功图片和对应提示词。
以后升级 ComfyUI 或 ComfyUI-GGUF，先用同一个提示词做回归测试。图生图和参考图编辑则要另行检查视觉权重、mmproj 和节点支持，不要直接把图片接进当前工作流，然后把报错归咎于模型质量。
最后一句
这次部署最重要的经验，不是“RTX 3080 能不能跑 Qwen-Image-2.1 Q4”，而是：
模型文件、插件架构、文本编码器和运行进程，必须同时处在同一套兼容状态。
少看一个版本号，少重启一次后端，或者只根据文件名判断模型用途，都可能让你在错误方向上折腾几个小时。
先按已验证配置跑通，再逐项改动。ComfyUI 的排错，很多时候不是靠“再试一次”，而是靠把每一次变化都控制住。
Qwen-Image-2.1 Q4已经折腾完了目前计划在本地部署minimaxi H3 + Qwen-Image-2.1 Q4 本地测试通过后将会将教程公开，敬请期待
