ComfyUI 安装新模型

在 ComfyUI 安装新模型：以 Z-Image-Turbo 走完整一遍

这份教程用 Z-Image-Turbo 当完整案例，但真正要带走的是后面反复出现的那套方法。换 Flux、Qwen-Image、Wan 2.2 时，步骤几乎一样，只是「文件名、目录、加载器类型、采样参数」四组数字会变。

本机 ComfyUI：/root/autodl-tmp/ComfyUI，已在 6006 端口启动。

0. 先记住这套通用流程

以后装任何模型，都按这 6 步走，不要先去搜「XX 一键包」。

步骤	做什么	换模型时会变的东西
1	确认 ComfyUI 版本已经原生支持这个模型	最低版本、是否缺节点
2	打开官方模板 / 工作流 JSON，而不是作者原始 Diffusers 仓库	模板名
3	从 JSON 里读出 `name + url + directory`	文件清单
4	把文件放到 `models/<directory>/`，刷新列表	目录名；下载方法见 §4.5
5	核加载器：文件名、CLIP type、latent 节点	节点类型和参数
6	先用官方默认采样参数跑通，再改提示词和分辨率	steps / CFG / sampler

判断标准：下拉框能选到文件、点 Queue 能出图、图不是纯噪声或纯黑。这三件事成立，安装才算完成。

1. 这个模型是什么（只记会影响安装的部分）

Z-Image（造相）是阿里通义实验室的 6B 单流 DiT。ComfyUI 里它走 Lumina2 家族 的加载路径，所以：

扩散模型用 UNETLoader，放到 models/diffusion_models/
文本编码器用 CLIPLoader，type 必须选 lumina2
潜空间用 EmptySD3LatentImage（不是 SD1.5 的 EmptyLatentImage）
Turbo 是蒸馏版，官方默认 8 步、CFG=1 ，负向条件用 ConditioningZeroOut 清零

三个变体不要混：

变体	权重文件	用途
Z-Image-Turbo	`z_image_turbo_bf16.safetensors`	快速文生图（本教程）
Z-Image-Base	`z_image_bf16.safetensors`	底模 / 微调，步数和 CFG 不同
Z-Image-Edit	另有编辑工作流	图生图指令编辑

ControlNet 不是普通 controlnet/ 文件，而是 model_patches/ 里的 Fun Union 补丁。后面单独说。

2. 环境：先让 ComfyUI 能稳定启动

新模型装不上，有一半其实是 ComfyUI 本身没起来，或版本太旧。

2.1 版本要求

Z-Image-Turbo 是核心节点，不需要额外 custom_nodes。缺节点几乎总是版本太旧。

本机已验证：ComfyUI 0.33.0。模板找不到、或加载 JSON 报红节点时，先更新核心再谈模型。

2.2 启动方式（AutoDL / 云主机）

云主机必须监听 0.0.0.0，否则只绑 127.0.0.1，映射端口打不开：

bash 复制代码

cd /root/autodl-tmp/ComfyUI
python main.py --listen --port 6006

成功标志：

text 复制代码

Starting server
To see the GUI go to: http://0.0.0.0:6006

浏览器走实例的 6006 映射即可。

2.3 启动阶段真实踩过的坑

这些坑和 Z-Image 无关，但装任何模型前都会撞上。

缺 Python 依赖

text 复制代码

ModuleNotFoundError: No module named 'sqlalchemy'
Error importing dependencies: No module named 'alembic'

解决：在 ComfyUI 根目录装官方依赖，不要只装某一个包。

bash 复制代码

python -m pip install -r requirements.txt

torchaudio 和当前 PyTorch CUDA 版本不一致

本机是 torch 2.8.0+cu128（CUDA 12.8）。直接 pip install -r requirements.txt 可能把 torchaudio 升到需要 libcudart.so.13（CUDA 13）的版本，启动直接崩：

text 复制代码

OSError: libcudart.so.13: cannot open shared object file

解决：把 torchaudio 钉回和 torch 同一套 CUDA：

bash 复制代码

python -m pip install --index-url https://download.pytorch.org/whl/cu128 'torchaudio==2.8.0' --no-deps

换机器时的通用规则：先看 python -c "import torch; print(torch.__version__, torch.version.cuda)"，再装对应 cu12x / cu13x 的 torchaudio/torchvision，不要让 pip 从默认源自作主张升版本。

自定义节点导入失败

启动日志末尾有 Import times for custom nodes。某个节点报错时，它只影响那一组节点，核心工作流通常仍能跑。Z-Image-Turbo 文生图不依赖第三方节点，先别管。

3. 找对文件源：这是最容易走错的一步

通用原则：ComfyUI 要的是拆好的 .safetensors，不是 Hugging Face 上作者仓库里的 Diffusers 目录树。

来源	适不适合 ComfyUI	原因
Comfy-Org/z_image_turbo	适合	已经按 `diffusion_models` / `text_encoders` / `vae` 拆好
Tongyi-MAI/Z-Image-Turbo	不适合直接塞	Diffusers / transformer 多文件结构，ComfyUI 加载器认不到
网盘「一键整合包」	慎用	目录、文件名、量化版本经常和官方模板对不上

以后换模型，优先搜这两个地方：

ComfyUI 界面 Workflow Templates，搜模型名
Hugging Face 搜 Comfy-Org <模型名>，找 *_ComfyUI / *_repackaged / split_files

官方文档：https://docs.comfy.org 左侧 Tutorials。

4. 从工作流 JSON 读出「购物清单」

不要靠记忆。模板 JSON 里已经写死了文件名、下载地址、该放哪个目录。

