Hugging Face's logo

Diffusers documentation

组件和配置

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

组件和配置

ComponentSpec

class diffusers.ComponentSpec

< >

( name: str | None = Nonetype_hint: typing.Optional[typing.Type] = Nonedescription: str | None = Noneconfig: diffusers.configuration_utils.FrozenDict | None = Nonepretrained_model_name_or_path: str | list[str] | None = Nonesubfolder: str | None = ''variant: str | None = Nonerevision: str | None = Nonedefault_creation_method: typing.Literal['from_config', 'from_pretrained'] = 'from_pretrained'repo: str | list[str] | None = None )

参数

  • name — 组件的名称
  • type_hint — 组件的类型（例如 UNet2DConditionModel）
  • description — 组件的可选描述
  • config — 用于 init 创建的可选配置字典
  • pretrained_model_name_or_path — 用于 from_pretrained 创建时可选的 pretrained_model_name_or_path 路径
  • subfolder — pretrained_model_name_or_path 中的可选子文件夹
  • variant — 预训练模型名称或路径中的可选变体
  • revision — 在 pretrained_model_name_or_path 中指定的可选版本
  • default_creation_method — 首选创建方式 - “from_config” 或 “from_pretrained”

流水线组件的规范。

组件可以通过两种方式创建：

  1. 使用配置字典通过 init 从头开始
  2. 使用 from_pretrained

创建

< >

( config: diffusers.configuration_utils.FrozenDict | dict[str, typing.Any] | None = None**kwargs )

使用 from_config 和 config 创建组件。

decode_load_id

< >

( load_id: str )

参数

  • load_id — 要解码的 load_id 字符串，格式为：“pretrained_model_name_or_path|subfolder|variant|revision” 其中 None 值表示为 “null”

将 load_id 字符串解码为包含加载字段及其值的字典。

from_component

< >

( name: strcomponent: Any )

参数

  • name — 组件的名称
  • component — 用于创建 spec 的组件对象

引发

ValueError

  • ValueError — 如果组件不受支持（例如没有 load_id 的 nn.Module，非 ConfigMixin）

从 Component 创建 ComponentSpec。

目前支持：

  • 使用 ComponentSpec.load() 方法创建的组件
  • ConfigMixin 的子类，但不是 nn.Module（例如调度器、引导器）

加载

< >

( **kwargs )

使用 from_pretrained 加载组件。

加载字段

< >

( )

返回所有加载相关字段的名称（即那些 field.metadata["loading"] 为 True 的字段）。

ConfigSpec

class diffusers.ConfigSpec

< >

( name: strdefault: Anydescription: str | None = None )

流水线配置参数的规范。

ComponentsManager

class diffusers.ComponentsManager

< >

( )

一个用于跨多个流水线管理模型组件的中心注册和管理系统。

ComponentsManager 提供了一种统一的方式，用于在不同的模块化流水线中注册、跟踪和复用模型组件（例如 UNet、VAE、文本编码器等）。它包含重复检测、内存管理和组件组织等功能。

> 这是一个实验性功能，未来可能会发生变化。

示例：

from diffusers import ComponentsManager

# Create a components manager
cm = ComponentsManager()

# Add components
cm.add("unet", unet_model, collection="sdxl")
cm.add("vae", vae_model, collection="sdxl")

# Enable auto offloading
cm.enable_auto_cpu_offload()

# Retrieve components
unet = cm.get_one(name="unet", collection="sdxl")

添加

< >

( name: strcomponent: Anycollection: str | None = None ) → str

参数

  • name (str) — 组件的名称
  • component (Any) — 要添加的组件
  • collection (str | None) — 要添加该组件的集合

返回值

str

唯一的组件 ID，其生成格式为“{name}_{id(component)}”，其中 id(component) 是 Python 内置的对象唯一标识符

向 ComponentsManager 添加一个组件。

disable_auto_cpu_offload

< >

( )

禁用所有组件的自动 CPU 卸载。

enable_auto_cpu_offload

< >

( device: str | int | torch.device = Nonememory_reserve_margin = '3GB'offload_strategy = None )

参数

  • device (str | int | torch.device) — 用于前向传播的模型执行设备
  • memory_reserve_margin (str) — 要使用的内存预留余量，默认为 3GB。这是设备上需要保持空闲的内存量，以避免在模型执行期间（例如用于中间激活值、梯度等）出现内存不足的情况。
  • offload_strategy — 任何具有签名 (hooks, model_id, model, execution_device) -> hooks 的可调用对象， 用于返回在加载即将进入的模型之前需要卸载的驻留模型。默认为 AutoOffloadStrategy，它会释放最小的足够组合。

为所有组件启用自动 CPU 卸载。

该算法的工作流程如下：

  1. 所有模型默认从 CPU 开始
  2. 当模型的 forward pass 被调用时，它会被移动到执行设备
  3. 如果内存不足，设备上的其他模型会被移回 CPU
  4. 系统会尝试卸载能够释放足够内存的最小模型组合
  5. 模型会一直保留在执行设备上，直到另一个模型需要内存并迫使它们被移出

