كيفية تثبيت وتشغيل Z-Image-Turbo محلياً (دليل Python وDiffusers والذاكرة المنخفضة)

يشرح هذا الدليل خطوة بخطوة كيفية تثبيت وتشغيل نموذج Z-Image-Turbo (Tongyi-MAI/Z-Image-Turbo) محلياً على أنظمة Windows أو Linux أو macOS. يعتمد النموذج على معمارية S3-DiT أحادية المسار بحجم 6 مليارات معامل (6B)، ويولّد صوراً فوتوغرافية واقعية بدقة 1024×1024 مع نصوص واضحة خلال 8 تقييمات دالة فقط (8 NFEs) (num_inference_steps=9 وguidance_scale=0.0).

لا تمتلك بطاقة رسومية بسعة 16GB VRAM؟ يمكنك تجاوز تنزيل أوزان تتجاوز 12GB وإعدادات CUDA بالكامل: سجّل الدخول إلى مساحة عمل Z-Image السحابية أو جرّب صفحة نموذج Z-Image-Turbo للحصول على رصيد ترحيبي مجاني وتوليد الصور في أقل من ثانية.

متطلبات الأجهزة والبرمجيات

لتشغيل النموذج بدقة bfloat16 الأصلية بسلاسة عالية، نوصي بالمواصفات التالية:

• البطاقة الرسومية الموصى بها (GPU): بطاقة NVIDIA بذاكرة 16 GB VRAM أو أكثر (مثل RTX 4080 أو RTX 4090 أو RTX 3090 أو RTX 4060 Ti 16GB أو A10G أو H100).
• بطاقات 8 GB – 12 GB VRAM: مدعومة عبر تفعيل التفريغ إلى المعالج enable_model_cpu_offload() أو استخدام نسخ مكمّاة FP8 / GGUF داخل ComfyUI (مع زمن توليد أطول نسبياً).
• الذاكرة والتخزين: ذاكرة نظام (RAM) لا تقل عن 24 GB ومساحة تخزين SSD فارغة تقارب 20 GB.
• البرمجيات: Python 3.10 أو أحدث مع تثبيت فعّال لبيئة NVIDIA CUDA 12.1+.

1. إنشاء بيئة Python افتراضية معزولة

اعزل حزم المشروع لتجنّب تعارض الإصدارات مع مشاريع PyTorch الأخرى. افتح الطرفية (Terminal أو PowerShell) وأنشئ البيئة zimage-env:

python -m venv zimage-env

فعّل البيئة الافتراضية:

# على Linux أو macOS
source zimage-env/bin/activate

# على Windows (CMD أو PowerShell)
zimage-env\Scripts\activate

2. تثبيت PyTorch ومكتبة Hugging Face Diffusers

ثبّت إصدار PyTorch المتوافق مع CUDA لديك (الأمر أدناه موجّه لإصدار CUDA 12.4؛ عدّل --index-url إذا كنت تستخدم إصداراً مختلفاً). ولأن الفئة ZImagePipeline تتطلب دعم S3-DiT الحديث، ثبّت مكتبة 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) وحمّل النموذج 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)، تختلف إعدادات الاستدلال عن نماذج الانتشار التقليدية:

• اضبط num_inference_steps=9 (وهو ما يكافئ 8 تمريرات أمامية S3-DiT / 8 NFEs).
• اضبط guidance_scale=0.0 (النموذج المقطّر لا يحتاج إلى توجيه CFG إضافي).

prompt = (
    "Modern luxury cafe terrace in Dubai at dusk, warm architectural lighting, "
    "clean brass sign reading 'OASIS ROASTERY', reflections on marble floor, 35mm lens"
)

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 المتوافقة (سلسلة RTX 30/40 وA100 وH100)، يتيح تفعيل Flash Attention 2 وتجميع المحوّل تسريع التوليد المتكرر بشكل ملحوظ:

# تفعيل واجهة Flash Attention
pipe.transformer.set_attention_backend("flash")

# اختياري: تجميع المحوّل لتسريع الدفعات المتتالية
# pipe.transformer.compile()

6. وضع الذاكرة المنخفضة (لبطاقات 8 GB – 12 GB VRAM)

إذا واجهت خطأ نفاد الذاكرة CUDA out of memory على بطاقات 8 GB أو 12 GB، استبدل 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 السحابي.