Diffusers documentation

Modèles

Diffusers

Commencer

Diffusers Installation Démarrage rapide Interface en ligne de commande

Inférence

Utilisation des pipelines de diffusion

Adaptateurs et personnalisation

Optimiser et mettre à l'échelle

Performances de base

Inférence

Méthodes de la communauté

Quantification

Accélération spécifique au matériel

Service et mise à l'échelle

Diffusers modulaires

Entraîner et affiner

Ressources

Contribuer

API

Classes principales

Modulaire

Chargeurs

Modèles

Aperçu AutoModel

ControlNets

Transformers

UNets

VAEs

Pipelines

Planificateurs

Classes internes

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Modèles

🤗 Diffusers fournit des modèles préentraînés pour des algorithmes populaires et des modules pour créer des systèmes de diffusion personnalisés. La fonction principale des modèles est de débruyer un échantillon d'entrée, tel que modélisé par la distribution $p_{\theta}(x_{t-1}|x_{t})$ .

Tous les modèles sont construits à partir de la classe de base ModelMixin, qui est un torch.nn.Module fournissant des fonctionnalités de base pour l'enregistrement et le chargement des modèles, en local et depuis le Hugging Face Hub.

ModelMixin

classe diffusers.ModelMixin

( )

Classe de base pour tous les modèles.

ModelMixin gère le stockage de la configuration du modèle et fournit des méthodes pour charger, télécharger et enregistrer les modèles.

config_name (str) — Nom du fichier pour enregistrer le modèle lors de l'appel à save_pretrained().

compile_repeated_blocks

( *args**kwargs )