参与此过程的组卸载模型会自行安排位置：它可以通过将其他模型移开来腾出空间，但自身永远不会被移开以为其他模型腾出空间。两种顺序均可——先进行组卸载，或先启用此功能。AutoOffloadStrategy 根据模型的内存占用大小来做出决策，而这些占用数据并不反映模型一次只持有一个组的情况，因此请传入一个offload_strategy，使其基于工作流来做出决策。

get_components_by_ids

< >

( ids: list[str]return_dict_with_names: bool | None = True ) → dict[str, Any]

参数

  • ids (list[str]) — 组件 ID 列表
  • return_dict_with_names (bool | None) — 是否返回一个以组件名称作为键的字典：

返回值

dict[str, Any]

组件字典。

  • 如果 return_dict_with_names=True，则键为组件名称。
  • If return_dict_with_names=False, keys are component IDs.

引发

ValueError

  • ValueError — 当 return_dict_with_names=True 时，如果在搜索结果中发现重复的组件名称

通过 ID 列表获取组件。

get_components_by_names

< >

( names: list[str]collection: str | None = None ) → dict[str, Any]

参数

  • names (list[str]) — 组件名称列表
  • collection (str | None) — 可选的用于过滤的集合

返回值

dict[str, Any]

以组件名称为键的组件字典

引发

ValueError

  • ValueError — 如果在搜索结果中发现重复的组件名称

通过名称列表获取组件，可选按集合进行筛选。

get_ids

< >

( names: str | list[str] = Nonecollection: str | None = None ) → list[str]

参数

  • names（str | list[str]）— 组件名称列表
  • collection (str | None) — 可选的用于过滤的集合

返回值

list[str]

组件 ID 列表

通过名称列表获取组件 ID，可选择按集合进行筛选。

get_model_info

< >

( component_id: strfields: str | list[str] | None = None )

参数

  • component_id (str) — 要获取信息的组件名称
  • fields (str | list[str] | None) — 要返回的字段。可以是表示单个字段的字符串，也可以是字段列表。如果为 None，则使用 available_info_fields 设置。

获取组件的详细信息。

get_one

< >

( component_id: str | None = Nonename: str | None = Nonecollection: str | None = Noneload_id: str | None = None )

参数

  • component_id (str | None) — 可选的组件 ID，用于获取
  • name (str | None) — 组件名称或模式
  • collection (str | None) — 可选的用于过滤的集合
  • load_id (str | None) — 可选的 load_id，用于进行筛选

引发

ValueError

  • ValueError — 如果没有组件匹配或有多个组件匹配

通过以下任一方式获取单个组件：

  • 搜索名称（模式匹配）、集合或 load_id。
  • 传入 component_id 如果匹配到多个组件或未找到任何组件，则引发错误。

移除

< >

( component_id: str = None )

参数

  • component_id (str) — 要移除的组件的 ID

从 ComponentsManager 中移除一个组件。

remove_from_collection

< >

( component_id: strcollection: str )

从集合中移除一个组件。

search_components

< >

( names: str | None = Nonecollection: str | None = Noneload_id: str | None = Nonereturn_dict_with_names: bool = True )

参数

  • names — 组件名称或模式 模式：
    • “unet”：匹配任何基础名称为“unet”的组件（例如，unet_123abc）
    • “!unet”：除基础名称为 “unet” 的组件外的所有内容
    • “unet*”：所有以“unet”开头的基础名称
    • “!unet*”：基础名称不以“unet”开头的任何内容
    • ”unet”：任何基础名称中包含 “unet” 的内容
    • “!unet”：任何基础名称中不包含“unet”的内容
    • “refiner|vae|unet”：任何基础名称与“refiner”、“vae”或“unet”完全匹配的内容
    • “!refiner|vae|unet”：基础名称并非完全匹配 “refiner”、“vae” 或 “unet” 的任意内容
    • “unet|vae”：任何基础名称以“unet”开头或以“vae”开头的文件
  • collection — 可选的用于过滤的集合
  • load_id — 可选的 load_id，用于进行筛选
  • return_dict_with_names — 如果为 True，则返回一个以组件名称为键的字典；如果发现多个同名组件，则抛出错误。如果为 False，则返回一个以组件 ID 为键的字典

通过简单的模式匹配按名称搜索组件。可选地按 collection 或 load_id 进行筛选。

set_offload_strategy

< >

( offload_strategy )

参数

  • offload_strategy — 任何具有 (hooks, model_id, model, execution_device) -> hooks 签名的可调用对象：它接收当前位于设备上的模型的 hooks，并返回在加载传入模型之前需要卸载的 hooks。默认值为 AutoOffloadStrategy，它会释放最小的充分组合。

替换所有受管理模型上的 offload 策略。仅在启用自动 CPU offload 时有效。

InsertableDict

class diffusers.modular_pipelines.InsertableDict

< >

( )

Update on GitHub

←状态 引导者→