本仓库对应文件：

blueprints/Text to Image (Z-Image-Turbo).json

里面每个加载器节点都有类似字段：

json 复制代码

"models": [
  {
    "name": "z_image_turbo_bf16.safetensors",
    "url": "https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/diffusion_models/z_image_turbo_bf16.safetensors",
    "directory": "diffusion_models"
  }
]

读法（对任何模型都成立）：

name：下拉框里必须出现的文件名，下载后不要改名（除非你同时改节点）
url：只下这一个文件，不要 clone 整个仓库
directory：放到 ComfyUI/models/<directory>/

Z-Image-Turbo 文生图三件套：

角色	文件	目录	大约体积
扩散模型	`z_image_turbo_bf16.safetensors`	`models/diffusion_models/`	12.3 GB
文本编码器	`qwen_3_4b.safetensors`	`models/text_encoders/`	8.04 GB
VAE	`ae.safetensors`	`models/vae/`	~335 MB

合计约 21 GB。磁盘不够先看第 8 节量化版。

界面里也可以不读 JSON：打开模板后，红色缺失的加载器会提示缺哪个文件，点下载即可。CLI 更稳，尤其是云主机中断后续传。

4.5 通用下载流程（AutoDL / 国内云主机）

以后从工作流 JSON 拿到 url + directory + name 之后，都按本节下载，不要每个模型各写一套。Z-Image、MiniMax H3、Wan 2.2、Stable Audio 3 只是文件清单不同。

4.5.1 选哪种方式

优先级	方式	适用场景	本机实测
1（推荐）	`source /etc/network_turbo` + aria2c	AutoDL 等大文件（>5 GB）	~20--35 MB/s（Stable Audio 3 约 8.6 GB / 4--5 分钟）
2	`HF_ENDPOINT=hf-mirror.com` + `huggingface-cli`	无学术加速、中小文件	可续传，大文件易超时
3	`wget -c` / `curl -C -` + hf-mirror 直链	没装 aria2 / huggingface_hub 时	单线程，慢但简单

AutoDL 上优先开 network_turbo 。它走学术代理加速 Hugging Face / GitHub；对 pip 源等国内资源反而可能更慢，下完模型可 unset http_proxy https_proxy。

bash 复制代码

source /etc/network_turbo   # 输出「设置成功!」即可

4.5.1b 填 `expect_gb`：用 `X-Linked-Size`（不要信 Content-Length）

HF 现已多用 Xet CDN （*.cdn.hf.co）。对 resolve/main/... 做 curl -sIL 时：

中间 302 的 Content-Length 经常是空的或只有几十字节（那段是跳转响应，不是文件本体）
真实体积在响应头 X-Linked-Size（字节数）

开好 network_turbo 后这样取期望 GB，再填进下面的 FILES：

bash 复制代码

source /etc/network_turbo
url="https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/checkpoints/stable_audio_3_medium.safetensors"
bytes=$(curl -sIL "$url" | awk 'BEGIN{IGNORECASE=1} /^X-Linked-Size:/{print $2}' | tr -d '\r' | tail -1)
python3 -c "print(round(int('$bytes')/1024**3, 2))"   # → 8.59

没有 X-Linked-Size 时再看最终 200 响应的 Content-Length。不要用 HTML 错误页的长度当 expect_gb。

4.5.2 通用 aria2c 批量下载（推荐）

把 JSON 里的每个 url 填进下面的 FILES 数组：目标目录:期望GB:下载URL。

bash 复制代码

source /etc/network_turbo
cd /root/autodl-tmp/ComfyUI

download_one() {
  local subdir="$1" expect_gb="$2" url="$3"
  local name="${url##*/}"   # 若 URL 带 query，改成手动指定 name
  name="${name%%\?*}"
  local dst="models/${subdir}/${name}"
  mkdir -p "models/${subdir}"

  if [[ -f "$dst" ]]; then
    local sz_gb
    sz_gb=$(python3 -c "print(round($(du -b "$dst" | awk '{print $1}')/1024**3, 2))")
    if python3 -c "exit(0 if float('$sz_gb') >= float('$expect_gb')*0.95 else 1)"; then
      echo "SKIP $name (${sz_gb} GB)"
      return 0
    fi
    echo "RESUME $name (${sz_gb} GB / ~${expect_gb} GB)"
  else
    echo "DOWNLOAD $name (~${expect_gb} GB)"
  fi

  aria2c -c -x 16 -s 16 -k 1M --file-allocation=none \
    --max-tries=0 --retry-wait=10 --timeout=120 --connect-timeout=60 \
    -d "models/${subdir}" -o "$name" "$url"
}

# 示例 A：Z-Image-Turbo 三件套（换模型时只改 FILES）
FILES=(
  "diffusion_models:12.3:https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/diffusion_models/z_image_turbo_bf16.safetensors"
  "text_encoders:8.0:https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/text_encoders/qwen_3_4b.safetensors"
  "vae:0.35:https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/vae/ae.safetensors"
)

# 示例 B：Stable Audio 3（blueprint 全量：ckpt + SA text encoder + reprompt Qwen）
# FILES=(
#   "checkpoints:8.59:https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/checkpoints/stable_audio_3_medium.safetensors"
#   "checkpoints:8.59:https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/checkpoints/stable_audio_3_medium_base.safetensors"
#   "text_encoders:1.11:https://huggingface.co/Comfy-Org/stable-audio-3/resolve/main/text_encoders/t5gemma_b_b_ul2.safetensors"
#   "text_encoders:4.24:https://huggingface.co/Comfy-Org/Qwen3.5/resolve/main/text_encoders/qwen3.5_2b_bf16.safetensors"
# )

