diffusers/main/ar/api/pipelines/stable_diffusion/stable_diffusion_3.md

Stable Diffusion 3

قُدِّم Stable Diffusion 3 (SD3) في Scaling Rectified Flow Transformers for High-Resolution Image Synthesis من قِبل Patrick Esser وSumith Kulal وAndreas Blattmann وRahim Entezari وJonas Muller وHarry Saini وYam Levi وDominik Lorenz وAxel Sauer وFrederic Boesel وDustin Podell وTim Dockhorn وZion English وKyle Lacey وAlex Goodwin وYannik Marek وRobin Rombach.

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

تُنشئ نماذج الانتشار البيانات من الضوضاء عن طريق عكس المسارات الأمامية للبيانات نحو الضوضاء، وقد برزت كتقنية قوية لنمذجة التوليد للبيانات عالية الأبعاد ذات الطابع الإدراكي مثل الصور والفيديوهات. يُعد التدفق المُصحَّح صياغة حديثة لنماذج التوليد تربط بين البيانات والضوضاء بخط مستقيم. وعلى الرغم من خصائصه النظرية الأفضل وبساطته المفاهيمية، إلا أنه لم يُثبَت بعد بشكل قاطع كممارسة قياسية. في هذا العمل، نحسّن تقنيات أخذ العينات من الضوضاء الحالية لتدريب نماذج التدفق المُصحَّح عن طريق تحيّزها نحو المقاييس ذات الصلة الإدراكية. من خلال دراسة واسعة النطاق، نُثبت الأداء المتفوق لهذا النهج مقارنة بصياغات الانتشار الراسخة في تركيب النص إلى صورة عالي الدقة. بالإضافة إلى ذلك، نعرض معمارية جديدة مبنية على الترانسفورمر لتوليد النص إلى صورة، تستخدم أوزانًا منفصلة لكل من النمطين وتُمكّن من تدفق ثنائي الاتجاه للمعلومات بين رموز الصورة والنص، مما يحسّن فهم النص والخطوط وتقييمات التفضيل البشري. نُثبت أن هذه المعمارية تتبع اتجاهات توسع قابلة للتنبؤ، وأن انخفاض خسارة التحقق يرتبط بتحسين تركيب النص إلى الصورة كما تقيسه مقاييس مختلفة وتقييمات بشرية.

مثال على الاستخدام

بما أن النموذج محمي، فقبل استخدامه مع diffusers، عليك أولاً الانتقال إلى صفحة Stable Diffusion 3 Medium على Hugging Face، وملء النموذج وقبول شروط الحماية. بعد الدخول، يجب عليك تسجيل الدخول حتى يعرف نظامك أنك قد قبلت شروط الحماية.

استخدم الأمر أدناه لتسجيل الدخول:

hf auth login

يستخدم خط أنابيب SD3 ثلاثة مشفّرات نصية لتوليد صورة. يكون تفريغ النماذج ضرورياً حتى يعمل على معظم الأجهزة التجارية. يُرجى استخدام نوع البيانات torch.float16 لتحقيق توفير إضافي في الذاكرة.

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", dtype=torch.float16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world.png")

ملاحظة: يمكن تشغيل Stable Diffusion 3.5 أيضًا باستخدام خط أنابيب SD3، وتُطبَّق جميع التحسينات والتقنيات المذكورة عليه كذلك. يوجد إجمالًا ثلاثة نماذج رسمية في عائلة SD3:

• stabilityai/stable-diffusion-3-medium-diffusers
• stabilityai/stable-diffusion-3.5-large
• stabilityai/stable-diffusion-3.5-large-turbo

التوجيه بالصور باستخدام IP-Adapters

يتيح لك IP-Adapter تقديم الصور إلى SD3 بالإضافة إلى النص الوصفي. وهذا مفيد بشكل خاص عند وصف مفاهيم معقدة يصعب التعبير عنها بالنص وحده، ولديك صور مرجعية. لتحميل IP-Adapter واستخدامه، تحتاج إلى:

