Hugging Face's logo

Diffusers documentation

Utilitaires

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

Utilitaires

Fonctions utilitaires et d’assistance pour travailler avec 🤗 Diffusers.

numpy_to_pil

diffusers.utils.numpy_to_pil

< >

( images )

Convertir une image numpy ou un lot d'images en image PIL.

pt_to_pil

diffusers.utils.pt_to_pil

< >

( images )

Convertir une image torch en image PIL.

load_image

diffusers.utils.load_image

< >

( image: str | PIL.Image.Imageconvert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None ) → PIL.Image.Image

Paramètres

  • image (str ou PIL.Image.Image) — L’image à convertir au format PIL Image.
  • convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], facultatif) — Méthode de conversion à appliquer à l’image après son chargement. Si défini sur None, l’image sera convertie en « RGB ».

Retourne

PIL.Image.Image

Une image PIL.

Loads image to a PIL Image.

load_video

diffusers.utils.load_video

< >

( video: strconvert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = Nonereturn_fps: bool = False ) → list[PIL.Image.Image] or tuple[list[PIL.Image.Image], float]

Paramètres

  • video (str) — Une URL ou un chemin vers une vidéo à convertir en liste d’images au format PIL Image.
  • convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], facultatif) — Méthode de conversion à appliquer à la vidéo après son chargement. Si défini sur None, les images seront converties en « RGB ».
  • return_fps (bool, facultatif, par défaut False) — Indique s'il faut également renvoyer la fréquence d'images à laquelle la vidéo a été encodée. Nécessaire pour les pipelines qui rééchantillonnent l'entrée à la fréquence d'images utilisée par leur modèle, car une liste d'images ne contient pas cette information.

Retourne

list[PIL.Image.Image] ou tuple[list[PIL.Image.Image], float]

La vidéo en tant que liste d'images PIL, et son taux de rafraîchissement si return_fps est défini.

Charge video dans une liste d'images PIL.

export_to_gif

diffusers.utils.export_to_gif

< >

( image: list[PIL.Image.Image]output_gif_path: str = Nonefps: int = 10 )

export_to_video

diffusers.utils.export_to_video

< >

( video_frames: list[np.ndarray] | list[PIL.Image.Image]output_video_path: str = Nonefps: int = 10quality: float = 5.0bitrate: int | None = Nonemacro_block_size: int | None = 16 )

quality: Qualité de la sortie vidéo. La valeur par défaut est 5. Utilise un débit binaire variable. La qualité la plus élevée est 10, la plus basse est 0. Définir sur None pour empêcher les drapeaux de débit binaire variable d'être passés à FFMPEG afin de pouvoir les spécifier manuellement à l'aide de output_params. Spécifier un débit binaire fixe à l'aide de bitrate désactive ce paramètre.

bitrate : Définit un débit binaire constant pour l’encodage vidéo. La valeur par défaut est None, ce qui entraîne l’utilisation du paramètre quality à la place. Des vidéos de meilleure qualité avec des tailles de fichier plus petites résultent de l’utilisation du paramètre de débit binaire variable quality plutôt que de la spécification d’un débit binaire fixe avec ce paramètre.

macro_block_size: Contrainte de taille pour la vidéo. La largeur et la hauteur doivent être divisibles par ce nombre. Si ce n'est pas le cas, imageio indiquera à ffmpeg de redimensionner l'image à la taille supérieure la plus proche divisible par ce nombre. La plupart des codecs sont compatibles avec une taille de macrobloc de 16 (par défaut), certains peuvent aller plus petit (4, 8). Pour désactiver cette fonctionnalité automatique, définissez-la sur None ou 1, mais sachez que de nombreux lecteurs ne peuvent pas décoder les vidéos dont les dimensions sont impaires et que certains codecs produiront des résultats médiocres ou échoueront. Voir https://en.wikipedia.org/wiki/Macroblock.

encode_video

diffusers.utils.encode_video

< >

