diffusers/main/ar/api/models/controlnet_sd3.md

SD3ControlNetModel

SD3ControlNetModel هو تطبيق لـ ControlNet مخصص لنموذج Stable Diffusion 3.

تم تقديم نموذج ControlNet في Adding Conditional Control to Text-to-Image Diffusion Models بواسطة Lvmin Zhang وAnyi Rao وManeesh Agrawala. يوفر هذا النموذج درجة أكبر من التحكم في توليد الصور من النص من خلال اشتراط النموذج على مدخلات إضافية مثل خرائط الحواف، وخرائط العمق، وخرائط التقسيم، ونقاط المفاتيح لكشف الوضعية.

ملخص الورقة البحثية هو:

نقدّم ControlNet، وهو معمارية شبكة عصبية لإضافة ضوابط شرطيّة مكانية إلى نماذج الانتشار النصّية-إلى-صورة الكبيرة المُدرَّبة مسبقًا. تقوم ControlNet بقفل نماذج الانتشار الكبيرة الجاهزة للإنتاج، وتعيد استخدام طبقات الترميز العميقة والقوية المُدرَّبة مسبقًا على مليارات الصور كهيكل أساسي قوي لتعلّم مجموعة متنوعة من الضوابط الشرطيّة. يتم ربط المعمارية العصبية بـ "التحويلات الصفرية" (طبقات تحويل مُهيّأة إلى الصفر) التي تُنمّي المعاملات تدريجيًا من الصفر وتضمن عدم تأثير أي ضوضاء ضارة على الضبط الدقيق. اختبرنا ضوابط شرطيّة متنوعة، مثل الحواف، والعمق، والتجزئة، ووضع الجسم البشري، وغيرها، باستخدام Stable Diffusion، باستخدام شرط واحد أو عدة شروط، مع وجود موجهات نصية أو بدونها. نُظهر أنّ تدريب نماذج ControlNet متين مع مجموعات البيانات الصغيرة (<50k) والكبيرة (>1m). تُظهر النتائج الواسعة أنّ ControlNet قد يسهّل تطبيقات أوسع للتحكم في نماذج انتشار الصور.

التحميل من التنسيق الأصلي

بشكل افتراضي، يجب تحميل SD3ControlNetModel باستخدام from_pretrained().

from diffusers import StableDiffusion3ControlNetPipeline
from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel

controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny")
pipe = StableDiffusion3ControlNetPipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet)

SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

diffusers.SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

diffusers.SD3ControlNetModel(sample_size: int = 128, patch_size: int = 2, in_channels: int = 16, num_layers: int = 18, attention_head_dim: int = 64, num_attention_heads: int = 18, joint_attention_dim: int = 4096, caption_projection_dim: int = 1152, pooled_projection_dim: int = 2048, out_channels: int = 16, pos_embed_max_size: int = 96, extra_conditioning_channels: int = 0, dual_attention_layers: tuple[int, ...] = (), qk_norm: str | None = None, pos_embed_type: str | None = 'sincos', use_pos_embed: bool = True, force_zeros_for_pooled_projection: bool = True)

المصدر

المعاملات:

sample_size (int، القيمة الافتراضية 128) : عرض/ارتفاع الكمونيات. يتم تثبيت هذا أثناء التدريب لأنه يُستخدم لتعلم عدد من تضمينات المواقع.

patch_size (int، القيمة الافتراضية 2) : حجم الباتش لتحويل البيانات المدخلة إلى باتشات صغيرة.

in_channels (int، القيمة الافتراضية 16) : عدد قنوات الحالة الكامنة في المدخلات.

num_layers (int، القيمة الافتراضية 18) : عدد طبقات كتل التحويل (transformer blocks) المستخدمة.

attention_head_dim (int، القيمة الافتراضية 64) : عدد القنوات في كل رأس.

num_attention_heads (int، القيمة الافتراضية 18) : عدد الرؤوس المستخدمة في الانتباه متعدد الرؤوس.

joint_attention_dim (int، القيمة الافتراضية 4096) : بُعد التضمين (embedding dimension) المستخدم للانتباه المشترك بين النص والصورة.

caption_projection_dim (int، القيمة الافتراضية 1152) : بُعد التضمين لتضمينات الوصف.

pooled_projection_dim (int، القيمة الافتراضية 2048) : بُعد التضمين (embedding) لإسقاطات النص المجمعة.

out_channels (int، القيمة الافتراضية 16) : عدد قنوات الحالة الكامنة في المخرجات.