• image_encoder: نموذج رؤية مُدرَّب مسبقًا يُستخدم للحصول على ميزات الصورة، وعادةً ما يكون مُشفِّر صور CLIP.
• feature_extractor: مُعالِج الصور الذي يُعدّ الصورة المُدخلة للمُشفِّر image_encoder المُختار.
• ip_adapter_id: نقطة تحقق تحتوي على معاملات طبقات الانتباه المتقاطع للصور والتسليط.

تُدرَّب مُكيّفات IP-Adapter على بنية نموذج محددة، لذا تعمل أيضًا مع النسخ المُحسَّنة من النموذج الأساسي. يمكنك استخدام دالة ~SD3IPAdapterMixin.set_ip_adapter_scale لضبط مدى توافق المخرجات مع موجه الصورة. كلما ارتفعت القيمة، زادت درجة التزام النموذج بموجه الصورة. عادةً ما تكون القيمة الافتراضية 0.5 توازنًا جيدًا، إذ تضمن أن يراعي النموذج كلا الموجهين النصي والصوري بالتساوي.

import torch
from PIL import Image

from diffusers import StableDiffusion3Pipeline
from transformers import SiglipVisionModel, SiglipImageProcessor

image_encoder_id = "google/siglip-so400m-patch14-384"
ip_adapter_id = "InstantX/SD3.5-Large-IP-Adapter"

feature_extractor = SiglipImageProcessor.from_pretrained(
    image_encoder_id,
    dtype=torch.float16
)
image_encoder = SiglipVisionModel.from_pretrained(
    image_encoder_id,
    dtype=torch.float16
).to( "cuda")  # or "mps", "xpu", "cpu"

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    dtype=torch.float16,
    feature_extractor=feature_extractor,
    image_encoder=image_encoder,
).to("cuda")

pipe.load_ip_adapter(ip_adapter_id)
pipe.set_ip_adapter_scale(0.6)

ref_img = Image.open("image.jpg").convert('RGB')

image = pipe(
    width=1024,
    height=1024,
    prompt="a cat",
    negative_prompt="lowres, low quality, worst quality",
    num_inference_steps=24,
    guidance_scale=5.0,
    ip_adapter_image=ref_img
).images[0]

image.save("result.jpg")

أمثلة على IP-Adapter مع الأمر النصي "قطة"

اطّلع على IP-Adapter لمعرفة المزيد حول كيفية عمل IP-Adapters.

تحسينات الذاكرة لـ SD3

يستخدم SD3 ثلاثة مشفّرات نصية، أحدها هو نموذج T5-XXL الضخم جدًا. وهذا يجعل تشغيل النموذج على وحدات معالجة رسومية (GPU) ذات ذاكرة VRAM أقل من 24 غيغابايت أمرًا صعبًا، حتى عند استخدام دقة fp16. توضح القسم التالي بعض تحسينات الذاكرة في Diffusers التي تسهّل تشغيل SD3 على الأجهزة ذات الموارد المحدودة.

تشغيل الاستدلال مع تفريغ النموذج

يتيح لك تحسين الذاكرة الأساسي المتاح في Diffusers نقل مكونات النموذج إلى وحدة المعالجة المركزية (CPU) أثناء الاستدلال (inference) لتوفير الذاكرة، مع حدوث زيادة طفيفة في زمن الاستجابة للاستدلال. لن ينقل نقل النموذج (Model offloading) مكوّنًا من مكونات النموذج إلى وحدة معالجة الرسوميات (GPU) إلا عند الحاجة إلى تنفيذه، مع إبقاء المكونات المتبقية على وحدة المعالجة المركزية (CPU).

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", dtype=torch.float16)
pipe.enable_model_cpu_offload()

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world.png")

إسقاط مُشفِّر النص T5 أثناء الاستدلال

يمكن أن يؤدي إزالة مُشفّر النص T5-XXL كثيف الاستهلاك للذاكرة والمكوّن من 4.7 مليار معامل أثناء الاستدلال إلى تقليل متطلبات الذاكرة بشكل كبير لنموذج SD3 مع فقدان طفيف فقط في الأداء.

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3-medium-diffusers",
    text_encoder_3=None,
    tokenizer_3=None,
    dtype=torch.float16
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world-no-T5.png")

استخدام نسخة مُكمّمة من مُشفّر النص T5

