Hugging Face's logo

Diffusers documentation

Stable Diffusion 3

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Stable Diffusion 3

LoRA MPS

Stable Diffusion 3 (SD3), 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 ve Robin Rombach tarafından Scaling Rectified Flow Transformers for High-Resolution Image Synthesis makalesinde önerilmiştir.

Makalenin özeti şudur:

Diffüzyon modelleri, verinin gürültüye doğru ilerleyen ileri yollarını tersine çevirerek gürültüden veri üretir ve görüntüler ile videolar gibi yüksek boyutlu, algısal veriler için güçlü bir üretken modelleme tekniği olarak ortaya çıkmıştır. Düzeltici akış (rectified flow), veriyi ve gürültüyü düz bir çizgiyle bağlayan son zamanlarda ortaya çıkan bir üretken model formülasyonudur. Daha iyi teorik özelliklere ve kavramsal basitliğe sahip olmasına rağmen, henüz standart uygulama olarak kesin bir şekilde yerleşmemiştir. Bu çalışmada, düzeltici akış modellerinin eğitimi için mevcut gürültü örneklemesi tekniklerini, onları algısal olarak ilgili ölçeklere doğru yönlendirerek iyileştiriyoruz. Büyük ölçekli bir çalışma aracılığıyla, bu yaklaşımın yüksek çözünürlüklü metinden görüntüye sentezinde yerleşik diffüzyon formülasyonlarına göre üstün performans gösterdiğini kanıtlıyoruz. Ayrıca, metinden görüntüye üretim için iki modalite için ayrı ağırlıklar kullanan ve görüntü ile metin jetonları arasında çift yönlü bilgi akışını mümkün kılan, metin anlama, tipografi ve insan tercih puanlarını iyileştiren yeni bir transformer tabanlı mimari sunuyoruz. Bu mimarinin öngörülebilir ölçeklenme eğilimlerini izlediğini ve çeşitli metrikler ile insan değerlendirmeleriyle ölçüldüğü üzere daha düşük doğrulama kaybının metinden görüntüye sentezde iyileşmeyle korelasyon gösterdiğini kanıtlıyoruz.

Kullanım Örneği

Model kapılı (gated) olduğu için, diffusers ile kullanmadan önce Stable Diffusion 3 Medium Hugging Face sayfasına gidip formu doldurmanız ve kapıyı (gate) kabul etmeniz gerekir. Sayfaya erişebildikten sonra, sisteminizin kapıyı kabul ettiğinizi bilmesi için oturum açmanız gerekir.

Giriş yapmak için aşağıdaki komutu kullanın:

hf auth login

SD3 hattı bir görüntü üretmek için üç metin kodlayıcı kullanır. Çoğu standart donanımda çalışabilmesi için model aktarımı (offloading) gereklidir. Ek bellek tasarrufu için torch.float16 veri türünü kullanın.

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")

Not: Stable Diffusion 3.5, SD3 hattı kullanılarak da çalıştırılabilir ve bahsedilen tüm optimizasyonlar ve teknikler buna da uygulanır. SD3 ailesinde toplamda üç resmi model bulunmaktadır:

IP-Adapters ile Görsel İfadelendirme

IP-Adapter, metin isteminin yanı sıra SD3'e görsellerle de istem göndermenizi sağlar. Bu, yalnızca metinle ifade etmesi zor karmaşık kavramları açıklarken ve referans görselleriniz olduğunda özellikle faydalıdır. Bir IP-Adapter yüklemek ve kullanmak için şunlara ihtiyacınız var:

  • image_encoder: Görüntü özelliklerini elde etmek için kullanılan, önceden eğitilmiş bir görme modeli, genellikle bir CLIP görüntü kodlayıcısıdır.
  • feature_extractor: Seçilen image_encoder için girdi görüntüsünü hazırlayan görüntü işleyicisi.
  • ip_adapter_id: Görsel çapraz dikkat katmanlarının ve görsel projeksiyonun parametrelerini içeren checkpoint.

