Z-Image-Turbo 完整实践指南

文档版本: v4.0 – 基于实际实践内容调整，去除 AI 润色内容
最后更新: 2025-12-05
适用设备: Mac Mini M4 32GB RAM
实测模型: Z-Image-Turbo (阿里巴巴通义实验室)

前言

给自己叠个甲：

全文都是自己的实践，内容是自己写的，文档一开始写了很多份，想着发到 L 站直接就整合一份完整的文档
就用了 CC 帮我整合了，没曾想，有个 AIGC 的限制，我的锅，只能手工调回来再重新发一遍了

什么是 Z-Image-Turbo

核心特性

Z-Image-Turbo 是阿里巴巴通义实验室于 2025 年底发布的高效图像生成模型。

60 亿参数高效图像生成模型
8 步采样即可生成高质量图像
Apache 2.0 开源协议（完全商用友好）
支持中英文双语文本渲染（中文表现优异）
专为消费级硬件优化（16GB+ RAM 即可运行）
基于 S3-DiT 单流 Transformer 架构

对我们普通硬件消费者而言

蒸馏优化：从大模型蒸馏到 8 步推理，大大减少生成时间
中文理解能力强：基于 Qwen 3 4B 文本编码器
Apple Silicon 友好：支持 MPS (Metal Performance Shaders) 后端

硬件要求与性能

官方推荐配置

最低配置

硬件	最低要求	推荐配置
GPU	8GB VRAM	12GB+ VRAM
内存	16GB RAM	32GB+ RAM
磁盘	40GB 可用空间	60GB+ 可用空间
系统	Windows 10/11, macOS 12.3+, Ubuntu 20.04+(Linux 其他的系统应该也可以，我只测试过 Ubuntu)	–

各平台推荐配置

NVIDIA GPU（最佳性能，推荐，我没有 N 卡，我看油管博主和 B 站 UP 主推荐的）

配置等级	GPU 型号	VRAM	预期性能 @ 768×768
入门级	RTX 3080 / RTX 4060 / RTX 4070 / RTX 5060	8 – 12GB	15-30秒
主流级	RTX 4070 Ti / RTX 5060 Ti / RTX 5070 Ti	12 – 16GB	10-20秒
专业级	RTX 4080 / RTX 4090 / RTX 5080 / RTX 5090	16-32GB	5-15秒
工作站	A6000 / H100	48-80GB	<5秒

特点：

CUDA 优化最好，社区支持最完善，支持 FP8/INT4/INT8 等多种量化模型

Apple Silicon（Mac 用户）

配置等级	芯片型号	统一内存	预期性能 @ 768×768
入门级	M系列芯片即可	16GB	60-120秒
主流级	M系列芯片即可	24-32GB	40-80秒
专业级	M系列芯片即可	36-48GB	30-60秒
顶配	M系列芯片即可	64-128GB	20-50秒

特点：

笔记本也能运行，功耗低，噪音小，GPU 和 CPU 统一共享内存，但是仅支持 BF16 和 UINT4

AMD GPU（仅推荐在原生 Linux 的用户使用）

在 Windows 没有受支持的 ROCm 服务，~~并且使用 WSL 的 Ubuntu 系统也无法直通硬件(驱动问题)~~，是 6000 系列显卡的支持问题，根据 comfy 的手动安装文档来安装，最后在本人已经在 windows11 上基于 rx6600xt & rx6950xt 试验了，无法找到 HIP 显卡, 7000 系及以上的显卡可以使用 WSL + Ubuntu 的方式进行尝试，参照 45 楼佬友的成功案例： Z-Image-Turbo 完整实践指南 – #45，来自 rellAXL

