diffusers/v0.43.0/ar/api/loaders/ip_adapter.md

IP-Adapter

IP-Adapter هو مُكيّف خفيف الوزن يتيح استخدام صورة كإدخال توجيهي لنموذج الانتشار. تفصل هذه الطريقة طبقات الانتباه المتقاطع بين ميزات الصورة وميزات النص. وتُستخرج ميزات الصورة من مُشفِّر الصور.

تعلّم كيفية تحميل واستخدام نقطة تحقق (checkpoint) وصورة في دليل IP-Adapter.

IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

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

diffusers.loaders.IPAdapterMixin()

المصدر

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

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

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)

المصدر

المعاملات:

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(). - قاموس حالة torch.

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

set_ip_adapter_scale(scale)

المصدر

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

مثال:

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

unload_ip_adapter()

المصدر

يفكك أوزان IP Adapter

أمثلة:

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

SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

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

diffusers.loaders.SD3IPAdapterMixin()

المصدر

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

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

is_ip_adapter_active()

المصدر

يعيد: bool

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

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

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

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

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)

المصدر

المعاملات:

pretrained_model_name_or_path_or_dict (str أو os.PathLike أو dict) : يمكن أن يكون أحد ما يلي: - نص، وهو معرف النموذج (مثل google/ddpm-celebahq-256) لنموذج مُدرَّب مسبقًا مستضاف على Hub. - مسار إلى مجلد (مثل ./my_model_directory) يحتوي على أوزان النموذج المحفوظة باستخدام ModelMixin.save_pretrained(). - قاموس حالة torch.

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

set_ip_adapter_scale(scale: float)

المصدر

المعاملات:

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

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

مثال:

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

unload_ip_adapter()

المصدر

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

مثال:

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

IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

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)

المصدر

المعاملات:

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

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

المصدر

المعاملات:

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

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

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

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

يعيد: torch.Tensor

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

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