for entry in "${FILES[@]}"; do
  IFS=':' read -r sub exp url <<< "$entry"
  download_one "$sub" "$exp" "$url"
done

要点：

-c ：断点续传；进程被杀或超时后，原命令再跑一遍即可接着下。
expect_gb ：用于跳过已完成的文件；体积 ≥ 期望 × 95% 视为完成。填法见 §4.5.1b （优先 X-Linked-Size）。
URL 用 huggingface.co （开 network_turbo 时），不必改 hf-mirror。
aria2 开头可能短暂显示 0B/0B（还在跟 Xet 跳转），随后会出真实总大小；属正常。
下完用 du -b 看实际落盘体积；ls -lh 对大稀疏文件会误导。
清单要从 blueprint / 工作流 JSON 里把所有带 url 的条目扫全 ，不要只下「主模型」仓库里的文件。辅助模型常来自别的仓库（例如 SA3 的 qwen3.5_2b_bf16 在 Comfy-Org/Qwen3.5，不在 stable-audio-3）。漏下时按 §4.5.5 补。

4.5.3 备选：huggingface-cli（镜像）

没开 network_turbo 时：

bash 复制代码

export HF_ENDPOINT=https://hf-mirror.com
pip install -U huggingface_hub

huggingface-cli download <Comfy-Org仓库> <仓库内相对路径> --local-dir /tmp/staging
# 再把文件 mv 到 models/<directory>/，不要保留 staging 子目录嵌套

大文件（10 GB+）若反复 read operation timed out，改用 4.5.2 的 aria2c。

4.5.4 下完必做校验

bash 复制代码

# 单文件：实际字节应接近 JSON / 官方体积表
du -b models/diffusion_models/某个文件.safetensors

# 批量自检（把清单换成你的模型）
python3 - <<'PY'
import os, subprocess
checks = [
    ("z_image_turbo_bf16.safetensors", "diffusion_models", 12.3),
    # Stable Audio 3:
    # ("stable_audio_3_medium.safetensors", "checkpoints", 8.59),
    # ("stable_audio_3_medium_base.safetensors", "checkpoints", 8.59),
    # ("t5gemma_b_b_ul2.safetensors", "text_encoders", 1.11),
    # ("qwen3.5_2b_bf16.safetensors", "text_encoders", 4.24),
]
base = "/root/autodl-tmp/ComfyUI/models"
for name, sub, exp in checks:
    p = os.path.join(base, sub, name)
    if not os.path.isfile(p):
        print(f"MISSING {name}"); continue
    gb = int(subprocess.check_output(["du", "-b", p]).split()[0]) / 1024**3
    ok = "OK" if gb >= exp * 0.95 else "INCOMPLETE"
    print(f"{ok}  {name}: {gb:.2f} GB (expect ~{exp})")
PY

体积差很多、或只有几 KB～几 MB，多半是 HTML 错误页，删掉重下 。ComfyUI 里按 R 刷新，或重启后看加载器下拉框。

4.5.5 跑图报缺模型：只补漏，不要整套重下

典型报错：Value not in list / 下拉框没有某文件 / 日志里写缺少 qwen3.5_2b_bf16.safetensors 这类名字。

原因：首次只下了主仓库（如 Comfy-Org/stable-audio-3），漏了 blueprint 里另一个 url（reprompt、ControlNet、LoRA、第二套 text encoder 等）。

做法：

在对应 blueprint / 工作流 JSON 里搜缺的文件名，拿到完整三元组：name + directory + url。
用 §4.5.1b 查 X-Linked-Size → expect_gb。
FILES 只放缺的那几行 ，再跑一遍 §4.5.2 的 download_one 循环。已下够体积的文件会 SKIP，不会重下。
du -b 校验 → ComfyUI 按 R 刷新列表。

从 JSON 批量抽出所有模型 URL（便于对照缺什么）：

bash 复制代码

# 把路径换成你的 blueprint / workflow
python3 - <<'PY'
import json, sys
path = "blueprints/Audio Generation (Stable Audio 3 Medium).json"
with open(path, encoding="utf-8") as f:
    data = json.load(f)

def walk(o, out):
    if isinstance(o, dict):
        if "url" in o and "directory" in o and "name" in o:
            out.append((o["directory"], o["name"], o["url"]))
        for v in o.values():
            walk(v, out)
    elif isinstance(o, list):
        for v in o:
            walk(v, out)

items = []
walk(data, items)
# 去重，按 name
seen = set()
for d, n, u in items:
    if n in seen:
        continue
    seen.add(n)
    print(f"{d}\t{n}\t{u}")
PY

补漏示例（只下之前漏的 Qwen；主 ckpt / t5gemma 已在盘上会自动 SKIP）：

bash 复制代码

source /etc/network_turbo
cd /root/autodl-tmp/ComfyUI
# 复用 §4.5.2 的 download_one 函数后：
FILES=(
  "text_encoders:4.24:https://huggingface.co/Comfy-Org/Qwen3.5/resolve/main/text_encoders/qwen3.5_2b_bf16.safetensors"
)
for entry in "${FILES[@]}"; do
  IFS=':' read -r sub exp url <<< "$entry"
  download_one "$sub" "$exp" "$url"
done

5. 下载并放到正确目录

Z-Image 按 §4.5 通用流程 下载即可；下面只列本模型专用路径。

5.1 建目录

bash 复制代码

cd /root/autodl-tmp/ComfyUI
mkdir -p models/diffusion_models models/text_encoders models/vae models/model_patches

