Hugging Face's logo

Diffusers documentation

المكوّنات والإعدادات

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

المكوّنات والإعدادات

ComponentSpec

فئة diffusers.ComponentSpec

< >

( name: str | None = Nonetype_hint: typing.Optional[typing.Type] = Nonedescription: str | None = Noneconfig: diffusers.configuration_utils.FrozenDict | None = Nonepretrained_model_name_or_path: str | list[str] | None = Nonesubfolder: str | None = ''variant: str | None = Nonerevision: str | None = Nonedefault_creation_method: typing.Literal['from_config', 'from_pretrained'] = 'from_pretrained'repo: str | list[str] | None = None )

المعاملات

  • name — اسم المكوّن
  • type_hint — نوع المكوّن (مثل UNet2DConditionModel)
  • description — وصف اختياري للمكوّن
  • config — قاموس إعدادات اختياري لإنشاء init
  • pretrained_model_name_or_path — مسار اختياري لـ pretrained_model_name_or_path لإنشاء from_pretrained
  • subfolder — مجلد فرعي اختياري داخل pretrained_model_name_or_path
  • variant — متغير اختياري في pretrained_model_name_or_path
  • revision — نسخة اختيارية في pretrained_model_name_or_path
  • default_creation_method — طريقة الإنشاء المفضلة - “from_config” أو “from_pretrained”

مواصفة لمكوّن خط أنابيب.

يمكن إنشاء مكوّن بطريقتين:

  1. من الصفر باستخدام init مع قاموس إعدادات
  2. باستخدام from_pretrained

إنشاء

< >

( config: diffusers.configuration_utils.FrozenDict | dict[str, typing.Any] | None = None**kwargs )

إنشاء مكوّن باستخدام from_config مع config.

decode_load_id

< >

( load_id: str )

المعاملات

  • load_id — سلسلة load_id التي سيتم فك ترميزها، الصيغة: “pretrained_model_name_or_path|subfolder|variant|revision” حيث يتم تمثيل القيم التي تساوي None على أنها “null”

فكّ ترميز سلسلة load_id مرة أخرى إلى قاموسٍ يحتوي على حقول التحميل وقيمها.

from_component

< >

( name: strcomponent: Any )

المعاملات

  • name — اسم المكوّن
  • component — كائن المكوّن الذي سيتم إنشاء المواصفة منه

يرفع

ValueError

  • ValueError — إذا لم يكن المكوّن مدعومًا (مثل nn.Module بدون load_id، أو غير ConfigMixin)

إنشاء ComponentSpec من Component.

يدعم حالياً:

  • المكوّنات التي تم إنشاؤها باستخدام طريقة ComponentSpec.load()
  • المكوّنات التي هي فئات فرعية من ConfigMixin لكنها ليست nn.Modules (مثل المجدولين والموجّهين)

load

< >

( **kwargs )

قم بتحميل المكوّن باستخدام from_pretrained.

loading_fields

< >

( )

إرجاع أسماء جميع الحقول المتعلقة بالتحميل (أي تلك التي يكون فيها field.metadata[“loading”] True).

ConfigSpec

فئة diffusers.ConfigSpec

< >

( name: strdefault: Anydescription: str | None = None )

مواصفة لبارامتر تكوين خط أنابيب.

ComponentsManager

فئة diffusers.ComponentsManager

< >

( )

سجل مركزي ونظام لإدارة مكوّنات النماذج عبر خطوط أنابيب متعددة.

يوفر ComponentsManager طريقة موحدة لتسجيل مكونات النموذج وتتبعها وإعادة استخدامها (مثل UNet وVAE ومشفرات النص، وغيرها) عبر خطوط الأنابيب المعيارية المختلفة. ويتضمن ميزات للكشف عن التكرار، وإدارة الذاكرة، وتنظيم المكونات.

> هذه ميزة تجريبية ومن المرجح أن تتغير في المستقبل.

مثال:

from diffusers import ComponentsManager

# Create a components manager
cm = ComponentsManager()

# Add components
cm.add("unet", unet_model, collection="sdxl")
cm.add("vae", vae_model, collection="sdxl")

# Enable auto offloading
cm.enable_auto_cpu_offload()

# Retrieve components
unet = cm.get_one(name="unet", collection="sdxl")

إضافة

< >

( name: strcomponent: Anycollection: str | None = None ) → str

المعاملات

  • name (str) — اسم المكوّن
  • component (Any) — المكوّن الذي يجب إضافته
  • collection (str | None) — المجموعة التي يُضاف إليها المكوّن

يعيد

str

