diffusers/pr_14304/en/api/modular_diffusers/pipeline_components.md

Components and configs

ComponentSpec[[diffusers.ComponentSpec]]

• name -- Name of the component
• type_hint -- Type of the component (e.g. UNet2DConditionModel)
• description -- Optional description of the component
• config -- Optional config dict for init creation
• pretrained_model_name_or_path -- Optional pretrained_model_name_or_path path for from_pretrained creation
• subfolder -- Optional subfolder in pretrained_model_name_or_path
• variant -- Optional variant in pretrained_model_name_or_path
• revision -- Optional revision in pretrained_model_name_or_path
• default_creation_method -- Preferred creation method - "from_config" or "from_pretrained" Specification for a pipeline component.

A component can be created in two ways:

1. From scratch using init with a config dict
2. using from_pretrained

Create component using from_config with config.

• load_id -- The load_id string to decode, format: "pretrained_model_name_or_path|subfolder|variant|revision" where None values are represented as "null"Dict mapping loading field names to their values. e.g. { "pretrained_model_name_or_path": "path/to/repo", "subfolder": "subfolder", "variant": "variant", "revision": "revision" } If a segment value is "null", it's replaced with None. Returns None if load_id is "null" (indicating component not created with load method).

Decode a load_id string back into a dictionary of loading fields and values.

• name -- Name of the component
• component -- Component object to create spec fromComponentSpec object- ValueError -- If component is not supported (e.g. nn.Module without load_id, non-ConfigMixin)ValueError Create a ComponentSpec from a Component.

Currently supports:

• Components created with ComponentSpec.load() method
• Components that are ConfigMixin subclasses but not nn.Modules (e.g. schedulers, guiders)

Load component using from_pretrained.

Return the names of all loading‐related fields (i.e. those whose field.metadata["loading"] is True).

ConfigSpec[[diffusers.ConfigSpec]]

Specification for a pipeline configuration parameter.

ComponentsManager[[diffusers.ComponentsManager]]

A central registry and management system for model components across multiple pipelines.

ComponentsManager provides a unified way to register, track, and reuse model components (like UNet, VAE, text encoders, etc.) across different modular pipelines. It includes features for duplicate detection, memory management, and component organization.

> This is an experimental feature and is likely to change in the future.

Example:

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 (str) -- The name of the component
• component (Any) -- The component to add
• collection (str | None) -- The collection to add the component tostrThe unique component ID, which is generated as "{name}_{id(component)}" where id(component) is Python's built-in unique identifier for the object

Add a component to the ComponentsManager.

Disable automatic CPU offloading for all components.

• device (str | int | torch.device) -- The execution device where models are moved for forward passes
• memory_reserve (str | int, optional, defaults to "3GB") -- The amount of available device memory to keep free when deciding whether an incoming model fits, checked at each offloading decision — e.g. "3GB" or a number of bytes. The reserve is what covers allocations the offloading cannot see, mainly activations, which scale with resolution / batch size / sequence length. Set it to 0 to keep as much on the device as possible, relying on the OOM retry.
• retry_on_oom (bool, optional, defaults to True) -- Whether to recover from a forward pass that runs out of device memory by offloading the models on the device one at a time, smallest first, and retrying until it fits. Set it to False to raise the error instead — the forward passes are then left untouched.

Enable automatic CPU offloading for all components.

The algorithm works as follows:

1. All models start on CPU by default
2. When a model's forward pass is called, it's moved to the execution device
3. If it doesn't fit into the memory currently available on the device minus memory_reserve, other models on the device are moved back to CPU first
4. The system tries to offload the smallest combination of models that frees enough memory
5. Models stay on the execution device until another model needs memory and forces them off
6. If a forward pass still runs out of device memory, the smallest model on the device is offloaded and the forward is retried, escalating one model at a time until it fits (inference only: each retried forward re-runs from its original inputs)

Every move the offloader makes is recorded in offload_record.

• ids (list[str]) -- list of component IDs
• return_dict_with_names (bool | None) -- Whether to return a dictionary with component names as keys:dict[str, Any]Dictionary of components.
• If return_dict_with_names=True, keys are component names.
• If return_dict_with_names=False, keys are component IDs.- ValueError -- If duplicate component names are found in the search results when return_dict_with_names=TrueValueError

Get components by a list of IDs.

• component_id (str) -- Name of the component to get info for

• fields (str | list[str] | None) -- Field(s) to return, all fields if None.Dictionary containing the requested component metadata. Get comprehensive information about a component.

• component_id (str | None) -- Optional component ID to get

• name (str | None) -- Component name

• collection (str | None) -- Optional collection to filter by

• load_id (str | None) -- Optional load_id to filter byA single component- ValueError -- If no components match or multiple components matchValueError

Get a single component by either:

• searching name, collection, or load_id.

• passing in a component_id Raises an error if multiple components match or none are found.

• component_id (str) -- The ID of the component to remove

Remove a component from the ComponentsManager.

Remove a component from a collection.

• offload_strategy -- Any callable with the signature (hooks, model_id, model, execution_device) -> hooks: it receives the hooks of the models currently on the device and returns the ones to offload before the incoming model loads. The default is AutoOffloadStrategy, which frees the smallest sufficient combination.

Replace the offload strategy on all managed models. Only valid while auto CPU offloading is enabled.

InsertableDict[[diffusers.modular_pipelines.InsertableDict]]