diffusers/main/id/api/utilities.md

Utilitas

Fungsi utilitas dan pembantu untuk bekerja dengan 🤗 Diffusers.

numpy_to_pil[[diffusers.utils.numpy_to_pil]]

diffusers.utils.numpy_to_pil[[diffusers.utils.numpy_to_pil]]

diffusers.utils.numpy_to_pil(images)

Sumber

Mengonversi gambar numpy atau batch gambar menjadi gambar PIL.

pt_to_pil[[diffusers.utils.pt_to_pil]]

diffusers.utils.pt_to_pil[[diffusers.utils.pt_to_pil]]

diffusers.utils.pt_to_pil(images)

Sumber

Mengubah gambar torch menjadi gambar PIL.

load_image[[diffusers.utils.load_image]]

diffusers.utils.load_image[[diffusers.utils.load_image]]

diffusers.utils.load_image(image: str | PIL.Image.Image, convert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None)

Sumber

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 untuk diterapkan pada gambar setelah dimuat. Ketika diset ke None, gambar akan dikonversi menjadi "RGB".

Mengembalikan: PIL.Image.Image

Gambar PIL.

Memuat image ke dalam PIL Image.

load_video[[diffusers.utils.load_video]]

diffusers.utils.load_video[[diffusers.utils.load_video]]

diffusers.utils.load_video(video: str, convert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = None, return_fps: bool = False)

Sumber

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 untuk diterapkan pada video setelah dimuat. Ketika diset ke None, gambar akan dikonversi ke "RGB".

return_fps (bool, opsional, defaultnya 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]]

diffusers.utils.export_to_gif[[diffusers.utils.export_to_gif]]

diffusers.utils.export_to_gif(image: list[PIL.Image.Image], output_gif_path: str = None, fps: int = 10)

Sumber

export_to_video[[diffusers.utils.export_to_video]]

diffusers.utils.export_to_video[[diffusers.utils.export_to_video]]

diffusers.utils.export_to_video(video_frames: list[np.ndarray] | list[PIL.Image.Image], output_video_path: str = None, fps: int = 10, quality: float = 5.0, bitrate: int | None = None, macro_block_size: int | None = 16)

Sumber

quality: Kualitas output video. Default adalah 5. Menggunakan variable bit rate. Kualitas tertinggi adalah 10, terendah adalah 0. Set 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: Menetapkan 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, atur 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]]

diffusers.utils.encode_video[[diffusers.utils.encode_video]]

diffusers.utils.encode_video(video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor'], fps: int, output_path: str, audio: 'torch.Tensor' | None = None, audio_sample_rate: int | None = None, video_chunks_number: int = 1)

Sumber

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

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, defaultnya 1) : Jumlah chunk untuk membagi video dalam proses 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]]

diffusers.utils.make_image_grid[[diffusers.utils.make_image_grid]]

diffusers.utils.make_image_grid(images: list[PIL.Image.Image], rows: int, cols: int, resize: int = None)

Sumber

Menyiapkan satu grid gambar. Berguna untuk keperluan visualisasi.

randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

diffusers.utils.torch_utils.randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

diffusers.utils.torch_utils.randn_tensor(shape: tuple | list, generator: list['torch.Generator'] | 'torch.Generator' | None = None, device: str | 'torch.device' | None = None, dtype: 'torch.dtype' | None = None, layout: 'torch.layout' | None = None)

Sumber

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[[diffusers.utils.torch_utils.TorchDeviceBackend]]

diffusers.utils.torch_utils.TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

diffusers.utils.torch_utils.TorchDeviceBackend(device: str | torch.device | None = None)

Sumber

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 menimpa 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[[diffusers.utils.torch_utils.TorchDeviceBackend.max_memory_allocated]]

max_memory_allocated()

Sumber

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

mem_get_info[[diffusers.utils.torch_utils.TorchDeviceBackend.mem_get_info]]

mem_get_info()

Sumber

Memori perangkat gratis dan total dalam byte.

apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

diffusers.hooks.apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

diffusers.hooks.apply_layerwise_casting(module: Module, storage_dtype: dtype, compute_dtype: dtype, skip_modules_pattern: str | tuple[str, ...] = 'auto', skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = None, non_blocking: bool = False)

Sumber

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 per lapisan. 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 per lapisan 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]]

diffusers.hooks.apply_group_offloading[[diffusers.hooks.apply_group_offloading]]

diffusers.hooks.apply_group_offloading(module: Module, onload_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 = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage: bool = False, offload_to_disk_path: str | None = None, block_modules: list[str] | None = None, exclude_kwargs: list[str] | None = None)

Sumber

Parameter:

module (torch.nn.Module) : Modul tempat group offloading diterapkan.

onload_device (torch.device) : Perangkat tempat grup modul dimuat.

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, defaultnya "block_level") : Jenis offloading yang akan diterapkan. Bisa berupa "block_level" atau "leaf_level". Defaultnya adalah "block_level".

offload_to_disk_path (str, opsional, defaultnya None) : Path ke direktori tempat parameter akan di-offload. Mengatur opsi ini dapat berguna dalam lingkungan dengan RAM terbatas di mana trade-off kecepatan- 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, parameter ini menandai tensor saat ini sebagai telah digunakan oleh stream ini. Prosesnya 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 mem-pin tensor secara on-the-fly alih-alih mem-pinnya sebelumnya. 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 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 (mutable) 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, (baik torch.nn.ModuleList maupun 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 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, 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,
... )