Hugging Face's logo

Diffusers documentation

Modeller

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

Modeller

🤗 Diffusers, popüler algoritmalar için önceden eğitilmiş modeller ve özel difüzyon sistemleri oluşturmak için modüller sağlar. Modellerin temel işlevi, dağılım tarafından modellenen bir girdi örneğini gürültüden arındırmaktır pθ(xt−1∣xt)p_{\theta}(x_{t-1}|x_{t}).

Tüm modeller, yerel olarak ve Hugging Face Hub'dan modellerin kaydedilmesi ve yüklenmesi için temel işlevselliği sağlayan torch.nn.Module olan temel ModelMixin sınıfından oluşturulur.

ModelMixin

sınıf diffusers.ModelMixin

< >

( )

Tüm modellerin temel sınıfı.

ModelMixin, model yapılandırmasının depolanmasından sorumlu olup modelleri yükleme, indirme ve kaydetme yöntemleri sağlar.

  • config_name (str) — save_pretrained() çağrıldığında bir modelin kaydedileceği dosya adı.

compile_repeated_blocks

< >

( *args**kwargs )

Bir modelin yalnızca sık tekrarlanan alt modüllerini (ör. Transformer katmanları) sadece derler, tüm modeli derlemez. Bu teknik—genellikle bölgesel derleme olarak adlandırılır (PyTorch tarifi: https://docs.pytorch.org/tutorials/recipes/regional_compilation.html)—tam bir torch.compile'den beklenen çalışma zamanı hızlandırmalarını korurken uçtan uca derleme süresini önemli ölçüde azaltabilir.

Derlenecek alt modüllerin kümesi, model tanımındaki _repeated_blocks özniteliğinin varlığıyla keşfedilir. Bu özniteliği, model alt sınıfınızda sınıf adlarının (dizelerin) bir listesi/tuplü olarak tanımlayın. Sınıf adı eşleşen her modül derlenecektir.

Keşfedildikten sonra, her eşleşen alt modül submodule.compile(*args, **kwargs) çağrılarak derlenir. compile_repeated_blocks fonksiyonuna sağladığınız konumsal veya anahtar kelime argümanları, torch.compile fonksiyonuna olduğu gibi aktarılır.

cuda

( *args**kwargs )

Noktalı bir yol için sahte bir değer (ör. torch.float32): öznitelik erişim zincirleri, çağrılar geçiş (pass-through) dekoratörleri gibi davranır, repr noktalı yoldur ve bir taban sınıf olarak kullanıldığında düz bir type tabanı yerine geçer (PEP 560 __mro_entries__), böylece gerçek alt sınıflar normal bir meta sınıfı korur ve inspect.signature sahtenin yerine gerçek __init__ değerlerini okur.

dequantize

< >

( )

Eğer model, dequantizasyonu destekleyen bir kuantizasyon yöntemiyle kuantize edilmişse, modelin dequantize edilmesini potansiyel olarak gerçekleştirin.

disable_gradient_checkpointing

< >

( )

Mevcut model için gradyan denetleme noktasını devre dışı bırakır (diğer çerçevelerde aktivasyon denetleme noktası veya aktivasyon denetleme noktaları olarak da adlandırılabilir).

disable_npu_flash_attention

< >

( )

torch_npu'dan npu flash attention'ı devre dışı bırak

disable_xformers_memory_efficient_attention

< >

( )

xFormers için bellek verimli dikkati devre dışı bırakın.

disable_xla_flash_attention

< >

( )

torch_xla için flash attention pallals çekirdeğini devre dışı bırakın.

enable_gradient_checkpointing

< >

( gradient_checkpointing_func: typing.Optional[typing.Callable] = None )

Parametreler

  • gradient_checkpointing_func (Callable, isteğe bağlı) — Gradyan denetimi için kullanılacak işlev. None ise, varsayılan PyTorch denetim noktası işlevi kullanılır (torch.utils.checkpoint.checkpoint).

Mevcut model için gradyan denetleme noktasını etkinleştirir (diğer çerçevelerde aktivasyon denetleme noktası veya aktivasyon denetleme noktaları olarak da adlandırılabilir).

enable_group_offload

< >

( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneblock_modules: str | None = Noneexclude_kwargs: str | None = None )

Mevcut model için grup boşaltmayı etkinleştirir.

Daha fazla bilgi için apply_group_offloading() bölümüne bakın.

Örnek:

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> transformer.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )

enable_layerwise_casting

< >

( storage_dtype: dtype = torch.float8_e4m3fncompute_dtype: typing.Optional[torch.dtype] = Noneskip_modules_pattern: tuple[str, ...] | None = Noneskip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Parametreler

  • storage_dtype (torch.dtype) — Depolama için modelin dönüştürülmesi gereken dtype.
  • compute_dtype (torch.dtype) — İleri geçiş sırasında model ağırlıklarının dönüştürüleceği dtype.
  • skip_modules_pattern (tuple[str, ...], isteğe bağlı) — Katman bazlı dökümleme (casting) işlemi sırasında atlanacak modüllerin adlarını eşleştirmek için desenlerin listesi. None olarak ayarlanırsa, modüllerin belirli iç katmanlarını ve PEFT katmanlarını yok saymak için varsayılan atlama desenleri kullanılır.
  • skip_modules_classes (tuple[Type[torch.nn.Module], ...], isteğe bağlı) — Katman bazlı dökümleme (casting) işlemi sırasında atlanacak modül sınıflarının listesi.
  • non_blocking (bool, isteğe bağlı, varsayılan False) — True ise, ağırlık dönüştürme işlemleri engellenmez.

Mevcut model için katman bazlı dökümlemeyi etkinleştirir.

Katman bazlı dönüştürme (casting), model ağırlıklarını depolama için daha düşük hassasiyetli bir veri türüne (dtype) dönüştüren, ancak hesaplama sırasında bunları anlık olarak daha yüksek hassasiyetli bir veri türüne yükselten bir tekniktir. Bu işlem, model ağırlıklarından kaynaklanan bellek kullanımını önemli ölçüde azaltabilir, ancak çıktılarda bazı kalite düşüşlerine yol açabilir. Çoğu düşüş ihmal edilebilir düzeydedir ve büyük ölçüde normalizasyon ve modülasyon katmanlarındaki ağırlık dönüştürmesinden kaynaklanır.

Varsayılan olarak, diffusers'taki modellerin çoğu, yama gömme, konumsal gömme ve normalizasyon katmanlarını yok saymak için _skip_layerwise_casting_patterns özniteliğini ayarlar. Bunun nedeni, bu katmanların kalite açısından büyük olasılıkla hassasiyet açısından kritik olmasıdır. Bu davranışı değiştirmek isterseniz, _skip_layerwise_casting_patterns özniteliğini None olarak ayarlayabilir veya apply_layerwise_casting() fonksiyonunu özel argümanlarla çağırabilirsiniz.

Örnek:

enable_layerwise_casting() kullanılarak:

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> # Enable layerwise casting via the model, which ignores certain modules by default
>>> transformer.enable_layerwise_casting(storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)

enable_npu_flash_attention

< >

( )

torch_npu'dan npu flash attention'ı etkinleştirin

enable_xformers_memory_efficient_attention

< >

( attention_op: typing.Optional[typing.Callable] = None )

Parametreler

  • attention_op (Callable, isteğe bağlı) — memory_efficient_attention() fonksiyonunun op argümanı olarak kullanılacak varsayılan None operatörünü geçersiz kılar.

xFormers ile bellek verimli dikkati etkinleştirin.

Bu seçenek etkinleştirildiğinde, GPU bellek kullanımının daha düşük olduğunu ve çıkarım sırasında olası bir hızlanma gözlemlemelisiniz. Eğitim sırasında hızlanma garanti edilmemektedir.

> ⚠️ Hem bellek verimli dikkat hem de dilimlenmiş dikkat etkinleştirildiğinde, bellek verimli dikkat > önceliklidir.

Örnekler:

>>> import torch
>>> from diffusers import UNet2DConditionModel
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> model = UNet2DConditionModel.from_pretrained(
...     "stabilityai/stable-diffusion-2-1", subfolder="unet", torch_dtype=torch.float16
... )
>>> model = model.to("cuda")
>>> model.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)

