Diffusers 工具函数与辅助 API 完全指南图像/视频加载导出、随机张量生成与显存优化 Hook【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本指南聚焦 docs/source/en/api/utilities.md 所定义的 Diffusers 工具函数与辅助 API系统讲解图像、视频的加载与导出、图像网格拼接、噪声张量生成以及面向显存优化的 Layerwise Casting 与 Group Offloading 两大类 Hook 的用法与底层实现。读完本文你将能够熟练地在推理脚本中完成「输入媒体加载 → 模型推理 → 结果可视化/保存」的完整闭环并掌握在有限显存下运行超大扩散模型的两套实战方案。一、总览Utilities 家族在 Diffusers 中的地位在 src/diffusers/utils 目录下这些工具函数被集中实现并按模块划分pil_utils.pynumpy_to_pil、pt_to_pil、make_image_gridloading_utils.pyload_image、load_videoexport_utils.pyexport_to_gif、export_to_video、encode_video另有export_to_ply、export_to_obj等网格导出工具torch_utils.pyrandn_tensorhooks/layerwise_casting.py 与 hooks/group_offloading.py两个显存优化 Hook。这些函数全部通过 src/diffusers/utils/init.py 对外导出并最终在diffusers.utils命名空间下直接可用例如from diffusers.utils import load_image, make_image_grid, export_to_video。前置依赖提示多数工具只依赖 Pillow、NumPy、PyTorch而视频相关函数load_video、export_to_video、encode_video还需要imageio、imageio-ffmpeg、avPyAV等可选后端安装命令会在下文对应小节给出。二、输入加载从 URL / 本地路径到 PIL 图像与视频帧2.1 load_image统一入口加载单张图像load_image是 Diffusers 中最常用的图像加载工具支持三种输入形态http/https URL、本地文件路径、已经存在的 PIL Image。其核心实现在 loading_utils.pydef load_image( image: str | PIL.Image.Image, convert_method: Callable[[PIL.Image.Image], PIL.Image.Image] | None None, ) - PIL.Image.Image:关键行为说明URL 加载使用requests.get(image, streamTrue)流式下载超时时间取自 constants.py 中的DIFFUSERS_REQUEST_TIMEOUT 6060 秒本地路径os.path.isfile(image)校验存在后直接PIL.Image.open非法输入既不是 URL 也不是文件路径的字符串会抛出ValueError提示URLs must start withhttp://orhttps://EXIF 方向修正加载后统一执行PIL.ImageOps.exif_transpose(image)避免手机拍摄照片因 EXIF 旋转信息导致方向错乱色彩模式默认convert_methodNone转换为RGB也可传入自定义转换函数convert_method如lambda img: img.convert(L)做灰度化等处理。from diffusers.utils import load_image # 从 URL 加载 img load_image(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/pipeline.png) # 从本地路径加载 img load_image(./my_input.png) # 自定义转换转为灰度图 img_gray load_image(./my_input.png, convert_methodlambda im: im.convert(L))2.2 load_video将视频统一读取为帧序列load_video用于把视频文件或视频 URL 加载为list[PIL.Image.Image]帧序列其签名位于 loading_utils.pydef load_video( video: str, convert_method: Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]] | None None, return_fps: bool False, ) - list[PIL.Image.Image] | tuple[list[PIL.Image.Image], float]:要点说明支持 .gif 与常规视频mp4/webm 等两种格式GIF直接迭代PIL.Image的各帧若 GIF 头信息含duration字段则换算帧率fps 1000 / duration其他格式需要imageioimageio-ffmpeg否则抛ImportError提示安装命令通过imageio.get_reader(video)逐帧读取帧率从reader.get_meta_data()[fps]获取URL 处理先流式下载到临时文件按 URL 后缀判断扩展名缺省.mp4读取完成后自动删除临时文件return_fps 参数当视频生成类 pipeline 需要将输入重采样到模型自身的帧率时如 LTX、CogVideoX 等视频扩散模型必须开启此参数同时拿到帧率因为仅凭帧列表无法推断帧率若视频无法读取到帧率而你又要求返回它会抛ValueError同样默认将所有帧转换为 RGB并支持convert_method自定义批量转换。from diffusers.utils import load_video frames load_video(./input.mp4) # 仅帧序列 frames, fps load_video(./input.mp4, return_fpsTrue) # 帧序列 帧率2.3 底层依赖的后端检查机制从源码可以看到load_video与export_to_video都通过is_imageio_available()定义于 import_utils.py检测后端是否安装并利用BACKENDS_MAPPING[imageio]中的安装提示生成异常信息。如果只是做文生图完全不需要安装这些视频后端只有用到视频 pipeline 时才需要pip install imageio imageio-ffmpeg三、结果导出PIL ↔ NumPy ↔ Torch 转换与媒体保存3.1 numpy_to_pil 与 pt_to_pil张量/数组 → PIL 图像这两个函数定义在 pil_utils.py用于把模型的数值输出转换为可直接保存/展示的 PIL 图像列表numpy_to_pil(images)接收 NumPy 数组。若为 3 维H, W, C会自动补为 4 维 batch数值乘 255 后round().astype(uint8)当通道数为 1 时按灰度模式modeL处理对每个图image.squeeze()否则直接Image.fromarray。注意输入应位于 [0, 1] 区间pt_to_pil(images)接收 Torch 张量。先做反归一化(images / 2 0.5).clamp(0, 1)即假定输入在 [-1, 1] 区间这是 Diffusers 大部分 pipeline 的内部数据范围再cpu().permute(0, 2, 3, 1)转成 NHWC最后复用numpy_to_pil完成转换。import torch from diffusers.utils import numpy_to_pil, pt_to_pil # pipeline 默认 output_typepil也可手动转换 # latents 形状 [B, C, H, W]取值约在 [-1, 1] pil_images pt_to_pil(latents) # 或对 [0, 1] 区间的 numpy 数组 [B, H, W, C] pil_images numpy_to_pil(np_images)3.2 make_image_grid一键拼接对比图make_image_grid(images, rows, cols, resizeNone)实现于 pil_utils.py用于可视化将rows * cols张 PIL 图拼成一张大图如展示同一提示词下多步去噪的中间结果、或多 seed 对比。核心逻辑断言len(images) rows * cols不满足会直接报错可选resize统一把每张图resize((resize, resize))支持正方形缩放到相同尺寸创建cols * w × rows * h的 RGB 画布按box(i % cols * w, i // cols * h)依次粘贴。from diffusers.utils import load_image, make_image_grid imgs [load_image(fhttps://example.com/{i}.png) for i in range(4)] grid make_image_grid(imgs, rows2, cols2, resize512) grid.save(comparison_grid.png)3.3 export_to_gif帧序列 → 动图export_to_gif(image, output_gif_pathNone, fps10)位于 export_utils.py把帧列表写成 GIFoutput_gif_path为空时写入临时文件并返回其路径通过image[0].save(save_allTrue, append_imagesimage[1:], duration1000 // fps, loop0)实现loop0表示无限循环播放fps默认 10即每帧展示 100ms。from diffusers.utils import export_to_gif, load_video frames load_video(./input.mp4) gif_path export_to_gif(frames, output_gif_path./output.gif, fps8)3.4 export_to_video帧序列 → MP4export_to_videoexport_utils.py是视频生成的标配导出函数支持list[np.ndarray][0,1] 浮点或list[PIL.Image.Image]两种输入参数远比export_to_gif丰富def 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, ) - str:参数详解来自源码 docstringquality输出画质默认 5.0取值范围 01010 最高使用可变比特率设为None则不给 FFmpeg 传 VBR 标志便于用output_params手工指定编码参数一旦指定了bitrate本参数失效bitrate恒定比特率默认None即走quality的 VBR 路线。源码建议追求更高质量 更小体积应优先使用quality可变比特率而非固定bitratemacro_block_size宏块对齐约束默认 16。宽高必须能被该值整除否则 imageio 会通知 ffmpeg 放大到最近的兼容尺寸多数编码器支持 16部分支持 4/8设为None或1可禁用自动缩放但许多播放器无法解码奇数尺寸视频且部分编码器会失败或画质劣化后端策略优先使用imageioimageio-ffmpeg若环境缺少这两个库会打印 warning 并回退到基于 OpenCV 的_legacy_export_to_videoexport_utils.py使用mp4vfourcc且该回退路径将在未来版本中被移除。from diffusers.utils import export_to_video video_frames [frame for frame in pil_frames] # 或 np 数组列表 path export_to_video(video_frames, output_video_path./out.mp4, fps16, quality8)3.5 encode_video带音频的高保真视频编码基于 PyAVencode_videoexport_utils.py是比export_to_video更底层的编码器源自 LTX-2 仓库的媒体 IO 工具支持同时混入音频轨适合音视频联合生成的模型如 LTX-2 的视频音频管线。依赖pip install avPyAV否则抛ImportError。def 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, ) - None:输入与行为要点输入兼容三种形态PIL 帧列表假定 RGBnp.ndarray若值域在 [0,1] 则自动*255取整否则按 [0,255] 像素值直接使用并打 warningtorch.Tensor形状[frames, height, width, channels]像素值 [0,255]video_chunks_number沿帧维度用torch.tensor_split分成多块分别编码块数通常对应视频 VAE 的 tiling 配置用于降低单次编码内存用tqdm显示每块进度编码配置视频流使用libx264、yuv420p像素格式音频流使用 AAC_prepare_audio_stream中设为 stereo 布局音频张量形状[channels, samples]需双声道float 输入会被 clip 到 [-1,1] 后转 int16并由AudioResampler重采样到编码器格式提供audio时必须同时给出audio_sample_rate否则抛ValueError。from diffusers.utils import encode_video # video_tensor: [frames, H, W, 3]像素值 [0, 255] encode_video( videovideo_tensor, fps24, output_path./movie.mp4, audioaudio_waveform, # [2, samples] 或 [samples] audio_sample_rate16000, video_chunks_number4, )四、randn_tensor可复现、设备感知的噪声张量生成randn_tensor是 Diffusers 推理链路中生成初始潜变量latent噪声的标准工具实现于 torch_utils.py几乎所有基于随机采样的 pipelineStable Diffusion、Flux、视频模型等内部都用它初始化latentsdef 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, ):关键行为批量 seed传入list[torch.Generator]时可为 batch 中每个样本独立设置随机种子——源码将 shape 改为(1,) shape[1:]逐样本torch.randn后再torch.cat这是实现同一批次不同样本分别可复现的标准手法长度为 1 的列表会被降级为单个 generator设备策略张量默认在device上创建若 generator 是 CPU 生成器而目标设备非 CPU则先在 CPU 生成再搬运并打印提示日志若 generator 是 CUDA 而目标是其他设备直接抛ValueErrorNeuronneuron设备强制在 CPU 生成默认行为deviceNone时落到 CPUlayoutNone时使用torch.strided返回结果已.to(device)可直接作为 pipeline 的latents参数传入实现确定性的可复现采样。import torch from diffusers.utils import randn_tensor # 单个 generator整批可复现 g torch.Generator(devicecuda).manual_seed(0) latents randn_tensor((2, 4, 64, 64), generatorg, devicecuda, dtypetorch.float16) # 列表 generatorbatch 内逐样本独立 seed gens [torch.Generator(devicecuda).manual_seed(i) for i in range(2)] latents randn_tensor((2, 4, 64, 64), generatorgens, devicecuda, dtypetorch.float16) # 与 pipeline 配合固定噪声实现完全可复现 pipe(prompt, latentslatents, generatorg)五、显存优化 Hookapply_layerwise_casting 与 apply_group_offloadingUtilities 文档末尾收录了两个来自 src/diffusers/hooks 的显存优化工具通过 hooks/init.py 导出为diffusers.hooks模块成员它们让超大扩散模型如 CogVideoX、LTX 等在有限显存上运行成为可能。5.1 apply_layerwise_casting存储/计算精度分离apply_layerwise_casting(module, storage_dtype, compute_dtype, ...)实现于 layerwise_casting.py原理是给模型的叶子层挂上LayerwiseCastingHook前向计算时用高精度compute_dtype前向之外用低精度storage_dtype存储——典型组合是storage_dtypetorch.float8_e4m3fnFP8 省显存compute_dtypetorch.bfloat16计算精度。函数签名def apply_layerwise_casting( module: torch.nn.Module, storage_dtype: torch.dtype, compute_dtype: torch.dtype, skip_modules_pattern: str | tuple[str, ...] auto, skip_modules_classes: tuple[Type[torch.nn.Module], ...] | None None, non_blocking: bool False, ) - None:参数与源码细节skip_modules_pattern按正则匹配模块名并跳过默认auto时使用 layerwise_casting.py 的DEFAULT_SKIP_MODULES_PATTERN (pos_embed, patch_embed, norm, ^proj_in$, ^proj_out$)——即嵌入层、Norm 层与投影层保持高精度避免精度敏感层被降精度设None则跳过所有匹配配合skip_modules_classesNone时直接把 hook 挂到模块本身而非其子模块skip_modules_classes按模块类跳过如nn.LayerNorm类遍历策略_apply_layerwise_casting递归named_children()只对_GO_LC_SUPPORTED_PYTORCH_LAYERS白名单内的 PyTorch 层线性、卷积、多头注意力等定义于 hooks/_common.py挂载 hook处理完成后调用_disable_peft_input_autocast(module)避免 PEFT 层的输入自动精度转换与 casting 冲突注意源码 docstring 特别提示当 LoRA 层同时参与时若存储 FP8、计算 BF16PEFT 线性层会把输入也压到 FP8 再回升属于有损操作、会降低生成质量使用 LoRA 时要权衡。import torch from diffusers import CogVideoXTransformer3DModel from diffusers.hooks import apply_layerwise_casting transformer CogVideoXTransformer3DModel.from_pretrained( THUDM/CogVideoX-5b, subfoldertransformer, torch_dtypetorch.bfloat16 ) apply_layerwise_casting( transformer, storage_dtypetorch.float8_e4m3fn, compute_dtypetorch.bfloat16, skip_modules_pattern[patch_embed, norm, proj_out], non_blockingTrue, )5.2 apply_group_offloading模块级与叶子级卸载之间的中间地带apply_group_offloadinggroup_offloading.py按组为单位卸载内部层torch.nn.ModuleList/torch.nn.Sequential从源码 docstring 可清晰对比三种卸载策略策略对应 API显存速度模块级卸载enable_model_cpu_offload()较高需模型运行时精度大小 最大中间激活快叶子级卸载enable_sequential_cpu_offload()最低慢同步次数过多组级卸载apply_group_offloading介于两者之间介于两者之间同步次数少于叶子级函数签名与参数def apply_group_offloading( module: torch.nn.Module, onload_device: str | torch.device, offload_device: str | torch.device torch.device(cpu), offload_type: str | 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, ) - None:参数要点onload_device / offload_device计算设备与存储设备后者默认 CPUoffload_to_disk_path可进一步把参数卸载到磁盘目录适合内存RAM也紧张的环境offload_type枚举GroupOffloadingTypegroup_offloading.py取值block_level或leaf_levelblock_level时必须通过num_blocks_per_group指定每组块数use_stream / record_stream / low_cpu_mem_usageCUDA或 Intel XPU上启用异步流后可通过层预取下一层开始 onload 时当前层仍在计算重叠数据传输与计算显著缩短总耗时但显存占用略增record_streamTrue记录张量被流使用更快但更占内存low_cpu_mem_usageTrue在流式 CPU 卸载时改为即时 pin 内存以压低 CPU 内存峰值但可能抵消流的收益use_streamTrue时若无 CUDA/XPU 会抛错block_modules手工指定哪些模块按块处理缺省用默认块检测逻辑exclude_kwargs跳过send_to_device处理的 kwargs 键如跨前向保持对象身份的可变缓存列表缺省从模块的_skip_keys推断。import torch from diffusers import CogVideoXTransformer3DModel from diffusers.hooks import apply_group_offloading transformer CogVideoXTransformer3DModel.from_pretrained( THUDM/CogVideoX-5b, subfoldertransformer, torch_dtypetorch.bfloat16 ) apply_group_offloading( transformer, onload_devicetorch.device(cuda), offload_devicetorch.device(cpu), offload_typeblock_level, num_blocks_per_group2, use_streamTrue, )从源码结构看该实现还提供了GroupOffloadingConfig、ModuleGroup等内部组件group_offloading.py用于描述卸载配置与按组管理参数生命周期并配套tests/hooks/test_group_offloading.py、tests/hooks/test_hooks.py等测试用例覆盖其正确性。六、实战串联一个完整的图像/视频生成脚本骨架将上述工具组合起来即可写出从加载到导出的完整脚本import torch from diffusers import AutoPipelineForText2Image from diffusers.utils import load_image, make_image_grid, export_to_gif # 1) 加载参考图图生图/ControlNet 场景 init_img load_image(https://example.com/input.png) # 2) 文生图 pipe AutoPipelineForText2Image.from_pretrained( stable-diffusion-xl-base-1.0, torch_dtypetorch.float16, variantfp16 ).to(cuda) g torch.Generator(devicecuda).manual_seed(42) imgs pipe([prompt] * 4, num_inference_steps30, generatorg).images # 3) 拼接对比图并保存 make_image_grid(imgs, rows2, cols2, resize512).save(grid.png) # 4) 视频生成场景帧序列导出 # video_frames pipe_video(...).frames[0] # list[PIL.Image] # export_to_gif(video_frames, out.gif, fps8) # export_to_video(video_frames, out.mp4, fps16, quality8)七、小结与进一步阅读本文系统梳理了 docs/source/en/api/utilities.md 定义的 11 个工具函数/APInumpy_to_pil、pt_to_pil、load_image、load_video、export_to_gif、export_to_video、encode_video、make_image_grid、randn_tensor、apply_layerwise_casting、apply_group_offloading。它们分别覆盖「媒体输入加载」「结果可视化与导出」「可复现噪声生成」「大模型显存优化」四个维度构成 Diffusers 推理脚本的公共基础设施。源码入口src/diffusers/utils含 pil_utils.py、loading_utils.py、export_utils.py、torch_utils.pyHook 实现src/diffusers/hooks/layerwise_casting.py、src/diffusers/hooks/group_offloading.py相关测试tests/hooks/test_hooks.py、tests/hooks/test_group_offloading.py、tests/hooks/test_mag_cache.py。在实际使用中请留意视频类工具需要imageio/imageio-ffmpeg/av等可选依赖export_to_video的 OpenCV 回退路径即将被移除apply_layerwise_casting与 PEFT LoRA 叠加时存在精度有损风险apply_group_offloading的block_level模式必须显式指定num_blocks_per_group。掌握这些细节后你便可以在各类生成任务中稳定、高效、可复现地完成全流程开发。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考