ユーティリティ

🤗 Diffusers を扱うためのユーティリティおよびヘルパー関数。

numpy_to_pil

diffusers.utils.numpy_to_pil

< source >

( images )

numpyの画像または画像のバッチをPIL画像に変換します。

pt_to_pil

diffusers.utils.pt_to_pil

< source >

( images )

torchの画像をPIL画像に変換します。

load_image

diffusers.utils.load_image

< source >

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

パラメータ

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

< source >

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

パラメータ

video (str) — PIL Image のリストに変換する動画の URL または Path。
convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], optional) — 動画を読み込んだ後に適用する変換メソッドです。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

< source >

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

export_to_video

diffusers.utils.export_to_video

< source >

( 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: 動画エンコードに一定のビットレートを設定します。デフォルトは 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

< source >

パラメータ

video (List[PIL.Image.Image] または np.ndarray または torch.Tensor) — [0, 255] の範囲の整数ピクセル値を持つ、形状が [frames, height, width, channels] の動画テンソルです。入力が 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, 任意、デフォルトは 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

< source >

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

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

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< source >

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

TorchDeviceBackend

class diffusers.utils.torch_utils.TorchDeviceBackend

< source >

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

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

max_memory_allocated

< source >

( )

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

mem_get_info

< source >

( )

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

apply_layerwise_casting

diffusers.hooks.apply_layerwise_casting

< source >

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

パラメータ

module (torch.nn.Module) — 計算には高精度の dtype、保存には低精度の dtype にキャストされるリーフモジュールを持つモジュール。
storage_dtype (torch.dtype) — フォワードパスの前後で、モジュールをストレージ用にキャストする際に使用する 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 でも構いません。

例:

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

< source >

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

パラメータ

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 公式ドキュメントを参照してください。
low_cpu_mem_usage (bool、デフォルトは False) — True の場合、テンソルを事前にピン留めするのではなく、オンザフライでピン留めすることで CPU メモリ使用量を最小限に抑えます。このオプションは、ストリーミング CPU オフロード（つまり use_stream=True）を使用している場合にのみ意味を持ちます。CPU メモリがボトルネックになる場合に有用ですが、ストリームを使用する利点を相殺する可能性があります。
block_modules (list[str], 任意) — オフローディングの対象ブロックとして扱うモジュール名のリストです。指定された場合、ブロックレベルのオフローディングの候補としてこれらのモジュールのみが考慮されます。指定されない場合、デフォルトのブロック検出ロジックが使用されます。
exclude_kwargs (list[str], optional) — List of kwarg keys that should not be processed by send_to_device. This is useful for mutable state like caching lists that need to maintain their object identity across forward passes. If not provided, will be inferred from the module’s _skip_keys attribute if it exists.

torch.nn.Module の内部レイヤーにグループオフロードを適用します。グループオフロードとは何か、またどのような場合に有効であるかを理解するには、まず他のサポートされているオフロード手法がどのように動作するかという背景を説明する必要があります。

通常、オフローディングは2つのレベルで行われます。

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

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

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

例:

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