# ユーティリティ

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

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

numpyの画像または画像のバッチを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)
```

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

torchの画像を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)
```

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

**パラメータ:**

image (`str` または `PIL.Image.Image`) : PIL Image 形式に変換する画像。

convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], *任意*) : 画像を読み込んだ後に適用する変換メソッド。`None`に設定されている場合、画像は"RGB"に変換されます。

**戻り値:** `PIL.Image.Image`

PILのImageです。

`image`を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)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/loading_utils.py#L57)

**パラメータ:**

video (`str`) : PIL Image のリストに変換する動画の URL または Path。

convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], *任意*) : 動画を読み込んだ後に適用する変換メソッド。`None`に設定されている場合、画像は"RGB"に変換されます。

return_fps (`bool`, *任意*, デフォルトは `False`) : 動画がエンコードされたフレームレートも返すかどうかを指定します。入力フレームをモデルが動作するフレームレートにリサンプリングするパイプラインでは、フレームのリスト自体にはその情報が含まれないため、この値が必要です。

**戻り値:** `list[PIL.Image.Image]` または `tuple[list[PIL.Image.Image], float]`

`return_fps` が設定されている場合、PIL 画像のリストとしての動画とそのフレームレート。

`video`をPIL Imageのリストに読み込みます。

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

[ソース](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)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/export_utils.py#L150)

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: 動画エンコードに一定のビットレートを設定します。デフォルトは None で、この場合 `quality` パラメータが代わりに使用されます。このパラメータで固定ビットレートを指定するのではなく、`quality` 可変ビットレートパラメータを使用すると、より高品質でファイルサイズが小さい動画が得られます。

macro_block_size: 動画のサイズ制約。幅と高さは、この数で割り切れる必要があります。割り切れない場合、imageio は ffmpeg に指示して、この数で割り切れる最も近い次のサイズに画像を拡大します。ほとんどのコーデックはマクロブロックサイズ 16（デフォルト）に対応しており、一部はより小さいサイズ（4、8）にも対応できます。この自動機能を無効にするには None または 1 を設定してください。ただし、サイズが奇数である動画をデコードできないプレイヤーが多く、また一部のコーデックでは品質が低下したり失敗したりする可能性があるため、注意してください。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)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/export_utils.py#L304)

**パラメータ:**

video (`List[PIL.Image.Image]` または `np.ndarray` または `torch.Tensor`) : 形状が [frames, height, width, channels] で、ピクセル値が [0, 255] の範囲の整数である動画テンソル。入力が `np.ndarray` の場合、値が [0, 1] の範囲の float 配列であることが期待されます（`output_type="np"` を指定してパイプラインが通常返す形式です）。

fps (`int`) : 符号化された動画の毎秒フレーム数（FPS）。

output_path (`str`) : エンコードされた動画を保存するパス。

audio (`torch.Tensor`, *任意*) : 形状が [audio_channels, samples] のオーディオ波形です。

audio_sample_rate : (`int`, *任意*): 音声波形のサンプリングレート。

video_chunks_number (`int`、*optional*、デフォルトは`1`) : エンコードのために動画を分割するチャンク数です。各チャンクは個別にエンコードされます。使用するチャンク数は、多くの場合、動画 VAE のタイル設定に依存します。

PyAVライブラリを使用して、任意のオーディオ付きで動画をエンコードします。元のLTX-2リポジトリのコードをベースにしています: 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)
```

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

画像の単一のグリッドを準備します。可視化に便利です。

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

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/torch_utils.py#L61)

`device` および `dtype` を指定して、ランダムなテンソルを作成するためのヘルパー関数です。ジェネレーターのリストを渡す場合、各バッチサイズごとに個別にシードを設定できます。CPU のジェネレーターが渡された場合、テンソルは常に 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)
```

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

`torch.<backend>` 名前空間(`torch.cuda`、`torch.xpu`、`torch.mps` など)の1つのデバイスのプロキシです。このクラスが定義していない属性は、モジュール自身のもの(`synchronize`、`device_count`、`Stream`、`current_stream` など)です。ここで定義されているメソッドは、バックエンド間で利用可能性が異なり、フォールバックが必要な操作(キャッシュのクリア、シード設定、メモリクエリ)をオーバーライドします。`device` が指定されていない場合、`torch.accelerator` を通じてホストアクセラレータを検出します。torch にバックエンド用のモジュールが存在しない場合は、`torch.cuda` に黙ってフォールバックするのではなく、例外を発生させます。

#### max_memory_allocated[[diffusers.utils.torch_utils.TorchDeviceBackend.max_memory_allocated]]

```python
max_memory_allocated()
```

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

前回リセット以降、デバイス上で割り当てられたピークメモリ量（バイト単位）。バックエンドが統計情報を保持しない場合は 0。

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

```python
mem_get_info()
```

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

バイト単位の空きメモリとデバイスの総メモリ。

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

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/hooks/layerwise_casting.py#L101)

**パラメータ:**

module (`torch.nn.Module`) : 計算には高精度の dtype、保存には低精度の dtype にキャストされるリーフモジュールを持つモジュール。

storage_dtype (`torch.dtype`) : モジュールを保存するために、forward pass の前後でキャストする dtype。

compute_dtype (`torch.dtype`) : 前向きパスの計算時にモジュールをキャストするdtype。

skip_modules_pattern (`tuple[str, ...]`、デフォルトは`"auto"`) : レイヤワイズキャスティング処理中にスキップするモジュールの名前を一致させるためのパターンリスト。`"auto"`に設定すると、デフォルトのパターンが使用されます。`None`に設定すると、モジュールはスキップされません。`None`に設定されるとともに`skip_modules_classes`が`None`の場合、モジュールの内部サブモジュールではなく、モジュール自体に直接レイヤワイズキャスティングが適用されます。