Compile uniquement les sous-modules fréquemment répétés d'un modèle (par exemple, les couches Transformer) au lieu de compiler l'ensemble du modèle. Cette technique, souvent appelée compilation régionale (voir la recette PyTorch https://docs.pytorch.org/tutorials/recipes/regional_compilation.html), peut réduire considérablement le temps de compilation de bout en bout, tout en conservant les gains de vitesse d'exécution attendus d'un torch.compile complet.

L'ensemble des sous-modules à compiler est déterminé par la présence de l'attribut _repeated_blocks dans la définition du modèle. Définissez cet attribut sur votre sous-classe de modèle sous forme d'une liste/tuple de noms de classes (chaînes de caractères). Tout module dont le nom de classe correspond sera compilé.

Une fois identifiés, chaque sous-module correspondant est compilé en appelant submodule.compile(*args, **kwargs). Tout argument positionnel ou par mot-clé fourni à compile_repeated_blocks est transmis tel quel à torch.compile.

cuda

( *args**kwargs )

Valeur factice pour un chemin pointé (par exemple torch.float32) : les chaînes d’accès aux attributs et les appels se comportent comme des décorateurs de pass-through, repr est le chemin pointé, et son utilisation comme classe de base substitue une base de type ordinaire (PEP 560 __mro_entries__), de sorte que les vraies sous-classes conservent un métaclasse normal et que inspect.signature lit leur __init__ réel plutôt que celui d’une valeur factice.

déquantiser

( )

Déquantiser éventuellement le modèle s'il a été quantisé par une méthode de quantisation prenant en charge la déquantisation.

disable_gradient_checkpointing

( )

Désactive le checkpointing des gradients pour le modèle actuel (également appelé activation checkpointing ou checkpoint activations dans d'autres frameworks).

disable_npu_flash_attention

( )

désactiver l'attention flash NPU depuis torch_npu

disable_xformers_memory_efficient_attention

( )

Désactiver l'attention efficace en mémoire de xFormers.

disable_xla_flash_attention

( )

Désactiver le noyau pallals de flash attention pour torch_xla.

enable_gradient_checkpointing

( gradient_checkpointing_func: typing.Optional[typing.Callable] = None )

Paramètres

gradient_checkpointing_func (Callable, facultatif) — La fonction à utiliser pour le gradient checkpointing. Si None, la fonction de checkpointing PyTorch par défaut est utilisée (torch.utils.checkpoint.checkpoint).

Active le checkpointing des gradients pour le modèle actuel (également appelé activation checkpointing ou checkpoint activations dans d'autres frameworks).

enable_group_offload

( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneblock_modules: str | None = Noneexclude_kwargs: str | None = None )

Active le déchargement par groupe pour le modèle actuel.

Voir apply_group_offloading() pour plus d’informations.

Exemple :

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> transformer.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )

enable_layerwise_casting

( storage_dtype: dtype = torch.float8_e4m3fncompute_dtype: typing.Optional[torch.dtype] = Noneskip_modules_pattern: tuple[str, ...] | None = Noneskip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Paramètres

storage_dtype (torch.dtype) — Le dtype auquel le modèle doit être converti pour le stockage.
compute_dtype (torch.dtype) — Le dtype auquel les poids du modèle doivent être convertis lors du passage avant.
skip_modules_pattern (tuple[str, ...], facultatif) — Une liste de motifs pour correspondre aux noms des modules à ignorer lors du processus de conversion par couche. Si défini sur None, des motifs d’ignorance par défaut sont utilisés pour ignorer certaines couches internes des modules et les couches PEFT.
skip_modules_classes (tuple[Type[torch.nn.Module], ...], facultatif) — Une liste de classes de modules à ignorer lors du processus de conversion par couche.
non_blocking (bool, facultatif, par défaut False) — Si True, les opérations de conversion des poids sont non bloquantes.

Active le castage par couche pour le modèle actuel.

Le cast par couche est une technique qui convertit les poids du modèle vers un dtype de précision inférieure pour le stockage, mais les remonte à la volée vers un dtype de précision supérieure pour le calcul. Ce processus peut réduire considérablement l’empreinte mémoire des poids du modèle, mais peut entraîner une certaine dégradation de la qualité des sorties. La plupart des dégradations sont négligeables, résultant principalement du cast des poids dans les couches de normalisation et de modulation.

Par défaut, la plupart des modèles de diffusers définissent l'attribut _skip_layerwise_casting_patterns afin d'ignorer les couches d'embedding de patch, d'embedding positionnel et de normalisation. Cela est dû au fait que ces couches sont très probablement sensibles à la précision en termes de qualité. Si vous souhaitez modifier ce comportement, vous pouvez définir l'attribut _skip_layerwise_casting_patterns sur None, ou appeler apply_layerwise_casting() avec des arguments personnalisés.

Exemple :

En utilisant enable_layerwise_casting() :

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> # Enable layerwise casting via the model, which ignores certain modules by default
>>> transformer.enable_layerwise_casting(storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)

enable_npu_flash_attention

( )

Activer l'attention flash NPU depuis torch_npu

enable_xformers_memory_efficient_attention

( attention_op: typing.Optional[typing.Callable] = None )

Paramètres

attention_op (Callable, facultatif) — Remplace l'opérateur par défaut None pour être utilisé comme argument op de la fonction memory_efficient_attention() de xFormers.

Activer l'attention efficace en mémoire à partir de xFormers.

Lorsque cette option est activée, vous devriez observer une réduction de l’utilisation de la mémoire GPU et une accélération potentielle lors de l’inférence. L’accélération lors de l’entraînement n’est pas garantie.

> ⚠️ Lorsque l'attention efficace en mémoire et l'attention par tranches sont toutes deux activées, l'attention efficace en mémoire a la > priorité.

Exemples :

>>> import torch
>>> from diffusers import UNet2DConditionModel
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> model = UNet2DConditionModel.from_pretrained(
...     "stabilityai/stable-diffusion-2-1", subfolder="unet", torch_dtype=torch.float16
... )
>>> model = model.to("cuda")
>>> model.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)

enable_xla_flash_attention

( partition_spec: typing.Optional[typing.Callable] = None**kwargs )

Activer le noyau pallals de flash attention pour torch_xla.

from_pretrained

( pretrained_model_name_or_path: str | os.PathLike | None**kwargs )

Paramètres

pretrained_model_name_or_path (str ou os.PathLike, facultatif) — Peut être soit :
- Une chaîne de caractères, l'identifiant du modèle (par exemple google/ddpm-celebahq-256) d'un modèle pré-entraîné hébergé sur le Hub.
- Un chemin vers un dossier (par exemple ./my_model_directory) contenant les poids du modèle enregistrés avec save_pretrained().
cache_dir (str | os.PathLike, facultatif) — Chemin vers un répertoire où la configuration d'un modèle pré-entraîné téléchargé est mise en cache si le cache standard n'est pas utilisé.
dtype (torch.dtype, facultatif) — Remplace le torch.dtype par défaut et charge le modèle avec un autre dtype.
force_download (bool, facultatif, par défaut False) — Indique s'il faut forcer le (re)téléchargement des poids du modèle et des fichiers de configuration, en ignorant les versions mises en cache si elles existent.
proxies (dict[str, str], facultatif) — Un dictionnaire de serveurs proxy à utiliser par protocole ou point de terminaison, par exemple, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Les proxys sont utilisés pour chaque requête.
output_loading_info (bool, facultatif, par défaut False) — Indique s'il faut également retourner un dictionnaire contenant les clés manquantes, les clés inattendues et les messages d'erreur.
local_files_only(bool, facultatif, par défaut False) — Indique s'il faut charger uniquement les poids et les fichiers de configuration du modèle locaux. Si défini sur True, le modèle ne sera pas téléchargé depuis le Hub.
token (str ou bool, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si True, le jeton généré par diffusers-cli login (stocké dans ~/.huggingface) est utilisé.
revision (str, facultatif, par défaut "main") — La version spécifique du modèle à utiliser. Il peut s’agir d’un nom de branche, d’un nom de tag, d’un identifiant de commit ou de tout identifiant autorisé par Git.
subfolder (str, facultatif, par défaut "") — L’emplacement du sous-dossier d’un fichier de modèle au sein d’un dépôt de modèle plus large sur le Hub ou en local.
mirror (str, facultatif) — Source miroir pour résoudre les problèmes d’accessibilité lors du téléchargement d’un modèle en Chine. Nous ne garantissons ni la réactivité ni la sécurité de la source ; veuillez consulter le site miroir pour plus d’informations.
device_map (int | str | torch.device ou dict[str, int | str | torch.device], facultatif) — Une carte qui spécifie où chaque sous-module doit être placé. Il n'est pas nécessaire de la définir pour chaque nom de paramètre/buffer ; dès qu'un nom de module est inclus, tous ses sous-modules seront envoyés sur le même appareil. La valeur par défaut est None, ce qui signifie que le modèle sera chargé sur le CPU.
Exemples :

Instanciez un modèle PyTorch pré-entraîné à partir d'une configuration de modèle pré-entraîné.

Le modèle est configuré en mode évaluation - model.eval() - par défaut, et les modules dropout sont désactivés. Pour entraîner le modèle, le remettre en mode entraînement avec model.train().

> Pour utiliser des modèles privés ou restreints, connectez-vous avec hf > auth login. Vous pouvez également activer le mode spécial > « hors-ligne » pour utiliser cette méthode dans un > environnement protégé par un pare-feu.

Exemple :

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5", subfolder="unet")

Si vous obtenez le message d’erreur ci-dessous, vous devez affiner les poids pour votre tâche en aval :

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

get_memory_footprint

( return_buffers = True )

Paramètres

return_buffers (bool, facultatif, par défaut True) — Indique s'il faut inclure la taille des tenseurs de tampon dans le calcul de l'empreinte mémoire. Les tampons sont des tenseurs qui ne nécessitent pas de gradients et qui ne sont pas enregistrés en tant que paramètres. Par exemple, la moyenne et l'écart-type dans les couches de normalisation par lot. Voir : https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Obtenir l’empreinte mémoire d’un modèle. Cette opération renvoie l’empreinte mémoire du modèle actuel en octets. Utile pour mesurer l’empreinte mémoire du modèle actuel et concevoir des tests. Solution inspirée des discussions PyTorch : https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

num_parameters

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

Paramètres

only_trainable (bool, facultatif, par défaut False) — Indique s'il faut renvoyer uniquement le nombre de paramètres entraînables.
exclude_embeddings (bool, facultatif, par défaut False) — Indique s'il faut renvoyer uniquement le nombre de paramètres non liés aux embeddings.

Retourne

int

Le nombre de paramètres.

Obtenir le nombre de paramètres (entraînables ou non-embedding) du module.

Exemple :

from diffusers import UNet2DConditionModel

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
unet = UNet2DConditionModel.from_pretrained(model_id, subfolder="unet")
unet.num_parameters(only_trainable=True)
859520964

reset_attention_backend

( )

Réinitialise le backend d'attention pour le modèle. Les appels suivants à forward utiliseront la valeur par défaut de l'environnement, si elle est définie, ou l'attention par produit scalaire pondéré natif de torch.

save_pretrained

( save_directory: str | os.PathLikeis_main_process: bool = Truesave_function: typing.Optional[typing.Callable] = Nonesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str = '10GB'push_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )

Paramètres

save_directory (str ou os.PathLike) — Répertoire dans lequel enregistrer le modèle et son fichier de configuration. Sera créé s'il n'existe pas.
is_main_process (bool, facultatif, par défaut True) — Indique si le processus qui appelle cette fonction est le processus principal ou non. Utile lors de l'entraînement distribué lorsque vous devez appeler cette fonction sur tous les processus. Dans ce cas, définissez is_main_process=True uniquement sur le processus principal pour éviter les conditions de course.
save_function (Callable) — La fonction à utiliser pour enregistrer le dictionnaire d'état. Utile lors de l'entraînement distribué lorsque vous devez remplacer torch.save par une autre méthode. Peut être configurée avec la variable d'environnement DIFFUSERS_SAVE_MODE.
safe_serialization (bool, facultatif, par défaut True) — Indique si le modèle doit être enregistré en utilisant safetensors ou la méthode traditionnelle de PyTorch avec pickle.
variant (str, facultatif) — Si spécifié, les poids sont enregistrés au format pytorch_model.<variant>.bin.
max_shard_size (int ou str, par défaut "10GB") — Taille maximale d'un point de contrôle avant son fractionnement. Les points de contrôle fractionnés auront chacun une taille inférieure à cette limite. S'il est exprimé sous forme de chaîne de caractères, il doit être composé de chiffres suivis d'une unité (comme "5GB"). S'il est exprimé sous forme d'entier, l'unité est l'octet. Notez que cette limite sera réduite après une certaine période (à partir d'octobre 2024) afin de permettre aux utilisateurs de passer à la dernière version de diffusers. Cela vise à établir une taille par défaut commune pour cet argument entre les différentes bibliothèques de l'écosystème Hugging Face (transformers et accelerate, par exemple).
push_to_hub (bool, facultatif, par défaut False) — Indique s'il faut ou non pousser votre modèle sur le Hugging Face Hub après l'avoir enregistré. Vous pouvez spécifier le dépôt auquel vous souhaitez pousser avec repo_id (par défaut, il s'agit du nom de save_directory dans votre espace de noms).
kwargs (dict[str, Any], facultatif) — Arguments supplémentaires passés à la méthode push_to_hub().

Enregistrer un modèle et son fichier de configuration dans un répertoire afin qu’il puisse être rechargé à l’aide de la méthode de classe from_pretrained().

set_attention_backend

( backend: str )

Paramètres

backend (str) — Le nom du backend à définir. Doit être l’un des backends disponibles définis dans AttentionBackendName. Les backends disponibles se trouvent dans diffusers.attention_dispatch.AttentionBackendName. Par défaut, l’attention produit scalaire normalisé native de torch est utilisée comme backend.

Définissez le backend d'attention pour le modèle.

set_use_npu_flash_attention

( valid: bool )

Définissez l’interrupteur pour l’attention flash du npu.

à

( *args**kwargs )

Valeur factice pour un chemin pointé (par exemple torch.float32) : les chaînes d’accès aux attributs et les appels se comportent comme des décorateurs de pass-through, repr est le chemin pointé, et son utilisation comme classe de base substitue une base de type ordinaire (PEP 560 __mro_entries__), de sorte que les vraies sous-classes conservent un métaclasse normal et que inspect.signature lit leur __init__ réel plutôt que celui d’une valeur factice.

PushToHubMixin

classe diffusers.utils.PushToHubMixin

( )

Un Mixin pour pousser un modèle, un planificateur ou un pipeline vers le Hugging Face Hub.

push_to_hub

( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )

Paramètres

repo_id (str) — Le nom du dépôt vers lequel vous souhaitez pousser vos fichiers de modèle, de planificateur ou de pipeline. Il doit contenir le nom de votre organisation lors d’un envoi vers une organisation. repo_id peut également être un chemin vers un répertoire local.
commit_message (str, facultatif) — Message à committer lors de la poussée. Par défaut, "Upload {object}".
private (bool, facultatif) — Indique s'il faut rendre le dépôt privé. Si None (par défaut), le dépôt sera public sauf si le défaut de l'organisation est privé. Cette valeur est ignorée si le dépôt existe déjà.
token (str, facultatif) — Le jeton à utiliser comme autorisation HTTP bearer pour les fichiers distants. Le jeton généré lors de l’exécution de hf auth login (stocké dans ~/.huggingface).
create_pr (bool, facultatif, par défaut False) — Indique s'il faut créer une PR avec les fichiers téléversés ou effectuer un commit direct.
safe_serialization (bool, facultatif, par défaut True) — Indique s'il faut convertir les poids du modèle au format safetensors.
variant (str, facultatif) — Si spécifié, les poids sont enregistrés au format pytorch_model.<variant>.bin.

Téléchargez des fichiers de modèle, de planificateur ou de pipeline sur le 🤗 Hugging Face Hub.

Exemples :

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")

Update on GitHub

←PEFT AutoModel→