صيغ النماذج

تُخزَّن نماذج الانتشار عادةً في صيغة Diffusers أو صيغة الملف الواحد. يمكن تخزين ملفات النموذج بأنواع ملفات مختلفة مثل safetensors أو ckpt.

يشير مصطلح Format إلى ما إذا كانت الأوزان مخزنة في هيكل مجلدات. أما نوع الملف فيشير إلى كيفية تسلسل تلك الأوزان، مثل safetensors أو ckpt.

Diffusers format                    Single-file format
model/                              model.safetensors   (or .ckpt)
├─ model_index.json                 └─ all components in one file
├─ unet/  (or transformer/)
├─ text_encoder/
├─ vae/
└─ scheduler/

ستُظهر لك هذه الدليل كيفية تحميل خطوط الأنابيب والنماذج من هذه الصيغ والملفات.

تنسيق Diffusers

يخزّن صيغة Diffusers كل نموذج (UNet، transformer، text encoder) في مجلد فرعي مستقل. وهناك عدة فوائد لتخزين النماذج بشكل منفصل.

أسرع في تهيئة خط الأنابيب بالكامل، حيث يمكنك تحميل النموذج الفردي الذي تحتاجه أو تحميلها جميعًا بالتوازي.
انخفاض في استهلاك الذاكرة لأنك لا تحتاج إلى تحميل جميع مكونات خط الأنابيب إذا كنت بحاجة إلى نموذج واحد فقط. إعادة استخدام نموذج مشترك بين خطوط أنابيب متعددة.
تقليل متطلبات التخزين لأن النماذج المشتركة بين خطوط الأنابيب المتعددة يتم تنزيلها مرة واحدة فقط.
المرونة في استخدام نماذج جديدة أو محسّنة في خط أنابيب.

تنسيق ملف واحد

يخزّن تنسيق الملف الواحد جميع أوزان النموذج (UNet، transformer، text encoder) في ملف واحد. ومن مزايا تنسيقات الملف الواحد:

توافق أكبر مع ComfyUI أو Automatic1111.
أسهل في تنزيل ملف واحد ومشاركته.

استخدم from_single_file() لتحميل ملف واحد.

import torch
from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

يدعم أسلوب from_single_file() أيضًا تمرير نماذج أو مجدولات جديدة.

import torch
from diffusers import FluxPipeline, FluxTransformer2DModel

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/Kijai/flux-fp8/blob/main/flux1-dev-fp8.safetensors", dtype=torch.bfloat16
)
pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

خيارات التهيئة

تحتوي نماذج صيغة Diffusers على ملف config.json في مستودعاتها يتضمن سمات مهمة مثل عدد الطبقات ورؤوس الانتباه. يحدد تلقائيًا from_single_file() الإعداد المناسب للاستخدام من config.json. ومع ذلك، قد يفشل هذا في بعض الحالات النادرة، وفي هذه الحالة يجب عليك استخدام الحجة config.

يجب عليك أيضاً استخدام معامل config إذا كانت النماذج في خط الأنابيب مختلفة عن التنفيذ الأصلي أو إذا لم يحتوي على البيانات الوصفية اللازمة لتحديد الإعداد الصحيح.

from diffusers import StableDiffusionXLPipeline

ckpt_path = "https://huggingface.co/segmind/SSD-1B/blob/main/SSD-1B.safetensors"

pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path, config="segmind/SSD-1B")

عند تمرير original_config مع local_files_only=True، يستنتج Diffusers مكونات خط المعالجة من توقيع فئة خط المعالجة. ولا يقوم بتنزيل ملفات الإعدادات من Hub، مما يتجنب التغييرات التي قد تكسر التوافق عند العمل دون اتصال. هذا المسار أقل موثوقية من منح config مسار نموذج محلي، وقد يؤدي إلى أخطاء. نفّذ العملية مرة واحدة مع local_files_only=False حتى تُحفظ ملفات الإعدادات في ذاكرة التخزين المؤقت المحلية إذا كنت بحاجة إليها دون اتصال لاحقًا.

يمكنك تجاوز الإعدادات الافتراضية عن طريق تمرير الحُجج مباشرةً إلى from_single_file(). تُظهر الأمثلة أدناه كيفية تجاوز الإعدادات في خط أنابيب أو نموذج.

pipeline

نموذج

الملفات المحلية

تسعى طريقة from_single_file() إلى تكوين خط أنابيب أو نموذج من خلال الاستدلال على نوع النموذج من المفاتيح الموجودة في ملف نقطة التفتيش. على سبيل المثال، يتم تكوين أي ملف نقطة تفتيش أحادي مبني على نموذج Stable Diffusion XL الأساسي من stabilityai/stable-diffusion-xl-base-1.0.

إذا كنت تعمل مع ملفات محلية، فحمّل ملفات الإعداد باستخدام طريقة snapshot_download ونقطة التفتيش للنموذج باستخدام hf_hub_download. يتم تنزيل هذه الملفات إلى مجلد الكاش الخاص بك، لكن يمكنك تنزيلها في مجلد محدد باستخدام الحجة local_dir.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors"
)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

رابط رمزي

إذا كنت تعمل مع نظام ملفات لا يدعم الروابط الرمزية، فحمّل ملف نقطة التفتيش إلى مجلد محلي أولاً باستخدام معامل local_dir. يؤدي استخدام معامل local_dir إلى تعطيل الروابط الرمزية تلقائياً.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors",
    local_dir="my_local_checkpoints",
)
print("My local checkpoint: ", my_local_checkpoint_path)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)
print("My local config: ", my_local_config_path)

