ComfyUI Z-Image-Turbo 安装教程
ComfyUI 用户可安装 Z-Image-Turbo 作为文生图引擎，解决 Flux 等默认模型对中文提示词理解弱、画面中文字渲染差的问题。需下载三个模型文件（文本编码器、扩散模型、VAE）并更新 ComfyUI 至支持该节点的版本。建议使用 ModelScope 国内下载，显存建议 ≥16GB，磁盘需 25GB+。注意与 Qwen-Image 区分，不可混装。
面向 已安装好 ComfyUI 环境（GPU、Python、能浏览器或 API 访问）的机器。
为什么要装（本项目）
ComfyUI 官方示例 / 默认模板 里文生图常用 Flux Schnell 等模型：速度快、生态成熟，但对 中文不友好——
| 问题 | Flux Schnell 等常见默认模型 | 物料封面需求 |
|---|---|---|
| 中文提示词 | 理解偏弱，易生成与歌名意境无关的泛用西方式场景 | 需要贴合中文歌名、歌词意象 的画面 |
| 画面里写中文 | 假字、乱码、笔画错误很常见 | 封面常要带准确的中文歌名 |
| 国风 / 亚洲人像 | 并非专长 | 歌曲封面常见东方审美、人像场景 |
因此我们增加 Z-Image-Turbo（通义造相蒸馏版）作为 ComfyUI 自建封面的可选引擎：中英文提示词理解更好，画面内中英文字渲染明显优于 Flux，更适合中文歌曲的专辑封面、海报。
仍建议：歌名等 必须 100% 正确的文字 用本软件 程序叠字（宋体居中标题），不要完全依赖模型「画出来」——Z-Image 是 减轻 中文问题，不是排版级 guarantees。
技术说明： Z-Image-Turbo 用于 文生图（约 8 步）。与 Flux 不是同一套工作流：需 三个模型文件 + 专用节点，不能只在原 Flux JSON 里改 checkpoint 名。
下文路径均相对于 ComfyUI 根目录（记为 ComfyUI/）。请把命令里的路径换成你的实际安装位置。
| 项目 | 路径 |
|---|---|
| ComfyUI 根目录 | ComfyUI/ |
| 文本编码器 | ComfyUI/models/text_encoders/qwen_3_4b.safetensors |
| 扩散模型 | ComfyUI/models/diffusion_models/z_image_turbo_bf16.safetensors |
| VAE | ComfyUI/models/vae/ae.safetensors |
| 输出图片 | ComfyUI/output/ |
0. 前置条件
- 已安装 ComfyUI，并能用浏览器或 API 正常访问
- NVIDIA GPU，建议 ≥ 16GB 显存（三套模型合计约 21GB 磁盘；推理时 16GB 可跑 1024 级）
- 磁盘空余约 25GB+（含下载缓存）
- Python 3.10+，CUDA 与 PyTorch 与 ComfyUI 一致
- 无需额外
custom_nodes（节点随 ComfyUI 主程序更新，见 §1）
1. 更新 ComfyUI（必须）
Z-Image-Turbo 节点在较新的 ComfyUI 中提供；版本过旧加载工作流会报 节点缺失。
cd ComfyUI
git pull
pip3 install -r requirements.txt
更新后 完整重启 ComfyUI（见 §3）。
若 git pull 后仍缺 Z-Image 相关节点，需使用带该功能的 ComfyUI 版本（官方说明：部分能力在稳定版发布前仅存在于较新构建；以你环境能加载官方 Z-Image 模板为准）。
与 Qwen-Image 的区别（勿混装）：
| Z-Image-Turbo | Qwen-Image（20B） | |
|---|---|---|
| 扩散文件 | z_image_turbo_bf16.safetensors |
qwen_image_*.safetensors |
| 文本编码器 | qwen_3_4b.safetensors（仅作编码器） |
qwen_2.5_vl_7b_* 等 |
| VAE | ae.safetensors |
qwen_image_vae.safetensors |
| 工作流 | Z-Image-Turbo 专用 JSON | Qwen-Image 专用 JSON |
别人说的「装 Qwen Image」≠ 本文的 Z-Image-Turbo；文件名里的 qwen_3_4b 只是 Z-Image 的文字编码器。
2. 下载模型（三个都要）
文生图 缺一不可：
| 文件 | 约大小 | 作用 |
|---|---|---|
qwen_3_4b.safetensors |
~8GB | 文本编码器（提示词 → 条件） |
z_image_turbo_bf16.safetensors |
~12GB | 扩散模型（真正画图） |
ae.safetensors |
~数百 MB | VAE（latent → PNG） |
目标目录：
ComfyUI/models/text_encoders/qwen_3_4b.safetensors
ComfyUI/models/diffusion_models/z_image_turbo_bf16.safetensors
ComfyUI/models/vae/ae.safetensors
国内怎么下（直连不行就用 ModelScope）
| 方式 | 适用 | 说明 |
|---|---|---|
ModelScope modelscope download |
国内服务器首选 | 仓库 Comfy-Org/z_image_turbo |
huggingface-cli / hf download + HF_ENDPOINT=https://hf-mirror.com |
备选 | 按文件路径下载 |
wget + hf-mirror.com |
易失败 | GB 级文件常 403，不推荐首选 |
pip install -U modelscope
2.1 国内推荐：ModelScope 按文件下载
在 ComfyUI/models 下建好目录，再分别拉三个文件（路径与官方 split_files 一致）：
cd ComfyUI/models
mkdir -p text_encoders diffusion_models vae
modelscope download \
--model Comfy-Org/z_image_turbo \
split_files/text_encoders/qwen_3_4b.safetensors \
--local_dir .
modelscope download \
--model Comfy-Org/z_image_turbo \
split_files/diffusion_models/z_image_turbo_bf16.safetensors \
--local_dir .
modelscope download \
--model Comfy-Org/z_image_turbo \
split_files/vae/ae.safetensors \
--local_dir .
ModelScope 模型页：https://www.modelscope.cn/models/Comfy-Org/z_image_turbo
若文件落在 models/split_files/... 下，挪到正确位置：
mv split_files/text_encoders/qwen_3_4b.safetensors text_encoders/ 2>/dev/null
mv split_files/diffusion_models/z_image_turbo_bf16.safetensors diffusion_models/ 2>/dev/null
mv split_files/vae/ae.safetensors vae/ 2>/dev/null
检查体积（勿是几 KB 占位）：
ls -lh text_encoders/qwen_3_4b.safetensors
ls -lh diffusion_models/z_image_turbo_bf16.safetensors
ls -lh vae/ae.safetensors
2.2 备选：HuggingFace 镜像 CLI
pip3 install -U huggingface_hub
export HF_ENDPOINT=https://hf-mirror.com
cd ComfyUI/models
mkdir -p text_encoders diffusion_models vae
huggingface-cli download Comfy-Org/z_image_turbo \
split_files/text_encoders/qwen_3_4b.safetensors \
--local-dir text_encoders \
--local-dir-use-symlinks False
huggingface-cli download Comfy-Org/z_image_turbo \
split_files/diffusion_models/z_image_turbo_bf16.safetensors \
--local-dir diffusion_models \
--local-dir-use-symlinks False
huggingface-cli download Comfy-Org/z_image_turbo \
split_files/vae/ae.safetensors \
--local-dir vae \
--local-dir-use-symlinks False
下载后若文件名带 split_files/... 前缀，请移动到 §2 表格中的最终路径。
2.3 显存紧张（可选）
16GB 仍 OOM 时，可将文本编码器换为量化版（需工作流节点里选对应文件名）：
qwen_3_4b_fp8_mixed.safetensors（约 5.6GB，同仓库split_files/text_encoders/）
扩散模型仍用 z_image_turbo_bf16.safetensors，或按 ComfyUI 文档尝试其它量化变体。
3. 重启并验证
cd ComfyUI
python3 main.py --listen 127.0.0.1 --port 8188
远程访问时将 127.0.0.1 改为 0.0.0.0 并放行端口。
浏览器中：
- 工作流 → 浏览模板，搜索 Z-Image / Z-Image-Turbo（名称因版本略有不同）
- 或从官方示例拖入 JSON（见 §4）
- 确认节点能选到上述三个模型文件
- 填写英文或中文提示词，Queue Prompt 试跑一张（首次加载较慢）
官方教程：https://docs.comfy.org/zh/tutorials/image/z-image/z-image-turbo
4. 工作流要点
4.1 节点结构（概念）
CLIP / 文本编码（qwen_3_4b）──┐
├──► KSampler（约 8 步）──► VAE 解码 ──► 保存图片
扩散模型（z_image_turbo）────┘
- 不是
Load Checkpoint单文件，而是 Load Diffusion Model + CLIP Loader（或 Z-Image 文本编码节点） + Load VAE - 采样步数常用 8（Turbo 蒸馏）；CFG 按模板默认值（通常较低）
- 分辨率常用 1024×1024；边长宜为 16 的倍数
4.2 获取示例工作流 JSON
任选其一：
- ComfyUI 界面 工作流模板 中打开 Z-Image-Turbo 文生图模板
- 官方示例仓库：https://github.com/comfyanonymous/ComfyUI_examples/tree/master/z_image（将 JSON 拷到本机后 Load）
- 官方文档页提供的「下载工作流」链接（与模板等价）
在界面 跑通一次 后再做 API 导出（§5）。
4.3 与本项目（物料封面）对接
定位： 在「生成配置 → 封面图 → ComfyUI」下，用 Z-Image-Turbo 工作流 替代或补充 原先基于官方 Flux 模板的出图，专门改善 中文歌名意境 + 中文场景；Sonic 视频对口型仍用 ComfyUI-Sonic安装教程.md，与本文无关。
桌面端 生成配置 → 封面图：
| 配置项 | 说明 |
|---|---|
| 服务商 | ComfyUI |
| ComfyUI 地址 / 鉴权 | 与现网一致（token 或 Cookie） |
| 工作流 JSON | 绑定 Z-Image-Turbo 的Save (API Format) 导出文件（不是 Flux 那份） |
| 出图规格 | 如 1024x2048 或 1024*1024（由工作流 Empty Latent / 脚本注入宽高） |
本软件提交 API 时会按工作流注入 提示词、seed、宽高 等；请保证 JSON 中含可识别的 CLIP 文本节点、KSampler、空 Latent（与 Flux 工作流节点 ID 不同，需用 Z-Image 专用 JSON）。
封面提示词逻辑见项目内 cover_image_prompt.py（单场景、标题居中、禁拼贴等）。若开启「根据歌词生成 ComfyUI 提示词」，仍走 DeepSeek，再写入 Z-Image 工作流。
注意： 若封面配置里服务商选 阿里云百炼、模型填 z-image-turbo，则走 云端 API，不需要在 ComfyUI 上下本文三个文件（见 §7 方式二）。
5. 导出 API 工作流
- 在界面把 Z-Image-Turbo 工作流 跑通
- 菜单 Save (API Format)（不是普通 Save）
- 保存为如
ComfyUI/workflows/z_image_turbo_api.json - 在桌面端 生成配置 → 封面图 选择该 JSON
正确 API JSON： 顶层为 "3"、"7" 等节点 ID，含 class_type、inputs
错误： 含 nodes、links 的界面版 JSON
5.1 API 调用流程
POST /prompt提交 API JSON（鉴权用启动日志里的 token，或浏览器 CookieAIOHTTP_SESSION）GET /history/{prompt_id}轮询直至outputs出现（封面建议间隔 20 秒 以上）GET /view下载images中的 png
单张 1024 图在 16GB 卡上通常 数十秒～数分钟（视首次加载而定）；客户端超时建议 ≥ 600 秒。
6. 常见问题
| 现象 | 处理建议 |
|---|---|
| 加载工作流提示节点缺失 | git pull 并重启；确认 ComfyUI 版本支持 Z-Image |
下拉框没有 qwen_3_4b / z_image_turbo_bf16 |
三个文件路径或文件名不对，对照 §2 检查 ls -lh |
wget hf-mirror 403 |
改用**§2.1 ModelScope** 或 §2.2 huggingface-cli + HF_ENDPOINT |
| 首次生成 CUDA OOM | 换 qwen_3_4b_fp8_mixed；降分辨率；关闭其它占 GPU 进程 |
| 与 Flux 工作流混用 | 必须单独 JSON；不能共用 flux1-schnell-fp8 的 Load Checkpoint |
| 画面中文标题仍错字 | 相对 Flux 已改善；固定歌名仍建议程序叠字（生成配置里宋体叠标题） |
| 和官方 Flux 模板比没提升 | 确认已换 Z-Image专用 JSON，且三个模型文件在 §2 路径下 |
| API 提交后无图 | 看 Queue / 日志；确认 JSON 为 API Format；鉴权 token 有效 |
7. 不用 ComfyUI 自建时的替代：百炼 API
若不想在 GPU 机上下约 21GB 权重，可在本项目中直接用 阿里云百炼（不占 ComfyUI 显存）：
- 开通百炼 / DashScope，创建 API Key
- 生成配置 → 封面图：服务商选 阿里云百炼，模型填
z-image-turbo（官方名） - Base URL：
https://dashscope.aliyuncs.com（北京） - 保存后重启桌面端，用「测试生成」验证
此方式 不经过 ComfyUI 工作流，也 不会 使用你在 §5 绑定的 Z-Image JSON。
8. 参考链接
- 通义 Z-Image 项目：Tongyi-MAI/Z-Image
- Hugging Face 权重：Comfy-Org/z_image_turbo
- ModelScope 权重：Comfy-Org/z_image_turbo
- ComfyUI 官方教程：Z-Image-Turbo 工作流
- ComfyUI 示例 JSON：comfyanonymous/ComfyUI_examples/z_image
附：与 Flux Schnell 并存
两套模型可同时放在同一 ComfyUI 目录下，互不覆盖：
models/checkpoints/flux1-schnell-fp8.safetensors ← 官方常见默认（快，中文弱）
models/diffusion_models/z_image_turbo_bf16.safetensors ← 本项目推荐（中文友好）
| 场景 | 建议 |
|---|---|
| 中文歌曲物料封面、要懂歌词意境 | Z-Image-Turbo + 叠字 |
| 仅测通 ComfyUI、不在乎中文 | 可继续 Flux |
| 不想自建 GPU 权重 | 百炼 API z-image-turbo（§7） |
切换封面引擎 = 在桌面端换绑 不同的 API 工作流 JSON，并在 ComfyUI 里用对应模板试跑即可。