Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /fr /api /utilities.md

mishig

1 day ago

preview code

download

raw

19.4 kB

# Utilitaires

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

## numpy_to_pil[[diffusers.utils.numpy_to_pil]]

#### diffusers.utils.numpy_to_pil[[diffusers.utils.numpy_to_pil]]

```python
diffusers.utils.numpy_to_pil(images)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L35)

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

## pt_to_pil[[diffusers.utils.pt_to_pil]]

#### diffusers.utils.pt_to_pil[[diffusers.utils.pt_to_pil]]

```python
diffusers.utils.pt_to_pil(images)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L25)

Convertir une image torch en image PIL.

## load_image[[diffusers.utils.load_image]]

#### diffusers.utils.load_image[[diffusers.utils.load_image]]

```python
diffusers.utils.load_image(image: str | PIL.Image.Image, convert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L14)

**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]]
#### diffusers.utils.load_video[[diffusers.utils.load_video]]
```python
diffusers.utils.load_video(video: str, convert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = None, return_fps: bool = False)
```
[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L57)
**Paramètres :**
video (`str`) : Une URL ou un chemin vers une vidéo à convertir en liste d'images au format PIL.
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*, valeur par défaut `False`) : Indique s'il faut également renvoyer le taux d'images par seconde (frame rate) auquel la vidéo a été encodée. Nécessaire pour les pipelines qui rééchantillonnent l'entrée au taux d'images par seconde auquel leur modèle fonctionne, 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]]
#### diffusers.utils.export_to_gif[[diffusers.utils.export_to_gif]]
```python
diffusers.utils.export_to_gif(image: list[PIL.Image.Image], output_gif_path: str = None, fps: int = 10)
```
[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L37)
## export_to_video[[diffusers.utils.export_to_video]]
#### diffusers.utils.export_to_video[[diffusers.utils.export_to_video]]
```python
diffusers.utils.export_to_video(video_frames: list[np.ndarray] | list[PIL.Image.Image], output_video_path: str = None, fps: int = 10, quality: float = 5.0, bitrate: int | None = None, macro_block_size: int | None = 16)
```
[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L150)
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éfinissez 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. L’utilisation du paramètre de débit binaire variable `quality` plutôt que la spécification d’un débit binaire fixe avec ce paramètre produit des vidéos de meilleure qualité avec des tailles de fichier plus petites.

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 des 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]]

#### diffusers.utils.encode_video[[diffusers.utils.encode_video]]

```python
diffusers.utils.encode_video(video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor'], fps: int, output_path: str, audio: 'torch.Tensor' | None = None, audio_sample_rate: int | None = None, video_chunks_number: int = 1)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L304)

**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`) : Le 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*, valeur 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]]

#### diffusers.utils.make_image_grid[[diffusers.utils.make_image_grid]]

```python
diffusers.utils.make_image_grid(images: list[PIL.Image.Image], rows: int, cols: int, resize: int = None)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L51)

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

## randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]
#### diffusers.utils.torch_utils.randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]
```python
diffusers.utils.torch_utils.randn_tensor(shape: tuple | list, generator: list['torch.Generator'] | 'torch.Generator' | None = None, device: str | 'torch.device' | None = None, dtype: 'torch.dtype' | None = None, layout: 'torch.layout' | None = None)
```
[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L61)
Fonction utilitaire pour créer des tenseurs aléatoires sur le `device` souhaité avec le `dtype` souhaité. En passant 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[[diffusers.utils.torch_utils.TorchDeviceBackend]]

#### diffusers.utils.torch_utils.TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

```python
diffusers.utils.torch_utils.TorchDeviceBackend(device: str | torch.device | None = None)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L228)

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[[diffusers.utils.torch_utils.TorchDeviceBackend.max_memory_allocated]]
```python
max_memory_allocated()
```
[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L291)
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[[diffusers.utils.torch_utils.TorchDeviceBackend.mem_get_info]]

```python
mem_get_info()
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L279)

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

## apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

#### diffusers.hooks.apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

```python
diffusers.hooks.apply_layerwise_casting(module: Module, storage_dtype: dtype, compute_dtype: dtype, skip_modules_pattern: str | tuple[str, ...] = 'auto', skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = None, non_blocking: bool = False)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/layerwise_casting.py#L101)

**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 de 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 tout nn.Module utilisant des couches diffusers ou des primitives pytorch.
Exemple :
```python
>>> 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]]
#### diffusers.hooks.apply_group_offloading[[diffusers.hooks.apply_group_offloading]]
```python
diffusers.hooks.apply_group_offloading(module: Module, onload_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 = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage: bool = False, offload_to_disk_path: str | None = None, block_modules: list[str] | None = None, exclude_kwargs: list[str] | None = None)
```
[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/group_offloading.py#L567)
**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*, valeur par défaut `None`) : Le chemin vers le 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 actuel 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](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html) 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 pré-épingler. 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 par mot-clé 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, il sera déduit 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 dans quels cas 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 lorsque cela 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 disposer d'une 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 des modules. 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 :
```python
>>> 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,
... )
```

Xet Storage Details