يمكننا الاستفادة من مكتبة bitsandbytes لتحميل مُشفِّر النص T5-XXL وتكميمه بدقة 8 بت. وهذا يتيح لك مواصلة استخدام مُشفِّرات النص الثلاثة جميعها مع تأثير طفيف فقط على الأداء.

قم أولاً بتثبيت مكتبة bitsandbytes.

pip install bitsandbytes

ثم حمّل نموذج T5-XXL باستخدام BitsAndBytesConfig.

import torch
from diffusers import StableDiffusion3Pipeline
from transformers import T5EncoderModel, BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(load_in_8bit=True)

model_id = "stabilityai/stable-diffusion-3-medium-diffusers"
text_encoder = T5EncoderModel.from_pretrained(
    model_id,
    subfolder="text_encoder_3",
    quantization_config=quantization_config,
)
pipe = StableDiffusion3Pipeline.from_pretrained(
    model_id,
    text_encoder_3=text_encoder,
    device_map="balanced",
    dtype=torch.float16
)

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world-8bit-T5.png")

يمكنك العثور على السكربت من البداية إلى النهاية هنا.

تحسينات الأداء لـ SD3

استخدام Torch Compile لتسريع الاستدلال

يمكن أن يؤدي استخدام المكونات المُجمَّعة في خط أنابيب SD3 إلى تسريع الاستدلال بمقدار يصل إلى 4 أضعاف. يوضح مقتطف الشيفرة التالي كيفية تجميع مكوّني Transformer وVAE في خط أنابيب SD3.

import torch
from diffusers import StableDiffusion3Pipeline

torch.set_float32_matmul_precision("high")

torch._inductor.config.conv_1x1_as_mm = True
torch._inductor.config.coordinate_descent_tuning = True
torch._inductor.config.epilogue_fusion = False
torch._inductor.config.coordinate_descent_check_all_directions = True

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3-medium-diffusers",
    dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"
pipe.set_progress_bar_config(disable=True)

pipe.transformer.to(memory_format=torch.channels_last)
pipe.vae.to(memory_format=torch.channels_last)

pipe.transformer = torch.compile(pipe.transformer, mode="max-autotune", fullgraph=True)
pipe.vae.decode = torch.compile(pipe.vae.decode, mode="max-autotune", fullgraph=True)

# Warm Up
prompt = "a photo of a cat holding a sign that says hello world"
for _ in range(3):
    _ = pipe(prompt=prompt, generator=torch.manual_seed(1))

# Run Inference
image = pipe(prompt=prompt, generator=torch.manual_seed(1)).images[0]
image.save("sd3_hello_world.png")

اطّلع على النص البرمجي الكامل هنا.

التكميم

يساعد التكميم (Quantization) في تقليل متطلبات الذاكرة للنماذج الكبيرة جدًا من خلال تخزين أوزان النموذج في نوع بيانات بدقة أقل. ومع ذلك، قد يكون للتكميم تأثير متباين على جودة الفيديو اعتمادًا على نموذج الفيديو المستخدم.

راجع نظرة عامة حول التكميم لمعرفة المزيد حول محركات التكميم المدعومة واختيار محرك تكميم يدعم حالتك الاستخدامية. يوضح المثال أدناه كيفية تحميل StableDiffusion3Pipeline مُكمَّم للاستدلال باستخدام bitsandbytes.

import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, SD3Transformer2DModel, StableDiffusion3Pipeline
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    subfolder="text_encoder_3",
    quantization_config=quant_config,
    dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = SD3Transformer2DModel.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = "a tiny astronaut hatching from an egg on the moon"
image = pipeline(prompt, num_inference_steps=28, guidance_scale=7.0).images[0]
image.save("sd3.png")

استخدام الموجهات الطويلة مع مشفّر النص T5

افتراضيًا، يستخدم مُرمِّز النص T5 لـ Text Encoder حدًا أقصى لطول التساوي يساوي 256. يمكن تعديل ذلك عن طريق تعيين max_sequence_length لقبول عدد أقل أو أكبر من الرموز. تجدر الإشارة إلى أن التساوي الأطول تتطلب موارد إضافية وتؤدي إلى أوقات توليد أطول، كما هو الحال أثناء الاستدلال الدُفعي.

