Z-Image-Turbo 로컬 설치 및 실행 가이드 (Python, Diffusers, 저사양 VRAM 설정)

이 가이드는 알리바바 Tongyi Lab이 공개한 Z-Image-Turbo(Tongyi-MAI/Z-Image-Turbo)를 Windows, Linux 또는 macOS 로컬 환경에 설치하고 실행하는 방법을 설명합니다. 60억(6B) 파라미터 단일 스트림 확산 트랜스포머(S3-DiT) 아키텍처를 기반으로 하며, 단 8 NFEs(num_inference_steps=9, guidance_scale=0.0)만으로 실사급 1024×1024 이미지와 선명한 영문·한자 타이포그래피를 생성합니다.

16GB VRAM 그래픽카드가 없으신가요? 12GB 이상의 가중치 다운로드나 CUDA 환경 설정 없이 Z-Image 온라인 워크스페이스 또는 Z-Image-Turbo 모델 페이지에 로그인하여 무료 스타터 크레딧으로 클라우드 GPU에서 1초 미만 초고속 생성을 바로 경험해 보세요.

권장 하드웨어 및 소프트웨어 사양

네이티브 bfloat16 정밀도로 원활하게 추론하려면 다음 환경을 권장합니다.

• 권장 GPU: 16GB 이상 VRAM을 탑재한 NVIDIA GPU (RTX 4080, RTX 4090, RTX 3090, RTX 4060 Ti 16GB, A10G, H100 등).
• 8GB ~ 12GB VRAM GPU: enable_model_cpu_offload()(CPU 오프로드) 옵션 또는 ComfyUI의 FP8 / GGUF 양자화 가중치를 통해 구동할 수 있습니다(생성 속도는 다소 느려질 수 있음).
• 시스템 메모리 및 저장 공간: 시스템 RAM 24GB 이상, 모델 체크포인트 저장을 위한 SSD 여유 공간 약 20GB 이상.
• 소프트웨어: Python 3.10 이상 및 정상 설치된 NVIDIA CUDA 12.1 이상.

1. Python 가상환경 생성

기존 Python 프로젝트나 다른 AI 패키지와 의존성이 충돌하지 않도록 전용 가상환경 zimage-env를 생성합니다. 터미널(또는 PowerShell)을 열고 아래 명령어를 실행하세요.

python -m venv zimage-env

가상환경을 활성화합니다.

# Linux 또는 macOS
source zimage-env/bin/activate

# Windows (명령 프롬프트 / PowerShell)
zimage-env\Scripts\activate

2. PyTorch 및 Hugging Face Diffusers 설치

사용 중인 CUDA 버전에 맞는 PyTorch를 설치합니다(아래 예시는 CUDA 12.4 기준이며, CUDA 12.1 또는 12.6 환경이라면 --index-url을 조정하세요). 최신 ZImagePipeline 지원을 위해 diffusers는 GitHub 소스에서 직접 설치하고, 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)를 생성하고 Hugging Face 허브에서 Tongyi-MAI/Z-Image-Turbo 체크포인트를 불러옵니다. 화질 손실 없이 VRAM 점유율을 줄이기 위해 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 단계 증류(step distillation)가 적용된 모델이므로 일반 확산 모델과 추론 파라미터가 다릅니다.

• num_inference_steps=9로 설정합니다(내부적으로 8회 DiT 순전파 / 8 NFEs 수행).
• guidance_scale=0.0으로 유지합니다(증류된 Turbo 모델은 별도의 CFG 스케일이 필요하지 않습니다).

prompt = (
    "Rainy Seoul alley at night, warm glowing cafe sign clearly reading "
    "'SEOUL ROASTERS', realistic reflections on wet pavement, 35mm lens photography"
)

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 및 모델 컴파일)

RTX 30 / 40 시리즈 및 A100 / H100 등 지원 GPU에서는 Flash Attention 2와 torch.compile()을 활성화하여 반복 생성 시 지연 시간을 더욱 단축할 수 있습니다.

# Flash Attention 백엔드 활성화
pipe.transformer.set_attention_backend("flash")

# 선택 사항: 반복 추론 가속을 위한 S3-DiT 트랜스포머 컴파일
# pipe.transformer.compile()

6. 저사양 VRAM 모드 (8GB ~ 12GB GPU용 CPU 오프로드)

8GB 또는 12GB 그래픽카드에서 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 온라인 생성기를 이용하세요.