folder_paths.py 里有别名：diffusion_models 也会扫 models/unet/，text_encoders 也会扫 models/clip/。官方模板用新名字，建议就按新名字放，避免以后对不上。

5.2 下载 Z-Image-Turbo 三件套

AutoDL 推荐 ：先 source /etc/network_turbo，再跑 §4.5.2 里 FILES 示例（三行 URL 已写好）。

备选：hf-mirror + huggingface-cli（无学术加速时）：

bash 复制代码

export HF_ENDPOINT=https://hf-mirror.com

用 huggingface-cli（可续传、校验）：

bash 复制代码

pip install -U huggingface_hub

huggingface-cli download Comfy-Org/z_image_turbo \
  split_files/diffusion_models/z_image_turbo_bf16.safetensors \
  --local-dir /tmp/z_image_turbo

huggingface-cli download Comfy-Org/z_image_turbo \
  split_files/text_encoders/qwen_3_4b.safetensors \
  --local-dir /tmp/z_image_turbo

huggingface-cli download Comfy-Org/z_image_turbo \
  split_files/vae/ae.safetensors \
  --local-dir /tmp/z_image_turbo

挪到 ComfyUI 目录（必须是文件本身，不要连 split_files/... 子目录一起嵌套进去）：

bash 复制代码

mv /tmp/z_image_turbo/split_files/diffusion_models/z_image_turbo_bf16.safetensors \
   /root/autodl-tmp/ComfyUI/models/diffusion_models/

mv /tmp/z_image_turbo/split_files/text_encoders/qwen_3_4b.safetensors \
   /root/autodl-tmp/ComfyUI/models/text_encoders/

mv /tmp/z_image_turbo/split_files/vae/ae.safetensors \
   /root/autodl-tmp/ComfyUI/models/vae/

或用 wget 续传：

bash 复制代码

cd /root/autodl-tmp/ComfyUI/models/diffusion_models
wget -c "https://hf-mirror.com/Comfy-Org/z_image_turbo/resolve/main/split_files/diffusion_models/z_image_turbo_bf16.safetensors"

5.3 放完后必须刷新

文件在磁盘上了，界面下拉框不一定立刻看见。按 R 刷新图，或重启 ComfyUI。

检查：

bash 复制代码

ls -lh models/diffusion_models/z_image_turbo_bf16.safetensors
ls -lh models/text_encoders/qwen_3_4b.safetensors
ls -lh models/vae/ae.safetensors

体积对不上（差很多）就是下残了，删掉重下。.safetensors 下到一半会变成几十字节的 HTML 错误页，加载时表现为损坏或 KeyError。

5.4 目录放错的典型症状

你把文件放哪了	现象
`models/checkpoints/`	`UNETLoader` / `CLIPLoader` 下拉框里没有
扩散模型放进 `vae/`	VAE 节点能选到它，一跑就报错
文本编码器放进 `diffusion_models/`	CLIP 下拉框没有
保留了 `split_files/diffusion_models/` 这层嵌套	ComfyUI 不递归扫描，依然看不见

6. 加载官方工作流并核加载器

6.1 打开模板

浏览器打开 6006
工作流模板里搜 Z-Image-Turbo
打开 Text to Image (Z-Image-Turbo)

或把本仓库的 blueprints/Text to Image (Z-Image-Turbo).json 拖进画布。

缺节点：先更新 ComfyUI，不要去装同名第三方节点。

6.2 三个加载器必须逐项核对

官方默认值：

节点	关键选项	正确值	常见错误
`UNETLoader`	unet_name	`z_image_turbo_bf16.safetensors`	选成 Base / 量化版但不改其它设置
`UNETLoader`	weight_dtype	`default`	乱切 fp8 导致质量差或报错
`CLIPLoader`	clip_name	`qwen_3_4b.safetensors`	选成 Flux 的 T5 / CLIP-L
`CLIPLoader`	type	`lumina2`	选 `flux` / `sd3` / `wan`，提示词几乎无效
`VAELoader`	vae_name	`ae.safetensors`	选成 SD1.5 VAE，出图花屏或报错

ae.safetensors 这个文件名和 Flux / Lumina 的 VAE 撞名。同目录只能留一份时，确认它就是 Comfy-Org Z-Image 这份（约 335 MB）。不要把 SD1.5 的 vae-ft-mse 改名成 ae.safetensors。

6.3 采样侧也有「装对了但图很差」的开关

这些不是安装问题，但第一次出图必须保持官方值，否则你会以为模型坏了。

节点	官方值	为什么
`EmptySD3LatentImage`	1024×1024	这是 DiT 潜空间；不要用 SD1.5 的 `EmptyLatentImage`
`ModelSamplingAuraFlow`	shift = 3	和模型 `sampling_settings.shift` 一致
`KSampler` steps	8	Turbo 蒸馏约 8 NFE，拉到 20+ 通常无收益
`KSampler` cfg	1	蒸馏模型不走高 CFG；2 以上容易过曝、假细节
`KSampler` sampler	`res_multistep`	官方模板值
`KSampler` scheduler	`simple`	官方模板值
`KSampler` denoise	1	文生图
`ConditioningZeroOut`	接负向	Turbo 默认把负向清零，不是 SDXL 那套负向提示词

工作流骨架（记这个，换模型时对照）：

text 复制代码

UNETLoader ──► ModelSamplingAuraFlow ──► KSampler ──► VAEDecode ──► SaveImage
CLIPLoader ──► CLIPTextEncode ──┬──► (positive)
                                └──► ConditioningZeroOut ──► (negative)
