Hugging Face's logo

Diffusers documentation

Composants et configurations

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

and get access to the augmented documentation experience

to get started

Composants et configurations

ComponentSpec

classe 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 )

Paramètres

  • name — Nom du composant
  • type_hint — Type du composant (par exemple, UNet2DConditionModel)
  • description — Description facultative du composant
  • config — Dictionnaire de configuration facultatif pour la création de init
  • pretrained_model_name_or_path — Chemin facultatif de pretrained_model_name_or_path pour la création via from_pretrained
  • subfolder — Sous-dossier facultatif dans pretrained_model_name_or_path
  • variant — Variante facultative dans pretrained_model_name_or_path
  • revision — Révision facultative dans pretrained_model_name_or_path
  • default_creation_method — Méthode de création préférée - « from_config » ou « from_pretrained »

Spécification d'un composant de pipeline.

Un composant peut être créé de deux manières :

  1. À partir de zéro en utilisant init avec un dictionnaire de configuration
  2. en utilisant from_pretrained

créer

< >

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

Créer un composant à l'aide de from_config avec config.

decode_load_id

< >

( load_id: str )

Paramètres

  • load_id — La chaîne load_id à décoder, format : “pretrained_model_name_or_path|subfolder|variant|revision” où les valeurs None sont représentées par “null”

Décode une chaîne load_id en un dictionnaire de champs et de valeurs de chargement.

from_component

< >

( name: strcomponent: Any )

Paramètres

  • name — Nom du composant
  • component — Objet de composant à partir duquel créer la spécification

Lève

ValueError

  • ValueError — Si le composant n'est pas pris en charge (par ex. nn.Module sans load_id, non-ConfigMixin)

Créer un ComponentSpec à partir d'un Component.

Prend actuellement en charge :

  • Composants créés avec la méthode ComponentSpec.load()
  • Les composants qui sont des sous-classes de ConfigMixin mais pas des nn.Modules (par exemple, les planificateurs, les guides)

load

< >

( **kwargs )

Charger le composant à l'aide de from_pretrained.

loading_fields

< >

( )

Retourne les noms de tous les champs liés au chargement (c’est-à-dire ceux dont field.metadata[“loading”] est True).

ConfigSpec

classe diffusers.ConfigSpec

< >

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

Spécification d'un paramètre de configuration de pipeline.

ComponentsManager

classe diffusers.ComponentsManager

< >

( )

Un registre central et un système de gestion pour les composants de modèles à travers plusieurs pipelines.

ComponentsManager offre une méthode unifiée pour enregistrer, suivre et réutiliser des composants de modèle (tels que UNet, VAE, encodeurs de texte, etc.) à travers différents pipelines modulaires. Il inclut des fonctionnalités de détection des doublons, de gestion de la mémoire et d’organisation des composants.

> Il s'agit d'une fonctionnalité expérimentale susceptible d'évoluer à l'avenir.

Exemple :

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")

add

< >

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

Paramètres

  • name (str) — Le nom du composant
  • component (Any) — Le composant à ajouter
  • collection (str | None) — La collection à laquelle ajouter le composant

Retourne

str

L'identifiant unique du composant, généré sous la forme « {name}_{id(component)} », où id(component) est l'identifiant unique intégré de Python pour l'objet

Ajouter un composant au ComponentsManager.

disable_auto_cpu_offload

< >

( )

Désactiver le déchargement automatique sur CPU pour tous les composants.

enable_auto_cpu_offload

< >

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

Paramètres

  • device (str | int | torch.device) — L’appareil d’exécution sur lequel les modèles sont déplacés pour les passes avant
  • memory_reserve_margin (str) — La marge de mémoire de réserve à utiliser, par défaut 3 Go. Il s'agit de la quantité de mémoire à laisser libre sur l'appareil pour éviter d'épuiser la mémoire pendant l'exécution du modèle (par exemple, pour les activations intermédiaires, les gradients, etc.).
  • offload_strategy — Tout appelable ayant la signature (hooks, model_id, model, execution_device) -> hooks, renvoyant les modèles résidents à décharger avant le chargement du modèle entrant. La valeur par défaut est AutoOffloadStrategy, qui libère la combinaison minimale suffisante.

Activer le déchargement automatique sur CPU pour tous les composants.

L'algorithme fonctionne comme suit :

  1. Tous les modèles démarrent sur le CPU par défaut
  2. Lorsque le passage avant d'un modèle est appelé, il est déplacé vers l'appareil d'exécution
  3. En cas de mémoire insuffisante, les autres modèles sur l’appareil sont transférés à nouveau vers le CPU
  4. Le système tente de décharger la plus petite combinaison de modèles qui libère suffisamment de mémoire
  5. Les modèles restent sur l'appareil d'exécution jusqu'à ce qu'un autre modèle ait besoin de mémoire et les force à en être retirés

