Hugging Face's logo

Diffusers documentation

Utilitas

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Utilitas

Fungsi utilitas dan pembantu untuk bekerja dengan 🤗 Diffusers.

numpy_to_pil

diffusers.utils.numpy_to_pil

< >

( images )

Mengonversi gambar numpy atau batch gambar menjadi gambar PIL.

pt_to_pil

diffusers.utils.pt_to_pil

< >

( images )

Mengubah gambar torch menjadi gambar PIL.

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

Parameter

  • image (str atau PIL.Image.Image) — Gambar yang akan dikonversi ke format PIL Image.
  • convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], opsional) — Metode konversi yang diterapkan pada gambar setelah dimuat. Jika diset ke None, gambar akan dikonversi ke “RGB”.

Mengembalikan

PIL.Image.Image

Gambar PIL.

Memuat image ke dalam PIL Image.

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]

Parameter

  • video (str) — URL atau Path ke video yang akan dikonversi menjadi daftar format PIL Image.
  • convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], opsional) — Metode konversi yang diterapkan pada video setelah dimuat. Jika diset ke None, gambar akan dikonversi ke “RGB”.
  • return_fps (bool, opsional, default False) — Apakah juga mengembalikan frame rate yang digunakan saat video di-encode. Diperlukan oleh pipeline yang melakukan resampling input ke frame rate yang digunakan oleh modelnya, karena daftar frame tidak membawa informasi tersebut.

Mengembalikan

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

Video sebagai daftar gambar PIL, dan frame rate-nya jika return_fps disetel.

Memuat video ke dalam daftar Gambar PIL.

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: Kualitas output video. Default adalah 5. Menggunakan variable bit rate. Kualitas tertinggi adalah 10, terendah adalah 0. Atur ke None untuk mencegah flag variable bitrate ke FFMPEG sehingga Anda dapat menentukannya secara manual menggunakan output_params. Menentukan bitrate tetap menggunakan bitrate akan menonaktifkan parameter ini.

bitrate: Atur bitrate konstan untuk pengkodean video. Nilai default adalah None sehingga parameter quality yang digunakan sebagai gantinya. Video dengan kualitas lebih baik dan ukuran file yang lebih kecil akan dihasilkan dengan menggunakan parameter bitrate variabel quality daripada menentukan bitrate tetap dengan parameter ini.

macro_block_size: Batasan ukuran untuk video. Lebar dan tinggi harus dapat dibagi habis oleh angka ini. Jika tidak dapat dibagi habis, imageio akan menginstruksikan ffmpeg untuk memperbesar gambar ke ukuran terdekat yang dapat dibagi habis oleh angka ini. Sebagian besar codec kompatibel dengan ukuran makroblok 16 (default), beberapa dapat lebih kecil (4, 8). Untuk menonaktifkan fitur otomatis ini, setel ke None atau 1, namun perlu diwaspadai bahwa banyak pemutar tidak dapat mendekode video yang ukurannya ganjil dan beberapa codec akan menghasilkan kualitas buruk atau gagal. Lihat https://en.wikipedia.org/wiki/Macroblock.

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 )

Parameter

  • video (List[PIL.Image.Image] atau np.ndarray atau torch.Tensor) — Tensor video dengan bentuk [frames, height, width, channels] yang berisi nilai piksel integer dalam rentang [0, 255]. Jika input berupa np.ndarray, array tersebut diharapkan berupa array float dengan nilai dalam rentang [0, 1] (yang merupakan hasil yang biasanya dikembalikan oleh pipeline dengan output_type="np").
  • fps (int) — Jumlah frame per detik (FPS) dari video yang dikodekan.
  • output_path (str) — Path untuk menyimpan video yang telah dikodekan.
  • audio (torch.Tensor, opsional) — Gelombang audio dengan bentuk [audio_channels, samples].
  • audio_sample_rate — (int, opsional): Laju sampling dari waveform audio.
  • video_chunks_number (int, opsional, default 1) — Jumlah chunk untuk membagi video saat encoding. Setiap chunk akan di-encode secara terpisah. Jumlah chunk yang digunakan sering kali bergantung pada konfigurasi tiling untuk VAE video.