EmptySD3LatentImage ─────────────────────────────► KSampler
VAELoader ───────────────────────────────────────► VAEDecode

7. 第一次出图

提示词中英都可以。Turbo 对中英文字渲染比较强，第一次建议写短、具体、带场景的句子，不要堆 30 个质量词。

示例：

text 复制代码

一只橙色的狐狸坐在图书馆里看书，暖黄灯光，电影感，照片级，画面中有清晰的中文招牌「造相」

点 Queue（或 Ctrl+Enter）。

成功：几秒到几十秒出图（本机 RTX 5090 D 会很快），图和提示词对得上。

失败对照第 9 节。

输出默认在 ComfyUI/output/。

8. 可选扩展（装完主模型再做）

8.1 Fun Union ControlNet

额外文件：

text 复制代码

https://huggingface.co/alibaba-pai/Z-Image-Turbo-Fun-Controlnet-Union/resolve/main/Z-Image-Turbo-Fun-Controlnet-Union.safetensors

放到 models/model_patches/ ，不是 models/controlnet/。

模板：ControlNet (Z-Image-Turbo) / Depth to Image (Z-Image-Turbo) / Canny to Image (Z-Image-Turbo) / Pose to Image (Z-Image-Turbo)。

支持 Canny、HED、Depth、Pose、MLSD。用错目录时，ModelPatchLoader 下拉框是空的，但 Load ControlNet Model 里可能能看到文件------那是装错槽位了。

8.2 显存不够时

官方 bf16 三件套峰值大约要消费级 16GB 能跑。更小显存按这个顺序降：

启动加 --lowvram 或 --novram
扩散模型改官方量化：z_image_turbo_int8_convrot.safetensors（约 6.2 GB）或 z_image_turbo_nvfp4.safetensors（需对应 GPU）
文本编码器改 qwen_3_4b_fp8_mixed.safetensors（约 5.63 GB）
社区 GGUF：需要 ComfyUI-GGUF 一类自定义节点，这已经不是「原生安装」了，出问题先怀疑节点版本

量化文件仍然放同一组目录，只换 UNETLoader / CLIPLoader 里的文件名。VAE 一般不用量化。

8.3 多模型共用权重

qwen_3_4b.safetensors 和 ae.safetensors 可能被其它工作流复用。不要为每个模型复制一份，除非文件内容其实不同却同名。同名不同内容时，改成可区分的名字，并在节点里改选项。

额外模型目录用 extra_model_paths.yaml（见仓库里的 extra_model_paths.yaml.example），不要把权重塞进 custom_nodes。

9. 坑点手册（安装 + 第一次出图）

按「你看到的现象」查，不要按感觉重装。

A. 模板 / 节点

现象	原因	处理
模板里搜不到 Z-Image	前端/核心过旧	更新 ComfyUI 后重启
拖入 JSON 出现红节点	核心版本不够，或自定义节点导入失败	看启动日志 `Import times`；Z-Image 文生图不需要第三方节点
节点名叫中文但类型不对	装了同名第三方包把核心节点盖掉	暂时 `--disable-all-custom-nodes` 验证

B. 文件看不见 / 加载失败

现象	原因	处理
下拉框没有文件	目录错、嵌套了 `split_files/`、没刷新	按第 5 节移动；按 `R` 或重启
文件在列表里但加载立刻报错	下残了（HTML 错误页）或选错变体	`ls -lh` 核对体积，重下
`KeyError` / 权重 key 对不上	下了 Tongyi 原始 Diffusers 或 Base/Turbo 混用	改用 Comfy-Org `split_files`
CUDA OOM	分辨率太大或没量化	先 768² / `--lowvram` / int8 或 fp8

C. 能跑但图不对

现象	原因	处理
纯噪声、结构崩	CLIP type 不是 `lumina2`	改回 `lumina2`
提示词完全不听	同上，或选错了文本编码器	确认 `qwen_3_4b.safetensors`
过曝、塑料感、假细节	CFG 按 SDXL 开到 7	Turbo 用 CFG=1，steps=8
花屏、颜色错乱	VAE 不是这一份 `ae.safetensors`	换回官方 VAE
潜空间报 shape 错	用了 `EmptyLatentImage`	换成 `EmptySD3LatentImage`
比官方示例差很多	没加 `ModelSamplingAuraFlow` 或 shift≠3	按模板接上
负向提示词完全无效	Turbo 工作流把负向 Zero Out 了	这是设计；要负向需改图，不能当 SDXL 用

D. ControlNet

现象	原因	处理
`ModelPatchLoader` 是空的	文件放进了 `controlnet/`	挪到 `model_patches/`
预处理器和 Union 类型不匹配	用了 Canny 图却走 Depth 工作流	用对应模板：Canny/Depth/Pose
控制完全没效果	strength=0 或没接到正确 patch 节点	对照官方 ControlNet 模板连线

E. 运行环境（和模型无关，但会被误判成模型坏了）

现象	原因	处理
6006 打不开	没 `--listen`，只绑了 127.0.0.1	`--listen --port 6006`
启动闪退 `libcudart.so.13`	torchaudio 跟 torch CUDA 不一致	见第 2.3 节
`No module named 'sqlalchemy'`	没装 `requirements.txt`	`pip install -r requirements.txt`

F. 下载中断 / 超时