Un modèle déchargé par groupe participe à ce processus, mais se place lui-même : il peut toujours libérer de l’espace en déplaçant d’autres modèles, et n’est jamais déplacé pour leur faire de la place. Les deux ordres fonctionnent — le déchargement par groupe avant ou après l’activation de cette option. AutoOffloadStrategy calibre ses décisions à partir de l’empreinte mémoire des modèles, ce qui ne décrit pas un modèle tenant un groupe à la fois ; passez donc un offload_strategy qui décide en fonction du flux de travail.

get_components_by_ids

< >

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

Paramètres

  • ids (list[str]) — liste des identifiants des composants
  • return_dict_with_names (bool | None) — Indique s'il faut retourner un dictionnaire dont les clés sont les noms des composants :

Retourne

dict[str, Any]

Dictionnaire de composants.

  • Si return_dict_with_names=True, les clés sont les noms des composants.
  • Si return_dict_with_names=False, les clés sont les identifiants des composants.

Lève

ValueError

  • ValueError — Si des noms de composants en double sont trouvés dans les résultats de recherche lorsque return_dict_with_names=True

Récupérer des composants à partir d'une liste d'identifiants.

get_components_by_names

< >

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

Paramètres

  • names (list[str]) — liste des noms des composants
  • collection (str | None) — Collection facultative à utiliser pour le filtrage

Retourne

dict[str, Any]

Dictionnaire de composants avec les noms de composants en tant que clés

Lève

ValueError

  • ValueError — Si des noms de composants en double sont trouvés dans les résultats de recherche

Récupérer des composants à partir d'une liste de noms, éventuellement filtrée par collection.

get_ids

< >

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

Paramètres

  • names (str | list[str]) — liste de noms de composants
  • collection (str | None) — Collection facultative à utiliser pour le filtrage

Retourne

list[str]

liste d'identifiants de composants

Obtenir les identifiants de composants à partir d'une liste de noms, éventuellement filtrée par collection.

get_model_info

< >

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

Paramètres

  • component_id (str) — Nom du composant pour lequel obtenir des informations
  • fields (str | list[str] | None) — Champ(s) à retourner. Peut être une chaîne de caractères pour un champ unique ou une liste de champs. Si None, utilise le paramètre available_info_fields.

Obtenez des informations complètes sur un composant.

get_one

< >

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

Paramètres

  • component_id (str | None) — ID de composant facultatif à récupérer
  • name (str | None) — Nom du composant ou motif
  • collection (str | None) — Collection facultative à utiliser pour le filtrage
  • load_id (str | None) — load_id facultatif pour filtrer

Lève

ValueError

  • ValueError — Si aucun composant ne correspond ou si plusieurs composants correspondent

Obtenir un composant unique en :

  • recherche par nom (correspondance de motif), collection ou load_id.
  • passage d'un component_id Lève une erreur si plusieurs composants correspondent ou si aucun n'est trouvé.

supprimer

< >

( component_id: str = None )

Paramètres

  • component_id (str) — L'identifiant du composant à supprimer

Supprimer un composant du ComponentsManager.

remove_from_collection

< >

( component_id: strcollection: str )

Supprimer un composant d'une collection.

search_components

< >

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

Paramètres

  • names — Nom(s) de composant(s) ou motif(s) Motifs :
    • “unet” : correspond à tout composant dont le nom de base est “unet” (par ex. unet_123abc)
    • “!unet” : tout sauf les composants dont le nom de base est “unet”
    • “unet*” : tout élément dont le nom de base commence par “unet”
    • “!unet*” : tout élément dont le nom de base ne commence PAS par “unet”
    • ”unet” : tout élément dont le nom de base contient “unet”
    • “!unet” : tout élément dont le nom de base ne contient pas “unet”
    • “refiner|vae|unet” : tout élément dont le nom de base correspond exactement à « refiner », « vae » ou « unet »
    • “!refiner|vae|unet” : tout élément dont le nom de base ne correspond pas exactement à “refiner”, “vae” ou “unet”
    • “unet|vae” : tout élément dont le nom de base commence par “unet” OU par “vae”
  • collection — Collection facultative à utiliser pour le filtrage
  • load_id — load_id facultatif pour filtrer
  • return_dict_with_names — Si True, renvoie un dictionnaire dont les clés sont les noms des composants, et lève une erreur si plusieurs composants portant le même nom sont trouvés. Si False, renvoie un dictionnaire dont les clés sont les identifiants des composants.

Recherchez des composants par nom à l'aide d'une correspondance de motifs simple. Filtrez éventuellement par collection ou load_id.

set_offload_strategy

< >

( offload_strategy )

Paramètres

  • offload_strategy — Toute fonction appelable ayant la signature (hooks, model_id, model, execution_device) -> hooks : elle reçoit les hooks des modèles actuellement sur l’appareil et renvoie ceux à décharger avant le chargement du modèle entrant. La valeur par défaut est AutoOffloadStrategy, qui libère la combinaison minimale suffisante.

Remplace la stratégie de déchargement sur tous les modèles gérés. Valable uniquement lorsque le déchargement automatique sur CPU est activé.

InsertableDict

classe diffusers.modular_pipelines.InsertableDict

< >

( )

Update on GitHub

←États Guides→