enable_xla_flash_attention

< >

( partition_spec: typing.Optional[typing.Callable] = None**kwargs )

torch_xla için flash attention pallals çekirdeğini etkinleştirin.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike | None**kwargs )

Parametreler

  • pretrained_model_name_or_path (str veya os.PathLike, isteğe bağlı) — Şu seçeneklerden biri olabilir:
    • Bir dize, Hub üzerinde barındırılan önceden eğitilmiş bir modelin model kimliği (örneğin google/ddpm-celebahq-256).
    • Model ağırlıklarının save_pretrained() ile kaydedildiği bir dizin (örneğin ./my_model_directory) yolunu belirtir.
  • cache_dir (str | os.PathLike, isteğe bağlı) — Standart önbellek kullanılmıyorsa, indirilen önceden eğitilmiş model yapılandırmasının önbelleğe alındığı dizinin yolu.
  • dtype (torch.dtype, isteğe bağlı) — Varsayılan torch.dtype değerini geçersiz kılar ve modeli başka bir dtype ile yükler.
  • force_download (bool, isteğe bağlı, varsayılan False) — Model ağırlıklarının ve yapılandırma dosyalarının (yeniden) indirilmesinin zorlanıp zorlanmayacağını belirler; önbellekteki sürümler varsa bunların üzerine yazar.
  • proxies (dict[str, str], isteğe bağlı) — Protokole veya uç noktaya göre kullanılacak vekil sunucuların sözlüğü, örneğin {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Vekiller her istekte kullanılır.
  • output_loading_info (bool, isteğe bağlı, varsayılan False) — Eksik anahtarlar, beklenmeyen anahtarlar ve hata mesajlarını içeren bir sözlüğün de döndürülüp döndürülmeyeceğini belirtir.
  • local_files_only(bool, isteğe bağlı, varsayılan False) — Yalnızca yerel model ağırlıkları ve yapılandırma dosyalarının yüklenip yüklenmeyeceğini belirtir. True olarak ayarlanırsa, model Hub'dan indirilmez.
  • token (str veya bool, isteğe bağlı) — Uzak dosyalar için HTTP bearer yetkilendirmesi olarak kullanılacak jeton. True ise, diffusers-cli login ile oluşturulan jeton ( ~/.huggingface içinde saklanır) kullanılır.
  • revision (str, isteğe bağlı, varsayılan "main") — Kullanılacak belirli model sürümü. Bir dal adı, etiket adı, commit kimliği veya Git tarafından izin verilen herhangi bir tanımlayıcı olabilir.
  • subfolder (str, isteğe bağlı, varsayılan "") — Hub'da veya yerel olarak daha büyük bir model deposu içindeki bir model dosyasının alt klasör konumu.
  • mirror (str, isteğe bağlı) — Çin'de bir model indirirken erişilebilirlik sorunlarını çözmek için kullanılacak ayna kaynağı. Kaynağın güncelliğini veya güvenliğini garanti etmiyoruz; daha fazla bilgi için lütfen ayna sitesine başvurun.
  • device_map (int | str | torch.device veya dict[str, int | str | torch.device], isteğe bağlı) — Her alt modülün nereye yerleştirileceğini belirten bir eşleme. Her parametre/buffer adı için tanımlanması gerekmez; belirli bir modül adı bir kez dahil edildiğinde, onun tüm alt modülleri aynı cihaza gönderilir. Varsayılan değer None, olduğunda model CPU üzerinde yüklenir.

    Örnekler:

Önceden eğitilmiş bir model yapılandırmasından önceden eğitilmiş bir PyTorch modeli örnekleyin.

Model varsayılan olarak değerlendirme moduna ayarlanır - model.eval() - ve dropout modülleri devre dışı bırakılır. Modeli eğitmek için model.train() ile eğitim moduna geri ayarlayın.

> Özel veya kısıtlı modelleri kullanmak için hf > auth login ile oturum açın. Ayrıca, bu yöntemi duvarlı bir ortamda kullanmak için özel > “çevrimdışı mod”u etkinleştirebilirsiniz.

Örnek:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5", subfolder="unet")

Aşağıdaki hata mesajını alıyorsanız, aşağı akış göreviniz için ağırlıkları ince ayar yapmanız gerekir:

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

get_memory_footprint

< >

( return_buffers = True )

Parametreler

  • return_buffers (bool, isteğe bağlı, varsayılan True) — Hafıza ayak izinin hesaplanmasında tampon tensörlerinin boyutunun döndürülüp döndürülmeyeceği. Tamponlar, gradyan gerektirmeyen ve parametre olarak kaydedilmemiş tensörlerdir. Örneğin, batch norm katmanlarındaki ortalama ve standart sapma. Lütfen şuraya bakın: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Bir modelin bellek ayak izini alın. Bu, mevcut modelin bayt cinsinden bellek ayak izini döndürür. Mevcut modelin bellek ayak izini ölçmek ve bazı testler tasarlamak için faydalıdır. Çözüm, PyTorch tartışmalarından ilham alınarak oluşturulmuştur: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

num_parameters

< >

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

Parametreler

  • only_trainable (bool, isteğe bağlı, varsayılan False) — Yalnızca eğitilebilir parametre sayısını döndürüp döndürmeyeceği.
  • exclude_embeddings (bool, isteğe bağlı, varsayılan False) — Yalnızca gömme olmayan parametre sayısını döndürülüp döndürülmemeye karar verir.

Dönüş değeri

int

Parametre sayısı.

Modüldeki (eğitilebilir veya gömme olmayan) parametre sayısını alın.

Örnek:

from diffusers import UNet2DConditionModel

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
unet = UNet2DConditionModel.from_pretrained(model_id, subfolder="unet")
unet.num_parameters(only_trainable=True)
859520964

reset_attention_backend

< >

( )

Model için dikkat (attention) arka ucunu sıfırlar. forward çağrılarının ardından, ayarlanmışsa ortam varsayılanı, aksi takdirde torch yerel ölçekli nokta çarpımı dikkati (scaled dot product attention) kullanılır.

save_pretrained

< >

( save_directory: str | os.PathLikeis_main_process: bool = Truesave_function: typing.Optional[typing.Callable] = Nonesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str = '10GB'push_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )

Parametreler

  • save_directory (str veya os.PathLike) — Bir modelin ve yapılandırma dosyasının kaydedileceği dizin. Var değilse oluşturulur.
  • is_main_process (bool, isteğe bağlı, varsayılan True) — Bu fonksiyonu çağıran sürecin ana süreç olup olmadığı. Dağıtık eğitim sırasında ve bu fonksiyonun tüm süreçlerde çağrılması gerektiğinde kullanışlıdır. Bu durumda, yarış durumlarını önlemek için is_main_process=True değerini yalnızca ana süreçte ayarlayın.
  • save_function (Callable) — Durum sözlüğünü kaydetmek için kullanılacak işlev. Dağıtık eğitim sırasında torch.save yerine başka bir yöntem kullanmanız gerektiğinde faydalıdır. DIFFUSERS_SAVE_MODE ortam değişkeni ile yapılandırılabilir.
  • safe_serialization (bool, isteğe bağlı, varsayılan True) — Modelin safetensors ile mi yoksa geleneksel PyTorch yöntemiyle pickle kullanılarak mı kaydedileceğini belirtir.
  • variant (str, isteğe bağlı) — Belirtilirse, ağırlıklar pytorch_model.<variant>.bin biçiminde kaydedilir.
  • max_shard_size (int veya str, varsayılan "10GB") — Parçalanmadan önce bir kontrol noktasının (checkpoint) alabileceği en büyük boyut. Parçalanan kontrol noktalarının her biri bu boyuttan küçük olacaktır. Dize olarak ifade ediliyorsa, rakamların ardından birim (örneğin "5GB") gelmelidir. Tamsayı olarak ifade ediliyorsa birim bayttır. Belirli bir süre sonra (Ekim 2024'ten itibaren) kullanıcıların diffusers'ın en son sürümüne yükselmesini sağlamak için bu sınırın düşürüleceğini unutmayın. Bu, Hugging Face ekosistemindeki farklı kütüphaneler arasında (örneğin transformers ve accelerate) bu argüman için ortak bir varsayılan boyut belirlemeyi amaçlamaktadır.
  • push_to_hub (bool, isteğe bağlı, varsayılan False) — Modelinizi kaydettikten sonra Hugging Face Hub'a gönderip göndermeyeceğinizi belirtir. Göndermek istediğiniz depoyu repo_id ile belirtebilirsiniz (varsayılan olarak ad alanınızdaki save_directory adını kullanır).
  • kwargs (dict[str, Any], isteğe bağlı) — push_to_hub() yöntemine iletilen ek anahtar kelime argümanları.

Bir modeli ve yapılandırma dosyasını, from_pretrained() sınıf yöntemiyle yeniden yüklenebilmesi için bir dizine kaydedin.

set_attention_backend

< >

( backend: str )

Parametreler

  • backend (str) — Ayarlanacak backend'in adı. AttentionBackendName içinde tanımlanan mevcut backend'lerden biri olmalıdır. Mevcut backend'ler diffusers.attention_dispatch.AttentionBackendName içinde bulunabilir. Varsayılan olarak backend olarak torch native scaled dot product attention kullanılır.

Model için dikkat (attention) arka ucunu ayarlayın.

set_use_npu_flash_attention

< >

( valid: bool )

npu flash attention için anahtarı ayarlayın.

'a

( *args**kwargs )

Noktalı bir yol için sahte bir değer (ör. torch.float32): öznitelik erişim zincirleri, çağrılar geçiş (pass-through) dekoratörleri gibi davranır, repr noktalı yoldur ve bir taban sınıf olarak kullanıldığında düz bir type tabanı yerine geçer (PEP 560 __mro_entries__), böylece gerçek alt sınıflar normal bir meta sınıfı korur ve inspect.signature sahtenin yerine gerçek __init__ değerlerini okur.

PushToHubMixin

sınıf diffusers.utils.PushToHubMixin

< >

( )

Bir model, zamanlayıcı veya hattı Hugging Face Hub'a göndermek için bir Mixin.

push_to_hub

< >

( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )

Parametreler

  • repo_id (str) — Model, zamanlayıcı veya pipeline dosyalarınızı yüklemek istediğiniz depoyun adı. Bir organizasyona yüklerken organizasyon adınızı içermelidir. repo_id ayrıca yerel bir dizine giden bir yol da olabilir.
  • commit_message (str, isteğe bağlı) — İterken iletilecek mesaj. Varsayılan değer "Upload {object}".
  • private (bool, isteğe bağlı) — Deponun özel yapılıp yapılmayacağı. None (varsayılan) ise, organizasyonun varsayılanı özel değilse depo herkese açık olacaktır. Depo zaten mevcutsa bu değer yok sayılır.
  • token (str, isteğe bağlı) — Uzak dosyalar için HTTP bearer yetkilendirmesi olarak kullanılacak jeton. hf auth login çalıştırıldığında oluşturulan jeton (~/.huggingface içinde saklanır).
  • create_pr (bool, isteğe bağlı, varsayılan False) — Yüklenen dosyalarla bir PR oluşturulup oluşturulmayacağı veya doğrudan commit atılıp atılmayacağı.
  • safe_serialization (bool, isteğe bağlı, varsayılan True) — Model ağırlıklarının safetensors biçimine dönüştürülüp dönüştürülmeyeceği.
  • variant (str, isteğe bağlı) — Belirtilirse, ağırlıklar pytorch_model.<variant>.bin biçiminde kaydedilir.

Model, zamanlayıcı veya boru hattı dosyalarını 🤗 Hugging Face Hub'a yükleyin.

Örnekler:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")
Update on GitHub

←PEFT AutoModel→