Mengodekan video dengan audio opsional menggunakan pustaka PyAV. Berdasarkan kode dari repo LTX-2 asli: 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: list[PIL.Image.Image]rows: intcols: intresize: int = None )

Menyiapkan satu grid gambar. Berguna untuk keperluan visualisasi.

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 )

Fungsi bantu untuk membuat tensor acak pada device yang diinginkan dengan dtype yang diinginkan. Saat meneruskan daftar generator, Anda dapat mengatur seed untuk setiap ukuran batch secara individual. Jika generator CPU diteruskan, tensor selalu dibuat di CPU.

TorchDeviceBackend

kelas diffusers.utils.torch_utils.TorchDeviceBackend

< >

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

Proksi untuk namespace torch.<backend> (torch.cuda, torch.xpu, torch.mps, …) dari satu perangkat. Atribut yang tidak didefinisikan oleh kelas ini adalah milik modul itu sendiri (synchronize, device_count, Stream, current_stream, …); metode yang didefinisikan di sini menggantikan operasi yang ketersediaan dan perbedaannya antar backend serta memerlukan fallback: pembersihan cache, seeding, dan kueri memori. Tanpa device, mendeteksi akselerator host melalui torch.accelerator. Mengangkat error jika torch tidak memiliki modul untuk backend tersebut, alih-alih secara diam-diam kembali ke torch.cuda.

max_memory_allocated

< >

( )

Puncak memori yang dialokasikan pada perangkat dalam byte sejak reset terakhir; 0 di mana backend tidak menyimpan statistik.

mem_get_info

< >

( )

Memori perangkat gratis dan total dalam byte.

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 )

Parameter

  • module (torch.nn.Module) — Modul yang modul daunnya akan di-cast ke dtype presisi tinggi untuk komputasi, dan ke dtype presisi rendah untuk penyimpanan.
  • storage_dtype (torch.dtype) — dtype untuk meng-cast modul sebelum/setelah forward pass untuk penyimpanan.
  • compute_dtype (torch.dtype) — dtype untuk meng-cast modul selama forward pass untuk komputasi.
  • skip_modules_pattern (tuple[str, ...], defaultnya "auto") — Daftar pola untuk mencocokkan nama modul yang akan dilewati selama proses casting layerwise. Jika diatur ke "auto", pola default digunakan. Jika diatur ke None, tidak ada modul yang dilewati. Jika diatur ke None bersamaan dengan skip_modules_classes yang bernilai None, casting layerwise diterapkan langsung ke modul bukan ke submodul internalnya.
  • skip_modules_classes (tuple[Type[torch.nn.Module], ...], defaultnya None) — Daftar kelas modul yang akan dilewati selama proses casting per lapisan.
  • non_blocking (bool, defaultnya False) — Jika True, operasi casting bobot bersifat non-blocking.

Menerapkan pencetakan per lapisan ke modul yang diberikan. Modul yang diharapkan di sini adalah ModelMixin Diffusers, tetapi bisa berupa nn.Module apa pun yang menggunakan lapisan diffusers atau primitif pytorch.

Contoh:

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