现象	原因	处理
`read operation timed out`（huggingface_hub）	大文件走 CDN 不稳定	AutoDL 上 `source /etc/network_turbo`，改用 §4.5.2 aria2c
aria2 速度只有 ~1 MB/s	没开 network_turbo，仍在走镜像	先 `source /etc/network_turbo`，URL 用 `huggingface.co`
`curl -sIL` 拿不到 Content-Length / expect_gb 填错	HF Xet CDN：体积在 `X-Linked-Size`	见 §4.5.1b
aria2 开头一直 `0B/0B`	还在跟 Xet 302 跳转	等几秒；出真实 GiB 后即正常
跑图缺 `xxx.safetensors`（如 qwen3.5_2b）	只下了主仓库，漏 blueprint 里其它 `url`	§4.5.5 从 JSON 抽清单，只补漏
`ls -lh` 显示 14G 但 `du` 只有几百 MB	aria2 预分配稀疏文件	以 `du -b` 为准判断进度
下到一半进程没了	SSH 断开 / 超时	同一命令再跑，`-c` 会续传
pip 突然变慢	network_turbo 开着	下完模型后 `unset http_proxy https_proxy`

10. 把同一套流程套到其它模型

Z-Image 走通之后，换模型只替换「购物清单 + 加载器类型 + 默认采样」。下面三张表够你起步。

10.1 对照表

	Z-Image-Turbo	Flux.1 Dev	Qwen-Image	Wan 2.2
模板	Text to Image (Z-Image-Turbo)	Text to Image (Flux.1 Dev)	Text to Image (Qwen-Image)	Text to Video (Wan 2.2)
Comfy-Org 仓库	`Comfy-Org/z_image_turbo`	`Comfy-Org/flux1-dev`	`Comfy-Org/Qwen-Image_ComfyUI`	`Comfy-Org/Wan_2.2_ComfyUI_Repackaged`
扩散模型目录	`diffusion_models/`	`diffusion_models/`	`diffusion_models/`	`diffusion_models/`（常有高低噪两份）
文本编码器	`CLIPLoader` type=`lumina2`	`DualCLIPLoader` type=`flux`	`CLIPLoader`（按模板 type）	`CLIPLoader` type=`wan`
文本编码器文件	`qwen_3_4b.safetensors`	`clip_l` + `t5xxl_fp16`	模板里的 Qwen TE	`umt5_xxl_...safetensors`
VAE	`ae.safetensors`	`ae.safetensors`（可能同名）	`qwen_image_vae.safetensors`	`wan_2.1_vae.safetensors`
潜空间	`EmptySD3LatentImage`	`EmptySD3LatentImage`	按模板	视频潜空间节点
额外文件	可选 ControlNet patch	无则能文生图	有的模板带 LoRA	常有 lightx2v 等 LoRA
采样习惯	8 步，CFG 1	约 20 步，CFG 1	跟模板走，不要套 SDXL	跟模板走，双 DiT 别接反

同名 ae.safetensors 在 Flux / Lumina / Z-Image 之间可能能共用，不要假设 SD1.5 VAE 也能叫这个名字。

10.2 操作时只问自己这 8 个问题

官方模板叫什么？JSON 在哪？
每个加载器的 models[].directory 是哪？
CLIP / DualCLIP / TripleCLIP？type 填什么？
潜空间是 SD1.5、SD3/Flux 还是视频？
有没有 ModelSampling* 节点？shift / max_shift 是多少？
CFG 是 1 还是 7？蒸馏 Turbo 类基本是 1。
ControlNet 进 controlnet/ 还是 model_patches/？
作者原始仓库是 Diffusers 多文件吗？有的话改下 Comfy-Org 拆包。

文件清单确定后，下载一律走 §4.5 （AutoDL 优先 network_turbo + aria2c）。

只要这 8 个问题能从模板 JSON 答出来，安装就不会靠猜。

10.3 读 JSON 的最快办法

在 ComfyUI 根目录：

bash 复制代码

python - <<'PY'
import json, glob, sys
path = sys.argv[1] if len(sys.argv) > 1 else "blueprints/Text to Image (Z-Image-Turbo).json"
data = json.load(open(path, encoding="utf-8"))

def walk(obj):
    if isinstance(obj, dict):
        models = obj.get("properties", {}).get("models") if "properties" in obj else obj.get("models")
        if models:
            ntype = obj.get("type", "?")
            w = obj.get("widgets_values", [])
            print(f"\n[{ntype}] widgets={w}")
            for m in models:
                print(f"  {m.get('directory')}/{m.get('name')}")
                print(f"  {m.get('url')}")
        for v in obj.values():
            walk(v)
    elif isinstance(obj, list):
        for v in obj:
            walk(v)

walk(data)
PY

把路径换成 blueprints/Text to Image (Flux.1 Dev).json 或任意拖进来的工作流，购物清单会自己打出来。

11. 安装完成自检

文生图满足下面全部即可认为 Z-Image-Turbo 装好了：

ComfyUI 能在 6006（或你的端口）打开
models/diffusion_models/z_image_turbo_bf16.safetensors 体积约 12.3 GB
models/text_encoders/qwen_3_4b.safetensors 体积约 8.04 GB
models/vae/ae.safetensors 体积约 335 MB
UNETLoader 能选到扩散模型
CLIPLoader 文件正确且 type = lumina2
使用 EmptySD3LatentImage + ModelSamplingAuraFlow(shift=3)
KSampler：8 / cfg 1 / res_multistep / simple
Queue 一次，出图且提示词可见地起作用

做 ControlNet 时再加：

models/model_patches/Z-Image-Turbo-Fun-Controlnet-Union.safetensors 存在
用的是 ModelPatchLoader，不是普通 ControlNet 加载器

附录：本机相关路径

text 复制代码

