Hugging Face's logo

Diffusers documentation

Yardımcılar

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

Yardımcılar

🤗 Diffusers ile çalışmak için yardımcı ve yardımcı işlevler.

numpy_to_pil

diffusers.utils.numpy_to_pil

< >

( images )

Bir numpy görüntüsünü veya görüntü grubunu bir PIL görüntüsüne dönüştürür.

pt_to_pil

diffusers.utils.pt_to_pil

< >

( images )

Bir torch görüntüsünü PIL görüntüsüne dönüştürür.

load_image

diffusers.utils.load_image

< >

( image: str | PIL.Image.Imageconvert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None ) → PIL.Image.Image

Parametreler

  • image (str veya PIL.Image.Image) — PIL Image formatına dönüştürülecek görüntü.
  • convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], isteğe bağlı) — Görsel yüklendikten sonra uygulanacak dönüştürme yöntemi. None olarak ayarlandığında görsel “RGB” olarak dönüştürülür.

Dönüş değeri

PIL.Image.Image

Bir PIL Görüntüsü.

image öğesini bir PIL Image olarak yükler.

load_video

diffusers.utils.load_video

< >

( video: strconvert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = Nonereturn_fps: bool = False ) → list[PIL.Image.Image] or tuple[list[PIL.Image.Image], float]

Parametreler

  • video (str) — PIL Image formatına dönüştürülecek bir videoya ait URL veya Path.
  • convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], isteğe bağlı) — Video yüklendikten sonra uygulanacak bir dönüştürme yöntemi. None olarak ayarlandığında görüntüler “RGB”ye dönüştürülür.
  • return_fps (bool, isteğe bağlı, varsayılan False) — Videonun kodlandığı kare hızının da döndürülüp döndürülmemesi. Girdiyi, modelin çalıştığı kare hızına yeniden örnekleyen hatlar tarafından gereklidir; çünkü kare listesi bu bilgiyi taşımaz.

Dönüş değeri

list[PIL.Image.Image] veya tuple[list[PIL.Image.Image], float]

PIL görüntüleri listesi olarak video ve return_fps ayarlanmışsa kare hızı.

video öğesini PIL Image listesine yükler.

export_to_gif

diffusers.utils.export_to_gif

< >

( image: list[PIL.Image.Image]output_gif_path: str = Nonefps: int = 10 )

export_to_video

diffusers.utils.export_to_video

< >

( video_frames: list[np.ndarray] | list[PIL.Image.Image]output_video_path: str = Nonefps: int = 10quality: float = 5.0bitrate: int | None = Nonemacro_block_size: int | None = 16 )

quality: Video output quality. Default is 5. Uses variable bit rate. Highest quality is 10, lowest is 0. Set to None to prevent variable bitrate flags to FFMPEG so you can manually specify them using output_params instead. Specifying a fixed bitrate using bitrate disables this parameter.

bitrate: Video kodlaması için sabit bir bitrate ayarlayın. Varsayılan değer None'dir ve bunun yerine quality parametresi kullanılır. Bu parametreyle sabit bir bitrate belirtmek yerine quality değişken bitrate parametresini kullanmak, daha küçük dosya boyutlarıyla daha kaliteli videolar elde edilmesini sağlar.

macro_block_size: Video için boyut kısıtı. Genişlik ve yükseklik, bu sayıya bölünebilmelidir. Bu sayıya bölünemiyorsa imageio, ffmpeg'e görüntüyü bu sayıya bölünebilen bir sonraki en yakın boyuta ölçeklendirmesini söyler. Çoğu codec 16 (varsayılan) makro blok boyutuyla uyumludur, bazıları daha küçük (4, 8) olabilir. Bu otomatik özellik devre dışı bırakılacaksa değeri None veya 1 olarak ayarlayın; ancak birçok oynatıcının boyutu tek olan videoları çözemeyeceğini ve bazı codec'lerin kötü sonuçlar üretebileceğini veya başarısız olabileceğini unutmayın. https://en.wikipedia.org/wiki/Macroblock adresine bakın.

encode_video

diffusers.utils.encode_video

< >