Parameter

  • module (torch.nn.Module) — Modul tempat offloading grup diterapkan.
  • onload_device (torch.device) — Perangkat tempat grup modul dimuat ulang.
  • offload_device (torch.device, defaultnya torch.device("cpu")) — Perangkat tempat grup modul di-offload. Ini biasanya harus CPU. Defaultnya adalah CPU.
  • offload_type (str atau GroupOffloadingType, default “block_level”) — Jenis offloading yang akan diterapkan. Bisa berupa “block_level” atau “leaf_level”. Default adalah “block_level”.
  • offload_to_disk_path (str, opsional, default None) — Path ke direktori tempat parameter akan di-offload. Mengatur opsi ini dapat berguna dalam lingkungan dengan RAM terbatas di mana trade-off antara kecepatan dan memori yang wajar diinginkan.
  • num_blocks_per_group (int, opsional) — Jumlah blok per grup saat menggunakan offload_type=“block_level”. Ini wajib diisi saat menggunakan offload_type=“block_level”.
  • non_blocking (bool, defaultnya False) — Jika True, offloading dan onloading dilakukan dengan transfer data non-blocking.
  • use_stream (bool, defaultnya False) — Jika True, offloading dan onloading dilakukan secara asinkron menggunakan CUDA stream. Hal ini dapat berguna untuk menumpuk komputasi dan transfer data.
  • record_stream (bool, defaultnya False) — Saat diaktifkan bersama use_stream, menandai tensor saat ini sebagai telah digunakan oleh stream ini. Proses ini lebih cepat dengan sedikit peningkatan penggunaan memori. Lihat dokumentasi resmi PyTorch untuk detail lebih lanjut.
  • low_cpu_mem_usage (bool, defaultnya False) — Jika True, penggunaan memori CPU diminimalkan dengan cara pinning tensor secara on-the-fly alih-alih pre-pinning. Opsi ini hanya relevan saat menggunakan streamed CPU offloading (yaitu use_stream=True). Hal ini dapat berguna ketika memori CPU menjadi bottleneck, tetapi mungkin mengurangi manfaat dari penggunaan streams.
  • block_modules (list[str], opsional) — Daftar nama modul yang harus diperlakukan sebagai blok untuk offloading. Jika disediakan, hanya modul-modul ini yang akan dipertimbangkan untuk offloading tingkat blok. Jika tidak disediakan, logika deteksi blok bawaan akan digunakan.
  • exclude_kwargs (list[str], opsional) — Daftar kunci kwarg yang tidak boleh diproses oleh send_to_device. Ini berguna untuk state yang dapat diubah seperti daftar cache yang perlu mempertahankan identitas objeknya di antara forward passes. Jika tidak disediakan, akan disimpulkan dari atribut _skip_keys modul jika ada.

Menerapkan group offloading ke lapisan internal dari torch.nn.Module. Untuk memahami apa itu group offloading dan di mana metode ini bermanfaat, kita perlu terlebih dahulu memberikan konteks tentang bagaimana metode offloading lain yang didukung bekerja.

Biasanya, offloading dilakukan pada dua tingkat:

  • Tingkat modul: Di Diffusers, ini dapat diaktifkan menggunakan metode ModelMixin::enable_model_cpu_offload(). Cara kerjanya adalah dengan memindahkan setiap komponen pipeline ke CPU untuk penyimpanan, lalu memuatnya kembali ke perangkat akselerator saat diperlukan untuk komputasi. Metode ini lebih hemat memori dibandingkan dengan menyimpan semua komponen di akselerator, tetapi persyaratan memori masih cukup tinggi. Agar metode ini berfungsi, diperlukan memori yang setara dengan ukuran model dalam dtype runtime + ukuran tensor aktivasi antara terbesar untuk dapat menyelesaikan forward pass.
  • Leaf-level: Di Diffusers, ini dapat diaktifkan menggunakan metode ModelMixin::enable_sequential_cpu_offload(). Cara kerjanya adalah dengan memindahkan parameter leaf-level terendah dari graf komputasi ke CPU untuk penyimpanan, dan hanya memuat ulang leaf ke perangkat akselerator untuk komputasi. Metode ini menggunakan memori akselerator paling sedikit, tetapi bisa lebih lambat karena jumlah sinkronisasi perangkat yang berlebihan.

Group offloading merupakan jalan tengah antara kedua metode tersebut. Metode ini bekerja dengan cara meng-offload kelompok lapisan internal, (yaitu torch.nn.ModuleList atau torch.nn.Sequential). Metode ini menggunakan memori lebih rendah daripada offloading tingkat modul. Metode ini juga lebih cepat daripada offloading tingkat daun/sequential, karena jumlah sinkronisasi perangkat berkurang.

Fitur lain yang didukung (untuk perangkat CUDA dengan dukungan untuk stream transfer data asinkron) adalah kemampuan untuk menumpuk (overlap) transfer data dan komputasi guna mengurangi waktu eksekusi keseluruhan dibandingkan dengan offloading berurutan. Hal ini diaktifkan menggunakan prefetching layer dengan stream, yaitu layer yang akan dieksekusi berikutnya mulai melakukan onloading ke perangkat akselerator sementara layer saat ini sedang dieksekusi - ini sedikit meningkatkan persyaratan memori. Perhatikan bahwa implementasi ini juga mendukung offloading tingkat daun (leaf-level) tetapi dapat dibuat jauh lebih cepat saat menggunakan stream.

Contoh:

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

←Lapisan normalisasi kustom Pemroses Gambar VAE→