-- 错误信息
(venv) lostsheep@lostsheep-windows:~/x-images/ComfyUI$ python main.py
Checkpoint files will always be loaded safely.
Traceback (most recent call last):
  File "/home/lostsheep/x-images/ComfyUI/main.py", line 176, in <module>
    import execution
  File "/home/lostsheep/x-images/ComfyUI/execution.py", line 15, in <module>
    import comfy.model_management
  File "/home/lostsheep/x-images/ComfyUI/comfy/model_management.py", line 238, in <module>
    total_vram = get_total_memory(get_torch_device()) / (1024 * 1024)
                                  ^^^^^^^^^^^^^^^^^^
  File "/home/lostsheep/x-images/ComfyUI/comfy/model_management.py", line 188, in get_torch_device
    return torch.device(torch.cuda.current_device())
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/lostsheep/x-images/venv/lib/python3.12/site-packages/torch/cuda/__init__.py", line 878, in current_device
    _lazy_init()
  File "/home/lostsheep/x-images/venv/lib/python3.12/site-packages/torch/cuda/__init__.py", line 314, in _lazy_init
    torch._C._cuda_init()
RuntimeError: No HIP GPUs are available

配置等级	GPU 型号	VRAM	ROCm 支持
主流级	RX 6800 XT / RX 6950 XT / RX 7800XT	16GB	Linux 受支持
专业级	RX 7900XT / RX 7900 XTX / RX 9070 XT	24GB	Linux 受支持
工作站	MI250 / MI300	128GB+	Linux 受支持

特点：

windows 原生 ROCm 不支持，~~windows 下可能需要 Zluda 的整合包(B 站有成功案例)~~, 我使用了 Zluda 仓库的指导方式进行安装和使用，也有部份问题，参考 75 楼我的报错信息 Z-Image-Turbo 完整实践指南 – #75，来自 lostsheep ，不过其他佬友使用 B 站 up 主的一个整合包没有出现这个问题，后面再看看这个整合包的方式
7000 系列显卡可以使用 WSL + Ubuntu 的方式根据 comfy 的手工安装方式进行

注意，非原生 Linux 用户不建议尝试了，真的很折腾，心累(就是那种浪费几个小时看不到结果的那种心累)，有时间的佬友的可以试试

Mac Mini M4 32GB RAM 实测数据

项目	说明
内存	32GB 超过官方建议（16GB+）
MPS 后端	Metal 3 / Metal 4 支持
量化支持	支持 BF16 和 UINT4（不支持 FP8）
实测速度	237-471 秒/张（取决于方案和配置）

真实性能数据（完整测试）

ComfyUI Desktop + LoRA: 214秒 @ 1024×1024（最快方案）
ComfyUI Desktop（无 LoRA）: 300 – 400秒 @ 1024×1024

Gradio 量化版（无 LoRA）: 255秒 @ 1024×1024

Loading Z-Image-Turbo UINT4 (quantized) on mps...
Loading pipeline components...:  80%|██████████████████████████████████████████████████████████████████████████████████████████▍                      | 4/5 [00:03<00:00,  1.17it/s]`torch_dtype` is deprecated! Use `dtype` instead!
Loading pipeline components...: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 5/5 [00:08<00:00,  1.76s/it]
Pipeline loaded on mps! (Model: quantized)
100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 8/8 [04:15<00:00, 31.91s/it]

Gradio + LoRA: 417秒 @ 1024×1024（不推荐）

Switching from quantized to full model...
Loading Z-Image-Turbo (full precision) on mps...
Loading checkpoint shards: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 3/3 [00:34<00:00, 11.33s/it]
Loading checkpoint shards: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 3/3 [00:00<00:00, 17.93it/s]
Loading pipeline components...: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 5/5 [00:34<00:00,  6.91s/it]
Pipeline loaded on mps! (Model: full)
100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 8/8 [06:57<00:00, 52.21s/it]

方案选择建议

方案对比（基于完整实测数据）

方案	界面	不带 LoRA	带 LoRA	安装难度	实测评价
方案 1：ComfyUI Desktop	节点工作流	300-400秒	214秒	非常简单	最推荐
方案 2：Gradio 量化版 / 无量化版	Web UI	278秒	417秒	简单	仅限无 LoRA 场景

最终推荐：方案 1（ComfyUI Desktop）

推荐理由

加载 LoRA 时最快：214秒（唯一低于 4 分钟的方案）
不加 LoRA 也很快：400秒左右，与 Gradio 量化版相当
节点工作流灵活：适合复杂工作流组合
安装简单：官方应用，双击安装
LoRA 管理方便：节点化操作，社区资源丰富
同时支持 CUDA 显卡& Apple Silicon 芯片 & AMD 显卡(仅限 Linux 系统)