Size:: 19.4 kB
Xet hash:: 485e25e7b286202ac1262b590c1d0f335b2fa4d7c7807899a32b5f801f56abb3

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# Utilitaires

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

	## numpy_to_pil[[diffusers.utils.numpy_to_pil]]

	#### diffusers.utils.numpy_to_pil[[diffusers.utils.numpy_to_pil]]

	```python
	diffusers.utils.numpy_to_pil(images)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L35)

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

	## pt_to_pil[[diffusers.utils.pt_to_pil]]

	#### diffusers.utils.pt_to_pil[[diffusers.utils.pt_to_pil]]

	```python
	diffusers.utils.pt_to_pil(images)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L25)

	Convertir une image torch en image PIL.

	## load_image[[diffusers.utils.load_image]]

	#### diffusers.utils.load_image[[diffusers.utils.load_image]]

	```python
	diffusers.utils.load_image(image: str \| PIL.Image.Image, convert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L14)

	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]]

	#### diffusers.utils.load_video[[diffusers.utils.load_video]]

	```python
	diffusers.utils.load_video(video: str, convert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = None, return_fps: bool = False)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L57)

	Paramètres :

	video (`str`) : Une URL ou un chemin vers une vidéo à convertir en liste d'images au format PIL.

	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, valeur par défaut `False`) : Indique s'il faut également renvoyer le taux d'images par seconde (frame rate) auquel la vidéo a été encodée. Nécessaire pour les pipelines qui rééchantillonnent l'entrée au taux d'images par seconde auquel leur modèle fonctionne, 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]]

	#### diffusers.utils.export_to_gif[[diffusers.utils.export_to_gif]]

	```python
	diffusers.utils.export_to_gif(image: list[PIL.Image.Image], output_gif_path: str = None, fps: int = 10)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L37)

	## export_to_video[[diffusers.utils.export_to_video]]

	#### diffusers.utils.export_to_video[[diffusers.utils.export_to_video]]

	```python
	diffusers.utils.export_to_video(video_frames: list[np.ndarray] \| list[PIL.Image.Image], output_video_path: str = None, fps: int = 10, quality: float = 5.0, bitrate: int \| None = None, macro_block_size: int \| None = 16)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L150)

	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éfinissez 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. L’utilisation du paramètre de débit binaire variable `quality` plutôt que la spécification d’un débit binaire fixe avec ce paramètre produit des vidéos de meilleure qualité avec des tailles de fichier plus petites.

	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 des 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]]

	#### diffusers.utils.encode_video[[diffusers.utils.encode_video]]

	```python
	diffusers.utils.encode_video(video: list[PIL.Image.Image] \| np.ndarray \| 'torch.Tensor' \| Iterator['torch.Tensor'], fps: int, output_path: str, audio: 'torch.Tensor' \| None = None, audio_sample_rate: int \| None = None, video_chunks_number: int = 1)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L304)

	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`) : Le 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, valeur 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]]

	#### diffusers.utils.make_image_grid[[diffusers.utils.make_image_grid]]

	```python
	diffusers.utils.make_image_grid(images: list[PIL.Image.Image], rows: int, cols: int, resize: int = None)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L51)

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

	## randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

	#### diffusers.utils.torch_utils.randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

	```python
	diffusers.utils.torch_utils.randn_tensor(shape: tuple \| list, generator: list['torch.Generator'] \| 'torch.Generator' \| None = None, device: str \| 'torch.device' \| None = None, dtype: 'torch.dtype' \| None = None, layout: 'torch.layout' \| None = None)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L61)

	Fonction utilitaire pour créer des tenseurs aléatoires sur le `device` souhaité avec le `dtype` souhaité. En passant 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[[diffusers.utils.torch_utils.TorchDeviceBackend]]

	#### diffusers.utils.torch_utils.TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

	```python
	diffusers.utils.torch_utils.TorchDeviceBackend(device: str \| torch.device \| None = None)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L228)

	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[[diffusers.utils.torch_utils.TorchDeviceBackend.max_memory_allocated]]

	```python
	max_memory_allocated()
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L291)

	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[[diffusers.utils.torch_utils.TorchDeviceBackend.mem_get_info]]

	```python
	mem_get_info()
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L279)

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

	## apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

	#### diffusers.hooks.apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

	```python
	diffusers.hooks.apply_layerwise_casting(module: Module, storage_dtype: dtype, compute_dtype: dtype, skip_modules_pattern: str \| tuple[str, ...] = 'auto', skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] \| None = None, non_blocking: bool = False)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/layerwise_casting.py#L101)

	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 de 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 tout nn.Module utilisant des couches diffusers ou des primitives pytorch.

	Exemple :

	```python
	>>> 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]]

	#### diffusers.hooks.apply_group_offloading[[diffusers.hooks.apply_group_offloading]]

	```python
	diffusers.hooks.apply_group_offloading(module: Module, onload_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 = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage: bool = False, offload_to_disk_path: str \| None = None, block_modules: list[str] \| None = None, exclude_kwargs: list[str] \| None = None)
	```

	[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/group_offloading.py#L567)

	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, valeur par défaut `None`) : Le chemin vers le 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 actuel 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](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html) 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 pré-épingler. 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 par mot-clé 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, il sera déduit 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 dans quels cas 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 lorsque cela 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 disposer d'une 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 des modules. 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 :
	```python
	>>> 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,
	... )
	```