diffusers/v0.43.0/zh/api/modular_diffusers/pipeline.md

Pipeline

ModularPipeline[[diffusers.ModularPipeline]]

diffusers.ModularPipeline[[diffusers.ModularPipeline]]

diffusers.ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)

源代码

参数：

blocks : ModularPipelineBlocks，流水线中要使用的块

所有 Modular 管线的基类。

from_pretrained[[diffusers.ModularPipeline.from_pretrained]]

from_pretrained(pretrained_model_name_or_path: str | os.PathLike | None, trust_remote_code: bool | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, **kwargs)

源代码

参数：

pretrained_model_name_or_path (str 或 os.PathLike，可选)：预训练 pipeline 配置的路径。它会首先尝试从 modular_model_index.json 加载配置，然后回退到 model_index.json，以兼容标准的非模块化仓库。如果 pretrained_model_name_or_path 中不包含任何 pipeline 配置，则在初始化时会将其设置为 None。

trust_remote_code (bool, 可选) : 加载 pipeline 时是否信任远程代码。如果希望基于 pretrained_model_name_or_path 中的自定义代码创建 pipeline 块，则需将其设置为 True

components_manager (ComponentsManager，可选)：用于管理跨不同流水线的多个组件并应用卸载策略的 ComponentsManager 实例。

collection (str, 可选) -- 用于在 ComponentsManager 中组织组件的集合名称。

workflow (str, 可选) : 由 pipeline 块声明的工作流名称。如果提供此参数，块将被修剪为该工作流的执行块，因此 pipeline 仅期望 — 且 load_components() 仅加载 — 该工作流所使用的组件。

从 huggingface hub 仓库加载 ModularPipeline。

get_component_spec[[diffusers.ModularPipeline.get_component_spec]]

get_component_spec(name: str)

源代码

返回值：

• 给定组件名称的 ComponentSpec 对象的副本

load_components[[diffusers.ModularPipeline.load_components]]

load_components(names: list[str] | str | None = None, workflow: str | None = None, **kwargs)

源代码

参数：

names : list of component names to load. If None, will load all components with default_creation_method == "from_pretrained". If provided as a list or string, will load only the specified components.

workflow : 由 pipeline 块声明的工作流名称。如果提供此参数，则仅加载该工作流的执行块所使用的组件。不能与 names 同时使用。

• **kwargs : 传递给 from_pretrained() 的额外参数。可以是：- 一个应用于所有待加载组件的单一值，例如 dtype=torch.bfloat16 - 一个字典，例如 dtype={"unet": torch.bfloat16, "default": torch.float32} - 如果通过 kwargs 传入了不同的加载字段，则可能会覆盖 ComponentSpec，例如 pretrained_model_name_or_path、variant、revision 等。 - 如果通过 kwargs 传入了不同的加载字段，则可能会覆盖 ComponentSpec，例如 pretrained_model_name_or_path、variant、revision 等。

从规范中加载所选组件。

register_components[[diffusers.ModularPipeline.register_components]]

register_components(**kwargs)

源代码

参数：

• **kwargs : 关键字参数，其中键为组件名称，值为组件对象。例如，register_components(unet=unet_model, text_encoder=encoder_model)

将其对应的规范注册到组件中。

此方法负责：

1. 将组件对象设置为加载器的属性（例如，self.unet = unet）
2. 更新配置字典，该字典将在 save_pretrained 期间保存为 modular_model_index.json（仅针对 from_pretrained 组件）
3. 如果已附加组件管理器，则向其中添加组件（仅适用于 from_pretrained 组件）

此方法在以下情况下被调用：

• 组件首先在 init 中初始化：
  • 在 init 期间未加载的 from_pretrained 组件会被注册为 None；
  • 非 from_pretrained 组件在 init 期间创建，并作为对象本身进行注册
• 组件通过 update_components() 方法进行更新：例如 loader.update_components(unet=unet) 或 loader.update_components(guider=guider_spec)
• (from_pretrained) 组件通过 load_components() 方法加载：例如，使用 loader.load_components(names=["unet"]) 或 loader.load_components() 来加载所有默认组件

注意事项：

• 当为组件注册 None 时，会将属性设置为 None，但仍会与配置字典同步规格，该字典将在 save_pretrained 期间保存为 modular_model_index.json
• component_specs 会在此方法之外更新以匹配新的组件，例如在 update_components() 方法中

save_pretrained[[diffusers.ModularPipeline.save_pretrained]]

save_pretrained(save_directory: str | os.PathLike, safe_serialization: bool = True, variant: str | None = None, max_shard_size: int | str | None = None, push_to_hub: bool = False, **kwargs)

源代码

参数：

save_directory (str 或 os.PathLike)：用于保存 pipeline 的目录。如果该目录不存在，将会自动创建。

