如何在本機安裝與執行 Z-Image-Turbo（Python、Diffusers 與低顯示記憶體指南）

本指南詳細說明如何在個人電腦（Windows、Linux 或 macOS）本機安裝並執行阿里巴巴通義實驗室開源的 Z-Image-Turbo（Tongyi-MAI/Z-Image-Turbo）。此模型採用 60 億參數（6B）單流擴散 Transformer（S3-DiT） 架構，僅需 8 次函數評估（8 NFEs，num_inference_steps=9） 且無需額外無分類器引導（guidance_scale=0.0），即可輸出商業級寫實攝影與清晰準確的中英文雙語字體。

手邊沒有 16 GB VRAM 顯示卡？ 免下載超過 12 GB 的模型權重，也無需設定 CUDA 環境，直接前往 Z-Image 線上工作台 或 Z-Image-Turbo 模型專頁，登入即可領取免費雲端 GPU 體驗點數，享受亞秒級生圖速度。

硬體與軟體需求

若要以原生 bfloat16 精度流暢執行推論，建議具備以下環境：

• 建議顯示卡（GPU）：具備 16 GB 以上顯示記憶體（VRAM） 的 NVIDIA 顯示卡（例如 RTX 4080、RTX 4090、RTX 3090、RTX 4060 Ti 16GB、A10G 或 H100）。
• 8 GB – 12 GB VRAM 顯示卡：可透過 enable_model_cpu_offload()（CPU 記憶體卸載）或在 ComfyUI 中載入 FP8 / GGUF 量化權重運作（單張生圖時間會稍長）。
• 系統記憶體與硬碟空間：建議至少 24 GB 系統記憶體（RAM）以及約 20 GB 以上的可用 SSD 空間。
• 基礎軟體：Python 3.10 以上版本，並已正確安裝 NVIDIA 驅動程式與 CUDA 12.1+。

1. 建立獨立的 Python 虛擬環境

使用虛擬環境隔離套件相依性，避免與電腦中其他 AI 專案衝突。開啟終端機（或 PowerShell），建立名為 zimage-env 的虛擬環境：

python -m venv zimage-env

啟用虛擬環境：

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

# Windows（命令提示字元 / PowerShell）
zimage-env\Scripts\activate

2. 安裝 PyTorch 與 Hugging Face Diffusers

安裝支援 GPU 加速的 PyTorch（下方指令對應 CUDA 12.4；若您的環境為 CUDA 12.1 或 12.6，請調整 --index-url）。由於 ZImagePipeline 需要最新的 S3-DiT 支援，請直接從 GitHub 原始碼安裝 diffusers，並一併安裝 transformers、accelerate 與 safetensors：

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

3. 載入 Z-Image-Turbo 推論管線

建立一個 Python 腳本（例如 run_zimage.py），透過 ZImagePipeline 從 Hugging Face 載入 Tongyi-MAI/Z-Image-Turbo，並使用 torch.bfloat16 精度兼顧畫質與顯示記憶體用量：

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")

4. 生成 1024×1024 高畫質影像（8 NFEs）

Z-Image-Turbo 經過 Decoupled-DMD 步數蒸餾，推論參數與傳統 30–50 步擴散模型不同：

• 將 num_inference_steps 設為 9（對應底層 8 次 DiT 前向評估 / 8 NFEs）。
• 將 guidance_scale 設為 0.0（蒸餾權重已內建引導效果，無需額外 CFG 計算）。

prompt = (
    "台北雨夜街角咖啡館特寫，溫暖霓虹招牌清晰寫著「深夜焙茶室 MIDNIGHT TEA」，"
    "濕潤柏油路面倒映暖色燈光，35mm定焦鏡頭電影感寫實攝影"
)

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

image.save("z_image_turbo_output.png")

5. 推論加速選項（Flash Attention 與模型編譯）

在支援的 NVIDIA GPU（RTX 30 / 40 系列、A100、H100）上，啟用 Flash Attention 2 與 torch.compile() 可大幅縮短連續批次生圖的延遲：

# 切換至 Flash Attention 後端
pipe.transformer.set_attention_backend("flash")

# 選用：編譯 S3-DiT 模組（首次執行需預熱編譯，後續推論顯著加速）
# pipe.transformer.compile()

6. 低顯示記憶體模式（適用 8 GB – 12 GB 顯示卡）

若在 8 GB 或 12 GB VRAM 顯示卡上遇到 CUDA out of memory 錯誤，請將 pipe.to("cuda") 替換為 enable_model_cpu_offload()，讓暫時閒置的子模組自動卸載至系統 RAM：

import torch
from diffusers import ZImagePipeline

pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()

進階微調與雲端免安裝方案

• 若需進行自訂 LoRA 訓練、ControlNet 構圖控制或完整負向提示詞（CFG）微調，請參考未蒸餾基底模型：Z-Image-Base 模型專頁。
• 若想在瀏覽器免設定直接體驗極速生圖，歡迎前往 Z-Image-Turbo 線上產生器。