skip_modules_classes (`tuple[Type[torch.nn.Module], ...]`、デフォルトは`None`) : レイヤワイズキャスト処理中にスキップするモジュールクラスのリスト。

non_blocking (`bool`、デフォルトは`False`) : `True`の場合、重みのキャスト操作はブロッキングなしで実行されます。

指定されたモジュールにレイヤー単位のキャストを適用します。ここで想定されるモジュールは Diffusers の ModelMixin ですが、diffusers のレイヤーや PyTorch のプリミティブを使用する任意の nn.Module でも構いません。

例:

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

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/hooks/group_offloading.py#L567)

**パラメータ:**

module (`torch.nn.Module`) : グループオフローディングが適用されるモジュール。

onload_device (`torch.device`) : モジュールのグループがロードされているデバイス。

offload_device (`torch.device`、デフォルトは`torch.device("cpu")`) : モジュールのグループがオフロードされるデバイスです。通常はCPUを指定します。デフォルトはCPUです。

offload_type (`str` または `GroupOffloadingType`、デフォルトは "block_level") : 適用するオフローディングの種類です。"block_level" または "leaf_level" のいずれかです。デフォルトは "block_level" です。

offload_to_disk_path (`str`、*任意*、デフォルトは`None`) : パラメータをオフロードするディレクトリのパスです。RAMが限られた環境で、速度とメモリ使用量のバランスを重視する場合に、このオプションを設定すると有用です。

num_blocks_per_group (`int`, *任意*) : offload_type="block_level" を使用する場合のグループあたりのブロック数。offload_type="block_level" を使用する場合は必須です。

non_blocking (`bool`、デフォルトは`False`) : True の場合、オフローディングとオンローディングがブロッキングなしのデータ転送で実行されます。

use_stream (`bool`、デフォルトは`False`) : True の場合、CUDA ストリームを使用してオフロードとオンロードを非同期で実行します。これにより、計算とデータ転送のオーバーラップが可能になります。

record_stream (`bool`、デフォルトは`False`) : `use_stream`を有効にした場合、現在のテンソルがこのストリームによって使用されたことをマークします。メモリ使用量がわずかに増加する代わりに、処理が高速になります。詳細については、[PyTorch 公式ドキュメント](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html)を参照してください。

low_cpu_mem_usage (`bool`、デフォルトは`False`) : True の場合、テンソルを事前にピン留めするのではなく、オンザフライでピン留めすることで CPU メモリ使用量を最小限に抑えます。このオプションは、ストリーミング CPU オフロード（つまり `use_stream=True`）を使用している場合にのみ意味があります。CPU メモリがボトルネックになる場合に有用ですが、ストリームを使用する利点を相殺する可能性があります。

block_modules (`list[str]`, *任意*) : オフロード対象のブロックとして扱うモジュール名のリストです。指定された場合、ブロックレベルのオフロードの候補としてこれらのモジュールのみが考慮されます。指定されない場合、デフォルトのブロック検出ロジックが使用されます。

exclude_kwargs (`list[str]`, *任意*) : send_to_device によって処理されるべきでない kwarg のキーのリストです。これは、フォワードパス間でオブジェクトの同一性を維持する必要があるキャッシュリストなどの可変状態に有用です。指定されない場合、モジュールの `_skip_keys` 属性が存在する場合はそこから推論されます。

torch.nn.Module の内部レイヤーにグループオフロードを適用します。グループオフロードとは何か、またどのような場合に有効であるかを理解するには、まず他のサポートされているオフロード方式の仕組みについて、いくつかの背景情報を提供する必要があります。

通常、オフローディングは2つのレベルで行われます。
- モジュールレベル: Diffusers では、`ModelMixin::enable_model_cpu_offload()` メソッドを使用してこれを有効にできます。このメソッドは、パイプラインの各コンポーネントを CPU にオフロードして保存し、計算が必要なときにアクセラレータデバイスにオンロードすることで動作します。すべてのコンポーネントをアクセラレータ上に保持するよりもメモリ効率に優れていますが、メモリ要件は依然としてかなり高くなります。このメソッドを動作させるには、ランタイムのデータ型でのモデルサイズに相当するメモリと、フォワードパスを完了するために必要な最大サイズの中間活性化テンソルに相当するメモリが必要です。
- リーフレベル: Diffusers では、`ModelMixin::enable_sequential_cpu_offload()` メソッドを使用してこれを有効にできます。計算グラフの最下層のリーフレベルのパラメータを CPU にオフロードして保存し、計算のためにリーフのみをアクセラレータデバイスにオンロードすることで動作します。これによりアクセラレータメモリ使用量が最小限に抑えられますが、デバイス同期の回数が多くなるため、処理が遅くなる可能性があります。

Group offloading は、上記2つの手法の中間的なアプローチです。`torch.nn.ModuleList` または `torch.nn.Sequential` として構成された内部レイヤーのグループ単位でオフロードを行うことで機能します。この手法は、モジュールレベルのオフロードよりもメモリ使用量が少なく、デバイス同期の回数が減るため、リーフレベル/シーケンシャルオフロードよりも高速です。

もう一つのサポートされている機能（非同期データ転送ストリームに対応する CUDA デバイス向け）は、データ転送と計算をオーバーラップさせることで、シーケンシャルなオフローディングと比較して全体の実行時間を短縮できる点です。これは、ストリームを用いたレイヤープリフェッチによって有効化されます。具体的には、現在のレイヤーが実行されている間に、次に実行されるレイヤーのオンローディングがアクセラレーターデバイス上で開始される仕組みです。これにより、メモリ要件はわずかに増加します。なお、この実装はリーフレベルのオフローディングにも対応していますが、ストリームを使用すると大幅に高速化されます。

例:
```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,
... )
```