المعرّف الفريد للمكوّن، والذي يتم توليده على النحو “{name}_{id(component)}” حيث id(component) هو المعرّف الفريد المدمج في Python الخاص بالكائن

أضف مكوّنًا إلى ComponentsManager.

disable_auto_cpu_offload

< >

( )

تعطيل النقل التلقائي إلى وحدة المعالجة المركزية لجميع المكونات.

enable_auto_cpu_offload

< >

( device: str | int | torch.device = Nonememory_reserve_margin = '3GB'offload_strategy = None )

المعاملات

  • device (str | int | torch.device) — جهاز التنفيذ الذي تُنقل إليه النماذج لإجراء عمليات المرور الأمامي
  • memory_reserve_margin (str) — هوامش الاحتياطي من الذاكرة المستخدمة، والافتراضي هو 3GB. هذه هي كمية الذاكرة التي يجب إبقاؤها فارغة على الجهاز لتجنب نفاد الذاكرة أثناء تنفيذ النموذج (مثل التفعيلات الوسيطة، والتدرجات، وما إلى ذلك).
  • offload_strategy — أي دالة قابلة للاستدعاء تحمل التوقيع (hooks, model_id, model, execution_device) -> hooks، وتعيد النماذج المقيمة التي يجب نقلها قبل تحميل النموذج الوارد. القيمة الافتراضية هي AutoOffloadStrategy، والتي تُحرّر أصغر مجموعة كافية.

تفعيل التفريغ التلقائي إلى وحدة المعالجة المركزية لجميع المكونات.

يعمل الخوارزمية على النحو التالي:

  1. تبدأ جميع النماذج على وحدة المعالجة المركزية (CPU) افتراضيًا
  2. عند استدعاء تمرير الأمامي (forward pass) للنموذج، يتم نقله إلى جهاز التنفيذ
  3. إذا كانت الذاكرة غير كافية، يتم نقل النماذج الأخرى الموجودة على الجهاز مرة أخرى إلى وحدة المعالجة المركزية (CPU)
  4. تسعى المنظومة إلى تفريغ أصغر تركيبة من النماذج التي تتيح تحرير مساحة ذاكرة كافية
  5. تبقى النماذج على جهاز التنفيذ حتى تحتاج نموذج آخر إلى ذاكرة فيُجبرها على مغادرته

يشارك نموذج مُحمَّل ضمن مجموعة في هذه العملية لكنه يضع نفسه: إذ يمكنه ما زال أن يُفسح مكانًا عن طريق نقل نماذج أخرى جانبًا، ولا يُنقل أبدًا لفسح مكان لها. يعمل أي ترتيب — إما التحميل ضمن المجموعة قبل تفعيل هذه الميزة أو بعدها. يحدد AutoOffloadStrategy قراراته بناءً على بصمات ذاكرة النموذج، والتي لا تصف نموذجًا يحتفظ بمجموعة واحدة في كل مرة، لذا مرّر offload_strategy يتخذ قراراته بناءً على سير العمل.

get_components_by_ids

< >

( ids: list[str]return_dict_with_names: bool | None = True ) → dict[str, Any]

المعاملات

  • ids (list[str]) — قائمة معرّفات المكونات
  • return_dict_with_names (bool | None) — ما إذا كان يجب إرجاع قاموس بأسماء المكونات كمفاتيح:

يعيد

dict[str, Any]

قاموس المكونات.

  • إذا كان return_dict_with_names=True، فإن المفاتيح هي أسماء المكونات.
  • إذا كان return_dict_with_names=False، فإن المفاتيح هي معرّفات المكوّنات.

يرفع

ValueError

  • ValueError — إذا تم العثور على أسماء مكوّنات مكررة في نتائج البحث عندما تكون return_dict_with_names=True

احصل على المكونات من خلال قائمة معرّفات.

get_components_by_names

< >

( names: list[str]collection: str | None = None ) → dict[str, Any]

المعاملات

  • names (list[str]) — قائمة بأسماء المكونات
  • collection (str | None) — مجموعة اختيارية للترشيح حسبها

يعيد

dict[str, Any]

قاموس للمكونات بأسماء المكونات كمفاتيح

يرفع

ValueError

  • ValueError — إذا تم العثور على أسماء مكوّنات مكررة في نتائج البحث

احصل على المكونات من خلال قائمة أسماء، مع إمكانية التصفية اختيارياً حسب المجموعة.

get_ids

< >

( names: str | list[str] = Nonecollection: str | None = None ) → list[str]

