Diffusers documentation
FluxControlInpaint
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 | رابط |
| Canny | Black Forest Labs | رابط |
قد يكون تشغيل Flux مكلفًا إلى حد كبير على أجهزة العتاد الاستهلاكي. ومع ذلك، يمكنك تنفيذ مجموعة من التحسينات لتشغيله بشكل أسرع وبطريقة أكثر كفاءة في استخدام الذاكرة. راجع هذا القسم لمزيد من التفاصيل. بالإضافة إلى ذلك، يمكن أن يستفيد Flux من التكميم (Quantization) لتحسين كفاءة الذاكرة مقابل زيادة في زمن الاستدلال (Inference Latency). للاطلاع على المزيد، راجع هذا المنشور على المدونة. للحصول على قائمة شاملة بالموارد، راجع هذا الملخص (Gist).
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
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModeltokenizer: CLIPTokenizertext_encoder_2: T5EncoderModeltokenizer_2: T5Tokenizertransformer: FluxTransformer2DModel )
المعاملات
- 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 لتعبئة الصور باستخدام Flux-dev-Depth/Canny.
مرجع: https://blackforestlabs.ai/announcing-black-forest-labs/
__call__
< source >( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrol_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemasked_image_latents: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Noneheight: int | None = Nonewidth: int | None = Nonestrength: float = 0.6num_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 7.0num_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512 ) → ~pipelines.flux.FluxPipelineOutput or tuple
المعاملات
- 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 تمثل دفعة من الصور تُستخدم كنقطة انطلاق. بالنسبة لمصفوفة numpy وtensor الخاص بـ pytorch، النطاق المتوقع للقيم هو بين[0, 1]إذا كان tensor أو قائمة من tensors، يجب أن يكون الشكل المتوقع(B, C, H, W)أو(C, H, W). أما إذا كانت مصفوفة numpy أو قائمة من المصفوفات، فيجب أن يكون الشكل المتوقع(B, H, W, C)أو(H, W, C)كما يمكنه قبول كامنات الصور كـ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. إذا لم يُقدَّم، فسيتم توليد تينسور latents للقناع بواسطة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. يُعرَّفguidance_scaleعلى أنهwمن المعادلة 2 في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيينguidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بـpromptالنصي، وعادةً على حساب انخفاض جودة الصورة. - num_images_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه. - generator (
torch.Generatorأوlist[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا. - latents (
torch.FloatTensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كائن latents عن طريق الاستخراج باستخدام مولّد الأرقام العشوائيةgeneratorالمُقدَّم. - prompt_embeds (
torch.FloatTensor, اختياري) — تضمينات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - pooled_prompt_embeds (
torch.FloatTensor، اختياري) — تضمينات نصية مجمّعة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص المجمّعة من معامل الإدخالprompt. - 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 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
< source >( prompt: str | list[str]prompt_2: str | list[str] | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonemax_sequence_length: int = 512lora_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
< source >( 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.