IP-Adapters, belirli bir model mimarisi için eğitildiğinden, temel modelin ince ayarlı varyantlarında da çalışır. Çıktının görüntü komutuyla ne kadar güçlü bir şekilde hizalandığını ayarlamak için ~SD3IPAdapterMixin.set_ip_adapter_scale işlevini kullanabilirsiniz. Değer ne kadar yüksekse, model görüntü komutuna o kadar yakından uyar. 0,5 varsayılan değeri genellikle iyi bir denge sağlar; bu, modelin hem metin hem de görüntü komutlarını eşit derecede dikkate almasını garanti eder.

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 örnekleri, "a cat" (bir kedi) istemiyle

IP-Adapter'ların nasıl çalıştığını öğrenmek için IP-Adapter'a göz atın.

SD3 için Bellek Optimizasyonları

SD3, üç metin kodlayıcı kullanır ve bunlardan biri çok büyük olan T5-XXL modelidir. Bu durum, fp16 hassasiyeti kullanılsa bile 24GB'tan az VRAM'e sahip GPU'larda modeli çalıştırmayı zorlaştırır. Aşağıdaki bölüm, SD3'ün düşük kaynaklı donanımlarda çalıştırılmasını kolaylaştıran Diffusers'taki birkaç bellek optimizasyonunu özetler.

Model Offloading ile Çıkarım Çalıştırma

Diffusers'da kullanılabilen en temel bellek optimizasyonu, model bileşenlerini çıkarım sırasında belleği tasarruf etmek amacıyla CPU'ya aktarmanıza olanak tanır; bu işlem çıkarım gecikmesinde hafif bir artışa yol açar. Model aktarımı, bir model bileşeni yalnızca çalıştırılması gerektiğinde GPU'ya taşınırken, kalan bileşenlerin CPU'da kalmasını sağlar.

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")

Çıkarım Sırasında T5 Metin Kodlayıcısının Düşürülmesi

Çıkarım sırasında bellek yoğun 4,7B parametreli T5-XXL metin kodlayıcısının kaldırılması, performansta yalnızca hafif bir kayba yol açarak SD3 için bellek gereksinimlerini önemli ölçüde azaltabilir.

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 Metin Kodlayıcısının Kuantize Edilmiş Sürümünü Kullanma

T5-XXL metin kodlayıcısını 8-bit hassasiyete yüklemek ve kuantize etmek için bitsandbytes kütüphanesinden yararlanabiliriz. Bu sayede, performans üzerinde yalnızca hafif bir etki yaratırken üç metin kodlayıcısının tamamını kullanmaya devam edebilirsiniz.

Önce bitsandbytes kütüphanesini yükleyin.

pip install bitsandbytes

Ardından BitsAndBytesConfig kullanarak T5-XXL modelini yükleyin.

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")

Uçtan uca betiği burada bulabilirsiniz.

SD3 için Performans Optimizasyonları

Torch Compile Kullanarak Çıkarımı Hızlandırma

SD3 hattında derlenmiş bileşenlerin kullanılması, çıkarımı 4 katına kadar hızlandırabilir. Aşağıdaki kod parçası, SD3 hattındaki Transformer ve VAE bileşenlerinin nasıl derleneceğini göstermektedir.

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")

Tam betiğe buradan göz atın.

Kantizasyon

Kantizasyon, model ağırlıklarını daha düşük hassasiyetli bir veri türünde saklayarak çok büyük modellerin bellek gereksinimlerini azaltmaya yardımcı olur. Ancak kantizasyonun video kalitesi üzerindeki etkisi, video modeline göre değişebilir.

Desteklenen kuantizasyon arka uçları ve kullanım durumunu destekleyen bir kuantizasyon arka ucunu seçmek hakkında daha fazla bilgi edinmek için Quantization genel bakışına başvurun. Aşağıdaki örnek, bitsandbytes ile çıkarım için kuantize edilmiş bir StableDiffusion3Pipeline yüklemenin nasıl yapılacağını göstermektedir.

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 Metin Kodlayıcı ile Uzun İfadelerin Kullanımı

