diffusers/main/ar/api/pipelines/controlnet_flux.md

ControlNet مع Flux.1

FluxControlNetPipeline هو تطبيق لـ ControlNet مخصص لنموذج Flux.1.

تم تقديم ControlNet في Adding Conditional Control to Text-to-Image Diffusion Models بواسطة Lvmin Zhang وAnyi Rao وManeesh Agrawala.

باستخدام نموذج ControlNet، يمكنك تقديم صورة تحكم إضافية لتكييف عملية توليد Stable Diffusion والتحكم فيها. على سبيل المثال، إذا قدمت خريطة عمق، فإن نموذج ControlNet يولّد صورة تحافظ على المعلومات المكانية المستمدة من خريطة العمق. وهي طريقة أكثر مرونة ودقة للتحكم في عملية توليد الصور.

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

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

تم تنفيذ كود controlnet هذا بواسطة فريق InstantX. يمكنك العثور على نقاط التفتيش المدربة مسبقًا لـ Flux-ControlNet في الجدول أدناه:

نوع ControlNet	المطوّر	رابط
Canny	فريق InstantX	رابط
العمق	فريق InstantX	رابط
اتحاد	فريق InstantX	رابط

تُدعَم شبكات ControlNet من XLabs أيضًا، وقد ساهم بها فريق XLabs.

نوع ControlNet	المطوّر	رابط
Canny	فريق XLabs	رابط
العمق	فريق XLabs	رابط
HED	فريق XLabs	رابط

تأكد من الاطلاع على دليل المجدولين لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم إعادة استخدام المكونات عبر خطوط الأنابيب لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.

FluxControlNetPipeline[[diffusers.FluxControlNetPipeline]]

diffusers.FluxControlNetPipeline[[diffusers.FluxControlNetPipeline]]

diffusers.FluxControlNetPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, text_encoder_2: T5EncoderModel, tokenizer_2: T5Tokenizer, transformer: FluxTransformer2DModel, controlnet: diffusers.models.controlnets.controlnet_flux.FluxControlNetModel | list[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | tuple[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | diffusers.models.controlnets.controlnet_flux.FluxMultiControlNetModel, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None)

المصدر

المعاملات:

transformer (FluxTransformer2DModel) : معمارية Transformer الشرطية (MMDiT) لإزالة الضوضاء من الكامنات المُرمّزة للصورة.

scheduler (FlowMatchEulerDiscreteScheduler) : مُجدوِل يُستخدم بالاقتران مع transformer لإزالة الضوضاء من كامنات الصورة المُرمَّزة.

vae (AutoencoderKL) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.

text_encoder (CLIPTextModel) : CLIP، وتحديداً النسخة clip-vit-large-patch14.

text_encoder_2 (T5EncoderModel) : T5، وتحديداً النسخة google/t5-v1_1-xxl.

tokenizer (CLIPTokenizer) : مُقسِّم من الفئة CLIPTokenizer.

tokenizer_2 (T5TokenizerFast) : مُرمِّز ثانٍ من الفئة T5TokenizerFast.

خط أنابيب Flux لتوليد الصور من النص.

مرجع: https://blackforestlabs.ai/announcing-black-forest-labs/

call[[diffusers.FluxControlNetPipeline.call]]

__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, negative_prompt: str | list[str] = None, negative_prompt_2: str | list[str] | None = None, true_cfg_scale: float = 1.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 28, sigmas: list[float] | None = None, guidance_scale: float = 7.0, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_mode: int | list[int] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, negative_ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, negative_ip_adapter_image_embeds: list[torch.Tensor] | None = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512)

المصدر

المعاملات:

prompt (str أو list[str]، اختياري) : الأمر أو الأوامر التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير prompt_embeds بدلاً من ذلك.

prompt_2 (str أو list[str]، اختياري) : الموجه أو الموجهات المرسل إلى tokenizer_2 وtext_encoder_2. إذا لم يُعرَّف، فسيتم استخدام prompt بدلاً منه

negative_prompt (str أو list[str]، اختياري) : الموجه أو الموجهات التي لا ينبغي توجيه توليد الصورة بها. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا لم يكن true_cfg_scale أكبر من 1).

negative_prompt_2 (str أو list[str]، اختياري) : الموجه أو الموجهات التي لا ينبغي توجيه توليد الصورة إليها، والتي سيتم إرسالها إلى tokenizer_2 وtext_encoder_2. إذا لم يُعرَّف، يُستخدم negative_prompt في جميع مشفّرات النص.

