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

```python
diffusers.utils.numpy_to_pil(images)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/pil_utils.py#L35)

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

```python
diffusers.utils.pt_to_pil(images)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/pil_utils.py#L25)

Mengubah gambar torch menjadi gambar PIL.

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

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

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/loading_utils.py#L14)

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

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/loading_utils.py#L57)

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

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/export_utils.py#L37)

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

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

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/export_utils.py#L150)

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

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/export_utils.py#L304)

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

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/pil_utils.py#L51)

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

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/torch_utils.py#L61)

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

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/torch_utils.py#L228)

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

```python
max_memory_allocated()
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/torch_utils.py#L291)

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

```python
mem_get_info()
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/torch_utils.py#L279)

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

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/hooks/layerwise_casting.py#L101)

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

```python
>>> 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]]

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/hooks/group_offloading.py#L567)

**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](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html) 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:
```python
>>> 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,
... )
```