Varsayılan olarak, T5 Text Encoder istemi 256 maksimum dizi uzunluğu kullanır. Bu, daha az veya daha fazla token kabul etmek için max_sequence_length değerini ayarlayarak değiştirilebilir. Daha uzun dizilerin ek kaynaklar gerektirdiğini ve toplu çıkarım sırasında daha uzun üretim sürelerine yol açtığını göz önünde bulundurun.

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 Metin Kodlayıcısına farklı bir istem gönderme

CLIP Metin Kodlayıcıları ve T5 Metin Kodlayıcısına farklı bir istem göndererek, istemin CLIP Metin Kodlayıcıları tarafından kırpılmasını önleyebilir ve üretimi iyileştirebilirsiniz.

CLIP Metin Kodlayıcıları ile istem hâlâ 77 jeton sınırına kısaltılıyor.

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]

Stable Diffusion 3 için Küçük AutoEncoder

Stable Diffusion için Küçük OtoKodlayıcı (TAESD3), Ollin Boer Bohan tarafından geliştirilen, Stable Diffusion 3'ün VAE'sinin küçültülmüş damıtılmış bir sürümüdür ve StableDiffusion3Pipeline latentlerini neredeyse anında çözebilir.

Stable Diffusion 3 ile kullanmak için:

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 ile orijinal denetim noktalarını yükleme

SD3Transformer2DModel ve StableDiffusion3Pipeline sınıfları, from_single_file yöntemi aracılığıyla orijinal kontrol noktalarını (checkpoint) yüklemeyi destekler. Bu yöntem, modellerin eğitilmesinde kullanılan orijinal kontrol noktası dosyalarını yüklemenizi sağlar.

SD3Transformer2DModel için orijinal kontrol noktalarının yüklenmesi

from diffusers import SD3Transformer2DModel

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

StableDiffusion3Pipeline için tek kontrol noktasını yükleme

T5 olmadan tek dosya kontrol noktasını yükleme

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 ile tek dosya kontrol noktasını yükleme

Aşağıdaki örnek, PyTorch 2.3 veya daha yeni bir sürüm gerektiren 8-bit kayan nokta biçiminde saklanan bir kontrol noktasını yükler.

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 Model için tek dosya kontrol noktasını yükleme

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

sınıf diffusers.StableDiffusion3Pipeline

< >

( transformer: SD3Transformer2DModelscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertext_encoder_2: CLIPTextModelWithProjectiontokenizer_2: CLIPTokenizertext_encoder_3: T5EncoderModeltokenizer_3: T5Tokenizerimage_encoder: SiglipVisionModel = Nonefeature_extractor: SiglipImageProcessorPil = None )

Parametreler

  • transformer (SD3Transformer2DModel) — Kodlanmış görüntü latentlerini gürültüden arındırmak için kullanılan Koşullu Transformer (MMDiT) mimarisi.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Kodlanmış görüntü latentlerini gürültüden arındırmak için transformer ile birlikte kullanılacak bir zamanlayıcı.
  • vae (AutoencoderKL) — Görselleri latent temsillere kodlamak ve bu temsillerden çözmek için kullanılan Varyasyonel Oto-Kodlayıcı (VAE) Modeli.
  • text_encoder (CLIPTextModelWithProjection) — CLIP, özellikle clip-vit-large-patch14 varyantı, boyutu hidden_size olan bir köşegen matrisle başlatılan ek bir projeksiyon katmanı ile.
  • text_encoder_2 (CLIPTextModelWithProjection) — CLIP, özellikle laion/CLIP-ViT-bigG-14-laion2B-39B-b160k değişkeni.
  • text_encoder_3 (T5EncoderModel) — Donmuş metin kodlayıcı. Stable Diffusion 3 T5'i, özellikle de t5-v1_1-xxl varyantını kullanır.
  • tokenizer (CLIPTokenizer) — CLIPTokenizer sınıfının tokenization aracı.
  • tokenizer_2 (CLIPTokenizer) — CLIPTokenizer sınıfının ikinci Tokenizer'ı.
  • tokenizer_3 (T5TokenizerFast) — T5Tokenizer sınıfının tokenizer'ı.
  • image_encoder (SiglipVisionModel, isteğe bağlı) — IP Adapter için önceden eğitilmiş Görüntü Modeli.
  • feature_extractor (SiglipImageProcessor, isteğe bağlı) — IP Adapter için görüntü işleyici.