文件名	大小	下载地址	存放路径
z_image_turbo_bf16.safetensors	11.46GB	Hugging Face	`~/ComfyUI/models/diffusion_models/`
qwen_3_4b.safetensors	6.8GB	Hugging Face	`~/ComfyUI/models/text_encoders/`
ae.safetensors	335MB	Hugging Face	`~/ComfyUI/models/vae/`

配置	生成时间	说明
不带 LoRA	400秒	性能稳定
加载 LoRA	214秒	最快方案

备选安装方案

方案 2：Ultra-Fast-Image-Generation（Gradio Web UI）

GitHub 仓库：GitHub – newideas99/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image: 6B parameter image gen that actually runs fast on your Mac. 14 seconds. No cloud. No GPU rental.

重要提示**：此方案仅推荐用于不使用 LoRA 的场景。加载 LoRA 后性能显著下降。

前置条件

已安装 pyenv 和 Python 3.11（推荐）

如果没有，先安装：

# 安装 pyenv
brew install pyenv

# 安装必要的系统库（重要！）
brew install xz  # 提供 lzma 支持，必须先安装

# 安装 Python 3.11.14
pyenv install 3.11.14

详细安装步骤

1. 克隆仓库

Shell 命令：

cd ~/programing/projects/z-image
git clone https://github.com/newideas99/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image.git
cd Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image

2. 设置 Python 版本并创建虚拟环境

Shell 命令：

# 为项目设置 Python 版本（类似 .nvmrc）
pyenv local 3.11.14

# 验证版本
python --version  # 应该显示 3.11.14

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 提示符变成：(venv) username@hostname:~/path$

3. 安装依赖

shell 命令：

# 升级 pip
pip install --upgrade pip

# 安装项目依赖
pip install -r requirements.txt

预期安装时间：5-10 分钟

4. 模型下载说明

重要：程序会自动从 Hugging Face 下载模型，不需要手动下载。

自动下载的模型：

量化版本（默认，无 LoRA 时使用）：
- 来源：Disty0/Z-Image-Turbo-SDNQ-uint4-svd-r32
- 大小：约 3.5GB
- 速度：278 秒/张 @ 768×768
- 内存占用：4-5GB
完整版本（加载 LoRA 时自动下载）：
- 来源：Tongyi-MAI/Z-Image-Turbo
- 大小：约 32GB
- 速度：471 秒/张 @ 768×768（非常慢）
- 内存占用：12-15GB

首次启动时：

会自动下载量化版本（3.5GB）
约 5-10 分钟（取决于网速）
下载后永久缓存在 ~/.cache/huggingface/hub/

加载 LoRA 时：

首次加载会自动下载完整版本（32GB）
约 15-30 分钟（取决于网速）
只下载一次，之后直接使用缓存

5. 启动 Gradio Web UI

# 确保在项目目录
cd ~/programing/projects/z-image/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image

# 确保虚拟环境已激活
source venv/bin/activate

# 启动 Gradio
python app.py

成功启动的日志：

Loading Z-Image-Turbo UINT4 (quantized) on mps...
Downloading model files...  (首次启动)
Pipeline loaded on mps! (Model: quantized)
* Running on local URL:  http://127.0.0.1:7860

这时使用浏览起打开： http://127.0.0.1:7860
可以看到正常的 UI 界面：

6. 生成第一张图片

在 Gradio 界面中：

输入提示词（支持中英文）：

一位身穿泳装的亚洲美女站在泳池边，阳光明媚，专业摄影，8k高清

设置参数（推荐值）：
- Height: 768
- Width: 768
- Steps: 8
- Guidance Scale (CFG): 1.0
- Device: mps
点击 Generate 按钮

首次生成预期：

时间：60-90 秒（需要加载模型到内存）
后续生成（量化版，无 LoRA）：278 秒/张
加载 LoRA 后：471 秒/张

性能问题：

量化版性能与 ComfyUI Desktop 相当（278秒 vs 280-320秒）
加载 LoRA 后性能暴跌到 471秒（比 ComfyUI + LoRA 慢 99%）
如需使用 LoRA，强烈推荐使用 ComfyUI Desktop（237秒）

