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

## ComponentSpec[[diffusers.ComponentSpec]]

#### diffusers.ComponentSpec[[diffusers.ComponentSpec]]

```python
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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L98)

**المعاملات:**

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]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L267)

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

#### decode_load_id[[diffusers.ComponentSpec.decode_load_id]]

```python
decode_load_id(load_id: str)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L228)

**المعاملات:**

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]]

```python
from_component(name: str, component: Any)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L149)

**المعاملات:**

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

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

**يعيد:**

كائن ComponentSpec

**يرفع:** ``ValueError``

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

إنشاء ComponentSpec من Component.

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

#### load[[diffusers.ComponentSpec.load]]

```python
load(**kwargs)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L295)

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

#### loading_fields[[diffusers.ComponentSpec.loading_fields]]

```python
loading_fields()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L209)

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

## ConfigSpec[[diffusers.ConfigSpec]]

#### diffusers.ConfigSpec[[diffusers.ConfigSpec]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L360)

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

## ComponentsManager[[diffusers.ComponentsManager]]

#### diffusers.ComponentsManager[[diffusers.ComponentsManager]]

```python
diffusers.ComponentsManager()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L296)

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

يوفر [ComponentsManager](/docs/diffusers/main/ar/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) طريقة موحدة لتسجيل ومراقبة وإعادة استخدام مكوّنات النموذج (مثل UNet وVAE ومشفّرات النص، وغيرها) عبر خطوط الأنابيب المعيارية المختلفة. ويتضمن ميزات للكشف عن التكرار، وإدارة الذاكرة، وتنظيم المكوّنات.

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

مثال:
```python
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]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L393)

**المعاملات:**

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

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

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

**يعيد:** `str`

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

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

#### disable_auto_cpu_offload[[diffusers.ComponentsManager.disable_auto_cpu_offload]]

```python
disable_auto_cpu_offload()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L795)

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

#### enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]

```python
enable_auto_cpu_offload(device: str | int | torch.device = None, memory_reserve_margin = '3GB', offload_strategy = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L701)

**المعاملات:**

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]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1104)

**المعاملات:**

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]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1137)

**المعاملات:**

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

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

**يعيد:** dict[str, Any]

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

**يرفع:** ``ValueError``

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

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

#### get_ids[[diffusers.ComponentsManager.get_ids]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1086)

**المعاملات:**

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

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

**يعيد:** list[str]

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

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

#### get_model_info[[diffusers.ComponentsManager.get_model_info]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L812)

**المعاملات:**

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

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

**يعيد:**

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

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

#### get_one[[diffusers.ComponentsManager.get_one]]

```python
get_one(component_id: str | None = None, name: str | None = None, collection: str | None = None, load_id: str | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1041)

**المعاملات:**

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]]

```python
remove(component_id: str = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L485)

**المعاملات:**

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

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

#### remove_from_collection[[diffusers.ComponentsManager.remove_from_collection]]

```python
remove_from_collection(component_id: str, collection: str)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L467)

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

#### search_components[[diffusers.ComponentsManager.search_components]]

```python
search_components(names: str | None = None, collection: str | None = None, load_id: str | None = None, return_dict_with_names: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L515)

**المعاملات:**

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]]

```python
set_offload_strategy(offload_strategy)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L779)

**المعاملات:**

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

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

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

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L60)