true_cfg_scale (float، اختياري، القيمة الافتراضية 1.0) : يتم تفعيل التوجيه الحر من التصنيف (مقياس التوجيه) عندما يكون true_cfg_scale > 1 ويتم توفير negative_prompt.

height (int، اختياري، الافتراضي هو self.unet.config.sample_size * self.vae_scale_factor) : ارتفاع الصورة المولّدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج.

width (int، اختياري، القيمة الافتراضية هي self.unet.config.sample_size * self.vae_scale_factor) : عرض الصورة المولدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج.

num_inference_steps (int، اختياري، القيمة الافتراضية 50) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال.

sigmas (list[float]، اختياري) : قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل sigmas في طريقة set_timesteps الخاصة بهم. إذا لم تُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps.

guidance_scale (float، اختياري، القيمة الافتراضية 7.0) : مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّف guidance_scale على أنه w من المعادلة 2. في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيين guidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص prompt، وعادةً على حساب انخفاض جودة الصورة.

control_guidance_start (float أو list[float]، اختياري، القيمة الافتراضية 0.0) : النسبة المئوية من إجمالي الخطوات التي يبدأ عندها ControlNet في التطبيق.

control_guidance_end (float أو list[float]، اختياري، القيمة الافتراضية 1.0) : النسبة المئوية من إجمالي الخطوات التي يتوقف عندها ControlNet عن التطبيق.

control_image (torch.Tensor، PIL.Image.Image، np.ndarray، list[torch.Tensor]، list[PIL.Image.Image]، list[np.ndarray]، : list[list[torch.Tensor]]، list[list[np.ndarray]] أو list[list[PIL.Image.Image]]): شرط الإدخال الخاص بـ ControlNet لتقديم التوجيه إلى unet للتوليد. إذا تم تحديد النوع على أنه torch.Tensor، فإنه يُمرَّر إلى ControlNet كما هو. يمكن أيضًا قبول PIL.Image.Image كصورة. الأبعاد الافتراضية للصورة الناتجة هي أبعاد image. إذا تم تمرير الارتفاع و/أو العرض، يتم تغيير حجم image وفقًا لذلك. إذا تم تحديد عدة وحدات ControlNet في init، يجب تمرير الصور كقائمة بحيث يمكن تجميع كل عنصر من عناصر القائمة بشكل صحيح للإدخال إلى وحدة ControlNet واحدة.

controlnet_conditioning_scale (float أو list[float]، اختياري، القيمة الافتراضية 1.0) : تُضرب مخرجات ControlNet في controlnet_conditioning_scale قبل إضافتها إلى الباقي في unet الأصلية. إذا تم تحديد عدة ControlNets في init، يمكنك تعيين المقياس المقابل كقائمة.

control_mode (int أو list[int]، اختياري، القيمة الافتراضية هي None) : وضع التحكم عند تطبيق ControlNet-Union.

num_images_per_prompt (int، اختياري، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه.

generator (torch.Generator أو list[torch.Generator]، اختياري) : مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا.

latents (torch.FloatTensor، اختياري) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، فسيتم إنشاء كامنات من خلال الاستخراج باستخدام generator العشوائي المُقدَّم.

prompt_embeds (torch.FloatTensor، اختياري) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال prompt.

pooled_prompt_embeds (torch.FloatTensor، اختياري) : تمثيلات نصية مجمّعة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد التمثيلات النصية المجمّعة من معامل الإدخال prompt.

negative_prompt_embeds (torch.FloatTensor، اختياري) : تمثيلات نصية سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.

negative_pooled_prompt_embeds (torch.FloatTensor، اختياري) : تمثيلات نصية مجمعة سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد pooled negative_prompt_embeds من معامل الإدخال negative_prompt.

ip_adapter_image : (PipelineImageInput، اختياري): إدخال صورة اختياري للعمل مع IP Adapters.

ip_adapter_image_embeds (list[torch.Tensor]، اختياري) : تمثيلات صور مُولّدة مسبقًا لـ IP-Adapter. يجب أن يكون قائمة بطول يساوي عدد وحدات IP-adapter. يجب أن يكون كل عنصر منها متجهًا (tensor) بشكل (batch_size, num_images, emb_dim). إذا لم يُقدَّم، تُحسب التمثيلات من معامل الإدخال ip_adapter_image.

negative_ip_adapter_image : (PipelineImageInput، اختياري): إدخال صورة اختياري للعمل مع IP Adapters.

negative_ip_adapter_image_embeds (list[torch.Tensor]، اختياري) : تمثيلات صور مُولّدة مسبقًا لـ IP-Adapter. يجب أن يكون قائمة بطول يساوي عدد وحدات IP-adapter. يجب أن يكون كل عنصر منها متجهًا (tensor) بشكل (batch_size, num_images, emb_dim). إذا لم يُقدَّم، تُحسب التمثيلات من معامل الإدخال ip_adapter_image.

output_type (str، اختياري، القيمة الافتراضية "pil") : صيغة الصورة الناتجة عن عملية التوليد. اختر بين PIL: PIL.Image.Image أو np.array.

return_dict (bool، اختياري، الافتراضي True) : ما إذا كان يجب إرجاع ~pipelines.flux.FluxPipelineOutput بدلاً من tuple عادي.

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

callback_on_step_end (Callable، اختياري) : دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). سيتضمن callback_kwargs قائمة بجميع المصفوفات كما حددتها callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (list، اختياري) : قائمة مدخلات المصفوفات (tensors) لدالة callback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كحجة callback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية ._callback_tensor_inputs لفئة خط الأنابيب (pipeline) الخاص بك.