快捷启动脚本（可选）

创建启动脚本方便日常使用：

# 创建启动脚本
# 将你的项目路径替换掉这个：<~/programing/projects/z-image/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image>
# 下面的路径都同上
cat > ~/programing/projects/z-image/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image/start.sh << 'EOF'
#!/bin/bash
cd ~/programing/projects/z-image/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image
source venv/bin/activate
python app.py
EOF

chmod +x ~/programing/projects/z-image/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image/start.sh

# 添加别名到 ~/.zshrc
echo 'alias zimage="~/programing/projects/z-image/Ultra-Fast-Image-Generation-Mac-Silicon-Z-Image/start.sh"' >> ~/.zshrc
source ~/.zshrc

以后启动只需一行命令：

zimage

LoRA 使用指南

什么是 LoRA？

LoRA = Low-Rank Adaptation（低秩适配）

通俗解释：

基础模型 = 通用画家（会画各种风格）
LoRA = 风格插件（让画家学会特定风格）
不修改原始模型，只添加小文件（100-500MB）作为”风格调整层”

常见用途：

艺术风格：像素风、油画风、水彩风、胶片风
主题强化：建筑细节、人像优化、风景增强
特定角色：动漫角色、特定 IP

下载 LoRA 资源

网站	免费	下载速度（国内）	资源量	推荐度
Civitai	完全免费	中等	最多	首选
Hugging Face	免费	慢（可用镜像）	一般	备选
GitHub	免费	中等	最少	最后搜索

Civitai 下载步骤

访问 Civitai：
```
https://civitai.com/
```
搜索兼容的 LoRA：
- 搜索：Flux LoRA
- 筛选：Base Model = Flux.1（重要！）
- 排序：按下载量或评分

直达链接（已筛选 Flux LoRA）：

https://civitai.com/models?modelType=LORA&baseModel=Flux.1

下载文件：
- 点击 Download 按钮
- 无需登录，直接下载 .safetensors 文件

兼容性检查清单

在下载前，务必确认：

Base Model 标注为 Flux.1
正确：Flux.1 D, Flux.1 S, Flux Dev
错误：SDXL, SD1.5, SD2.1（不兼容！）
文件格式为 .safetensors
文件大小合理：50MB – 500MB

在 Gradio 中使用 LoRA

加载 LoRA

上传 LoRA 文件：
- 点击 LoRA Settings 部分的 LoRA File 按钮
- 选择下载的 .safetensors 文件
设置 LoRA Strength：
- 0.5-0.7：subtle（微妙效果）
- 0.8-1.0：balanced（平衡，推荐）
- 1.0-1.5：strong（强烈效果）
生成图片：
- 点击 Generate
- 程序会自动切换到完整模型（24GB）
- 首次加载会下载完整模型（约 20-30 分钟）

关键结论：

ComfyUI Desktop + LoRA 是唯一推荐的 LoRA 使用方案（237秒）
Gradio + LoRA 不推荐（417秒）
Gradio 量化版仅适合不使用 LoRA 的场景（278秒）

实测示例

测试 LoRA：Flux_lora_hotgirl02_Vietnamese_RC Hoang.safetensors (328MB)

效果：

兼容性：完美支持
风格影响：强化越南/东南亚女性特征
质量：照片级真实感保持
ComfyUI Desktop 生成速度：237 秒/张 @ 1024×1024（推荐）
Gradio 生成速度：417 秒/张 @ 1024×1024（不推荐）

常见问题解决

Q1: 启动时报错 `ModuleNotFoundError: No module named '_lzma'`

原因：pyenv 安装 Python 时缺少 xz 库。

解决方法：

# 1. 安装 xz
brew install xz

# 2. 重新安装 Python
pyenv uninstall 3.11.14
pyenv install 3.11.14

# 3. 验证
python -c "import lzma; print('lzma OK')"

# 4. 重新创建虚拟环境
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Q2: 首次生成特别慢（5 分钟以上）

这是正常现象！首次生成需要：

下载模型到缓存（3.5GB 量化版或 32GB 完整版）
加载模型到内存
编译 Metal 着色器
预热 MPS 后端

