diffusers/main/ar/api/modular_diffusers/pipeline_components.md

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

ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec(name: str | None = None, type_hint: typing.Optional[typing.Type] = None, description: str | None = None, config: diffusers.configuration_utils.FrozenDict | None = None, pretrained_model_name_or_path: str | list[str] | None = None, subfolder: str | None = '', variant: str | None = None, revision: str | None = None, default_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

إنشاء[[diffusers.ComponentSpec.create]]

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

المصدر

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

decode_load_id[[diffusers.ComponentSpec.decode_load_id]]

decode_load_id(load_id: str)

المصدر

المعاملات:

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

يعيد:

خريطة (Dict) تربط أسماء حقول التحميل بقيمها. على سبيل المثال: { "pretrained_model_name_or_path": "path/to/repo", "subfolder": "subfolder", "variant": "variant", "revision": "revision" }. إذا كانت قيمة المقطع "null"، يتم استبدالها بـ None. تُرجع None إذا كانت قيمة load_id هي "null" (مما يشير إلى أن المكوّن لم يُنشأ باستخدام طريقة load).

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

from_component[[diffusers.ComponentSpec.from_component]]

from_component(name: str, component: Any)

المصدر

المعاملات:

name : اسم المكوّن

component : كائن المكوّن لإنشاء المواصفات منه

يعيد:

كائن ComponentSpec

يرفع: ValueError

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

إنشاء ComponentSpec من Component.

يدعم حالياً:

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

load[[diffusers.ComponentSpec.load]]

load(**kwargs)

المصدر

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

loading_fields[[diffusers.ComponentSpec.loading_fields]]

loading_fields()

المصدر

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

ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec(name: str, default: Any, description: str | None = None)

المصدر

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

ComponentsManager[[diffusers.ComponentsManager]]

diffusers.ComponentsManager[[diffusers.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")

إضافة[[diffusers.ComponentsManager.add]]

add(name: str, component: Any, collection: str | None = None)

المصدر

المعاملات:

name (str) : اسم المكوّن

component (أي): المكوّن الذي يجب إضافته

collection (str | None) : المجموعة التي سيتم إضافة المكوّن إليها

يعيد: str

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

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

disable_auto_cpu_offload[[diffusers.ComponentsManager.disable_auto_cpu_offload]]

disable_auto_cpu_offload()

المصدر

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

enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]

enable_auto_cpu_offload(device: str | int | torch.device = None, memory_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. عند استدعاء تمرير الأمامي لنموذج ما، يتم نقله إلى جهاز التنفيذ
3. إذا كانت الذاكرة غير كافية، يتم نقل النماذج الأخرى الموجودة على الجهاز مرة أخرى إلى وحدة المعالجة المركزية (CPU)
4. تسعى المنظومة إلى تفريغ أصغر تركيبة من النماذج التي تتيح تحرير مساحة ذاكرة كافية
5. تبقى النماذج على جهاز التنفيذ حتى تحتاج نموذج آخر إلى ذاكرة فيُجبرها على مغادرته

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

get_components_by_ids[[diffusers.ComponentsManager.get_components_by_ids]]

get_components_by_ids(ids: list[str], return_dict_with_names: bool | None = True)

المصدر

المعاملات:

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[[diffusers.ComponentsManager.get_components_by_names]]

get_components_by_names(names: list[str], collection: str | None = None)

المصدر

المعاملات:

names (list[str]) : قائمة بأسماء المكونات

collection (str | None) : مجموعة اختيارية للترشيح حسبها

يعيد: dict[str, Any]

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

يرفع: ValueError

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

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

get_ids[[diffusers.ComponentsManager.get_ids]]

get_ids(names: str | list[str] = None, collection: str | None = None)

المصدر

المعاملات:

names (str | list[str]) : قائمة بأسماء المكونات

collection (str | None) : مجموعة اختيارية للترشيح حسبها

يعيد: list[str]

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

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

get_model_info[[diffusers.ComponentsManager.get_model_info]]

get_model_info(component_id: str, fields: str | list[str] | None = None)

المصدر

المعاملات:

component_id (str) : اسم المكوّن الذي تريد الحصول على معلوماته

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

يعيد:

قاموس يحتوي على بيانات الوصف المكوّن المطلوب. إذا تم تحديد fields، يُرجع تلك الحقول فقط. وإلا، يُرجع جميع الحقول.

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

get_one[[diffusers.ComponentsManager.get_one]]

get_one(component_id: str | None = None, name: str | None = None, collection: str | None = None, load_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 يرفع خطأً إذا تطابقت عدة مكونات أو لم يُعثر على أي منها.

إزالة[[diffusers.ComponentsManager.remove]]

remove(component_id: str = None)

المصدر

المعاملات:

component_id (str) : معرّف المكوّن المراد إزالته

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

remove_from_collection[[diffusers.ComponentsManager.remove_from_collection]]

remove_from_collection(component_id: str, collection: str)

المصدر

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

search_components[[diffusers.ComponentsManager.search_components]]

search_components(names: str | None = None, collection: str | None = None, load_id: str | None = None, return_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، تُرجع قاموسًا تُستخدم فيه معرّفات المكونات كمفاتيح

يعيد:

Dictionary mapping component names to components if return_dict_with_names=True, or a dictionary mapping component IDs to components if return_dict_with_names=False

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

set_offload_strategy[[diffusers.ComponentsManager.set_offload_strategy]]

set_offload_strategy(offload_strategy)

المصدر

المعاملات:

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

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

InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

diffusers.modular_pipelines.InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

المصدر