# Pipeline

## ModularPipeline[[diffusers.ModularPipeline]]

#### diffusers.ModularPipeline[[diffusers.ModularPipeline]]

```python
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)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L1697)

**参数：**

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

所有 Modular 管线的基类。

#### from_pretrained[[diffusers.ModularPipeline.from_pretrained]]

```python
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)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L1922)

**参数：**

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]]

```python
get_component_spec(name: str)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2408)

**返回值：**

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

#### load_components[[diffusers.ModularPipeline.load_components]]

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

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2496)

**参数：**

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]]

```python
register_components(**kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2193)

**参数：**

- ****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 are updated to match the new component outside of this method, e.g. in `update_components()` method

#### save_pretrained[[diffusers.ModularPipeline.save_pretrained]]

```python
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)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2023)

**参数：**

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()](/docs/diffusers/main/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline.from_pretrained) 类方法重新加载。

#### 到[[diffusers.ModularPipeline.to]]

```python
to(*args, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2658)

**参数：**

dtype (`torch.dtype`，*可选*)：返回一个使用指定 [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) 的 pipeline

device (`torch.Device`, *可选*) : 返回一个使用指定 [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) 的 pipeline

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

**返回：** [DiffusionPipeline](/docs/diffusers/main/zh/api/pipelines/overview#diffusers.DiffusionPipeline)

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

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

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

以下是调用 `to` 的方式：

- `to(dtype, silence_dtype_warnings=False) → DiffusionPipeline` 返回一个具有指定 [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) 的 pipeline
- `to(device, silence_dtype_warnings=False) → DiffusionPipeline` 用于返回一个使用指定 [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) 的 pipeline
- `to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline` 返回一个具有指定 [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) 和 [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) 的 pipeline

#### unload_components[[diffusers.ModularPipeline.unload_components]]

```python
unload_components(names: list[str] | str)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2602)

**参数：**

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

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

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

#### update_components[[diffusers.ModularPipeline.update_components]]

```python
update_components(**kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2415)

**参数：**

- ****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`

示例：
```python
# 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 对象（例如调度器、引导器）可以直接传入。