Diffusers documentation
ControlNetModel
ControlNetModel
تم تقديم نموذج ControlNet في Adding Conditional Control to Text-to-Image Diffusion Models بواسطة Lvmin Zhang وAnyi Rao وManeesh Agrawala. يوفر هذا النموذج درجة أكبر من التحكم في توليد الصور من النص من خلال اشتراط النموذج على مدخلات إضافية مثل خرائط الحواف، وخرائط العمق، وخرائط التقسيم، ونقاط المفاتيح لكشف الوضعية.
ملخص الورقة البحثية هو:
نقدّم ControlNet، وهو معمارية شبكة عصبية لإضافة ضوابط شرطيّة مكانية إلى نماذج الانتشار النصّية-إلى-صورة الكبيرة المُدرَّبة مسبقًا. تقوم ControlNet بقفل نماذج الانتشار الكبيرة الجاهزة للإنتاج، وتعيد استخدام طبقات الترميز العميقة والقوية المُدرَّبة مسبقًا على مليارات الصور كهيكل أساسي قوي لتعلّم مجموعة متنوعة من الضوابط الشرطيّة. يتم ربط المعمارية العصبية بـ«التحويلات الصفرية» (طبقات تحويل مُهيّأة إلى الصفر) التي تُنمّي المعاملات تدريجيًا من الصفر وتضمن عدم تأثير أي ضوضاء ضارة على الضبط الدقيق. اختبرنا ضوابط شرطيّة متنوعة، مثل الحواف، والعمق، والتجزئة، ووضع الجسم البشري، وغيرها، باستخدام Stable Diffusion، باستخدام شرط واحد أو عدة شروط، مع وجود موجهات نصية أو بدونها. نُظهر أنّ تدريب نماذج ControlNet متين مع مجموعات البيانات الصغيرة (<50k) والكبيرة (>1m). تُظهر النتائج الواسعة أنّ ControlNet قد يسهّل تطبيقات أوسع للتحكم في نماذج انتشار الصور.
التحميل من التنسيق الأصلي
بشكل افتراضي، يجب تحميل ControlNetModel باستخدام from_pretrained()، لكن يمكن أيضًا تحميله
من التنسيق الأصلي باستخدام FromOriginalModelMixin.from_single_file على النحو التالي:
from diffusers import StableDiffusionControlNetPipeline, ControlNetModel
url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth" # can also be a local path
controlnet = ControlNetModel.from_single_file(url)
url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors" # can also be a local path
pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)التحميل من Control LoRA
تم تقديم Control-LoRA من قبل Stability AI في stabilityai/control-lora من خلال إضافة الضبط الدقيق الفعال المعتمد على المعلمات منخفضة الرتبة إلى ControlNet. توفر هذه الطريقة نهجًا أكثر كفاءة ومضغوطًا لجلب التحكم في النموذج إلى مجموعة أوسع من وحدات معالجة الرسومات الموجهة للمستهلكين.
from diffusers import ControlNetModel, UNet2DConditionModel
lora_id = "stabilityai/control-lora"
lora_filename = "control-LoRAs-rank128/control-lora-canny-rank128.safetensors"
unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", dtype=torch.bfloat16).to("cuda") # or "mps", "xpu", "cpu"
controlnet = ControlNetModel.from_unet(unet).to(device="cuda", dtype=torch.bfloat16)
controlnet.load_lora_adapter(lora_id, weight_name=lora_filename, prefix=None, controlnet_config=controlnet.config)ControlNetModel
فئة diffusers.ControlNetModel
< source >( in_channels: int = 4conditioning_channels: int = 3flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D')mid_block_type: str | None = 'UNetMidBlock2DCrossAttn'only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 1280transformer_layers_per_block: int | tuple[int, ...] = 1encoder_hid_dim: int | None = Noneencoder_hid_dim_type: str | None = Noneattention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseclass_embed_type: str | None = Noneaddition_embed_type: str | None = Noneaddition_time_embed_dim: int | None = Nonenum_class_embeds: int | None = Noneupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'projection_class_embeddings_input_dim: int | None = Nonecontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falseaddition_embed_type_num_heads: int = 64 )
المعاملات
- in_channels (
int، القيمة الافتراضية 4) — عدد القنوات في العينة المدخلة. - flip_sin_to_cos (
bool، القيمة الافتراضيةTrue) — ما إذا كان يجب عكس sin إلى cos في تضمين الوقت. - freq_shift (
int، القيمة الافتراضية 0) — إزاحة التردد التي تُطبَّق على تضمين الزمن. - down_block_types (
tuple[str]، الافتراضي("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) — المجموعة المرتبة (tuple) من كتل التقليل (downsample) المستخدمة. - only_cross_attention (
bool | tuple[bool]، القيمة الافتراضيةFalse) — - block_out_channels (
tuple[int]، القيمة الافتراضية(320, 640, 1280, 1280)) — مجموعة قنوات الإخراج لكل كتلة. - layers_per_block (
int، القيمة الافتراضية 2) — عدد الطبقات في كل كتلة. - downsample_padding (
int، القيمة الافتراضية 1) — الحشو المستخدم لتحويل الاستيفاء النازل. - mid_block_scale_factor (
float، القيمة الافتراضية 1) — معامل المقياس المستخدم للكتلة الوسطى. - act_fn (
str، القيمة الافتراضية “silu”) — دالة التنشيط المستخدمة. - norm_num_groups (
int, اختياري، القيمة الافتراضية 32) — عدد المجموعات المستخدمة للتطبيع. إذا كانت القيمة None، يتم تجاوز طبقات التطبيع والتفعيل في المعالجة اللاحقة. - norm_eps (
float، القيمة الافتراضية 1e-5) — قيمة الإيبسلون المستخدمة في عملية التطبيع. - cross_attention_dim (
int، القيمة الافتراضية 1280) — بعد ميزات الانتباه المتقاطع. - transformer_layers_per_block (
intأوtuple[int]، اختياري، القيمة الافتراضية 1) — عدد كتل الترانسفورمر من النوعBasicTransformerBlock. ذو صلة فقط بـ~models.unet_2d_blocks.CrossAttnDownBlock2D،~models.unet_2d_blocks.CrossAttnUpBlock2D،~models.unet_2d_blocks.UNetMidBlock2DCrossAttn. - encoder_hid_dim (
int، اختياري، القيمة الافتراضية None) — إذا تم تعريفencoder_hid_dim_type، فسيتم إسقاطencoder_hidden_statesمن بُعدencoder_hid_dimإلىcross_attention_dim. - encoder_hid_dim_type (
str، اختياري، القيمة الافتراضيةNone) — إذا تم تقديمه، تُخفَّض أبعادencoder_hidden_statesوالتضمينات الأخرى المحتملة إلى تضمينات نصية بأبعادcross_attentionوفقاً لـencoder_hid_dim_type. - attention_head_dim (
int | tuple[int]، القيمة الافتراضية 8) — بعد رؤوس الانتباه. - use_linear_projection (
bool، القيمة الافتراضيةFalse) — - class_embed_type (
str، اختياري، القيمة الافتراضيةNone) — نوع تضمين الفئة المستخدم، والذي يُجمع في النهاية مع تضمينات الوقت. اختر من بين None،"timestep"،"identity"،"projection"، أو"simple_projection". - addition_embed_type (
str، اختياري، القيمة الافتراضيةNone) — يُهيّئ تضمينًا اختياريًا سيُجمع مع تضمينات الوقت. اختر من بينNoneأو “text”. سيستخدم “text” طبقةTextTimeEmbedding. - num_class_embeds (
int, اختياري، القيمة الافتراضية 0) — بُعد المدخلات لمصفوفة التضمين القابلة للتعلم التي سيتم إسقاطها إلىtime_embed_dim، عند تنفيذ التكييف حسب الفئة باستخدامclass_embed_typeيساويNone. - upcast_attention (
bool، القيمة الافتراضيةFalse) — - resnet_time_scale_shift (
str) — إعدادات إزاحة مقياس الوقت لكتل ResNet (انظرResnetBlock2D). القيمة الافتراضية"default". اختر من بينdefaultأوscale_shift. - projection_class_embeddings_input_dim (
int، اختياري، القيمة الافتراضيةNone) — البُعد الخاص بمدخلclass_labelsعندما يكونclass_embed_type="projection". مطلوب عندما يكونclass_embed_type="projection". - controlnet_conditioning_channel_order (
str، القيمة الافتراضية"rgb") — ترتيب القنوات للصورة الشرطية. سيتم التحويل إلىrgbإذا كانتbgr. - conditioning_embedding_out_channels (
tuple[int]، اختياري، القيمة الافتراضية(16, 32, 96, 256)) — مجموعة قنوات الإخراج لكل كتلة في طبقةconditioning_embedding. - global_pool_conditions (
bool، القيمة الافتراضيةFalse) — TODO(Patrick) - معامل غير مستخدم. - addition_embed_type_num_heads (
int، القيمة الافتراضية 64) — عدد الرؤوس المستخدمة في طبقةTextTimeEmbedding.
نموذج ControlNet.
forward
< source >( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0class_labels: typing.Optional[torch.Tensor] = Nonetimestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneadded_cond_kwargs: dict[str, torch.Tensor] | None = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ControlNetOutput or tuple
المعاملات
- sample (
torch.Tensor) — مصفوفة الإدخال الضجيج. - timestep (
torch.Tensor | float | int) — عدد خطوات الزمن (timesteps) لإزالة الضوضاء من مدخل. - encoder_hidden_states (
torch.Tensor) — حالات المُشفِّر المخفية. - controlnet_cond (
torch.Tensor) — مصفوفة الإدخال الشرطية ذات الشكل(batch_size, sequence_length, hidden_size). - conditioning_scale (
float، القيمة الافتراضية1.0) — معامل المقياس لمخرجات ControlNet. - class_labels (
torch.Tensor، اختياري، القيمة الافتراضيةNone) — تسميات فئات اختيارية للشروط. سيتم جمع تمثيلاتها مع تمثيلات خطوة الزمن. - timestep_cond (
torch.Tensor، اختياري، القيمة الافتراضيةNone) — تضمينات شرطية إضافية لخطوة الزمن. إذا تم توفيرها، سيتم جمع التضمينات مع timestep_embedding المُمررة عبر طبقةself.time_embeddingللحصول على تضمينات خطوة الزمن النهائية. - attention_mask (
torch.Tensor، اختياري، القيمة الافتراضيةNone) — يُطبَّق قناع انتباه (attention mask) بأبعاد(batch, key_tokens)علىencoder_hidden_states. إذا كانت القيمة1يُحفظ القناع، وإلا إذا كانت0يُستبعد. يُحوَّل القناع إلى انحياز (bias) يضيف قيمًا سالبة كبيرة إلى درجات الانتباه المقابلة لرموز “الاستبعاد”. - added_cond_kwargs (
dict) — شروط إضافية لشبكة UNet في Stable Diffusion XL. - cross_attention_kwargs (
dict[str]، اختياري، القيمة الافتراضيةNone) — قاموس kwargs يُمرَّر إلىAttnProcessorإذا تم تحديده. - guess_mode (
bool، القيمة الافتراضيةFalse) — في هذا الوضع، يحاول مُشفِّر ControlNet بأقصى قدراته التعرف على محتوى الإدخال حتى إذا قمت بإزالة جميع الأوامر النصية. يُوصى باستخدام قيمةguidance_scaleبين 3.0 و5.0. - return_dict (
bool، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع ControlNetOutput بدلاً من tuple عادي.
يعيد
ControlNetOutput or tuple
إذا كان return_dict هو True، يُعاد ControlNetOutput،
وإلا يُعاد tuple حيث العنصر الأول هو tensor العينة.
طريقة ControlNetModel الأمامية.
from_unet
< source >( unet: UNet2DConditionModelcontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)load_weights_from_unet: bool = Trueconditioning_channels: int = 3 )
المعاملات
- unet (
UNet2DConditionModel) — أوزان نموذج UNet التي سيتم نسخها إلى ControlNetModel. كما يتم نسخ جميع خيارات الإعداد حيثما كان ذلك ممكنًا.
أنشئ نموذج ControlNetModel من UNet2DConditionModel.
set_attention_slice
< source >( slice_size: str | int | list[int] )
المعاملات
- slice_size (
strأوintأوlist(int)، اختياري، القيمة الافتراضية"auto") — عندما تكون القيمة"auto"، يتم تقسيم مدخلات رؤوس الانتباه إلى نصفين، بحيث يُحسب الانتباه في خطوتين. أما إذا كانت"max"، فيتم توفير أقصى قدر من الذاكرة من خلال تشغيل شريحة واحدة في كل مرة. وإذا تم تقديم رقم، يتم استخدام عدد من الشرائح يساويattention_head_dim // slice_size. في هذه الحالة، يجب أن يكونattention_head_dimمضاعفًا لـslice_size.
تفعيل حساب الانتباه المقطّع.
عند تمكين هذا الخيار، يقسم وحدة الانتباه (attention module) المصفوفة المدخلة إلى شرائح لحساب الانتباه على عدة خطوات. وهذا مفيد لتوفير بعض الذاكرة مقابل انخفاض طفيف في السرعة.
يعطّل معالجات الانتباه المخصصة ويضبط تطبيق الانتباه الافتراضي.
ControlNetOutput
فئة diffusers.models.controlnets.ControlNetOutput
< source >( down_block_res_samples: tuplemid_block_res_sample: Tensor )
المعاملات
- down_block_res_samples (
tuple[torch.Tensor]) — مجموعة (tuple) من تنشيطات التقليل (downsample) عند دقات مختلفة لكل كتلة تقليل. يجب أن يكون شكل كل متجه(batch_size, channel * resolution, height //resolution, width // resolution). يمكن استخدام المخرجات لتكييف تنشيطات التقليل الأصلية في UNet. - mid_down_block_re_sample (
torch.Tensor) — تفعيل الكتلة الوسطى (أدنى دقة عينة). يجب أن يكون شكل كل متجه(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution). يمكن استخدام المخرجات لتكييف تفعيل الكتلة الوسطى في UNet الأصلية.
مخرجات ControlNetModel.