prompt = "A whimsical and creative image depicting a hybrid creature that is a mix of a waffle and a hippopotamus, basking in a river of melted butter amidst a breakfast-themed landscape. It features the distinctive, bulky body shape of a hippo. However, instead of the usual grey skin, the creature’s body resembles a golden-brown, crispy waffle fresh off the griddle. The skin is textured with the familiar grid pattern of a waffle, each square filled with a glistening sheen of syrup. The environment combines the natural habitat of a hippo with elements of a breakfast table setting, a river of warm, melted butter, with oversized utensils or plates peeking out from the lush, pancake-like foliage in the background, a towering pepper mill standing in for a tree.  As the sun rises in this fantastical world, it casts a warm, buttery glow over the scene. The creature, content in its butter river, lets out a yawn. Nearby, a flock of birds take flight"

image = pipe(
    prompt=prompt,
    negative_prompt="",
    num_inference_steps=28,
    guidance_scale=4.5,
    max_sequence_length=512,
).images[0]

إرسال موجه مختلف إلى مشفّر النص T5

يمكنك إرسال موجه مختلف إلى مشفّرات النص CLIP ومشفّر النص T5 لمنع تقصير الموجه بواسطة مشفّرات النص CLIP وتحسين عملية التوليد.

لا يزال النص المُدخل مع مشفّرات نصوص CLIP يُقتطع عند حد 77 رمزًا.

prompt = "A whimsical and creative image depicting a hybrid creature that is a mix of a waffle and a hippopotamus, basking in a river of melted butter amidst a breakfast-themed landscape. A river of warm, melted butter, pancake-like foliage in the background, a towering pepper mill standing in for a tree."

prompt_3 = "A whimsical and creative image depicting a hybrid creature that is a mix of a waffle and a hippopotamus, basking in a river of melted butter amidst a breakfast-themed landscape. It features the distinctive, bulky body shape of a hippo. However, instead of the usual grey skin, the creature’s body resembles a golden-brown, crispy waffle fresh off the griddle. The skin is textured with the familiar grid pattern of a waffle, each square filled with a glistening sheen of syrup. The environment combines the natural habitat of a hippo with elements of a breakfast table setting, a river of warm, melted butter, with oversized utensils or plates peeking out from the lush, pancake-like foliage in the background, a towering pepper mill standing in for a tree.  As the sun rises in this fantastical world, it casts a warm, buttery glow over the scene. The creature, content in its butter river, lets out a yawn. Nearby, a flock of birds take flight"

image = pipe(
    prompt=prompt,
    prompt_3=prompt_3,
    negative_prompt="",
    num_inference_steps=28,
    guidance_scale=4.5,
    max_sequence_length=512,
).images[0]

AutoEncoder صغير لـ Stable Diffusion 3

يُعدّ TAESD3 (Tiny AutoEncoder for Stable Diffusion) نسخة مصغّرة مُمزوجة من VAE الخاص بـ Stable Diffusion 3، من إعداد Ollin Boer Bohan، والتي يمكنها فكّ ترميز الكامنات (latents) الخاصة بـ StableDiffusion3Pipeline بشكل شبه فوري.

للاستخدام مع Stable Diffusion 3:

import torch
from diffusers import StableDiffusion3Pipeline, AutoencoderTiny

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3-medium-diffusers", dtype=torch.float16
)
pipe.vae = AutoencoderTiny.from_pretrained("madebyollin/taesd3", dtype=torch.float16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "slice of delicious New York-style berry cheesecake"
image = pipe(prompt, num_inference_steps=25).images[0]
image.save("cheesecake.png")

تحميل نقاط التفتيش الأصلية عبر from_single_file

تدعم فئتا SD3Transformer2DModel وStableDiffusion3Pipeline تحميل نقاط التفتيش الأصلية عبر الطريقة from_single_file. تتيح لك هذه الطريقة تحميل ملفات نقاط التفتيش الأصلية التي استُخدمت لتدريب النماذج.

تحميل نقاط التفتيش الأصلية لـ SD3Transformer2DModel

from diffusers import SD3Transformer2DModel

model = SD3Transformer2DModel.from_single_file("https://huggingface.co/stabilityai/stable-diffusion-3-medium/blob/main/sd3_medium.safetensors")

تحميل نقطة التفتيش المفردة الخاصة بـ StableDiffusion3Pipeline

تحميل نقطة التفتيش من ملف واحد دون T5

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-3-medium/blob/main/sd3_medium_incl_clips.safetensors",
    dtype=torch.float16,
    text_encoder_3=None
)
pipe.enable_model_cpu_offload()