pos_embed_max_size (int، القيمة الافتراضية 96) : أقصى ارتفاع/عرض كامن لتضمينات الموضع.

extra_conditioning_channels (int، القيمة الافتراضية 0) : عدد القنوات الإضافية المستخدمة للتكييف في تضمين البقع.

dual_attention_layers (tuple[int, ...]، الافتراضي ()) : عدد كتل الترانسفورمر ذات التدفق المزدوج التي سيتم استخدامها.

qk_norm (str، اختياري، القيمة الافتراضية None) : طريقة التطبيع المستخدمة للاستعلام والمفتاح في طبقة الانتباه. إذا كانت None، فلا يُستخدم أي تطبيع.

pos_embed_type (str، الافتراضي "sincos") : نوع تضمين الموضع (positional embedding) المستخدم. اختر بين "sincos" وNone.

use_pos_embed (bool، القيمة الافتراضية True) : ما إذا كان سيتم استخدام التضمينات الموضعية.

force_zeros_for_pooled_projection (bool، القيمة الافتراضية True) : ما إذا كان سيتم إجبار قيم التضمينات المُجمَّعة (pooled projection embeddings) على أن تكون صفرًا. يتم التعامل مع ذلك في خطوط الأنابيب (pipelines) من خلال قراءة قيمة الإعداد (config) لنموذج ControlNet.

نموذج ControlNet لـ Stable Diffusion 3.

enable_forward_chunking[[diffusers.SD3ControlNetModel.enable_forward_chunking]]

enable_forward_chunking(chunk_size: int | None = None, dim: int = 0)

المصدر

المعاملات:

chunk_size (int, اختياري) : حجم الدفعة (chunk size) لطبقات التغذية الأمامية. إذا لم يُحدد، فسيتم تشغيل طبقة التغذية الأمامية بشكل فردي على كل متجه (tensor) ذي بُعد dim.

dim (int، اختياري، القيمة الافتراضية 0) : البُعد الذي يجب تقسيم عملية الحساب الأمامي (feed-forward) عليه. اختر بين dim=0 (الحزمة) أو dim=1 (طول التسلسل).

يحدد معالج الانتباه لاستخدام تقطيع الأمامي.

forward[[diffusers.SD3ControlNetModel.forward]]

forward(hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, joint_attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)

المصدر

المعاملات:

hidden_states (torch.Tensor من الشكل (batch size, channel, height, width)) : مدخلات hidden_states.

controlnet_cond (torch.Tensor) : متجه الإدخال الشرطي ذو الشكل (batch_size, sequence_length, hidden_size).

conditioning_scale (float، القيمة الافتراضية 1.0) : معامل المقياس لمخرجات ControlNet.

encoder_hidden_states (torch.Tensor من الشكل (batch size, sequence_len, embed_dims)) : التضمينات الشرطية (التضمينات المحسوبة من الشروط المدخلة مثل الأوامر) للاستخدام.

pooled_projections (torch.Tensor من الشكل (batch_size, projection_dim)) : تمثيلات مُسقطَة من تمثيلات شروط الإدخال.

timestep ( torch.LongTensor) : يُستخدم للإشارة إلى خطوة إزالة الضوضاء.

joint_attention_kwargs (dict، اختياري) : قاموس kwargs يُمرَّر إلى AttentionProcessor إذا تم تحديده، كما هو معرَّف تحت self.processor في diffusers.models.attention_processor.

return_dict (bool، اختياري، القيمة الافتراضية True) : ما إذا كان يجب إرجاع ~models.transformer_2d.Transformer2DModelOutput بدلاً من tuple عادي.

يعيد:

إذا كان return_dict صحيحًا، يُعاد ~models.transformer_2d.Transformer2DModelOutput، وإلا يُعاد tuple يكون عنصره الأول هو تينسور العينة.

طريقة SD3Transformer2DModel الأمامية.

fuse_qkv_projections[[diffusers.SD3ControlNetModel.fuse_qkv_projections]]

fuse_qkv_projections()

المصدر

…

> هذه الواجهة البرمجية 🧪 تجريبية.

unfuse_qkv_projections[[diffusers.SD3ControlNetModel.unfuse_qkv_projections]]

unfuse_qkv_projections()

المصدر

يعطّل إسقاط QKV المدمج إذا كان مفعّلًا.

> هذه الواجهة البرمجية 🧪 تجريبية.

SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

diffusers.models.controlnets.SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

diffusers.models.controlnets.SD3ControlNetOutput(controlnet_block_samples: tuple[torch.Tensor])

المصدر