# FluxControlInpaint FluxControlInpaintPipeline هو تطبيق لتعبئة المناطق المفقودة (Inpainting) لنماذج Flux.1 Depth/Canny. وهو خط أنابيب يتيح لك تعبئة الصور باستخدام نماذج Flux.1 Depth/Canny. يستقبل الخط أنابيب صورة وقناعًا كمدخلات ويعيد الصورة بعد التعبئة. FLUX.1 Depth and Canny [dev] هو محوّل تدفق مُصحح (rectified flow transformer) يحتوي على 12 مليار معامل، قادر على توليد صورة بناءً على وصف نصي مع الالتزام ببنية صورة الإدخال المعطاة. **هذا ليس نموذج ControlNet**. | نوع التحكم | المطوّر | رابط | | -------- | ---------- | ---- | | العمق | [Black Forest Labs](https://huggingface.co/black-forest-labs) | [رابط](https://huggingface.co/black-forest-labs/FLUX.1-Depth-dev) | | Canny | [Black Forest Labs](https://huggingface.co/black-forest-labs) | [رابط](https://huggingface.co/black-forest-labs/FLUX.1-Canny-dev) | > [!TIP] > قد يكون تشغيل Flux مكلفًا إلى حد كبير على أجهزة العتاد الاستهلاكي. ومع ذلك، يمكنك تنفيذ مجموعة من التحسينات لتشغيله بشكل أسرع وبطريقة أكثر كفاءة في استخدام الذاكرة. راجع [هذا القسم](https://huggingface.co/blog/sd3#memory-optimizations-for-sd3) لمزيد من التفاصيل. بالإضافة إلى ذلك، يمكن أن يستفيد Flux من التكميم (Quantization) لتحسين كفاءة الذاكرة مقابل زيادة في زمن الاستدلال (Inference Latency). للاطلاع على المزيد، راجع [هذا المنشور على المدونة](https://huggingface.co/blog/quanto-diffusers). للحصول على قائمة شاملة بالموارد، راجع [هذا الملخص (Gist)](https://gist.github.com/sayakpaul/b664605caf0aa3bf8585ab109dd5ac9c). ```python import torch from diffusers import FluxControlInpaintPipeline from diffusers.models.transformers import FluxTransformer2DModel from transformers import T5EncoderModel from diffusers.utils import load_image, make_image_grid from image_gen_aux import DepthPreprocessor # https://github.com/huggingface/image_gen_aux from PIL import Image import numpy as np pipe = FluxControlInpaintPipeline.from_pretrained( "black-forest-labs/FLUX.1-Depth-dev", dtype=torch.bfloat16, ) # use following lines if you have GPU constraints # --------------------------------------------------------------- transformer = FluxTransformer2DModel.from_pretrained( "sayakpaul/FLUX.1-Depth-dev-nf4", subfolder="transformer", dtype=torch.bfloat16 ) text_encoder_2 = T5EncoderModel.from_pretrained( "sayakpaul/FLUX.1-Depth-dev-nf4", subfolder="text_encoder_2", dtype=torch.bfloat16 ) pipe.transformer = transformer pipe.text_encoder_2 = text_encoder_2 pipe.enable_model_cpu_offload() # --------------------------------------------------------------- pipe.to("cuda") # or "mps", "xpu", "cpu" prompt = "a blue robot singing opera with human-like expressions" image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/robot.png") head_mask = np.zeros_like(image) head_mask[65:580,300:642] = 255 mask_image = Image.fromarray(head_mask) processor = DepthPreprocessor.from_pretrained("LiheYoung/depth-anything-large-hf") control_image = processor(image)[0].convert("RGB") output = pipe( prompt=prompt, image=image, control_image=control_image, mask_image=mask_image, num_inference_steps=30, strength=0.9, guidance_scale=10.0, generator=torch.Generator().manual_seed(42), ).images[0] make_image_grid([image, control_image, mask_image, output.resize(image.size)], rows=1, cols=4).save("output.png") ``` ## FluxControlInpaintPipeline[[diffusers.FluxControlInpaintPipeline]] #### diffusers.FluxControlInpaintPipeline[[diffusers.FluxControlInpaintPipeline]] ```python diffusers.FluxControlInpaintPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, text_encoder_2: T5EncoderModel, tokenizer_2: T5Tokenizer, transformer: FluxTransformer2DModel) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_flux_control_inpaint.py#L204) **المعاملات:** transformer ([FluxTransformer2DModel](/docs/diffusers/v0.43.0/ar/api/models/flux_transformer#diffusers.FluxTransformer2DModel)) : معمارية Transformer الشرطية (MMDiT) لإزالة الضوضاء من الكامنات المُرمّزة للصورة. scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مُجدوِل يُستخدم بالاقتران مع `transformer` لإزالة الضوضاء من كامنات الصورة المُرمَّزة. vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl#diffusers.AutoencoderKL)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها. text_encoder (`CLIPTextModel`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel)، وتحديداً النسخة [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14). text_encoder_2 (`T5EncoderModel`) : [T5](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5EncoderModel)، وتحديداً النسخة [google/t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl). tokenizer (`CLIPTokenizer`) : مُقسِّم من الفئة [CLIPTokenizer](https://huggingface.co/docs/transformers/en/model_doc/clip#transformers.CLIPTokenizer). tokenizer_2 (`T5TokenizerFast`) : مُرمِّز ثانٍ من الفئة [T5TokenizerFast](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5TokenizerFast). خط أنابيب Flux لتعبئة الصور باستخدام Flux-dev-Depth/Canny. مرجع: https://blackforestlabs.ai/announcing-black-forest-labs/ #### __call__[[diffusers.FluxControlInpaintPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, mask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, masked_image_latents: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, height: int | None = None, width: int | None = None, strength: float = 0.6, num_inference_steps: int = 28, sigmas: list[float] | None = None, guidance_scale: float = 7.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, 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_flux_control_inpaint.py#L753) **المعاملات:** prompt (`str` أو `list[str]`، *اختياري*) : الأمر أو الأوامر التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير `prompt_embeds` بدلاً من ذلك. prompt_2 (`str` أو `list[str]`، *اختياري*) : الموجه أو الموجهات المرسل إلى `tokenizer_2` و`text_encoder_2`. إذا لم يُعرَّف، فسيتم استخدام `prompt` بدلاً منه image (`torch.Tensor`، `PIL.Image.Image`، `np.ndarray`، `list[torch.Tensor]`، `list[PIL.Image.Image]`، أو `list[np.ndarray]`) : `Image`، مصفوفة numpy أو tensor تمثل دفعة من الصور (image batch) لاستخدامها كنقطة انطلاق. لكل من مصفوفة numpy وtensor الخاص بـ pytorch، النطاق المتوقع للقيم هو بين `[0, 1]` إذا كان tensor أو قائمة من tensors، فيجب أن يكون الشكل المتوقع `(B, C, H, W)` أو `(C, H, W)`. إذا كانت مصفوفة numpy أو قائمة من المصفوفات، فيجب أن يكون الشكل المتوقع `(B, H, W, C)` أو `(H, W, C)` كما يمكنه قبول كامنات الصور (image latents) كـ `image`، ولكن إذا تم تمرير الكامنات مباشرةً فلن يتم ترميزها مرة أخرى. 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 واحدة. mask_image (`torch.Tensor`، `PIL.Image.Image`، `np.ndarray`، `list[torch.Tensor]`، `list[PIL.Image.Image]`، أو `list[np.ndarray]`) : `Image`، مصفوفة numpy أو tensor تمثل دفعة من الصور لتطبيق قناع على `image`. يتم إعادة رسم البكسلات البيضاء في القناع بينما تُحفظ البكسلات السوداء. إذا كان `mask_image` صورة PIL، يتم تحويلها إلى قناة واحدة (السطوع) قبل الاستخدام. وإذا كانت مصفوفة numpy أو tensor من pytorch، يجب أن تحتوي على قناة لون واحدة (L) بدلاً من ثلاث، لذا فإن الشكل المتوقع لـ tensor من pytorch هو `(B, 1, H, W)`، `(B, H, W)`، `(1, H, W)`، `(H, W)`. أما لمصفوفة numpy فيكون الشكل `(B, H, W, 1)`، `(B, H, W)`، `(H, W, 1)`، أو `(H, W)`. masked_image_latents (`torch.Tensor`، `list[torch.Tensor]`) : `Tensor` يمثل دفعة من الصور لتطبيق قناع على `image` التي ولّدها VAE. إذا لم يُقدَّم، فسيتم توليد متجه قناع الكامنات بواسطة `mask_image`. height (`int`، *اختياري*، الافتراضي هو self.unet.config.sample_size * self.vae_scale_factor) : ارتفاع الصورة المولّدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج. width (`int`، *اختياري*، القيمة الافتراضية هي self.unet.config.sample_size * self.vae_scale_factor) : عرض الصورة المولدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج. strength (`float`، *اختياري*، القيمة الافتراضية 1.0) : يحدد مدى تحويل الصورة المرجعية `image`. يجب أن يكون بين 0 و 1. تُستخدم `image` كنقطة انطلاق، وكلما ارتفعت قيمة `strength` زاد مقدار الضوضاء المضافة. يعتمد عدد خطوات إزالة الضوضاء على كمية الضوضاء المضافة في البداية. عندما تكون `strength` تساوي 1، تكون الضوضاء المضافة في أقصى حد، وتعمل عملية إزالة الضوضاء لعدد التكرارات الكامل المحدد في `num_inference_steps`. القيمة 1 تتجاهل `image` بشكل أساسي. num_inference_steps (`int`، *اختياري*، القيمة الافتراضية 50) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال. sigmas (`list[float]`، *اختياري*) : قيم `sigmas` مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل `sigmas` في طريقة `set_timesteps` الخاصة بهم. إذا لم تُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير `num_inference_steps`. guidance_scale (`float`، *اختياري*، القيمة الافتراضية 7.0) : مقياس التوجيه كما هو مُعرَّف في [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://huggingface.co/papers/2205.11487). يتم تفعيل مقياس التوجيه عن طريق تعيين `guidance_scale > 1`. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt`، وعادةً على حساب انخفاض جودة الصورة. num_images_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه. generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : مولّد واحد أو قائمة من [مولّدات torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا. latents (`torch.FloatTensor`، *اختياري*) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، فسيتم إنشاء كامنات من خلال الاستخراج باستخدام `generator` العشوائي المُقدَّم. prompt_embeds (`torch.FloatTensor`، *اختياري*) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال `prompt`. pooled_prompt_embeds (`torch.FloatTensor`، *اختياري*) : تمثيلات نصية مجمّعة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد التمثيلات النصية المجمّعة من معامل الإدخال `prompt`. output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر بين [PIL](https://pillow.readthedocs.io/en/stable/): `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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). 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، يكون العنصر الأول قائمة تحتوي على الصور المولّدة. الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد. أمثلة: ```py import torch from diffusers import FluxControlInpaintPipeline from diffusers.models.transformers import FluxTransformer2DModel from transformers import T5EncoderModel from diffusers.utils import load_image, make_image_grid from image_gen_aux import DepthPreprocessor # https://github.com/huggingface/image_gen_aux from PIL import Image import numpy as np pipe = FluxControlInpaintPipeline.from_pretrained( "black-forest-labs/FLUX.1-Depth-dev", torch_dtype=torch.bfloat16, ) # use following lines if you have GPU constraints # --------------------------------------------------------------- transformer = FluxTransformer2DModel.from_pretrained( "sayakpaul/FLUX.1-Depth-dev-nf4", subfolder="transformer", torch_dtype=torch.bfloat16 ) text_encoder_2 = T5EncoderModel.from_pretrained( "sayakpaul/FLUX.1-Depth-dev-nf4", subfolder="text_encoder_2", torch_dtype=torch.bfloat16 ) pipe.transformer = transformer pipe.text_encoder_2 = text_encoder_2 pipe.enable_model_cpu_offload() # --------------------------------------------------------------- pipe.to("cuda") prompt = "a blue robot singing opera with human-like expressions" image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/robot.png") head_mask = np.zeros_like(image) head_mask[65:580, 300:642] = 255 mask_image = Image.fromarray(head_mask) processor = DepthPreprocessor.from_pretrained("LiheYoung/depth-anything-large-hf") control_image = processor(image)[0].convert("RGB") output = pipe( prompt=prompt, image=image, control_image=control_image, mask_image=mask_image, num_inference_steps=30, strength=0.9, guidance_scale=10.0, generator=torch.Generator().manual_seed(42), ).images[0] make_image_grid([image, control_image, mask_image, output.resize(image.size)], rows=1, cols=4).save( "output.png" ) ``` #### encode_prompt[[diffusers.FluxControlInpaintPipeline.encode_prompt]] ```python 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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_flux_control_inpaint.py#L376) **المعاملات:** 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]] ```python diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray) ``` [المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/flux/pipeline_output.py#L11) **المعاملات:** 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.