image = pipe("a picture of a cat holding a sign that says hello world").images[0]
image.save('sd3-single-file.png')

تحميل نقطة التفتيش أحادية الملف باستخدام T5

يُحمّل المثال التالي نقطة تفتيش محفوظة بتنسيق فاصلة عشرية 8-بت، ويتطلب ذلك استخدام PyTorch 2.3 أو إصدار أحدث.

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-3-medium/blob/main/sd3_medium_incl_clips_t5xxlfp8.safetensors",
    dtype=torch.float16,
)
pipe.enable_model_cpu_offload()

image = pipe("a picture of a cat holding a sign that says hello world").images[0]
image.save('sd3-single-file-t5-fp8.png')

تحميل نقطة التفتيش أحادية الملف لنموذج Stable Diffusion 3.5 Transformer

import torch
from diffusers import SD3Transformer2DModel, StableDiffusion3Pipeline

transformer = SD3Transformer2DModel.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-3.5-large-turbo/blob/main/sd3.5_large.safetensors",
    dtype=torch.bfloat16,
)
pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    transformer=transformer,
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
image = pipe("a cat holding a sign that says hello world").images[0]
image.save("sd35.png")

StableDiffusion3Pipeline[[diffusers.StableDiffusion3Pipeline]]

diffusers.StableDiffusion3Pipeline[[diffusers.StableDiffusion3Pipeline]]

diffusers.StableDiffusion3Pipeline(transformer: SD3Transformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, text_encoder_2: CLIPTextModelWithProjection, tokenizer_2: CLIPTokenizer, text_encoder_3: T5EncoderModel, tokenizer_3: T5Tokenizer, image_encoder: SiglipVisionModel = None, feature_extractor: SiglipImageProcessorPil = None)

المصدر

المعاملات:

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

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

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

text_encoder (CLIPTextModelWithProjection) : CLIP، وتحديداً النسخة clip-vit-large-patch14، مع إضافة طبقة إسقاط إضافية يتم تهيئتها بمصفوفة قطرية بعدد أبعاد hidden_size.

text_encoder_2 (CLIPTextModelWithProjection) : CLIP، وتحديداً النسخة laion/CLIP-ViT-bigG-14-laion2B-39B-b160k.

text_encoder_3 (T5EncoderModel) : مُشفِّر نص ثابت. يستخدم Stable Diffusion 3 T5، وتحديداً النسخة t5-v1_1-xxl.

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

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

tokenizer_3 (T5TokenizerFast) : مُجزِّئ من الفئة T5Tokenizer.

image_encoder (SiglipVisionModel، اختياري) : نموذج رؤية مُدرَّب مسبقًا لـ IP Adapter.

feature_extractor (SiglipImageProcessor، اختياري) : معالج الصور الخاص بـ IP Adapter.

call[[diffusers.StableDiffusion3Pipeline.call]]

__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, prompt_3: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 28, sigmas: list[float] | None = None, guidance_scale: float = 7.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, negative_prompt_3: str | list[str] | None = None, 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, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_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: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, clip_skip: int | 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 = 256, skip_guidance_layers: list[int] = None, skip_layer_guidance_scale: float = 2.8, skip_layer_guidance_stop: float = 0.2, skip_layer_guidance_start: float = 0.01, mu: float | None = None)

المصدر

المعاملات:

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

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

prompt_3 (str أو list[str]، اختياري) : الموجه أو الموجهات المرسل إلى tokenizer_3 وtext_encoder_3. إذا لم يُعرَّف، فسيتم استخدام 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، وعادةً على حساب انخفاض جودة الصورة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

clip_skip (int, اختياري) : عدد الطبقات التي سيتم تجاوزها من CLIP أثناء حساب تمثيلات الموجه. القيمة 1 تعني أنه سيتم استخدام مخرجات الطبقة قبل الأخيرة لحساب تمثيلات الموجه.

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 الافتراضي 256) : أقصى طول تسلسل يُستخدم مع prompt.