( video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor']fps: intoutput_path: straudio: 'torch.Tensor' | None = Noneaudio_sample_rate: int | None = Nonevideo_chunks_number: int = 1 )

Parametreler

  • video (List[PIL.Image.Image] veya np.ndarray veya torch.Tensor) — [0, 255] aralığında tamsayı piksel değerlerine sahip, [frames, height, width, channels] biçiminde bir video tensörü. Girdi np.ndarray ise, [0, 1] aralığında değerlere sahip bir float dizi olması beklenir (bu, hatların output_type="np" ile genellikle döndürdüğü şeydir).
  • fps (int) — Kodlanmış videonun saniyedeki kare sayısı (FPS).
  • output_path (str) — Kodlanmış videonun kaydedileceği yol.
  • audio (torch.Tensor, isteğe bağlı) — [audio_channels, samples] biçiminde bir ses dalgası.
  • audio_sample_rate — (int, isteğe bağlı): Ses dalgasının örneklem hızı.
  • video_chunks_number (int, isteğe bağlı, varsayılan 1) — Kodlama için videonun bölüneceği parça sayısı. Her parça ayrı ayrı kodlanır. Kullanılacak parça sayısı genellikle video VAE için döşeme yapılandırmasına bağlıdır.

PyAV kütüphanesini kullanarak isteğe bağlı sesle bir videoyu kodlar. Orijinal LTX-2 deposundaki koda dayanır: https://github.com/Lightricks/LTX-2/blob/4f410820b198e05074a1e92de793e3b59e9ab5a0/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py#L182

make_image_grid

diffusers.utils.make_image_grid

< >

( images: listrows: intcols: intresize: int = None )

Tek bir görüntü ızgarası hazırlar. Görselleştirme amaçları için kullanışlıdır.

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< >

( shape: tuple | listgenerator: list['torch.Generator'] | 'torch.Generator' | None = Nonedevice: str | 'torch.device' | None = Nonedtype: 'torch.dtype' | None = Nonelayout: 'torch.layout' | None = None )

İstenen device üzerinde istenen dtype ile rastgele tensörler oluşturmak için yardımcı bir işlev. Üreteçler listesi geçirildiğinde, her parti boyutu için ayrı ayrı tohum atılabilir. CPU üreteçleri geçirilirse, tensör her zaman CPU üzerinde oluşturulur.

TorchDeviceBackend

sınıf diffusers.utils.torch_utils.TorchDeviceBackend

< >

( device: str | torch.device | None = None )

Bir cihazın torch.<backend> ad alanının (torch.cuda, torch.xpu, torch.mps, …) vekili. Sınıfın tanımlamadığı öznitelikler, modülün kendi öznitelikleridir (synchronize, device_count, Stream, current_stream, …); burada tanımlanan yöntemler, kullanılabilirliği arka uçlar arasında farklılık gösteren ve yedek bir çözüm gerektiren işlemleri devre dışı bırakır: önbellek temizleme, tohumlama ve bellek sorguları. device belirtilmediğinde, torch.accelerator aracılığıyla ana bilgisayar hızlandırıcısını algılar. torch'un arka uç için bir modülü yoksa sessizce torch.cuda'ya geri dönmek yerine hata fırlatır.

max_memory_allocated

< >

( )

Son sıfırlamadan bu yana cihazda ayrılan tepe bellek (bayt cinsinden); arka uç istatistik tutmuyorsa 0.

mem_get_info

< >

( )

Bayt cinsinden boş ve toplam cihaz belleği.

apply_layerwise_casting

diffusers.hooks.apply_layerwise_casting

< >

( module: Modulestorage_dtype: dtypecompute_dtype: dtypeskip_modules_pattern: str | tuple[str, ...] = 'auto'skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Parametreler

  • module (torch.nn.Module) — Hesaplama için yaprak modülleri yüksek hassasiyetli bir veri türüne, depolama için ise düşük hassasiyetli bir veri türüne dönüştürülecek modül.
  • storage_dtype (torch.dtype) — Depolama için ileri geçişten önce/sonra modülün dönüştürüleceği dtype.
  • compute_dtype (torch.dtype) — İleri geçiş sırasında hesaplama için modülün dönüştürüleceği dtype.
  • skip_modules_pattern (tuple[str, ...], varsayılan "auto") — Katman bazlı dökümleme (casting) işlemi sırasında atlanacak modüllerin adlarını eşleştirmek için kullanılan desenlerin listesi. "auto" olarak ayarlanırsa, varsayılan desenler kullanılır. None olarak ayarlanırsa, hiçbir modül atlanmaz. None olarak ayarlanıp skip_modules_classes de None ise, katman bazlı dökümleme, modülün iç alt modülleri yerine doğrudan modüle uygulanır.
  • skip_modules_classes (tuple[Type[torch.nn.Module], ...], varsayılan None) — Katman bazlı dökümleme (casting) işlemi sırasında atlanacak modül sınıflarının listesi.
  • non_blocking (bool, varsayılan False) — True ise, ağırlık dönüştürme işlemleri engellenmez.

Verilen bir modüle katman bazlı döküm uygular. Burada beklenen modül bir Diffusers ModelMixin'dir ancak diffusers katmanları veya pytorch birincil yapılarını kullanan herhangi bir nn.Module olabilir.

Örnek:

>>> import torch
>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     model_id, subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> apply_layerwise_casting(
...     transformer,
...     storage_dtype=torch.float8_e4m3fn,
...     compute_dtype=torch.bfloat16,
...     skip_modules_pattern=["patch_embed", "norm", "proj_out"],
...     non_blocking=True,
... )

apply_group_offloading

diffusers.hooks.apply_group_offloading

< >

( module: Moduleonload_device: typing.Union[str, torch.device]offload_device: typing.Union[str, torch.device] = torch.device()offload_type: str | diffusers.hooks.group_offloading.GroupOffloadingType = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage: bool = Falseoffload_to_disk_path: str | None = Noneblock_modules: list[str] | None = Noneexclude_kwargs: list[str] | None = None )

Parametreler

  • module (torch.nn.Module) — Grup taşımalarının uygulandığı modül.
  • onload_device (torch.device) — Modüller grubunun yüklendiği cihaz.
  • offload_device (torch.device, varsayılan torch.device("cpu")) — Modül grubunun aktarıldığı cihaz. Bu genellikle CPU olmalıdır. Varsayılan değer CPU'dur.
  • offload_type (str veya GroupOffloadingType, varsayılan “block_level”) — Uygulanacak offloading türü. “block_level” veya “leaf_level” değerlerinden biri olabilir. Varsayılan değer “block_level”dir.
  • offload_to_disk_path (str, isteğe bağlı, varsayılan None) — Parametrelerin taşınacağı dizinin yolu. Bu seçeneğin ayarlanması, makul bir hız-bellek ödüşlemesi istenen sınırlı RAM ortamı ayarlarında faydalı olabilir.
  • num_blocks_per_group (int, isteğe bağlı) — offload_type=“block_level” kullanıldığında grup başına blok sayısı. offload_type=“block_level” kullanıldığında zorunludur.
  • non_blocking (bool, varsayılan False) — True ise, offloading ve onloading işlemleri bloklayıcı olmayan veri aktarımıyla yapılır.
  • use_stream (bool, varsayılan False) — True ise, offloading ve onloading işlemleri bir CUDA stream kullanılarak asenkron olarak yapılır. Bu, hesaplama ve veri aktarımının üst üste binmesini sağlayarak faydalı olabilir.
  • record_stream (bool, varsayılan False) — use_stream ile etkinleştirildiğinde, mevcut tensörün bu akış tarafından kullanıldığını işaretler. Biraz daha fazla bellek kullanımı pahasına daha hızlıdır. Daha fazla ayrıntı için PyTorch resmi belgeleri'ne bakın.
  • low_cpu_mem_usage (bool, varsayılan False) — True ise, tensörler önceden sabitlenmek yerine anlık olarak sabitlenerek CPU bellek kullanımı en aza indirilir. Bu seçenek yalnızca akışlı CPU dışa aktarma kullanıldığında (yani use_stream=True) önem taşır. CPU belleği darboğaz olduğunda faydalı olabilir ancak akışların kullanımından sağlanan avantajları azaltabilir.
  • block_modules (list[str], isteğe bağlı) — Offloading için blok olarak ele alınacak modül adlarının listesi. Verildiğinde, blok düzeyinde offloading için yalnızca bu modüller dikkate alınır. Verilmediğinde, varsayılan blok algılama mantığı kullanılır.
  • exclude_kwargs (list[str], isteğe bağlı) — send_to_device tarafından işlenmemesi gereken kwarg anahtarlarının listesi. Bu, forward geçişleri arasında nesne kimliklerini korumaları gereken önbellekleme listeleri gibi değişken durumlar için kullanışlıdır. Sağlanmazsa, modülün _skip_keys özniteliği varsa bu öznitelikten çıkarılır.

Bir torch.nn.Module'ün iç katmanlarına grup offloading uygular. Grup offloading'in ne olduğunu ve nerede faydalı olduğunu anlamak için, öncelikle diğer desteklenen offloading yöntemlerinin nasıl çalıştığına dair bazı bağlam sunmamız gerekir.

Genellikle, offloading iki düzeyde yapılır:

  • Modül düzeyinde: Diffusers'ta bu, ModelMixin::enable_model_cpu_offload() yöntemi kullanılarak etkinleştirilebilir. Çalışma mantığı, bir pipeline'ın her bileşenini depolama için CPU'ya aktarmak ve hesaplama için gerektiğinde hızlandırıcı cihaza geri yüklemektir. Bu yöntem, tüm bileşenleri hızlandırıcıda tutmaktan daha bellek verimlidir, ancak bellek gereksinimleri hâlâ oldukça yüksektir. Bu yöntemin çalışabilmesi için, ileri geçişi tamamlayabilmek adına çalışma zamanı veri türündeki model boyutuna eşdeğer bellek + en büyük ara aktivasyon tensörlerinin boyutu kadar belleğe ihtiyaç vardır.
  • Yaprak düzeyi: Diffusers'ta bu, ModelMixin::enable_sequential_cpu_offload() yöntemi kullanılarak etkinleştirilebilir. Hesaplama grafiğinin en alt yaprak düzeyindeki parametrelerini depolama için CPU'ya aktararak ve hesaplama için yalnızca yaprakları hızlandırıcı cihaza yükleyerek çalışır. Bu, en düşük hızlandırıcı bellek miktarını kullanır ancak aşırı sayıda cihaz senkronizasyonu nedeniyle daha yavaş olabilir.

Grup offloading, iki yöntem arasında bir orta yol sunar. İç katman gruplarını (ya da torch.nn.ModuleList ya da torch.nn.Sequential) offload ederek çalışır. Bu yöntem, modül düzeyindeki offloading'e göre daha az bellek kullanır. Ayrıca, cihaz senkronizasyonlarının sayısı azaldığı için yaprak düzeyi/sıralı offloading'den daha hızlıdır.

CUDA cihazlarında asenkron veri aktarım akışlarını destekleyenler için desteklenen bir diğer özellik, ardışık offloading'e kıyasla genel çalışma süresini azaltmak için veri aktarımı ile hesaplamayı üst üste bindirme yeteneğidir. Bu, akışlar kullanılarak katman ön yükleme (layer prefetching) ile etkinleştirilir; yani bir sonraki çalıştırılacak katman, mevcut katman çalıştırılırken hızla hızlandırıcı cihaza onloading edilir - bu, bellek gereksinimlerini hafifçe artırır. Bu uygulamanın yaprak seviyesinde offloading'i de desteklediğini, ancak akışlar kullanıldığında çok daha hızlı hale gelebileceğini unutmayın.

Örnek:

>>> from diffusers import CogVideoXTransformer3DModel
>>> from diffusers.hooks import apply_group_offloading

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

>>> apply_group_offloading(
...     transformer,
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="block_level",
...     num_blocks_per_group=2,
...     use_stream=True,
... )
Update on GitHub

←Özel normalizasyon katmanları VAE Görüntü İşleyici→