المعاملات

  • names (str | list[str]) — قائمة بأسماء المكونات
  • collection (str | None) — مجموعة اختيارية للترشيح حسبها

يعيد

list[str]

قائمة معرّفات المكوّنات

احصل على معرّفات المكوّنات من خلال قائمة أسماء، مع إمكانية التصفية اختيارياً حسب المجموعة.

get_model_info

< >

( component_id: strfields: str | list[str] | None = None )

المعاملات

  • component_id (str) — اسم المكوّن الذي تريد الحصول على معلوماته
  • fields (str | list[str] | None) — الحقل (أو الحقول) المطلوب إرجاعه. يمكن أن يكون نصًا لحقل واحد أو قائمة من الحقول. إذا كان None، يتم استخدام إعداد available_info_fields.

احصل على معلومات شاملة عن مكوّن.

get_one

< >

( component_id: str | None = Nonename: str | None = Nonecollection: str | None = Noneload_id: str | None = None )

المعاملات

  • component_id (str | None) — معرّف مكوّن اختياري للحصول عليه
  • name (str | None) — اسم المكوّن أو النمط
  • collection (str | None) — مجموعة اختيارية للترشيح حسبها
  • load_id (str | None) — load_id اختياري للترشيح

يرفع

ValueError

  • ValueError — إذا لم تتطابق أي مكونات أو تطابقت عدة مكونات

احصل على مكوّن واحد إما عن

  • البحث بالاسم (مطابقة الأنماط)، المجموعة، أو load_id.
  • عند تمرير component_id يُطلق خطأً إذا تطابقت عدة مكوّنات أو لم يُعثر على أيٍّ منها.

إزالة

< >

( component_id: str = None )

المعاملات

  • component_id (str) — المعرّف المكوّن الذي يجب إزالته

إزالة مكوّن من ComponentsManager.

remove_from_collection

< >

( component_id: strcollection: str )

إزالة مكوّن من مجموعة.

search_components

< >

( names: str | None = Nonecollection: str | None = Noneload_id: str | None = Nonereturn_dict_with_names: bool = True )

المعاملات

  • names — اسم المكوّن أو الأسماء أو الأنماط الأنماط:
    • “unet” : يطابق أي مكوّن باسم أساسي “unet” (مثل unet_123abc)
    • “!unet”: كل شيء باستثناء المكونات التي يكون اسمها الأساسي “unet”
    • “unet*” : أي شيء يبدأ اسم قاعدته بـ “unet”
    • “!unet*” : أي شيء لا يبدأ اسمه الأساسي بـ “unet”
    • ”unet” : أي شيء يحتوي اسمه الأساسي على “unet”
    • “!unet” : أي شيء لا يحتوي اسمه الأساسي على “unet”
    • “refiner|vae|unet” : أي شيء يطابق اسمه الأساسي تمامًا مع “refiner” أو “vae” أو “unet”
    • “!refiner|vae|unet” : أي شيء لا يطابق اسمه الأساسي تمامًا “refiner” أو “vae” أو “unet”
    • “unet|vae”: أي شيء يبدأ اسمه الأساسي بـ “unet” أو يبدأ بـ “vae”
  • collection — مجموعة اختيارية للترشيح حسبها
  • load_id — load_id اختياري للتصفية
  • return_dict_with_names — إذا كانت القيمة True، تُرجع قاموسًا تُستخدم فيه أسماء المكونات كمفاتيح، وتُطلق خطأً إذا وُجدت مكونات متعددة تحمل نفس الاسم. وإذا كانت القيمة False، تُرجع قاموسًا تُستخدم فيه معرّفات المكونات كمفاتيح

ابحث عن المكونات بالاسم باستخدام مطابقة الأنماط البسيطة. يمكنك اختيارياً التصفية حسب المجموعة أو load_id.

set_offload_strategy

< >

( offload_strategy )

المعاملات

  • offload_strategy — أي دالة قابلة للاستدعاء تحمل التوقيع (hooks, model_id, model, execution_device) -> hooks: تستقبل خطافات النماذج الموجودة حاليًا على الجهاز وتعيد الخطافات التي يجب تفريغها قبل تحميل النموذج الوارد. القيمة الافتراضية هي AutoOffloadStrategy، والتي تفرّغ أصغر تركيبة كافية.

استبدل استراتيجية الإزاحة على جميع النماذج المُدارة. صالح فقط أثناء تمكين الإزاحة التلقائية إلى وحدة المعالجة المركزية.

InsertableDict

فئة diffusers.modular_pipelines.InsertableDict

< >

( )

Update on GitHub

←الحالات الموجّهون→