max_sequence_length (int الافتراضي 512) : أقصى طول تسلسل يُستخدم مع prompt.

يعيد: ~pipelines.flux.FluxPipelineOutput أو tuple

~pipelines.flux.FluxPipelineOutput إذا كان return_dict هو True، وإلا tuple. عند إرجاع tuple، يكون العنصر الأول قائمة تحتوي على الصور المولّدة.

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:

>>> import torch
>>> from diffusers.utils import load_image
>>> from diffusers import FluxControlNetPipeline
>>> from diffusers import FluxControlNetModel

>>> base_model = "black-forest-labs/FLUX.1-dev"
>>> controlnet_model = "InstantX/FLUX.1-dev-controlnet-canny"
>>> controlnet = FluxControlNetModel.from_pretrained(controlnet_model, torch_dtype=torch.bfloat16)
>>> pipe = FluxControlNetPipeline.from_pretrained(
...     base_model, controlnet=controlnet, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> control_image = load_image("https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg")
>>> prompt = "A girl in city, 25 years old, cool, futuristic"
>>> image = pipe(
...     prompt,
...     control_image=control_image,
...     control_guidance_start=0.2,
...     control_guidance_end=0.8,
...     controlnet_conditioning_scale=1.0,
...     num_inference_steps=28,
...     guidance_scale=3.5,
... ).images[0]
>>> image.save("flux.png")

encode_prompt[[diffusers.FluxControlNetPipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], prompt_2: str | list[str] | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, max_sequence_length: int = 512, lora_scale: float | None = None)

المصدر

المعاملات:

prompt (str أو list[str]، اختياري) : النص الذي سيتم ترميزه

prompt_2 (str أو list[str]، اختياري) : الموجه أو الموجهات المرسل إلى tokenizer_2 وtext_encoder_2. إذا لم يُعرَّف، يُستخدم prompt في جميع مُشفِّرات النص

device : (torch.device): جهاز torch

num_images_per_prompt (int) : عدد الصور التي يجب توليدها لكل موجه

prompt_embeds (torch.FloatTensor، اختياري) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال prompt.

pooled_prompt_embeds (torch.FloatTensor، اختياري) : تمثيلات نصية مجمّعة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد التمثيلات النصية المجمّعة من معامل الإدخال prompt.

lora_scale (float، اختياري) : مقياس lora سيُطبَّق على جميع طبقات LoRA في مُشفِّر النص إذا كانت طبقات LoRA محمَّلة.

FluxPipelineOutput[[diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput]]

diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput[[diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput]]

diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)

المصدر

المعاملات:

images (list[PIL.Image.Image] أو torch.Tensor أو np.ndarray) : قائمة من صور PIL منزوعة الضوضاء بطول batch_size أو مصفوفة numpy أو tensor من torch بأبعاد (batch_size, height, width, num_channels). تمثل صور PIL أو مصفوفة numpy الصور منزوعة الضوضاء في خط أنابيب الانتشار. يمكن أن تمثل tensors من torch إما الصور منزوعة الضوضاء أو الكمونيات الوسيطة الجاهزة للتحويل إلى المُفكِّك.

فئة الإخراج لخطوط أنابيب توليد صور Flux.