Diffusers 文档
AutoPipeline
并获得增强的文档体验
开始使用
AutoPipeline
AutoPipeline
旨在方便地为任务加载检查点,而无需了解具体的管道类。根据任务,AutoPipeline
会自动从检查点的 model_index.json
文件中检索正确的管道类。
查看AutoPipeline教程以了解如何使用此API!
AutoPipelineForText2Image
AutoPipelineForText2Image 是一个通用管道类,它实例化一个文本到图像的管道类。具体的底层管道类会自动从 from_pretrained() 或 from_pipe() 方法中选择。
该类不能通过 __init__()
实例化(会抛出错误)。
类属性
- config_name (
str
) — 存储所有扩散管道组件的类名和模块名的配置文件名。
from_pretrained
< 来源 >( pretrained_model_or_path **kwargs )
参数
- pretrained_model_or_path (
str
或os.PathLike
, 可选) — 可以是:- 一个字符串,即托管在 Hub 上的预训练管道的 *repo id*(例如
CompVis/ldm-text2im-large-256
)。 - 一个 *目录* 路径(例如
./my_pipeline_directory/
),其中包含使用 save_pretrained() 保存的管道权重。
- 一个字符串,即托管在 Hub 上的预训练管道的 *repo id*(例如
- torch_dtype (
torch.dtype
, 可选) — 覆盖默认的torch.dtype
并使用其他 dtype 加载模型。 - force_download (
bool
, 可选, 默认为False
) — 是否强制(重新)下载模型权重和配置文件,如果存在缓存版本则覆盖。 - cache_dir (
Union[str, os.PathLike]
, 可选) — 存放下载的预训练模型配置的目录路径,如果未使用标准缓存。 - proxies (
Dict[str, str]
, 可选) — 按协议或端点使用的代理服务器字典,例如{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}
。代理用于每个请求。 - output_loading_info(
bool
, 可选, 默认为False
) — 是否同时返回一个包含缺失键、意外键和错误消息的字典。 - local_files_only (
bool
, 可选, 默认为False
) — 是否只加载本地模型权重和配置文件。如果设置为True
,则模型不会从 Hub 下载。 - token (
str
或 bool, 可选) — 用于远程文件的 HTTP Bearer 授权令牌。如果为True
,则使用从diffusers-cli login
生成的令牌(存储在~/.huggingface
中)。 - revision (
str
, 可选, 默认为"main"
) — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。 - custom_revision (
str
, 可选, 默认为"main"
) — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID,与从 Hub 加载自定义管道时的revision
类似。当从 GitHub 加载自定义管道时,它可以是 🤗 Diffusers 版本,否则从 Hub 加载时默认为"main"
。 - mirror (
str
, 可选) — 如果您在中国下载模型,用于解决访问问题的镜像源。我们不保证源的及时性或安全性,您应参考镜像站点获取更多信息。 - device_map (
str
或Dict[str, Union[int, str, torch.device]]
, 可选) — 指定每个子模块应放置在哪里的映射。无需为每个参数/缓冲区名称定义;一旦给定的模块名称在其中,它的每个子模块都将被发送到同一设备。设置
device_map="auto"
以让 🤗 Accelerate 自动计算最优化的device_map
。有关每个选项的更多信息,请参阅 设计设备映射。 - max_memory (
Dict
, 可选) — 最大内存的设备标识符字典。如果未设置,则默认为每个 GPU 的最大可用内存和可用的 CPU RAM。 - offload_folder (
str
或os.PathLike
, 可选) — 如果 device_map 包含值"disk"
,则卸载权重的路径。 - offload_state_dict (
bool
, 可选) — 如果为True
,则暂时将 CPU 状态字典卸载到硬盘驱动器,以避免在 CPU 状态字典的权重 + 检查点的最大分片不适合时耗尽 CPU RAM。如果存在一些磁盘卸载,则默认为True
。 - low_cpu_mem_usage (
bool
, 可选, 如果 torch 版本 >= 1.9.0 则默认为True
,否则为False
) — 通过只加载预训练权重而不初始化权重来加速模型加载。在加载模型时,这也试图不使用超过模型大小 1 倍的 CPU 内存(包括峰值内存)。仅支持 PyTorch >= 1.9.0。如果您使用的是旧版 PyTorch,将此参数设置为True
将引发错误。 - use_safetensors (
bool
, 可选, 默认为None
) — 如果设置为None
,则如果 safetensors 库已安装且可用,则下载 safetensors 权重。如果设置为True
,则强制从 safetensors 权重加载模型。如果设置为False
,则不加载 safetensors 权重。 - kwargs (剩余的关键字参数字典,可选) — 可用于覆盖可加载和可保存的变量(特定管道类的管道组件)。被覆盖的组件直接传递给管道的
__init__
方法。有关更多信息,请参阅以下示例。 - variant (
str
, 可选) — 从指定的变体文件名(如"fp16"
或"ema"
)加载权重。从from_flax
加载时会忽略此参数。
从预训练的管道权重实例化文本到图像的 PyTorch 扩散管道。
from_pretrained() 方法通过以下方式返回正确的管道类实例:
- 根据其配置对象的 _class_name 属性检测 pretrained_model_or_path 的管道类
- 使用管道类名上的模式匹配查找与管道类关联的文本到图像管道。
如果传入 controlnet
参数,它将实例化一个 StableDiffusionControlNetPipeline 对象。
默认情况下,管道设置为评估模式(model.eval()
)。
如果您收到以下错误消息,则需要针对您的下游任务微调权重
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
要使用私有或封闭模型,请使用 huggingface-cli login
登录。
from_pipe
< 来源 >( pipeline **kwargs )
从另一个已实例化的扩散管道类实例化文本到图像的 PyTorch 扩散管道。
from_pipe() 方法通过使用管道类名上的模式匹配查找与管道类关联的文本到图像管道,从而返回正确的管道类实例。
管道包含的所有模块都将用于初始化新管道,而无需重新分配额外的内存。
默认情况下,管道设置为评估模式(model.eval()
)。
>>> from diffusers import AutoPipelineForText2Image, AutoPipelineForImage2Image
>>> pipe_i2i = AutoPipelineForImage2Image.from_pretrained(
... "stable-diffusion-v1-5/stable-diffusion-v1-5", requires_safety_checker=False
... )
>>> pipe_t2i = AutoPipelineForText2Image.from_pipe(pipe_i2i)
>>> image = pipe_t2i(prompt).images[0]
AutoPipelineForImage2Image
AutoPipelineForImage2Image 是一个通用管道类,它实例化一个图像到图像的管道类。具体的底层管道类会自动从 from_pretrained() 或 from_pipe() 方法中选择。
该类不能通过 __init__()
实例化(会抛出错误)。
类属性
- config_name (
str
) — 存储所有扩散管道组件的类名和模块名的配置文件名。
from_pretrained
< 来源 >( pretrained_model_or_path **kwargs )
参数
- pretrained_model_or_path (
str
或os.PathLike
, 可选) — 可以是以下之一:- 一个字符串,即托管在 Hub 上的预训练管道的 *repo id* (例如
CompVis/ldm-text2im-large-256
)。 - 一个 *目录* 的路径 (例如
./my_pipeline_directory/
),包含使用 save_pretrained() 保存的管道权重。
- 一个字符串,即托管在 Hub 上的预训练管道的 *repo id* (例如
- torch_dtype (
str
或torch.dtype
, 可选) — 覆盖默认的torch.dtype
,并用另一种 dtype 加载模型。 - force_download (
bool
, 可选, 默认为False
) — 是否强制(重新)下载模型权重和配置文件,覆盖已存在的缓存版本。 - cache_dir (
Union[str, os.PathLike]
, 可选) — 如果不使用标准缓存,则为下载的预训练模型配置的缓存目录路径。 - proxies (
Dict[str, str]
, 可选) — 要按协议或端点使用的代理服务器字典,例如{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}
。代理用于每个请求。 - output_loading_info(
bool
, 可选, 默认为False
) — 是否同时返回包含缺失键、意外键和错误消息的字典。 - local_files_only (
bool
, 可选, 默认为False
) — 是否只加载本地模型权重和配置文件。如果设置为True
,模型将不会从 Hub 下载。 - token (
str
或 bool, 可选) — 用作远程文件 HTTP 承载授权的令牌。如果为True
,则使用diffusers-cli login
生成的令牌(存储在~/.huggingface
中)。 - revision (
str
, 可选, 默认为"main"
) — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。 - custom_revision (
str
, 可选, 默认为"main"
) — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID,类似于从 Hub 加载自定义管道时的revision
。从 GitHub 加载自定义管道时,它可以是 🤗 Diffusers 版本,否则从 Hub 加载时默认为"main"
。 - mirror (
str
, 可选) — 解决在中国下载模型时的可访问性问题的镜像源。我们不保证该源的时效性或安全性,您应参考镜像站点以获取更多信息。 - device_map (
str
或Dict[str, Union[int, str, torch.device]]
, 可选) — 指定每个子模块应放置在哪里的映射。无需为每个参数/缓冲区名称定义;一旦给定的模块名称在其内部,它的每个子模块都将被发送到同一设备。设置
device_map="auto"
让 🤗 Accelerate 自动计算最优化的device_map
。有关每个选项的更多信息,请参阅 设计设备映射。 - max_memory (
Dict
, 可选) — 最大内存的设备标识符字典。如果未设置,将默认为每个 GPU 的可用最大内存和可用的 CPU RAM。 - offload_folder (
str
或os.PathLike
, 可选) — 如果 device_map 包含值"disk"
,则为卸载权重的路径。 - offload_state_dict (
bool
, 可选) — 如果为True
,则暂时将 CPU 状态字典卸载到硬盘驱动器,以避免在 CPU 状态字典的权重 + 检查点最大分片不适合时,CPU RAM 用尽。当存在一些磁盘卸载时,默认为True
。 - low_cpu_mem_usage (
bool
, 可选, 如果 torch 版本 >= 1.9.0 默认为True
,否则为False
) — 加快模型加载速度,仅加载预训练权重而不初始化权重。这在加载模型时还尝试使 CPU 内存(包括峰值内存)的使用不超过模型大小的 1 倍。仅支持 PyTorch >= 1.9.0。如果您使用的是旧版 PyTorch,将此参数设置为True
将引发错误。 - use_safetensors (
bool
, 可选, 默认为None
) — 如果设置为None
,则在可用 且 已安装 safetensors 库时下载 safetensors 权重。如果设置为True
,则强制从 safetensors 权重加载模型。如果设置为False
,则不加载 safetensors 权重。 - kwargs (剩余的关键字参数字典,可选) — 可用于覆盖可加载和可保存的变量(特定管道类的管道组件)。被覆盖的组件直接传递给管道的
__init__
方法。更多信息请参见以下示例。 - variant (
str
, 可选) — 从指定的变体文件名(如"fp16"
或"ema"
)加载权重。从from_flax
加载时会忽略此项。
从预训练的管道权重实例化图像到图像的 PyTorch 扩散管道。
from_pretrained() 方法通过以下方式返回正确的管道类实例:
- 根据其配置对象的 _class_name 属性检测 pretrained_model_or_path 的管道类
- 通过管道类名称上的模式匹配,查找与管道类关联的图像到图像管道。
如果传入 controlnet
参数,它将实例化一个 StableDiffusionControlNetImg2ImgPipeline 对象。
默认情况下,管道设置为评估模式(model.eval()
)。
如果您收到以下错误消息,则需要针对您的下游任务微调权重
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
要使用私有或封闭模型,请使用 huggingface-cli login
登录。
from_pipe
< source >( pipeline **kwargs )
从另一个已实例化的扩散管道类实例化图像到图像的 PyTorch 扩散管道。
from_pipe()
方法通过对管道类名称进行模式匹配,负责返回与该管道类关联的正确图像到图像管道实例。
管道包含的所有模块都将用于初始化新管道,而无需重新分配额外的内存。
默认情况下,管道设置为评估模式(model.eval()
)。
示例
>>> from diffusers import AutoPipelineForText2Image, AutoPipelineForImage2Image
>>> pipe_t2i = AutoPipelineForText2Image.from_pretrained(
... "stable-diffusion-v1-5/stable-diffusion-v1-5", requires_safety_checker=False
... )
>>> pipe_i2i = AutoPipelineForImage2Image.from_pipe(pipe_t2i)
>>> image = pipe_i2i(prompt, image).images[0]
AutoPipelineForInpainting
AutoPipelineForInpainting 是一个通用管道类,它实例化一个图像修复管道类。具体的底层管道类是根据 from_pretrained() 或 from_pipe() 方法通过自动选择获得的。
该类不能通过 __init__()
实例化(会抛出错误)。
类属性
- config_name (
str
) — 存储所有扩散管道组件的类名和模块名的配置文件名。
from_pretrained
< source >( pretrained_model_or_path **kwargs )
参数
- pretrained_model_or_path (
str
或os.PathLike
, 可选) — 可以是以下之一:- 一个字符串,即托管在 Hub 上的预训练管道的 *repo id* (例如
CompVis/ldm-text2im-large-256
)。 - 一个 *目录* 的路径 (例如
./my_pipeline_directory/
),包含使用 save_pretrained() 保存的管道权重。
- 一个字符串,即托管在 Hub 上的预训练管道的 *repo id* (例如
- torch_dtype (
str
或torch.dtype
, 可选) — 覆盖默认的torch.dtype
,并使用另一种 dtype 加载模型。 - force_download (
bool
, 可选, 默认为False
) — 是否强制(重新)下载模型权重和配置文件,覆盖已存在的缓存版本。 - cache_dir (
Union[str, os.PathLike]
, 可选) — 如果不使用标准缓存,则为下载的预训练模型配置的缓存目录路径。 - proxies (
Dict[str, str]
, 可选) — 要按协议或端点使用的代理服务器字典,例如{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}
。代理用于每个请求。 - output_loading_info(
bool
, 可选, 默认为False
) — 是否同时返回包含缺失键、意外键和错误消息的字典。 - local_files_only (
bool
, 可选, 默认为False
) — 是否只加载本地模型权重和配置文件。如果设置为True
,模型将不会从 Hub 下载。 - token (
str
或 bool, 可选) — 用作远程文件 HTTP 承载授权的令牌。如果为True
,则使用diffusers-cli login
生成的令牌(存储在~/.huggingface
中)。 - revision (
str
, 可选, 默认为"main"
) — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。 - custom_revision (
str
, 可选, 默认为"main"
) — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID,类似于从 Hub 加载自定义管道时的revision
。从 GitHub 加载自定义管道时,它可以是 🤗 Diffusers 版本,否则从 Hub 加载时默认为"main"
。 - mirror (
str
, 可选) — 解决在中国下载模型时的可访问性问题的镜像源。我们不保证该源的时效性或安全性,您应参考镜像站点以获取更多信息。 - device_map (
str
或Dict[str, Union[int, str, torch.device]]
, 可选) — 指定每个子模块应放置在哪里的映射。无需为每个参数/缓冲区名称定义;一旦给定的模块名称在其内部,它的每个子模块都将被发送到同一设备。设置
device_map="auto"
让 🤗 Accelerate 自动计算最优化的device_map
。有关每个选项的更多信息,请参阅 设计设备映射。 - max_memory (
Dict
, 可选) — 最大内存的设备标识符字典。如果未设置,将默认为每个 GPU 的可用最大内存和可用的 CPU RAM。 - offload_folder (
str
或os.PathLike
, 可选) — 如果 device_map 包含值"disk"
,则为卸载权重的路径。 - offload_state_dict (
bool
, 可选) — 如果为True
,则暂时将 CPU 状态字典卸载到硬盘驱动器,以避免在 CPU 状态字典的权重 + 检查点最大分片不适合时,CPU RAM 用尽。当存在一些磁盘卸载时,默认为True
。 - kwargs (剩余的关键字参数字典,可选) — 可用于覆盖可加载和可保存的变量(特定管道类的管道组件)。被覆盖的组件直接传递给管道的
__init__
方法。更多信息请参见以下示例。 - variant (
str
, 可选) — 从指定的变体文件名(如"fp16"
或"ema"
)加载权重。从from_flax
加载时会忽略此项。
从预训练的管道权重实例化图像修复的 PyTorch 扩散管道。
from_pretrained() 方法通过以下方式返回正确的管道类实例:
- 根据其配置对象的 _class_name 属性检测 pretrained_model_or_path 的管道类
- 通过管道类名称上的模式匹配,查找与管道类关联的图像修复管道。
如果传入 controlnet
参数,它将实例化一个 StableDiffusionControlNetInpaintPipeline 对象。
默认情况下,管道设置为评估模式(model.eval()
)。
如果您收到以下错误消息,则需要针对您的下游任务微调权重
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
要使用私有或封闭模型,请使用 huggingface-cli login
登录。
from_pipe
< source > ( pipeline **kwargs )
从另一个已实例化的扩散管道类实例化图像修复的 PyTorch 扩散管道。
from_pipe()
方法通过对管道类名称进行模式匹配,负责返回与该管道类关联的正确图像修复管道实例。
管道类包含的所有模块都将用于初始化新的管道,而无需重新分配额外的内存。
默认情况下,管道设置为评估模式(model.eval()
)。
示例
>>> from diffusers import AutoPipelineForText2Image, AutoPipelineForInpainting
>>> pipe_t2i = AutoPipelineForText2Image.from_pretrained(
... "DeepFloyd/IF-I-XL-v1.0", requires_safety_checker=False
... )
>>> pipe_inpaint = AutoPipelineForInpainting.from_pipe(pipe_t2i)
>>> image = pipe_inpaint(prompt, image=init_image, mask_image=mask_image).images[0]