Hugging Face's logo

Diffusers documentation

Components and configs

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.34.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Components and configs

ComponentSpec

class diffusers.ComponentSpec

< >

( name: typing.Optional[str] = None type_hint: typing.Optional[typing.Type] = None description: typing.Optional[str] = None config: typing.Optional[diffusers.configuration_utils.FrozenDict] = None repo: typing.Union[str, typing.List[str], NoneType] = None subfolder: typing.Optional[str] = '' variant: typing.Optional[str] = None revision: typing.Optional[str] = None default_creation_method: typing.Literal['from_config', 'from_pretrained'] = 'from_pretrained' )

Parameters

  • 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
  • repo — Optional repo path for from_pretrained creation
  • subfolder — Optional subfolder in repo
  • variant — Optional variant in repo
  • revision — Optional revision in repo
  • 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

< >

( config: typing.Union[diffusers.configuration_utils.FrozenDict, typing.Dict[str, typing.Any], NoneType] = None **kwargs )

Create component using from_config with config.

decode_load_id

< >

( load_id: str )

Parameters

  • load_id — The load_id string to decode, format: “repo|subfolder|variant|revision” where None values are represented as “null”

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

from_component

< >

( name: str component: typing.Any )

Parameters

  • name — Name of the component
  • component — Component object to create spec from

Raises

ValueError

  • ValueError — If component is not supported (e.g. nn.Module without load_id, non-ConfigMixin)

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

< >

( **kwargs )

Load component using from_pretrained.

loading_fields

< >

( )

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

ConfigSpec

class diffusers.modular_pipelines.ConfigSpec

< >

( name: str default: typing.Any description: typing.Optional[str] = None )

Specification for a pipeline configuration parameter.

ComponentsManager

class 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(device="cuda")

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

add

< >

( name: str component: typing.Any collection: typing.Optional[str] = None ) → str

Parameters

  • name (str) — The name of the component
  • component (Any) — The component to add
  • collection (Optional[str]) — The collection to add the component to

Returns

str

The 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_auto_cpu_offload

< >

( )

Disable automatic CPU offloading for all components.

enable_auto_cpu_offload

< >

( device: typing.Union[str, int, torch.device] = 'cuda' memory_reserve_margin = '3GB' )

Parameters

  • device (Union[str, int, torch.device]) — The execution device where models are moved for forward passes
  • memory_reserve_margin (str) — The memory reserve margin to use, default is 3GB. This is the amount of memory to keep free on the device to avoid running out of memory during model execution (e.g., for intermediate activations, gradients, etc.)

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 there’s insufficient memory, other models on the device are moved back to CPU
  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

get_components_by_ids

< >

( ids: typing.List[str] return_dict_with_names: typing.Optional[bool] = True ) → Dict[str, Any]

Parameters

  • ids (List[str]) — List of component IDs
  • return_dict_with_names (Optional[bool]) — Whether to return a dictionary with component names as keys:

Returns

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.

Raises

ValueError

  • ValueError — If duplicate component names are found in the search results when return_dict_with_names=True

Get components by a list of IDs.

get_components_by_names

< >

( names: typing.List[str] collection: typing.Optional[str] = None ) → Dict[str, Any]

Parameters

  • names (List[str]) — List of component names
  • collection (Optional[str]) — Optional collection to filter by

Returns

Dict[str, Any]

Dictionary of components with component names as keys

Raises

ValueError

  • ValueError — If duplicate component names are found in the search results

Get components by a list of names, optionally filtered by collection.

get_ids

< >

( names: typing.Union[str, typing.List[str]] = None collection: typing.Optional[str] = None ) → List[str]

Parameters

  • names (Union[str, List[str]]) — List of component names
  • collection (Optional[str]) — Optional collection to filter by

Returns

List[str]

List of component IDs

Get component IDs by a list of names, optionally filtered by collection.

get_model_info

< >

( component_id: str fields: typing.Union[str, typing.List[str], NoneType] = None )

Parameters

  • component_id (str) — Name of the component to get info for
  • fields (Optional[Union[str, List[str]]]) — Field(s) to return. Can be a string for single field or list of fields. If None, uses the available_info_fields setting.

Get comprehensive information about a component.

get_one

< >

( component_id: typing.Optional[str] = None name: typing.Optional[str] = None collection: typing.Optional[str] = None load_id: typing.Optional[str] = None )

Parameters

  • component_id (Optional[str]) — Optional component ID to get
  • name (Optional[str]) — Component name or pattern
  • collection (Optional[str]) — Optional collection to filter by
  • load_id (Optional[str]) — Optional load_id to filter by

Raises

ValueError

  • ValueError — If no components match or multiple components match

Get a single component by either:

  • searching name (pattern matching), collection, or load_id.
  • passing in a component_id Raises an error if multiple components match or none are found.

remove

< >

( component_id: str = None )

Parameters

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

Remove a component from the ComponentsManager.

remove_from_collection

< >

( component_id: str collection: str )

Remove a component from a collection.

search_components

< >

( names: typing.Optional[str] = None collection: typing.Optional[str] = None load_id: typing.Optional[str] = None return_dict_with_names: bool = True )

Parameters

  • names — Component name(s) or pattern(s) Patterns:
    • “unet” : match any component with base name “unet” (e.g., unet_123abc)
    • “!unet” : everything except components with base name “unet”
    • “unet*” : anything with base name starting with “unet”
    • “!unet*” : anything with base name NOT starting with “unet”
    • ”unet” : anything with base name containing “unet”
    • “!unet” : anything with base name NOT containing “unet”
    • “refiner|vae|unet” : anything with base name exactly matching “refiner”, “vae”, or “unet”
    • “!refiner|vae|unet” : anything with base name NOT exactly matching “refiner”, “vae”, or “unet”
    • “unet|vae” : anything with base name starting with “unet” OR starting with “vae”
  • collection — Optional collection to filter by
  • load_id — Optional load_id to filter by
  • return_dict_with_names — If True, returns a dictionary with component names as keys, throw an error if multiple components with the same name are found If False, returns a dictionary with component IDs as keys

Search components by name with simple pattern matching. Optionally filter by collection or load_id.

InsertableDict

class diffusers.modular_pipelines.InsertableDict

< >

( )

< > Update on GitHub

←States Guiders→