skip_guidance_layers (list[int], اختياري) : قائمة من الأعداد الصحيحة تحدد الطبقات التي يجب تجاوزها أثناء التوجيه. إذا لم تُقدَّم، فسيتم استخدام جميع الطبقات للتوجيه. وإذا قُدِّمت، فسيُطبَّق التوجيه فقط على الطبقات المحددة في القائمة. القيمة الموصى بها من قبل StabiltyAI لنموذج Stable Diffusion 3.5 Medium هي [7, 8, 9].

skip_layer_guidance_scale (int, اختياري) : مقياس التوجيه للطبقات المحددة في skip_guidance_layers. سيُطبَّق التوجيه على الطبقات المحددة في skip_guidance_layers بمقياس skip_layer_guidance_scale. وسيُطبَّق التوجيه على بقية الطبقات بمقياس 1.

skip_layer_guidance_stop (int, اختياري) : الخطوة التي سيتوقف عندها التوجيه للطبقات المحددة في skip_guidance_layers. سيُطبَّق التوجيه على الطبقات المحددة في skip_guidance_layers حتى الكسر المحدد في skip_layer_guidance_stop. القيمة الموصى بها من قبل StabiltyAI لنموذج Stable Diffusion 3.5 Medium هي 0.2.

skip_layer_guidance_start (int, اختياري) : الخطوة التي يبدأ عندها توجيه الطبقات المحددة في skip_guidance_layers. سيُطبَّق التوجيه على الطبقات المحددة في skip_guidance_layers بدءًا من الكسر المحدد في skip_layer_guidance_start. القيمة الموصى بها من قبل StabiltyAI لنموذج Stable Diffusion 3.5 Medium هي 0.01.

mu (float، اختياري) : قيمة mu المستخدمة في dynamic_shifting.

يعيد: ~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput أو tuple

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

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

أمثلة:

>>> import torch
>>> from diffusers import StableDiffusion3Pipeline

>>> pipe = StableDiffusion3Pipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers", torch_dtype=torch.float16
... )
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> image = pipe(prompt).images[0]
>>> image.save("sd3.png")

encode_image[[diffusers.StableDiffusion3Pipeline.encode_image]]

encode_image(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], device: device)

المصدر

المعاملات:

image (PipelineImageInput) : صورة الإدخال المراد ترميزها.

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

يعيد: torch.Tensor

تمثيل ميزات الصورة المُرمّزة.

يقوم بتشفير الصورة المعطاة إلى تمثيل ميزات باستخدام مشفر صور مُدرَّب مسبقًا.

encode_prompt[[diffusers.StableDiffusion3Pipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], prompt_2: str | list[str], prompt_3: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, negative_prompt_3: str | list[str] | None = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, clip_skip: int | None = None, max_sequence_length: int = 256, lora_scale: float | None = None)

المصدر

المعاملات:

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

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

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

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

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

do_classifier_free_guidance (bool) : ما إذا كان سيتم استخدام التوجيه الحر للتصنيف أم لا

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

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

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

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

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

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

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

clip_skip (int, اختياري) : عدد الطبقات التي سيتم تجاوزها من CLIP أثناء حساب تمثيلات الموجه. القيمة 1 تعني أنه سيتم استخدام مخرجات الطبقة قبل الأخيرة لحساب تمثيلات الموجه.

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

prepare_ip_adapter_image_embeds[[diffusers.StableDiffusion3Pipeline.prepare_ip_adapter_image_embeds]]

prepare_ip_adapter_image_embeds(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: typing.Optional[torch.Tensor] = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True)

المصدر

المعاملات:

ip_adapter_image (PipelineImageInput، اختياري) : الصورة المدخلة لاستخراج الميزات من أجل IP-Adapter.

ip_adapter_image_embeds (torch.Tensor، اختياري) : تمثيلات الصور المحسوبة مسبقًا.

device : (torch.device, اختياري): جهاز Torch.

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

do_classifier_free_guidance (bool، القيمة الافتراضية True) : ما إذا كان سيتم استخدام classifier free guidance أم لا.

يُعدّ تمثيلات الصور للاستخدام في IP-Adapter.

يجب تمرير ip_adapter_image أو ip_adapter_image_embeds.