手把手教你安装 Z-Image-Turbo 文生图模型

# 先安装下载工具
pip3 install modelscope

# 创建下载脚本
cat > download_zimage.py << 'EOF'
from modelscope import snapshot_download

print('开始下载 Z-Image-Turbo 模型...')

download_path = snapshot_download(
    'Tongyi-MAI/Z-Image-Turbo',
    cache_dir='/root/autodl-tmp/Z-Image-Turbo'
)

print(f'下载完成！位置：{download_path}')
EOF

# 运行下载
python3 download_zimage.py

1.3 下载进度

模型大小：约 30GB
下载速度：5-30 MB/s（取决于网络）
预计时间：20-60 分钟

❌ 遇到的第一个坑：磁盘空间不足！

问题描述

下载到一半，突然报错：

OSError: No space left on device

原因分析

租用的服务器默认只有 50GB 硬盘，但模型需要 30GB，加上系统和其他文件，空间不够了！

解决方法

方法 1：清理不需要的文件

# 查看哪些文件占空间
du -sh /root/autodl-tmp/* | sort -hr

# 删除不需要的文件
rm -rf /root/autodl-tmp/旧项目文件夹

方法 2：扩容硬盘（推荐）

登录 AutoDL 网站
找到你的实例
点击"扩容"
选择 100GB 或更大
等待扩容完成

经验教训：开始前先检查空间！

df -h  # 查看磁盘空间

🔧 第二步：安装依赖

2.1 找到正确的 Python 环境

大坑预警！ 服务器里可能有多个 Python，一定要用对！

# 检查 Python 版本
python3 --version  # 可能是系统 Python

# 查找 conda 环境
find /root -name 'python*' -type f

# 使用正确的 Python（比如 miniconda）
/root/miniconda3/bin/python3 --version

2.2 安装必要的库

# 使用正确的 pip
/root/miniconda3/bin/pip3 install modelscope diffusers transformers accelerate

❌ 遇到的第二个坑：版本冲突地狱！

问题 1：导入错误

ImportError: cannot import name 'AuxRequest' from 'torch.nn.attention.flex_attention'

原因：PyTorch 版本太旧，和新版 transformers 不兼容

解决：

# 升级 PyTorch
pip3 install --upgrade torch

问题 2：ZImagePipeline 找不到

ImportError: cannot import name 'ZImagePipeline' from 'diffusers'

原因：diffusers 官方版本还不支持 Z-Image-Turbo

解决：

# 安装最新版 diffusers（从 GitHub）
pip3 uninstall diffusers -y
pip3 install git+https://github.com/huggingface/diffusers.git

问题 3：transformers 版本不匹配

ImportError: cannot import name 'Dinov2WithRegistersConfig' from 'transformers'

原因：diffusers 需要新版 transformers

解决：

pip3 install --upgrade transformers

问题 4：PyTorch 内部错误

ImportError: cannot import name 'TransformGetItemToIndex' from 'torch._dynamo'

原因：transformers 5.4.0 需要 PyTorch 2.6+

最终解决方案：

# 确认使用正确的 Python 环境
/root/miniconda3/bin/python3 -c 'import torch; print(torch.__version__)'
# 应该显示 2.8.0+cu128 或更高版本

经验教训：

开始前检查所有版本
使用 conda 环境管理依赖
不要混用系统 Python 和 conda Python

🎨 第三步：生成图片

3.1 创建生成脚本

#!/usr/bin/env python3
"""用 Z-Image-Turbo 生成图片"""

import torch
from diffusers import ZImagePipeline

# 模型路径
model_path = "/root/autodl-tmp/Z-Image-Turbo/Tongyi-MAI/Z-Image-Turbo"

# 加载模型
print("加载模型...")
pipe = ZImagePipeline.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16  # 使用 bfloat16 节省显存
)

# 使用 GPU
pipe = pipe.to("cuda")
print(f"GPU: {torch.cuda.get_device_name(0)}")

# 提示词（告诉 AI 你想画什么）
prompt = "一只可爱的小猫正在吃一个鸡腿，特写镜头"
negative_prompt = "ugly, deformed, noisy, blurry, distorted"

# 生成图片
print("开始生成...")
image = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    num_inference_steps=28,  # 推理步数
    guidance_scale=5.5,       # 指导比例
    width=512,
    height=512,
    generator=torch.Generator(device="cuda").manual_seed(42)
).images[0]

# 保存图片
image.save("/root/autodl-tmp/cute_cat.png")
print("生成成功！")

3.2 运行脚本

/root/miniconda3/bin/python3 generate_cat.py

❌ 遇到的第三个坑：图片全黑！

问题描述

脚本显示成功，但生成的图片是全黑的！

原因分析

float16 数值不稳定：某些计算会产生 NaN（非数字）
MPS 兼容性问题：Mac 的 GPU 加速有 bug
显存不足：导致计算错误

解决方法

尝试 1：使用 float32

pipe = ZImagePipeline.from_pretrained(
    model_path,
    torch_dtype=torch.float32
)

结果：显存爆了！RTX 5090 32GB 都不够 ❌

尝试 2：使用 bfloat16（成功！）

pipe = ZImagePipeline.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16
)

结果：成功！图片正常 ✅

经验教训：

bfloat16 比 float16 更稳定
生成后检查图片统计信息
不要盲目相信"成功"提示

❌ 遇到的第四个坑：选错 Python 环境

问题描述

一直报错版本冲突，怎么升级都没用。

原因分析

服务器里有两个 Python：

/usr/bin/python3 → PyTorch 2.5.1（太旧）❌
/root/miniconda3/bin/python3 → PyTorch 2.8.0（正确）✅

我一直用错成第一个了！

解决方法

# 检查当前 Python
which python3
python3 -c 'import torch; print(torch.__version__)'

# 使用正确的 Python
/root/miniconda3/bin/python3 your_script.py

经验教训：开始前先确认环境！

✅ 最终成功！

完整检查清单

# 1. 检查磁盘空间
df -h  # 确保有 100GB+

# 2. 检查 Python 环境
/root/miniconda3/bin/python3 -c 'import torch; print(torch.__version__)'
# 应该显示 2.8.0+cu128

# 3. 检查模型文件
du -sh /root/autodl-tmp/Z-Image-Turbo
# 应该显示约 31G

# 4. 检查依赖
/root/miniconda3/bin/pip3 list | grep -E 'torch|diffusers|transformers'

# 5. 测试生成
/root/miniconda3/bin/python3 generate_cat.py

成功标志

✅ 模型加载完成（约 20 秒）
✅ 使用 NVIDIA GPU 加速
✅ 生成成功！
✅ 图片统计：min=0, max=255, mean=xxx（不是全黑）

📊 性能数据

项目	数据
模型大小	30.64 GB
下载时间	20-60 分钟
模型加载	20-30 秒
图片生成（512×512）	5 秒
图片生成（1024×1024）	40 秒
显存占用	约 30GB
GPU	NVIDIA RTX 5090

🎯 关键经验总结

1. 空间要够

开始前检查磁盘空间
不够就扩容，不要侥幸

2. 环境要对

找到正确的 Python
检查 PyTorch 版本
不要混用环境

3. 版本要新

PyTorch 2.8.0+
diffusers 最新版（从 GitHub）
transformers 最新版

4. 数据类型要选对

用 bfloat16，不要用 float16
float32 显存不够

5. 下载要选对地方

国内用魔搭（ModelScope）
不要用 HuggingFace（太慢）

🆘 常见问题 FAQ

Q1: 下载太慢怎么办？

A: 用魔搭，不要用 HuggingFace。魔搭是国内的，速度快。

Q2: 显存不够怎么办？

降低分辨率（512×512 而不是 1024×1024）
减少推理步数（28 步而不是 50 步）
使用 bfloat16

Q3: 图片全黑怎么办？

用 bfloat16 代替 float16
检查提示词是否太复杂
固定随机种子

Q4: 导入错误怎么办？

检查 PyTorch 版本
升级 diffusers 和 transformers
确保使用正确的 Python 环境

🎉 结语

安装 Z-Image-Turbo 确实不容易，会遇到很多坑。但只要按照本文的步骤，注意每一个警告和错误，你一定能成功！

记住：不要怕犯错，每一个错误都是学习的机会！

祝你玩得开心，画出漂亮的图片！🎨✨

本文基于真实安装经历编写，所有错误都实际遇到过并已解决。
最后更新：2026 年 3 月 27 日

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

掌控机器人行为的核心密码：深入解析状态空间及其在机器人开发中的实践

AtomGit开源社区

SFT 微调实战：LoRA / QLoRA / 全参微调对比

AtomGit开源社区

Python爬虫实战：构建你的“开源示例代码”本地索引库！

AtomGit开源社区

所有评论(0)

查看更多评论

张3蜂

@AngelCryToo

已为社区贡献5条内容

手把手教你安装 Z-Image-Turbo 文生图模型

张3蜂

📖 前言

🛠️ 准备工作

你需要什么？

什么是 AutoDL？

📥 第一步：下载模型

1.1 选择下载源

1.2 开始下载

1.3 下载进度

❌ 遇到的第一个坑：磁盘空间不足！

问题描述

原因分析

解决方法

🔧 第二步：安装依赖

2.1 找到正确的 Python 环境

2.2 安装必要的库

❌ 遇到的第二个坑：版本冲突地狱！

问题 1：导入错误

问题 2：ZImagePipeline 找不到

问题 3：transformers 版本不匹配

问题 4：PyTorch 内部错误

🎨 第三步：生成图片

3.1 创建生成脚本

3.2 运行脚本

❌ 遇到的第三个坑：图片全黑！

问题描述

原因分析

解决方法

❌ 遇到的第四个坑：选错 Python 环境

问题描述

原因分析

解决方法

✅ 最终成功！

完整检查清单

成功标志

📊 性能数据

🎯 关键经验总结

1. 空间要够

2. 环境要对

3. 版本要新

4. 数据类型要选对

5. 下载要选对地方

🆘 常见问题 FAQ

Q1: 下载太慢怎么办？

Q2: 显存不够怎么办？

Q3: 图片全黑怎么办？

Q4: 导入错误怎么办？

🎉 结语

所有评论(0)

温馨提示：您尚未绑定手机号

张3蜂