Hugging Face's logo

Diffusers documentation

IP-Adapter

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

IP-Adapter

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

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

IPAdapterMixin

فئة diffusers.loaders.IPAdapterMixin

< >

( )

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

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) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. تُستخدم هذه الوكلاء في كل طلب.
  • local_files_only (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تحميل أوزان النموذج وملفات الإعداد المحلية فقط أم لا. إذا تم ضبطه على True، فلن يتم تنزيل النموذج من Hub.
  • token (str أو bool، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. إذا كان True، يُستخدم الرمز المولّد من diffusers-cli login (المخزّن في ~/.huggingface).
  • revision (str، اختياري، القيمة الافتراضية "main") — الإصدار المحدد من النموذج الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف commit، أو أي معرّف مسموح به بواسطة Git.
  • low_cpu_mem_usage (bool، اختياري، القيمة الافتراضية True إذا كان إصدار torch >= 1.9.0 وإلا False) — تسريع تحميل النموذج من خلال تحميل الأوزان المُسبقة التدريب فقط دون تهيئة الأوزان. كما يحاول هذا الخيار عدم استخدام أكثر من 1x حجم النموذج في ذاكرة المعالج المركزي (بما في ذلك الذروة) أثناء تحميل النموذج. مدعوم فقط لـ PyTorch >= 1.9.0. إذا كنت تستخدم إصدارًا أقدم من PyTorch، فإن تعيين هذا الحجج إلى True سيؤدي إلى رفع خطأ.

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

< >

( )

يفكك أوزان IP Adapter

أمثلة:

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

SD3IPAdapterMixin

فئة diffusers.loaders.SD3IPAdapterMixin

< >

( )

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

is_ip_adapter_active

< >

( ) → bool

يعيد

bool

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

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

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

load_ip_adapter

< >

( pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor]weight_name: str = 'ip-adapter.safetensors'subfolder: str | None = Noneimage_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) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. تُستخدم هذه الوكلاء في كل طلب.
  • local_files_only (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تحميل أوزان النموذج وملفات الإعداد المحلية فقط أم لا. إذا تم ضبطه على True، فلن يتم تنزيل النموذج من Hub.
  • token (str أو bool، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. إذا كان True، يُستخدم الرمز المولّد من diffusers-cli login (المخزّن في ~/.huggingface).
  • revision (str، اختياري، القيمة الافتراضية "main") — الإصدار المحدد من النموذج الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف commit، أو أي معرّف مسموح به بواسطة Git.
  • low_cpu_mem_usage (bool، اختياري، القيمة الافتراضية True إذا كان إصدار torch >= 1.9.0 وإلا False) — تسريع تحميل النموذج من خلال تحميل الأوزان المُسبقة التدريب فقط دون تهيئة الأوزان. كما يحاول هذا الخيار عدم استخدام أكثر من 1x حجم النموذج في ذاكرة المعالج المركزي (بما في ذلك الذروة) أثناء تحميل النموذج. مدعوم فقط لـ PyTorch >= 1.9.0. إذا كنت تستخدم إصدارًا أقدم من PyTorch، فإن تعيين هذا الحجج إلى True سيؤدي إلى رفع خطأ.

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

< >

( )

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

مثال:

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

IPAdapterMaskProcessor

فئة diffusers.IPAdapterMaskProcessor

< >

( do_resize: bool = Truevae_scale_factor: int = 8resample: str = 'lanczos'do_normalize: bool = Falsedo_binarize: bool = Truedo_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.

تقليل الدقة

< >

( mask: Tensorbatch_size: intnum_queries: intvalue_embed_dim: int ) → torch.Tensor

المعاملات

  • mask (torch.Tensor) — مصفوفة القناع المُدخلة التي تم إنشاؤها باستخدام IPAdapterMaskProcessor.preprocess().
  • batch_size (int) — حجم الدفعة.
  • num_queries (int) — عدد الاستعلامات.
  • value_embed_dim (int) — أبعاد تمثيلات القيم.

يعيد

torch.Tensor

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

يقوم بتقليل دقة مُتجه القناع المُقدَّم ليتطابق مع الأبعاد المتوقعة لانتباه النقطي المُقيَّم. إذا لم يتطابق نسبة أبعاد القناع مع نسبة أبعاد الصورة الناتجة، يتم إصدار تحذير.

Update on GitHub

←الموجّهون LoRA→