safe_serialization (bool，可选，默认为 True)：是否使用 safetensors 保存模型，还是使用传统的 PyTorch 方式（通过 pickle）。

variant (str, 可选) : 如果指定，权重将以 pytorch_model.<variant>.bin 格式保存。

max_shard_size (int 或 str，默认为 None)：检查点在分片前的最大大小。分片后的每个检查点大小都将小于该值。如果以字符串形式表示，需要是数字后跟单位（例如 "5GB"）。如果以整数形式表示，单位为字节。

push_to_hub (bool，可选，默认为 False)：是否在保存后将流水线推送到 Hugging Face 模型库。

• kwargs : 其他关键字参数： - overwrite_modular_index (bool，可选，默认为 True)：是否更新 modular_model_index.json，使每个已保存组件的加载规范指向目标位置：推送到 Hub 时为 repo_id，否则为 save_directory。未加载的组件不会被保存，并且始终保留其记录的加载规范。传入 False 可保留正在保存的组件的记录规范（例如，对于有意引用其他仓库的索引）；没有加载 ID 的组件（例如使用 update_components 添加的自定义模型）仍会被重写，因为它们没有记录的来源。 - repo_id (str，可选)：要推送流水线到的仓库 ID。默认为 save_directory 的最后一个组件。 - commit_message (str，可选)：推送到 Hub 操作的提交信息。 - private (bool，可选)：仓库是否应为私有。 - create_pr (bool，可选，默认为 False)：是否创建拉取请求而不是直接推送。 - token (str，可选)：用于身份验证的 Hugging Face 令牌。

将 pipeline 及其所有组件保存到目录中，以便之后可以使用 from_pretrained() 类方法重新加载。

到[[diffusers.ModularPipeline.to]]

to(*args, **kwargs)

源代码

参数：

dtype (torch.dtype，可选)：返回一个使用指定 dtype 的 pipeline

device (torch.Device, 可选) : 返回一个使用指定 device 的 pipeline

silence_dtype_warnings (str，可选，默认为 False)：如果目标 dtype 与目标 device 不兼容，是否省略警告。

返回： DiffusionPipeline

Pipeline 已转换为指定的 dtype 和/或 dtype。

执行 Pipeline 的 dtype 和/或 device 转换。torch.dtype 和 torch.device 是从 self.to(*args, **kwargs). 的参数中推断出来的。

> 如果 pipeline 已经具有正确的 torch.dtype 和 torch.device，则会直接返回。 否则，返回的 pipeline 是 self 的副本，具有所需的 torch.dtype 和 torch.device。

以下是调用 to 的方式：

• to(dtype, silence_dtype_warnings=False) → DiffusionPipeline 返回一个具有指定 dtype 的 pipeline
• to(device, silence_dtype_warnings=False) → DiffusionPipeline 用于返回一个使用指定 device 的 pipeline
• to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline 返回一个具有指定 device 和 dtype 的 pipeline

unload_components[[diffusers.ModularPipeline.unload_components]]

unload_components(names: list[str] | str)

源代码

参数：

names : 要卸载的组件名称或组件名称列表。

卸载选定的组件，释放其内存。

component 属性被重置为 None，如果已附加 ComponentsManager，则组件将从其中移除。组件规范保持不变，因此之后可以使用 load_components() 再次加载该组件。

update_components[[diffusers.ModularPipeline.update_components]]

update_components(**kwargs)

源代码

参数：

• **kwargs : 要更新的组件对象或配置值： - 组件对象：使用 AutoModel.from_pretrained() 或 ComponentSpec.load() 加载的模型会自动标记加载信息。没有权重的 ConfigMixin 对象（例如调度器、引导器）可以直接传入。 - 配置值：用于更新配置设置的简单值（例如 requires_safety_checker=False）

在流水线实例化之后，更新组件以及配置值和规格。

此方法允许您：

1. 用新的组件替换现有组件（例如，更新 self.unet 或 self.text_encoder）
2. 更新配置值（例如，更改 self.requires_safety_checker 标志）

除了将组件和配置值作为流水线属性进行更新外，该方法还会更新以下内容：

• _component_specs 和 _config_specs 中对应的规格
• config 字典，将在调用 save_pretrained 时保存为 modular_model_index.json

示例：

# Update pre-trained model
pipeline.update_components(unet=new_unet_model, text_encoder=new_text_encoder)

# Update configuration values
pipeline.update_components(requires_safety_checker=False)

注意事项：

• 使用 AutoModel.from_pretrained() 或 ComponentSpec.load() 加载的组件将 加载时保留的规格信息用于序列化。没有 Hub 引用的自定义或本地加载的组件，其 modular_model_index.json 条目会在 save_pretrained() 期间自动更新。
• 没有权重的 ConfigMixin 对象（例如调度器、引导器）可以直接传入。