ComfyUI 根目录     /root/autodl-tmp/ComfyUI
启动命令           python main.py --listen --port 6006
官方文生图模板     blueprints/Text to Image (Z-Image-Turbo).json
ControlNet 模板    blueprints/ControlNet (Z-Image-Turbo).json
模型目录映射       folder_paths.py
额外模型路径示例   extra_model_paths.yaml.example
输出图             output/

外部链接：

教程：https://docs.comfy.org/tutorials/image/z-image/z-image-turbo
拆包权重：https://huggingface.co/Comfy-Org/z_image_turbo
原始模型卡：https://huggingface.co/Tongyi-MAI/Z-Image-Turbo
Fun Union ControlNet：https://huggingface.co/alibaba-pai/Z-Image-Turbo-Fun-Controlnet-Union

附录 B：同一套流程安装 MiniMax H3（音视频联合生成）

下面用 MiniMax H3 T2V 再走一遍第 0 节的 6 步。它和 Z-Image 最大的区别是：一次生成带立体声的 MP4 ，需要 两个 VAE（视频 + 音频），扩散模型和 R2V 还不是同一个权重。

官方文档：MiniMax H3 in ComfyUI

官方拆包仓库：Comfy-Org/MiniMax-H3

本机模板包路径：comfyui_workflow_templates_json/templates/video_minimax_h3_t2v.json

B.1 版本与节点

需要 ComfyUI ≥ 0.30.0（本机 0.33.0 已满足）
不需要 额外 custom_nodes；核心节点在 nodes_minimax_h3.py
模板库搜：MiniMax H3 T2V / I2V / R2V

工作流	扩散模型	用途
T2V / I2V	`minimax_h3_fl2va_pruned_int8_convrot.safetensors`	文生视频 / 图生视频
R2V	`minimax_h3_ref2va_pruned_int8_convrot.safetensors`	参考图/视频/音频驱动

R2V 和 T2V 不能共用同一个扩散权重，装 R2V 要再下一份 ~19.5 GB。

B.2 购物清单（T2V 官方推荐组合）

从模板 JSON 读出的 T2V 最小集 （约 41 GB，另加可选 LoRA ~1.8 GB）：

角色	文件	目录	体积
扩散模型	`minimax_h3_fl2va_pruned_int8_convrot.safetensors`	`models/diffusion_models/`	19.5 GB
文本编码器	`qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`	`models/text_encoders/`	14.6 GB
视频 VAE	`minimax_h3_video_vae_fp16.safetensors`	`models/vae/`	4.9 GB
音频 VAE	`minimax_h3_audio_vae_fp32.safetensors`	`models/vae/`	0.6 GB
Turbo LoRA（可选，8 步加速）	`minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors`	`models/loras/`	1.8 GB

不要去下 MiniMaxAI/MiniMax-H3 的 Diffusers 目录------和 Z-Image 一样，ComfyUI 只吃 Comfy-Org 拆包。

显存参考（本机 RTX 5090 D 31 GB 可跑上述 int8 + nvfp4 组合）：

组合	大致目标
`pruned_int8_convrot` + `nvfp4_awq` TE	24 GB+ 消费级卡（官方 T2V 模板默认）
`pruned_bf16` + `bf16` TE	32 GB+ 且需要较大系统内存
完整 bf16 未剪枝	66 GB 级，工作室配置

B.3 加载器核对（和 Z-Image 不同的点）

节点	关键选项	正确值
`UNETLoader`	unet_name	`minimax_h3_fl2va_pruned_int8_convrot.safetensors`
`CLIPLoader`	clip_name	`qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`
`CLIPLoader`	type	`minimax` （不是 `lumina2` / `wan`）
`VAELoader` ×2	视频	`minimax_h3_video_vae_fp16.safetensors`
`VAELoader` ×2	音频	`minimax_h3_audio_vae_fp32.safetensors`
`LoraLoaderModelOnly`	可选	`minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors`
条件节点	T2V/I2V	`MiniMaxH3ImageToVideo`
条件节点	R2V	`MiniMaxH3ReferenceToVideo`
潜空间		`EmptyMiniMaxH3LatentAV` 或由 ImageToVideo 节点输出
采样		模板用 `SamplerCustomAdvanced` + `BasicGuider`，不是普通 `KSampler`
输出		`VAEDecode`（视频帧）+ `VAEDecodeAudio` + `CreateVideo` → `SaveVideo`

工作流骨架：

text 复制代码

UNETLoader ──► [LoraLoader 可选] ──► BasicGuider ──► SamplerCustomAdvanced
CLIPLoader(type=minimax) ──► MiniMaxH3ImageToVideo ──► BasicGuider
VAELoader(视频) ──► MiniMaxH3ImageToVideo / VAEDecode
VAELoader(音频) ──► VAEDecodeAudio
SamplerCustomAdvanced ──► VAEDecode + VAEDecodeAudio ──► CreateVideo ──► SaveVideo

B.4 下载命令

按 §4.5 通用流程 ：AutoDL 上先 source /etc/network_turbo，再用 aria2c 批量下。

bash 复制代码

source /etc/network_turbo
cd /root/autodl-tmp/ComfyUI
mkdir -p models/{diffusion_models,text_encoders,vae,loras}

# 把下面 FILES 交给 §4.5.2 的 download_one 循环
FILES=(
  "vae:0.6:https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/vae/minimax_h3_audio_vae_fp32.safetensors"
  "vae:4.9:https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/vae/minimax_h3_video_vae_fp16.safetensors"
  "text_encoders:14.6:https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors"
  "diffusion_models:19.5:https://huggingface.co/Comfy-Org/MiniMax-H3/resolve/main/diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors"
  "loras:1.8:https://huggingface.co/lightx2v/Minimax-h3-Turbo/resolve/main/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors"
)

