# IP-Adapter

[IP-Adapter](https://hf.co/papers/2308.06721) هو مُكيّف خفيف الوزن يتيح استخدام صورة كإدخال توجيهي لنموذج الانتشار. تفصل هذه الطريقة طبقات الانتباه المتقاطع بين ميزات الصورة وميزات النص. وتُستخرج ميزات الصورة من مُشفِّر الصور.

> [!TIP]
> تعلّم كيفية تحميل واستخدام نقطة تحقق (checkpoint) وصورة في دليل [IP-Adapter](../../using-diffusers/ip_adapter).

## IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

#### diffusers.loaders.IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

```python
diffusers.loaders.IPAdapterMixin()
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L54)

مزيج للتعامل مع محولات IP.

#### load_ip_adapter[[diffusers.loaders.IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | list[str] | dict[str, torch.Tensor], subfolder: str | list[str], weight_name: str | list[str], image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L57)

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

pretrained_model_name_or_path_or_dict (`str` أو `list[str]` أو `os.PathLike` أو `list[os.PathLike]` أو `dict` أو `list[dict]`) : يمكن أن يكون أيًا مما يلي:  - نص، وهو *معرف النموذج* (مثل `google/ddpm-celebahq-256`) لنموذج مُدرَّب مسبقًا مستضاف على Hub. - مسار إلى *مجلد* (مثل `./my_model_directory`) يحتوي على أوزان النموذج المحفوظة باستخدام [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/ar/api/models/overview#diffusers.ModelMixin.save_pretrained). - [قاموس حالة torch](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

subfolder (`str` أو `list[str]`) : موقع المجلد الفرعي لملف النموذج داخل مستودع نموذج أكبر على Hub أو محليًا. إذا تم تمرير قائمة، فيجب أن يكون طولها مطابقًا لطول `weight_name`.

weight_name (`str` أو `list[str]`) : اسم ملف الأوزان الذي سيتم تحميله. إذا تم تمرير قائمة، فيجب أن يكون طولها مطابقًا لطول `subfolder`.

image_encoder_folder (`str`، *اختياري*، القيمة الافتراضية هي `image_encoder`) : موقع المجلد الفرعي لمُشفِّر الصور داخل مستودع نموذج أكبر على Hub أو محليًا. مرّر `None` لعدم تحميل مُشفِّر الصور. إذا كان مُشفِّر الصور موجودًا في مجلد داخل `subfolder`، فأنت بحاجة فقط إلى تمرير اسم المجلد الذي يحتوي على أوزان مُشفِّر الصور، على سبيل المثال `image_encoder_folder="image_encoder"`. إذا كان مُشفِّر الصور موجودًا في مجلد غير `subfolder`، فيجب عليك تمرير المسار إلى المجلد الذي يحتوي على أوزان مُشفِّر الصور، على سبيل المثال `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`، *اختياري*) : مسار إلى مجلد حيث تُخزَّن مؤقتًا إعدادات النموذج المُسبق التحميل المُحمَّل إذا لم يُستخدم التخزين المؤقت القياسي.

force_download (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إجبار إعادة تنزيل أوزان النموذج وملفات الإعداد، مع تجاوز النسخ المخزنة مؤقتًا إذا كانت موجودة.

proxies (`dict[str, str]`، *اختياري*) : قاموس لخوادم الوكيل (proxy servers) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال، `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. تُستخدم هذه الوكلاء في كل طلب.

local_files_only (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تحميل أوزان النموذج المحلية وملفات الإعداد فقط أم لا. إذا تم ضبطه على `True`، فلن يتم تنزيل النموذج من Hub.

token (`str` أو *bool*، *اختياري*) : الرمز الذي يُستخدم كتوكن مصادقة HTTP bearer للملفات البعيدة. إذا كان `True`، يُستخدم التوكن المولّد من `diffusers-cli login` (المخزَّن في `~/.huggingface`).

revision (`str`، *اختياري*، القيمة الافتراضية `"main"`) : إصدار النموذج المحدد الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف التزامن، أو أي معرّف مسموح به بواسطة Git.

low_cpu_mem_usage (`bool`، *اختياري*، القيمة الافتراضية هي `True` إذا كانت إصدار torch >= 1.9.0 وإلا `False`) : تسريع تحميل النموذج من خلال تحميل الأوزان المُسبقة التدريب فقط دون تهيئة الأوزان. كما يحاول هذا الخيار عدم استخدام أكثر من 1x حجم النموذج في ذاكرة المعالج المركزي (بما في ذلك الذروة) أثناء تحميل النموذج. مدعوم فقط لـ PyTorch >= 1.9.0. إذا كنت تستخدم إصدارًا أقدم من PyTorch، فإن تعيين هذا الحجة إلى `True` سيؤدي إلى رفع خطأ.

#### set_ip_adapter_scale[[diffusers.loaders.IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L252)

تُعيّن IP-Adapter مقاييس لكل كتلة محوّلة. يمكن أن يكون المدخل `scale` تكوينًا واحدًا أو قائمة من التكوينات للتحكم الدقيق في سلوك كل IP-Adapter. يمكن أن يكون التكوين عددًا عشريًا أو قاموسًا.

مثال:

```py
# To use original IP-Adapter
scale = 1.0
pipeline.set_ip_adapter_scale(scale)

# To use style block only
scale = {
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style+layout blocks
scale = {
    "down": {"block_2": [0.0, 1.0]},
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style and layout from 2 reference images
scales = [{"down": {"block_2": [0.0, 1.0]}}, {"up": {"block_0": [0.0, 1.0, 0.0]}}]
pipeline.set_ip_adapter_scale(scales)
```

#### unload_ip_adapter[[diffusers.loaders.IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L305)

يفكك أوزان IP Adapter

أمثلة:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

#### diffusers.loaders.SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

```python
diffusers.loaders.SD3IPAdapterMixin()
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L885)

مزيج (Mixin) للتعامل مع محولات IP Adapter في StableDiffusion 3.

#### is_ip_adapter_active[[diffusers.loaders.SD3IPAdapterMixin.is_ip_adapter_active]]

```python
is_ip_adapter_active()
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L888)

**يعيد:** `bool`

صحيح عند تحميل IP-Adapter ووجود أي طبقة لها قيمة مقياس > 0.

يتحقق من تحميل IP-Adapter وأن scale > 0.

يتحكم مقياس IP-Adapter في تأثير موجه الصورة مقارنةً بموجه النص. عند ضبط هذه القيمة على 0، يصبح سياق الصورة غير ذي صلة.

#### load_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor], weight_name: str = 'ip-adapter.safetensors', subfolder: str | None = None, image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L906)

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

pretrained_model_name_or_path_or_dict (`str` أو `os.PathLike` أو `dict`) : يمكن أن يكون أحد ما يلي: - نص، وهو *معرف النموذج* (مثل `google/ddpm-celebahq-256`) لنموذج مُدرَّب مسبقًا مستضاف على Hub. - مسار إلى *مجلد* (مثل `./my_model_directory`) يحتوي على أوزان النموذج المحفوظة باستخدام [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/ar/api/models/overview#diffusers.ModelMixin.save_pretrained). - [قاموس حالة torch](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

weight_name (`str`، القيمة الافتراضية هي "ip-adapter.safetensors") : اسم ملف الأوزان الذي سيتم تحميله. إذا تم تمرير قائمة، فيجب أن يكون طولها مطابقًا لطول `subfolder`.

subfolder (`str`, *اختياري*) : موقع المجلد الفرعي لملف النموذج داخل مستودع نموذج أكبر على Hub أو محليًا. إذا تم تمرير قائمة، فيجب أن يكون طولها مطابقًا لطول `weight_name`.

image_encoder_folder (`str`، *اختياري*، القيمة الافتراضية هي `image_encoder`) : موقع المجلد الفرعي لمُشفِّر الصور داخل مستودع نموذج أكبر على Hub أو محليًا. مرّر `None` لعدم تحميل مُشفِّر الصور. إذا كان مُشفِّر الصور موجودًا في مجلد داخل `subfolder`، فأنت بحاجة فقط إلى تمرير اسم المجلد الذي يحتوي على أوزان مُشفِّر الصور، على سبيل المثال `image_encoder_folder="image_encoder"`. إذا كان مُشفِّر الصور موجودًا في مجلد غير `subfolder`، فيجب عليك تمرير المسار إلى المجلد الذي يحتوي على أوزان مُشفِّر الصور، على سبيل المثال `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`، *اختياري*) : مسار إلى مجلد حيث تُخزَّن مؤقتًا إعدادات النموذج المُسبق التحميل المُحمَّل إذا لم يُستخدم التخزين المؤقت القياسي.

force_download (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إجبار إعادة تنزيل أوزان النموذج وملفات الإعداد، مع تجاوز النسخ المخزنة مؤقتًا إذا كانت موجودة.

proxies (`dict[str, str]`، *اختياري*) : قاموس لخوادم الوكيل (proxy servers) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال، `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. تُستخدم هذه الوكلاء في كل طلب.

local_files_only (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تحميل أوزان النموذج المحلية وملفات الإعداد فقط أم لا. إذا تم ضبطه على `True`، فلن يتم تنزيل النموذج من Hub.

token (`str` أو *bool*، *اختياري*) : الرمز الذي يُستخدم كتوكن مصادقة HTTP bearer للملفات البعيدة. إذا كان `True`، يُستخدم التوكن المولّد من `diffusers-cli login` (المخزَّن في `~/.huggingface`).

revision (`str`، *اختياري*، القيمة الافتراضية `"main"`) : إصدار النموذج المحدد الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف التزامن، أو أي معرّف مسموح به بواسطة Git.

low_cpu_mem_usage (`bool`، *اختياري*، القيمة الافتراضية هي `True` إذا كانت إصدار torch >= 1.9.0 وإلا `False`) : تسريع تحميل النموذج من خلال تحميل الأوزان المُسبقة التدريب فقط دون تهيئة الأوزان. كما يحاول هذا الخيار عدم استخدام أكثر من 1x حجم النموذج في ذاكرة المعالج المركزي (بما في ذلك الذروة) أثناء تحميل النموذج. مدعوم فقط لـ PyTorch >= 1.9.0. إذا كنت تستخدم إصدارًا أقدم من PyTorch، فإن تعيين هذا الحجة إلى `True` سيؤدي إلى رفع خطأ.

#### set_ip_adapter_scale[[diffusers.loaders.SD3IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale: float)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L1054)

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

scale (float) : قيمة مقياس IP-Adapter التي يجب ضبطها.

تعيين مقياس IP-Adapter، الذي يتحكم في تكييف موجه الصورة. القيمة 1.0 تعني أن النموذج مشروط بموجه الصورة فقط، بينما القيمة 0.0 تعني أنه مشروط بموجه النص فقط. خفض هذه القيمة يشجع النموذج على إنتاج صور أكثر تنوعاً، لكنها قد لا تكون متوافقة مع موجه الصورة بنفس الدرجة.

مثال:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.set_ip_adapter_scale(0.6)
>>> ...
```

#### unload_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L1077)

يفكك أوزان مُكيّف الإدخال (IP Adapter).

مثال:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

#### diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

```python
diffusers.IPAdapterMaskProcessor(do_resize: bool = True, vae_scale_factor: int = 8, resample: str = 'lanczos', do_normalize: bool = False, do_binarize: bool = True, do_convert_grayscale: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/image_processor.py#L1277)

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

do_resize (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم تصغير أبعاد الصورة (الارتفاع، العرض) إلى مضاعفات لـ`vae_scale_factor`.

vae_scale_factor (`int`، *اختياري*، القيمة الافتراضية `8`) : معامل مقياس VAE. إذا كان `do_resize` هو `True`، يتم تغيير حجم الصورة تلقائيًا إلى مضاعفات لهذا المعامل.

resample (`str`، *اختياري*، الافتراضي `lanczos`) : مرشح إعادة العينة المستخدم عند تغيير حجم الصورة.

do_normalize (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تطبيع الصورة إلى [-1,1].

do_binarize (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم تحويل الصورة إلى ثنائية (0/1).

do_convert_grayscale (`bool`، *اختياري*، القيمة الافتراضية هي `True`) : ما إذا كان سيتم تحويل الصور إلى تنسيق رمادي.

معالج الصور لأقنعة صور IP Adapter.

#### تقليل الحجم[[diffusers.IPAdapterMaskProcessor.downsample]]

```python
downsample(mask: Tensor, batch_size: int, num_queries: int, value_embed_dim: int)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/image_processor.py#L1318)

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

mask (`torch.Tensor`) : متجه القناع المُدخل المُولَّد باستخدام `IPAdapterMaskProcessor.preprocess()`.

batch_size (`int`) : حجم الدفعة.

num_queries (`int`) : عدد الاستعلامات.

value_embed_dim (`int`) : بُعد تمثيلات القيم.

**يعيد:** `torch.Tensor`

مصفوفة القناع المُصغّرة.

يُقلّص هذا الدالة حجم مُتجه القناع المُقدَّم (mask tensor) ليتطابق مع الأبعاد المتوقعة لانتباه النقطي المُقيَّم (scaled dot-product attention). إذا لم يتطابق نسبة أبعاد القناع مع نسبة أبعاد الصورة الناتجة، يتم إصدار تحذير.