Diffusers documentation
Stable Diffusion 3
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-diffusersstabilityai/stable-diffusion-3.5-largestabilityai/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-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
يُعدّ Tiny AutoEncoder for Stable Diffusion (TAESD3) نسخة مصغّرة مُميَّزة من VAE الخاص بـ Stable Diffusion 3، من إعداد Ollin Boer Bohan، والتي يمكنها فكّ ترميز الكامنات الخاصة بـ 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
< source >( transformer: SD3Transformer2DModelscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertext_encoder_2: CLIPTextModelWithProjectiontokenizer_2: CLIPTokenizertext_encoder_3: T5EncoderModeltokenizer_3: T5Tokenizerimage_encoder: SiglipVisionModel = Nonefeature_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__
< source >( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneprompt_3: str | list[str] | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 7.0negative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Nonenum_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] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Noneclip_skip: int | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 256skip_guidance_layers: list = Noneskip_layer_guidance_scale: float = 2.8skip_layer_guidance_stop: float = 0.2skip_layer_guidance_start: float = 0.01mu: float | None = None ) → ~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput or tuple
المعاملات
- 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، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كائن latents عن طريق الاستخراج باستخدام مولّد الأرقام العشوائية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، اختياري) — تضمينات نصية مجمعة سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن المحفّز. إذا لم تُقدَّم، فسيتم توليد تضمينات 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
< source >( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]device: device ) → torch.Tensor
يقوم بتشفير الصورة المعطاة إلى تمثيل ميزات باستخدام مشفر صور مُدرَّب مسبقًا.
encode_prompt
< source >( prompt: str | list[str]prompt_2: str | list[str]prompt_3: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneclip_skip: int | None = Nonemax_sequence_length: int = 256lora_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) — ما إذا كان سيتم استخدام classifier free guidance أم لا - 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، اختياري) — تضمينات نصية مجمعة سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن المحفّز. إذا لم تُقدَّم، فسيتم توليد تضمينات negative_prompt_embeds المجمعة من معامل الإدخالnegative_prompt. - clip_skip (
int, اختياري) — عدد الطبقات التي سيتم تجاوزها من CLIP أثناء حساب تمثيلات الموجه. القيمة 1 تعني أنه سيتم استخدام مخرجات الطبقة قبل الأخيرة لحساب تمثيلات الموجه. - lora_scale (
float، اختياري) — مقياس LoRA سيُطبَّق على جميع طبقات LoRA في مُشفِّر النص إذا كانت طبقات LoRA محمَّلة.
prepare_ip_adapter_image_embeds
< source >( ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_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.