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,
... )