如何在本地安装 Z-Image Turbo

本指南介绍如何在你的电脑上配置 Z-Image Turbo。这是一个 60 亿参数的图像生成模型。运行该模型需要一张性能较强的显卡。你将使用 Python 和终端命令行来完成操作。

硬件和软件要求

你需要特定的硬件才能顺畅运行此模型。显卡最好拥有 16 GB 显存。主流的消费级显卡或服务器显卡通常都能满足要求。显存较低的设备也能运行，但速度会慢很多。你还需要安装 Python 3.9 或更高版本。请确保电脑上已经配置好了 CUDA 环境。

创建虚拟环境

建议使用虚拟环境来隔离项目依赖。这可以防止与其他 Python 项目发生冲突。打开你的终端程序。运行下方命令创建一个名为 zimage-env 的新环境。

python -m venv zimage-env

激活环境以开始后续步骤。

# Linux 或 macOS 系统
source zimage-env/bin/activate

# Windows 系统
zimage-env\Scripts\activate

安装 PyTorch 和核心库

你需要安装支持 GPU 加速的 PyTorch 版本。下方命令使用的是 CUDA 12.4 版本。如果你的 CUDA 版本不同，请调整对应的下载链接。你需要直接从源代码安装 diffusers 库。同时安装 transformers 和 accelerate 等必要组件。

pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install git+https://github.com/huggingface/diffusers
pip install transformers accelerate safetensors

加载 Z-Image Turbo 流程

创建一个 Python 脚本来加载模型。我们将使用 ZImagePipeline 类。这段代码会自动从 Hugging Face 仓库下载模型。使用 bfloat16 精度加载可以节省显存。最后将模型移动到 CUDA 设备上运行。

import torch
from diffusers import ZImagePipeline

pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=False,
)
pipe.to("cuda")

生成第一张图片

现在可以生成图片了。定义一个文本提示词来描述场景。将图片尺寸设置为 1024x1024 像素。该模型在 9 步推理下效果很好。将引导系数（guidance scale）设置为 0.0。执行代码后图片将保存到当前目录。

prompt = "City street at night with clear bilingual store signs, warm lighting, and detailed reflections on wet pavement."

image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=9,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(123),
).images[0]

image.save("z_image_turbo_city.png")

性能优化选项

如果硬件支持，你可以开启优化以提升速度。启用 Flash Attention 2 可以加速 Transformer 计算。你也可以选择编译模型模块。这些步骤是可选的。

# 切换 Attention 后端
pipe.transformer.set_attention_backend("flash")

# 编译模型
# pipe.transformer.compile()

低显存模式

显存有限的设备可以使用 CPU 卸载功能。这会在闲置时将部分模型数据转移到系统内存中。这样可以让大模型在小显存显卡上运行。生成图片的时间会因此变长。

pipe.enable_model_cpu_offload()