本机曾用 /root/autodl-tmp/minimax_download.sh 跑通过上述清单；日志在 /root/autodl-tmp/minimax_download_progress.log。

备选（无 network_turbo） ：§4.5.3 的 huggingface-cli + hf-mirror。14 GB 的 text encoder 容易超时，大文件仍建议 aria2c。

工作流模板已复制到 user/default/workflows/video_minimax_h3_t2v.json。

B.5 磁盘与共存（本机当前状况）

数据盘 /root/autodl-tmp 总容量 150 GB 。Z-Image（~21 GB）与 MiniMax H3（~41 GB）已并存 ，当前约 88 GB 已用 / 63 GB 剩余。

若再装 R2V 扩散权重（+19.5 GB）或其它大项目，空间会紧张。可选：

AutoDL 控制台扩容到 200 GB 以上（最省事）
清理不需要的大目录 （本机还有 RynnVLA-002 ~73 GB、GraspVLA_repro ~22 GB）
只保留常用模型 ：删掉不用的 .safetensors 腾出空间

B.6 MiniMax 特有坑点

现象	原因	处理
CLIP 下拉有文件但编码报错	type 不是 `minimax`	改 `CLIPLoader` type
只有画面没声音	没加载音频 VAE / 没走 `CreateVideo`	模板里需要两个 `VAELoader`
R2V 效果不对	用了 fl2va 扩散权重	R2V 必须换 `ref2va_pruned_int8_convrot`
时长不对	H3 帧数 snap 到 17k+5 网格	模板里 `Math Expression` 会换算；24 fps
分辨率怪	短边 768、总面积上限 768×1344、32 对齐	用 `Resolution Selector`，Megapixels≈1.0 → 约 1344×768
OOM	分辨率或时长过大	降 Megapixels / 缩短 duration / `--lowvram`
生成很慢	默认 attention	可选 SageAttention + KJNodes，或 `--use-sage-attention`
大文件下载反复超时	hf-mirror / CDN 不稳定	`source /etc/network_turbo` + §4.5.2 aria2c（见 §9.F）

B.7 第一次出视频

模板库打开 MiniMax H3 T2V
确认五个加载器下拉框都能选到文件
Resolution Selector：Aspect 16:9，Megapixels 1.0，Multiple 32
写 prompt：场景 + 分镜 + 对白/音效/音乐（官方 Prompt Guide）
Duration 约 5 秒先试跑
Queue → 输出在 output/，格式 MP4（含立体声）

B.8 安装自检（MiniMax H3 T2V）

本机 2026-08-19 已验证下载完成 （du -b 实测）：

文件	实测体积
`minimax_h3_fl2va_pruned_int8_convrot.safetensors`	19.53 GB
`qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`	14.61 GB
`minimax_h3_video_vae_fp16.safetensors`	4.85 GB
`minimax_h3_audio_vae_fp32.safetensors`	0.56 GB
`minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors`（可选）	1.82 GB

运行前再确认：

五个 .safetensors 已在对应 models/ 子目录（核心四件 + 可选 LoRA）
CLIPLoader type = minimax
两个 VAE 都已加载
模板 Queue 一次，得到 带声音的 MP4

ComfyUI 安装新模型

在 ComfyUI 安装新模型：以 Z-Image-Turbo 走完整一遍

0. 先记住这套通用流程

1. 这个模型是什么（只记会影响安装的部分）

2. 环境：先让 ComfyUI 能稳定启动

2.1 版本要求

2.2 启动方式（AutoDL / 云主机）

2.3 启动阶段真实踩过的坑

3. 找对文件源：这是最容易走错的一步

4. 从工作流 JSON 读出「购物清单」

4.5 通用下载流程（AutoDL / 国内云主机）

4.5.1 选哪种方式

4.5.1b 填 expect_gb：用 X-Linked-Size（不要信 Content-Length）

4.5.2 通用 aria2c 批量下载（推荐）

4.5.3 备选：huggingface-cli（镜像）

4.5.4 下完必做校验

4.5.5 跑图报缺模型：只补漏，不要整套重下

5. 下载并放到正确目录

5.1 建目录

5.2 下载 Z-Image-Turbo 三件套

5.3 放完后必须刷新

5.4 目录放错的典型症状

6. 加载官方工作流并核加载器

6.1 打开模板

6.2 三个加载器必须逐项核对

6.3 采样侧也有「装对了但图很差」的开关

7. 第一次出图

8. 可选扩展（装完主模型再做）

8.1 Fun Union ControlNet

8.2 显存不够时

8.3 多模型共用权重

9. 坑点手册（安装 + 第一次出图）

A. 模板 / 节点

B. 文件看不见 / 加载失败

C. 能跑但图不对

D. ControlNet

E. 运行环境（和模型无关，但会被误判成模型坏了）

F. 下载中断 / 超时

10. 把同一套流程套到其它模型

10.1 对照表

10.2 操作时只问自己这 8 个问题

10.3 读 JSON 的最快办法

11. 安装完成自检

附录：本机相关路径

附录 B：同一套流程安装 MiniMax H3（音视频联合生成）

B.1 版本与节点

B.2 购物清单（T2V 官方推荐组合）

B.3 加载器核对（和 Z-Image 不同的点）

B.4 下载命令

B.5 磁盘与共存（本机当前状况）

B.6 MiniMax 特有坑点

B.7 第一次出视频

B.8 安装自检（MiniMax H3 T2V）

4.5.1b 填 `expect_gb`：用 `X-Linked-Size`（不要信 Content-Length）