( video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor']fps: intoutput_path: straudio: 'torch.Tensor' | None = Noneaudio_sample_rate: int | None = Nonevideo_chunks_number: int = 1 )

Paramètres

  • video (List[PIL.Image.Image] ou np.ndarray ou torch.Tensor) — Un tenseur vidéo de forme [frames, height, width, channels] avec des valeurs de pixels entières dans [0, 255]. Si l'entrée est un np.ndarray, il est attendu que ce soit un tableau flottant avec des valeurs dans [0, 1] (ce que les pipelines retournent généralement avec output_type="np").
  • fps (int) — Le nombre d'images par seconde (FPS) de la vidéo encodée.
  • output_path (str) — Chemin où enregistrer la vidéo encodée.
  • audio (torch.Tensor, facultatif) — Une forme d’onde audio de forme [audio_channels, samples].
  • audio_sample_rate — (int, facultatif) : Le taux d'échantillonnage de la forme d'onde audio.
  • video_chunks_number (int, facultatif, par défaut 1) — Le nombre de morceaux en lesquels diviser la vidéo pour l'encodage. Chaque morceau sera encodé séparément. Le nombre de morceaux à utiliser dépend souvent de la configuration de tuilage pour le VAE vidéo.

Encode une vidéo avec un audio facultatif à l’aide de la bibliothèque PyAV. Basé sur le code du dépôt original LTX-2 : https://github.com/Lightricks/LTX-2/blob/4f410820b198e05074a1e92de793e3b59e9ab5a0/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py#L182

make_image_grid

diffusers.utils.make_image_grid

< >

( images: listrows: intcols: intresize: int = None )

Prépare une grille unique d'images. Utile à des fins de visualisation.

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< >

( shape: tuple | listgenerator: list['torch.Generator'] | 'torch.Generator' | None = Nonedevice: str | 'torch.device' | None = Nonedtype: 'torch.dtype' | None = Nonelayout: 'torch.layout' | None = None )

Fonction utilitaire pour créer des tenseurs aléatoires sur le device souhaité avec le dtype souhaité. Lors du passage d'une liste de générateurs, vous pouvez initialiser individuellement chaque taille de lot. Si des générateurs CPU sont passés, le tenseur est toujours créé sur le CPU.

TorchDeviceBackend

classe diffusers.utils.torch_utils.TorchDeviceBackend

< >

( device: str | torch.device | None = None )

Un proxy pour l’espace de noms torch.<backend> (torch.cuda, torch.xpu, torch.mps, …) d’un appareil. Les attributs que la classe ne définit pas sont ceux du module (synchronize, device_count, Stream, current_stream, …) ; les méthodes définies ici remplacent les opérations dont la disponibilité varie selon les backends et qui nécessitent un repli : effacement du cache, initialisation de l’aléatoire et requêtes mémoire. En l’absence de device, détecte l’accélérateur hôte via torch.accelerator. Lève une exception si torch ne possède pas de module pour le backend, plutôt que de basculer silencieusement sur torch.cuda.

max_memory_allocated

< >

( )

Mémoire maximale allouée sur l'appareil en octets depuis le dernier réinitialisation ; 0 si le backend ne conserve pas de statistiques.

mem_get_info

< >

( )

Mémoire libre et mémoire totale de l'appareil, en octets.

apply_layerwise_casting

diffusers.hooks.apply_layerwise_casting

< >

( module: Modulestorage_dtype: dtypecompute_dtype: dtypeskip_modules_pattern: str | tuple[str, ...] = 'auto'skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Paramètres

  • module (torch.nn.Module) — Le module dont les modules feuilles seront convertis en un type de données de haute précision pour le calcul et en un type de données de basse précision pour le stockage.
  • storage_dtype (torch.dtype) — Le dtype vers lequel convertir le module avant/après le passage avant pour le stockage.
  • compute_dtype (torch.dtype) — Le dtype vers lequel convertir le module lors de la passe avant pour le calcul.
  • skip_modules_pattern (tuple[str, ...], par défaut "auto") — Une liste de motifs pour correspondre aux noms des modules à ignorer lors du processus de conversion par couche. Si défini sur "auto", les motifs par défaut sont utilisés. Si défini sur None, aucun module n’est ignoré. Si défini sur None en même temps que skip_modules_classes est None, la conversion par couche est appliquée directement au module plutôt qu’à ses sous-modules internes.
  • skip_modules_classes (tuple[Type[torch.nn.Module], ...], par défaut None) — Une liste de classes de modules à ignorer lors du processus de conversion par couche.
  • non_blocking (bool, par défaut False) — Si True, les opérations de conversion des poids sont non bloquantes.

Applique un castage par couche à un module donné. Le module attendu ici est un ModelMixin de Diffusers, mais il peut s’agir de n’importe quel nn.Module utilisant des couches diffusers ou des primitives pytorch.

Exemple :

>>> import torch
>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     model_id, subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> apply_layerwise_casting(
...     transformer,
...     storage_dtype=torch.float8_e4m3fn,
...     compute_dtype=torch.bfloat16,
...     skip_modules_pattern=["patch_embed", "norm", "proj_out"],
...     non_blocking=True,
... )

apply_group_offloading

diffusers.hooks.apply_group_offloading

< >

( module: Moduleonload_device: typing.Union[str, torch.device]offload_device: typing.Union[str, torch.device] = torch.device()offload_type: str | diffusers.hooks.group_offloading.GroupOffloadingType = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage: bool = Falseoffload_to_disk_path: str | None = Noneblock_modules: list[str] | None = Noneexclude_kwargs: list[str] | None = None )

Paramètres

  • module (torch.nn.Module) — Le module auquel le group offloading est appliqué.
  • onload_device (torch.device) — L'appareil sur lequel le groupe de modules est chargé.
  • offload_device (torch.device, par défaut torch.device("cpu")) — L'appareil sur lequel le groupe de modules est déchargé. Il s'agit généralement du CPU. La valeur par défaut est le CPU.
  • offload_type (str ou GroupOffloadingType, par défaut “block_level”) — Le type de déchargement à appliquer. Peut être “block_level” ou “leaf_level”. La valeur par défaut est “block_level”.
  • offload_to_disk_path (str, facultatif, par défaut None) — Le chemin du répertoire où les paramètres seront déchargés. Définir cette option peut être utile dans des environnements à mémoire RAM limitée où un compromis raisonnable entre vitesse et mémoire est recherché.
  • num_blocks_per_group (int, facultatif) — Le nombre de blocs par groupe lors de l'utilisation de offload_type=“block_level”. Ce paramètre est requis lorsque offload_type=“block_level” est utilisé.
  • non_blocking (bool, par défaut False) — Si True, le déchargement et le rechargement sont effectués avec un transfert de données non bloquant.
  • use_stream (bool, par défaut False) — Si True, le déchargement et le rechargement sont effectués de manière asynchrone à l'aide d'un flux CUDA. Cela peut être utile pour superposer le calcul et le transfert de données.
  • record_stream (bool, par défaut False) — Lorsqu’il est activé avec use_stream, il marque le tenseur courant comme ayant été utilisé par ce flux. C’est plus rapide au prix d’une utilisation légèrement plus importante de la mémoire. Consultez les docs officielles de PyTorch pour plus de détails.
  • low_cpu_mem_usage (bool, par défaut False) — Si True, l'utilisation de la mémoire CPU est minimisée en épinglant les tenseurs à la volée au lieu de les épingler à l'avance. Cette option n'a d'importance que lors de l'utilisation du déchargement CPU en flux (c'est-à-dire use_stream=True). Cela peut être utile lorsque la mémoire CPU est un goulot d'étranglement, mais peut contrebalancer les avantages de l'utilisation de flux.
  • block_modules (list[str], facultatif) — Liste des noms de modules qui doivent être traités comme des blocs pour le déchargement. Si fournie, seuls ces modules seront pris en compte pour le déchargement au niveau des blocs. Si non fournie, la logique de détection des blocs par défaut sera utilisée.
  • exclude_kwargs (list[str], facultatif) — Liste des clés d’arguments nommés qui ne doivent pas être traitées par send_to_device. Cela est utile pour les états mutables, comme les listes de cache, qui doivent conserver leur identité d’objet entre les passages en avant. Si non fourni, sera inféré à partir de l’attribut _skip_keys du module s’il existe.

Applique le group offloading aux couches internes d'un module torch.nn.Module. Pour comprendre ce qu'est le group offloading et où il est bénéfique, il faut d'abord fournir un contexte sur le fonctionnement des autres méthodes de offloading prises en charge.

En général, le déchargement est effectué à deux niveaux :

  • Au niveau du module : dans Diffusers, cela peut être activé à l'aide de la méthode ModelMixin::enable_model_cpu_offload(). Elle fonctionne en déplaçant chaque composant d'un pipeline vers le CPU pour le stockage, puis en le rechargeant sur l'appareil d'accélération lorsqu'il est nécessaire pour le calcul. Cette méthode est plus efficace en termes de mémoire que de conserver tous les composants sur l'accélérateur, mais les exigences en mémoire restent tout de même assez élevées. Pour que cette méthode fonctionne, il faut une quantité de mémoire équivalente à la taille du modèle dans le type de données d'exécution + la taille des tenseurs d'activation intermédiaires les plus grands, afin de pouvoir terminer le passage avant.
  • Niveau feuille : dans Diffusers, cela peut être activé à l'aide de la méthode ModelMixin::enable_sequential_cpu_offload(). Elle fonctionne en déplaçant les paramètres de niveau feuille les plus bas du graphe de calcul vers le CPU pour le stockage, et en ne chargeant que les feuilles sur le dispositif d'accélération pour le calcul. Cela utilise la plus faible quantité de mémoire d'accélérateur, mais peut être plus lent en raison du nombre excessif de synchronisations de dispositifs.

Le group offloading est un compromis entre les deux méthodes. Il fonctionne en déplaçant des groupes de couches internes, (soit torch.nn.ModuleList ou torch.nn.Sequential). Cette méthode utilise moins de mémoire que le offloading au niveau du module. Elle est également plus rapide que le offloading au niveau des feuilles/séquentiel, car le nombre de synchronisations de périphérique est réduit.

Une autre fonctionnalité prise en charge (pour les appareils CUDA prenant en charge les flux de transfert de données asynchrones) est la possibilité de superposer le transfert de données et le calcul afin de réduire le temps d'exécution global par rapport au déchargement séquentiel. Cela est activé grâce au préchargement des couches avec des flux, c'est-à-dire que la couche à exécuter ensuite commence à être chargée sur l'appareil accélérateur pendant que la couche actuelle est en cours d'exécution - cela augmente légèrement les exigences en mémoire. Notez que cette implémentation prend également en charge le déchargement au niveau des feuilles, mais peut être considérablement accélérée en utilisant des flux.

Exemple :

>>> from diffusers import CogVideoXTransformer3DModel
>>> from diffusers.hooks import apply_group_offloading

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

>>> apply_group_offloading(
...     transformer,
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="block_level",
...     num_blocks_per_group=2,
...     use_stream=True,
... )
Update on GitHub

←Couches de normalisation personnalisées Processeur d'images VAE→