Diffusers 文件
實用工具
並獲得增強的文件體驗
開始使用
工具
用於 🤗 Diffusers 的實用和輔助函式。
numpy_to_pil
將 numpy 影像或影像批次轉換為 PIL 影像。
pt_to_pil
將 torch 影像轉換為 PIL 影像。
load_image
diffusers.utils.load_image
< source 原始碼 >( image: typing.Union[str, PIL.Image.Image] convert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None ) → PIL.Image.Image
將 image 載入為 PIL 影像。
export_to_gif
diffusers.utils.export_to_gif
< source 原始碼 >( image: typing.List[PIL.Image.Image] output_gif_path: str = None fps: int = 10 )
export_to_video
diffusers.utils.export_to_video
< source 原始碼 >( video_frames: typing.Union[typing.List[numpy.ndarray], typing.List[PIL.Image.Image]] output_video_path: str = None fps: int = 10 quality: float = 5.0 bitrate: typing.Optional[int] = None macro_block_size: typing.Optional[int] = 16 )
quality: 影片輸出質量。預設為 5。使用可變位元率。最高質量為 10，最低質量為 0。設定為 None 可防止向 FFMPEG 傳遞可變位元率標誌，以便您可以手動使用 output_params 指定它們。使用 bitrate 指定固定位元率會停用此引數。
bitrate: 設定影片編碼的恆定位元率。預設為 None，此時將使用 quality 引數。與使用此引數指定固定位元率相比，使用 quality 可變位元率引數將生成更高質量、檔案更小的影片。
macro_block_size: 影片的尺寸約束。寬度和高度必須能被此數字整除。如果不能被此數字整除，imageio 將告訴 ffmpeg 將影像放大到下一個最接近的、能被此數字整除的尺寸。大多數編解碼器與宏塊大小 16（預設）相容，有些可以更小（4、8）。要停用此自動功能，請將其設定為 None 或 1，但請注意，許多播放器無法解碼奇數尺寸的影片，並且某些編解碼器會產生較差結果或失敗。請參閱 https://en.wikipedia.org/wiki/Macroblock。
make_image_grid
diffusers.utils.make_image_grid
< source 原始碼 >( images: typing.List[PIL.Image.Image] rows: int cols: int resize: int = None )
準備單個影像網格。對視覺化很有用。
randn_tensor
diffusers.utils.torch_utils.randn_tensor
< source 原始碼 >( shape: typing.Union[typing.Tuple, typing.List] generator: typing.Union[typing.List[ForwardRef('torch.Generator')], ForwardRef('torch.Generator'), NoneType] = None device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None dtype: typing.Optional[ForwardRef('torch.dtype')] = None layout: typing.Optional[ForwardRef('torch.layout')] = None )
一個輔助函式，用於在所需 device 上使用所需 dtype 建立隨機張量。當傳遞生成器列表時，您可以單獨為每個批處理大小設定種子。如果傳遞 CPU 生成器，則張量始終在 CPU 上建立。
apply_layerwise_casting
diffusers.hooks.apply_layerwise_casting
< source 原始碼 >( module: Module storage_dtype: dtype compute_dtype: dtype skip_modules_pattern: typing.Union[str, typing.Tuple[str, ...]] = 'auto' skip_modules_classes: typing.Optional[typing.Tuple[typing.Type[torch.nn.modules.module.Module], ...]] = None non_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: Module onload_device: device offload_device: device = device(type='cpu') offload_type: str = 'block_level' num_blocks_per_group: typing.Optional[int] = None non_blocking: bool = False use_stream: bool = False record_stream: bool = False low_cpu_mem_usage: bool = False offload_to_disk_path: typing.Optional[str] = None )
引數
- module (
torch.nn.Module) — 應用組解除安裝的模組。 - onload_device (
torch.device) — 模組組載入到的裝置。 - offload_device (
torch.device, 預設為torch.device("cpu")) — 模組組解除安裝到的裝置。這通常應該是 CPU。預設為 CPU。 - offload_type (
str, 預設為“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 記憶體成為瓶頸時，這可能很有用，但可能會抵消使用流的好處。
將組解除安裝應用於 torch.nn.Module 的內部層。要了解什麼是組解除安裝以及它在何處有益，我們首先需要提供一些關於其他支援的解除安裝方法如何工作的背景。
通常，解除安裝在兩個級別進行
- 模組級：在 Diffusers 中，可以透過使用
ModelMixin::enable_model_cpu_offload()方法啟用此功能。它的工作原理是將管道的每個元件解除安裝到 CPU 進行儲存，並在需要計算時載入到加速器裝置。此方法比將所有元件保留在加速器上更節省記憶體，但記憶體需求仍然很高。為了使此方法工作，需要相當於執行時 dtype 中模型大小 + 最大中間啟用張量大小的記憶體才能完成前向傳遞。 - 葉級：在 Diffusers 中，可以透過使用
ModelMixin::enable_sequential_cpu_offload()方法啟用此功能。它的工作原理是將計算圖的最低葉級引數解除安裝到 CPU 進行儲存，並且僅將葉級載入到加速器裝置進行計算。這使用最少的加速器記憶體，但由於裝置同步過多而可能較慢。
組解除安裝是兩種方法之間的中間地帶。它的工作原理是解除安裝內部層的組（無論是 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,
... )