مرر هذه المسارات إلى from_single_file().

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

أنواع الملفات

يمكن تخزين النماذج في عدة أنواع ملفات. يُعدّ Safetensors النوع الأكثر شيوعاً، لكن قد تواجه أنواع ملفات أخرى على Hub أو في مجتمع الانتشار.

safetensors

Safetensors هو نوع ملف آمن وسريع لتخزين وتحميل المصفوفات (tensors) بشكل آمن. وهو يحد من حجم الترويسة (header) للحد من أنواع معينة من الهجمات، ويدعم التحميل الكسول (lazy loading) وهو مفيد للإعدادات الموزعة، وعادةً ما يتم تحميله بشكل أسرع.

يحمّل Diffusers ملف safetensors افتراضيًا (وهو اعتماد إلزامي) إذا كان متاحًا وكان مكتبة Safetensors مثبّتة.

Use from_pretrained() or from_single_file() to load safetensor files.

import torch
from diffusers import DiffusionPipeline, StableDiffusionXLPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    dtype=torch.float16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
)

إذا كنت تستخدم نقطة تحقق (checkpoint) تم تدريبها باستخدام سكربت تدريب Diffusers، فإن البيانات الوصفية مثل إعدادات LoRA تُحفظ تلقائيًا. عند تحميل الملف، يتم تحليل تلك البيانات الوصفية ليتم ضبط LoRA بشكل صحيح. افحص البيانات الوصفية لملف safetensors بالنقر على أيقونة المجاورة للملف على Hub.

احفظ بيانات الوصف (metadata) لمُكيّف LoRA للمحطات (checkpoints) التي لم تُدرَّب باستخدام Diffusers عن طريق تمريرها إلى save_lora_weights(). استخدم transformer_lora_adapter_metadata للمحوّل (transformer) وtext_encoder_lora_adapter_metadata لمُشفّر النص (text encoder). يجب عليك أيضًا تمرير save_directory وواحد على الأقل من transformer_lora_layers أو text_encoder_lora_layers. هذا المسار مدعوم فقط لملفات safetensors.

import torch
from peft.utils import get_peft_model_state_dict
from diffusers import FluxPipeline

pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.load_lora_weights("linoyts/yarn_art_Flux_LoRA")

transformer_lora_layers = get_peft_model_state_dict(pipeline.transformer)
pipeline.save_lora_weights(
    save_directory="path/to/lora",
    transformer_lora_layers=transformer_lora_layers,
    transformer_lora_adapter_metadata={"r": 8, "lora_alpha": 8},
)

ckpt

تُحفظ أوزان النماذج الأقدم بشكل شائع باستخدام أداة pickle في بايثون داخل ملف ckpt.

قد تكون الملفات المُخلَّلة غير آمنة لأنها يمكن أن تُستغل لتنفيذ أكواد خبيثة. يُوصى باستخدام ملفات safetensors أو تحويل الأوزان إلى ملفات safetensors.

استخدم from_single_file() لتحميل ملف ckpt.

from diffusers import StableDiffusionPipeline

pipeline = StableDiffusionPipeline.from_single_file(
    "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.ckpt"
)

GGUF

يخزّن GGUF الأوزان المُكمّاة مسبقًا في ملف واحد. يقوم Diffusers بتحميل GGUF عبر نموذج from_single_file() باستخدام GGUFQuantizationConfig. لا يُدعم تحميل GGUF على مستوى خط الأنابيب.

راجع GGUF لمعرفة خطوات التثبيت والأمثلة الكاملة.

import torch
from diffusers import FluxTransformer2DModel, GGUFQuantizationConfig

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf",
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
)

تحويل الصيغ والملفات

توفر مكتبة Diffusers سكربتات وطرقًا لتحويل الصيغ والملفات حتى تتمكن المزيد من الأدوات في منظومة الانتشار من استخدامها.

اطّلع على مجلد diffusers/scripts للعثور على سكربت التحويل. السكربتات التي يُضاف إليها "to_diffusers" في نهايتها تُحوّل النموذج إلى صيغة Diffusers. لكل سكربت مجموعة محددة من الحُجج (arguments) لضبط عملية التحويل. تأكد من التحقق من الحُجج المتاحة.

يحوّل المثال أدناه نموذجًا مخزّنًا بتنسيق Diffusers إلى تنسيق ملف واحد. قدّم المسار إلى النموذج المراد تحويله والمكان الذي ستحفظ فيه النموذج المحوّل. يمكنك اختيارًا تحديد نوع الملف ونوع البيانات الذي تريد حفظ النموذج به.

python convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors

يحفظ أيضاً أسلوب save_pretrained() النموذج بتنسيق Diffusers ويتولى إنشاء مجلدات فرعية لكل نموذج. كما يحفظ الملفات بشكل افتراضي بصيغة safetensor.

from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
)
pipeline.save_pretrained("path/to/save/model")

الخطوات التالية

تعرّف على المزيد حول قرارات التصميم ولماذا تُفضَّل ملفات safetensor لحفظ أوزان النماذج وتحميلها في منشور المدونة تم تدقيق Safetensors لتأكيد أمانها الحقيقي وأصبحت الافتراضية.

Update on GitHub