__call__

< >

( 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

Parametreler

  • prompt (str veya list[str], isteğe bağlı) — Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmadıysa bunun yerine prompt_embeds geçirilmelidir.
  • prompt_2 (str veya list[str], isteğe bağlı) — tokenizer_2 ve text_encoder_2'ye gönderilecek istem veya istemler. Tanımlanmamışsa bunun yerine prompt kullanılır.
  • prompt_3 (str veya list[str], isteğe bağlı) — tokenizer_3 ve text_encoder_3'e gönderilecek istem veya istemler. Tanımlanmamışsa bunun yerine prompt kullanılır.
  • height (int, isteğe bağlı, varsayılan: self.unet.config.sample_size * self.vae_scale_factor) — Oluşturulan görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için varsayılan olarak 1024 olarak ayarlanır.
  • width (int, isteğe bağlı, varsayılan: self.unet.config.sample_size * self.vae_scale_factor) — Oluşturulan görüntünün piksel cinsinden genişliği. En iyi sonuçlar için varsayılan olarak 1024 olarak ayarlanır.
  • num_inference_steps (int, isteğe bağlı, varsayılan 50) — Gürültü azaltma adım sayısı. Daha fazla gürültü azaltma adımı genellikle daha yavaş çıkarım pahasına daha yüksek kaliteli bir görüntüye yol açar.
  • sigmas (list[float], isteğe bağlı) — set_timesteps yöntemlerinde sigmas argümanını destekleyen zamanlayıcılarla gürültü azaltma sürecinde kullanılacak özel sigmalar. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılır.
  • guidance_scale (float, isteğe bağlı, varsayılan 7.0) — Classifier-Free Diffusion Guidance makalesinde tanımlandığı gibi yönlendirme ölçeği. guidance_scale, Imagen Paper makalesindeki 2. denklemindeki w olarak tanımlanır. Yönlendirme ölçeği, guidance_scale > 1 olarak ayarlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, prompt metniyle yakından ilişkili görsellerin üretilmesini teşvik eder, genellikle bu da daha düşük görsel kalitesi pahasına olur.
  • negative_prompt (str veya list[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa, bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yani guidance_scale değeri 1'den küçükse) yok sayılır.
  • negative_prompt_2 (str veya list[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için tokenizer_2 ve text_encoder_2'ye gönderilecek istem veya istemler. Tanımlanmamışsa bunun yerine negative_prompt kullanılır
  • negative_prompt_3 (str veya list[str], isteğe bağlı) — tokenizer_3 ve text_encoder_3'e gönderilecek, görsel üretimini yönlendirmemesi gereken istem veya istemler. Tanımlanmamışsa bunun yerine negative_prompt kullanılır
  • num_images_per_prompt (int, isteğe bağlı, varsayılan 1) — Her istem için oluşturulacak görsel sayısı.
  • generator (torch.Generator veya list[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için bir veya torch üreteci listesi.
  • latents (torch.FloatTensor, isteğe bağlı) — Gaussian dağılımdan örneklenmiş, gürültülü ve önceden oluşturulmuş latents; görsel üretimi için girdi olarak kullanılabilir. Farklı istemlerle aynı üretimi ince ayar yapmak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklemeye dayalı bir latents tensörü oluşturulur.
  • prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
  • negative_prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş negatif metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
  • pooled_prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş havuzlanmış metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, havuzlanmış metin gömme değerleri prompt girdi argümanından oluşturulur.
  • negative_pooled_prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş negatif havuzlanmış metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, havuzlanmış negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
  • ip_adapter_image (PipelineImageInput, isteğe bağlı) — IP Adapter'larla çalışmak için isteğe bağlı görüntü girdisi.
  • ip_adapter_image_embeds (torch.Tensor, isteğe bağlı) — IP-Adapter için önceden oluşturulmuş gömme vektörleri. Şekli (batch_size, num_images, emb_dim) olan bir tensör olmalıdır. do_classifier_free_guidance True olarak ayarlandıysa negatif gömme vektörünü içermelidir. Sağlanmazsa, gömme vektörleri ip_adapter_image girdi argümanından hesaplanır.
  • output_type (str, isteğe bağlı, varsayılan "pil") — Görsel oluşturma çıktısının biçimi. Şunlardan birini seçin: PIL: PIL.Image.Image veya np.array.
  • return_dict (bool, isteğe bağlı, varsayılan True) — Düz bir tuple yerine ~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput döndürülüp döndürülmemesi.
  • joint_attention_kwargs (dict, isteğe bağlı) — Belirtilirse, diffusers.models.attention_processor içindeki self.processor altında tanımlanan AttentionProcessor'a iletilen bir kwargs sözlüğü.
  • clip_skip (int, isteğe bağlı) — İstem gömmelemelerini hesaplanırken CLIP'ten atlanacak katman sayısı. 1 değeri, istem gömmelemelerini hesaplamak için son öncesi katmanın çıktısının kullanılacağı anlamına gelir.
  • callback_on_step_end (Callable, isteğe bağlı) — Çıkarım sırasında her gürültü azaltma adımının sonunda çağrılan bir işlev. İşlev aşağıdaki argümanlarla çağrılır: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs, callback_on_step_end_tensor_inputs tarafından belirtilen tüm tensörlerin listesini içerir.
  • callback_on_step_end_tensor_inputs (list, isteğe bağlı) — callback_on_step_end işlevi için girdi tensörlerinin listesi. Listede belirtilen tensörler, callback_kwargs argümanı olarak geçirilir. Yalnızca pipeline sınıfınızın ._callback_tensor_inputs özniteliğinde listelenen değişkenleri dahil edebilirsiniz.
  • max_sequence_length (int, varsayılan 256) — prompt ile kullanılacak maksimum dizi uzunluğu.
  • skip_guidance_layers (list[int], isteğe bağlı) — Guidance sırasında atlanacak katmanları belirleyen tamsayı listesi. Verilmezse, guidance için tüm katmanlar kullanılır. Verilirse, guidance yalnızca listede belirtilen katmanlara uygulanır. StabiltyAI tarafından Stable Diffusion 3.5 Medium için önerilen değer [7, 8, 9]'dur.
  • skip_layer_guidance_scale (int, isteğe bağlı) — skip_guidance_layers içinde belirtilen katmanlar için yönlendirme ölçeği. Yönlendirme, skip_guidance_layers içinde belirtilen katmanlara skip_layer_guidance_scale ölçeğiyle uygulanır. Yönlendirme, diğer katmanlara 1 ölçeğiyle uygulanır.
  • skip_layer_guidance_stop (int, isteğe bağlı) — skip_guidance_layers içinde belirtilen katmanlar için rehberliğin duracağı adım. Rehberlik, skip_layer_guidance_stop içinde belirtilen oran kadar skip_guidance_layers içinde belirtilen katmanlara uygulanır. StabiltyAI'nin Stable Diffusion 3.5 Medium için önerdiği değer 0.2'dir.
  • skip_layer_guidance_start (int, isteğe bağlı) — skip_guidance_layers içinde belirtilen katmanlar için rehberliğin başlayacağı adım. Rehberlik, skip_layer_guidance_start içinde belirtilen kesirden itibaren skip_guidance_layers içinde belirtilen katmanlara uygulanır. StabiltyAI'nin Stable Diffusion 3.5 Medium için önerdiği değer 0.01'dir.
  • mu (float, isteğe bağlı) — dynamic_shifting için kullanılan mu değeri.

Dönüş değeri

~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput veya tuple

return_dict True ise ~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput, aksi halde bir tuple. Bir tuple döndürüldüğünde, ilk öğe üretilen görsellerin listesidir.

Üretim için pipeline çağrıldığında tetiklenen işlev.

Örnekler:

>>> 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

< >

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

Parametreler

  • image (PipelineImageInput) — Kodlanacak giriş görüntüsü.
  • device — (torch.device): Torch cihazı.

Dönüş değeri

torch.Tensor

Kodlanmış görüntü özellik gösterimi.

Verilen görüntüyü, önceden eğitilmiş bir görüntü kodlayıcı kullanarak özellik temsiline dönüştürür.

encode_prompt

< >

( 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 )

Parametreler

  • prompt (str veya list[str], isteğe bağlı) — kodlanacak prompt
  • prompt_2 (str veya list[str], isteğe bağlı) — tokenizer_2 ve text_encoder_2'e gönderilecek istem veya istemler. Tanımlanmamışsa, tüm metin kodlayıcılarda prompt kullanılır
  • prompt_3 (str veya list[str], isteğe bağlı) — tokenizer_3 ve text_encoder_3'e gönderilecek istem veya istemler. Tanımlanmamışsa, tüm metin kodlayıcılarda prompt kullanılır
  • device — (torch.device): torch cihazı
  • num_images_per_prompt (int) — her prompt için oluşturulacak görsel sayısı
  • do_classifier_free_guidance (bool) — classifier free guidance kullanılacak mı
  • negative_prompt (str veya list[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa, bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yani guidance_scale değeri 1'den küçükse) yok sayılır.
  • negative_prompt_2 (str veya list[str], isteğe bağlı) — Görsel üretimini yönlendirmemek için tokenizer_2 ve text_encoder_2'ye gönderilecek istem veya istemler. Tanımlanmamışsa, tüm metin kodlayıcılarda negative_prompt kullanılır.
  • negative_prompt_3 (str veya list[str], isteğe bağlı) — tokenizer_3 ve text_encoder_3'e gönderilecek, görsel üretimi yönlendirmeyecek istem veya istemler. Tanımlanmamışsa, tüm metin kodlayıcılarda negative_prompt kullanılır.
  • prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. prompt ağırlıklandırma. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.
  • negative_prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş negatif metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
  • pooled_prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş havuzlanmış metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, havuzlanmış metin gömme değerleri prompt girdi argümanından oluşturulur.
  • negative_pooled_prompt_embeds (torch.FloatTensor, isteğe bağlı) — Önceden oluşturulmuş negatif havuzlanmış metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, havuzlanmış negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.
  • clip_skip (int, isteğe bağlı) — İstem gömmelemelerini hesaplanırken CLIP'ten atlanacak katman sayısı. 1 değeri, istem gömmelemelerini hesaplamak için son öncesi katmanın çıktısının kullanılacağı anlamına gelir.
  • lora_scale (float, isteğe bağlı) — LoRA katmanları yüklendiyse, metin kodlayıcısının tüm LoRA katmanlarına uygulanacak bir LoRA ölçeği.

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] = Noneip_adapter_image_embeds: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = True )

Parametreler

  • ip_adapter_image (PipelineImageInput, isteğe bağlı) — IP-Adapter için özellik çıkarılacak girdi görüntüsü.
  • ip_adapter_image_embeds (torch.Tensor, isteğe bağlı) — Önceden hesaplanmış gömme vektörleri.
  • device — (torch.device, isteğe bağlı): Torch cihazı.
  • num_images_per_prompt (int, varsayılan 1) — Her istem için oluşturulacak görsel sayısı.
  • do_classifier_free_guidance (bool, varsayılan True) — Classifier free guidance kullanılacak mı?

IP-Adapter'da kullanılmak üzere görsel gömme (embedding) verilerini hazırlar.

ip_adapter_image veya ip_adapter_image_embeds parametrelerinden biri iletilmelidir.

Update on GitHub

←Stable Diffusion 2 Stable Diffusion XL→