后续生成速度（实测）：

ComfyUI Desktop + LoRA：237秒
ComfyUI Desktop（无 LoRA）：280-320秒
Gradio 量化版（无 LoRA）：278秒

Q3: 加载 LoRA 后开始下载大量文件（32GB）

这是正常行为

原因：

量化版本（3.5GB）不支持 LoRA
加载 LoRA 时自动切换到完整版（32GB）
首次加载会从 Hugging Face 下载

建议：

让它下载完（约 15-30 分钟）
只需下载一次，之后使用缓存
磁盘占用：3.5GB（量化）+ 32GB（完整）≈ 35GB

Q4: 如何获得最快的生成速度？

最快方案：ComfyUI Desktop + LoRA（237秒）

操作步骤：

使用 ComfyUI Desktop
在工作流中加载 LoRA 文件
生成速度：237秒/张（最快）

Q5: 生成的图片质量不够好

调整建议：

提高分辨率：
- 768×768 → 1024×1024
增加步数（轻微提升）：
- 8 steps → 10 steps

优化提示词（最重要）：

# 不够详细
一只猫

# 详细描述
一只橘色短毛猫坐在月球表面的岩石上，穿着宇航服，背景是星空和地球，
摄影级真实感，8k 超高清，专业摄影，电影级光线

加载合适的 LoRA：
- 人像：人像增强 LoRA
- 风景：风景细节 LoRA
- 艺术风格：对应风格 LoRA

Q6: 如何查看已下载的模型位置和大小？

查看缓存位置：

# Hugging Face 缓存目录
ls -lh ~/.cache/huggingface/hub/

# 查看总占用
du -sh ~/.cache/huggingface/hub/

# 预期输出
# 3.5GB  models--Disty0--Z-Image-Turbo-SDNQ-uint4-svd-r32/
# 32GB   models--Tongyi-MAI--Z-Image-Turbo/

Q7: 可以删除量化版本只保留完整版吗？

看情况！

如果你只用 ComfyUI Desktop：

可以删除量化版本
ComfyUI Desktop 不使用量化版本
只需保留完整版（18GB）

如果你也用 Gradio：

不建议删除
不加 LoRA 时，量化版速度和 ComfyUI 相当（278秒 vs 280-320秒）
量化版内存占用更小（5GB vs 12GB）

最佳实践总结

提示词技巧

基本结构：

[主体] + [场景] + [风格] + [质量词]

示例：

一位身穿红色礼服的亚洲女性站在现代办公室中，
自信的表情，专业商务摄影，自然光线，
8k超高清，时尚杂志封面风格

A young Asian woman in red dress standing in modern office,
confident expression, professional business photography, natural lighting,
8k ultra HD, fashion magazine cover style

质量词推荐：

中文：摄影级真实感、8k高清、专业摄影、电影级光线、超高清
英文：photorealistic, 8k ultra HD, professional photography, cinematic lighting, ultra detailed

参考资料

官方文档

社区资源

技术论文

更新日志

v4.0 (2025-12-05)

遵循 AIGC 被禁止的原则调整文章内容

v3.1 (2025-12-04)

添加详细的硬件推荐配置
包含 NVIDIA GPU（CUDA）推荐配置
包含 AMD GPU（ROCm）配置说明
添加各平台预期性能数据

v3.0 (2025-12-04)

基于完整实测数据大幅修正
修正方案推荐：ComfyUI Desktop 为最佳方案
添加完整性能矩阵（不带/带 LoRA）
修正所有错误的性能数据

v2.0 (2025-12-03)

基于初步操作经验重写
推荐方案调整为 Gradio Web UI（已修正）
添加详细的 LoRA 使用指南
添加初步性能数据（存在错误，已修正）
添加常见问题解决方案
添加最佳实践建议

v1.0 (2025-12-03)

初始版本发布
包含三种安装方案对比
基础故障排查指南

社区

社区讨论：

Hugging Face Discussions: Tongyi-MAI/Z-Image-Turbo · Discussions

祝各位佬友生成愉快

秒出高质图像：Z-Image-Turbo 完整实践指南（Mac Mini M4 实测与跨平台调优）