Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /fr /api /models /controlnet_sparsectrl.md

mishig

2 days ago

preview code

download

raw

14.8 kB

# SparseControlNetModel

SparseControlNetModel est une implémentation de ControlNet pour [AnimateDiff](https://huggingface.co/papers/2307.04725).

ControlNet a été introduit dans [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) par Lvmin Zhang, Anyi Rao et Maneesh Agrawala.

La version SparseCtrl de ControlNet a été introduite dans [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) pour réaliser une génération contrôlée dans les modèles de diffusion texte-vers-vidéo, par Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin et Bo Dai.

L'abstract de l'article est :

*Le développement du texte-vers-vidéo (T2V), c'est-à-dire la génération de vidéos à partir d'un prompt textuel donné, a connu des avancées significatives ces dernières années. Cependant, s'appuyer uniquement sur des prompts textuels conduit souvent à une composition d'images ambiguë en raison de l'incertitude spatiale. La communauté de recherche exploite donc les signaux de structure denses, par exemple des séquences de profondeur ou de contours par image, pour améliorer la contrôlabilité, ce qui augmente en conséquence la charge d'inférence. Dans ce travail, nous présentons SparseCtrl pour permettre un contrôle de structure flexible avec des signaux temporellement espacés, nécessitant uniquement une ou quelques entrées, comme le montre la Figure 1. Il intègre un encodeur de condition supplémentaire pour traiter ces signaux espacés tout en laissant le modèle T2V pré-entraîné inchangé. L'approche proposée est compatible avec diverses modalités, y compris les croquis, les cartes de profondeur et les images RGB, offrant un contrôle plus pratique pour la génération de vidéos et favorisant des applications telles que le storyboarding, le rendu de profondeur, l'animation par images clés et l'interpolation. Des expériences étendues démontrent la généralisation de SparseCtrl sur les générateurs T2V originaux et personnalisés. Les codes et les modèles seront disponibles publiquement à [cette URL https](https://guoyww.github.io/projects/SparseCtrl).*

## Exemple de chargement de SparseControlNetModel

```python
import torch
from diffusers import SparseControlNetModel
# fp32 variant in float16
# 1. Scribble checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-scribble", dtype=torch.float16)
# 2. RGB checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-rgb", dtype=torch.float16)
# For loading fp16 variant, pass `variant="fp16"` as an additional parameter
```

## SparseControlNetModel[[diffusers.SparseControlNetModel]]

#### diffusers.SparseControlNetModel[[diffusers.SparseControlNetModel]]

```python
diffusers.SparseControlNetModel(in_channels: int = 4, conditioning_channels: int = 4, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion'), only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple[int, ...] = (320, 640, 1280, 1280), layers_per_block: int = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, act_fn: str = 'silu', norm_num_groups: int | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int = 768, transformer_layers_per_block: int | tuple[int, ...] = 1, transformer_layers_per_mid_block: int | tuple[int] | None = None, temporal_transformer_layers_per_block: int | tuple[int, ...] = 1, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), global_pool_conditions: bool = False, controlnet_conditioning_channel_order: str = 'rgb', motion_max_seq_length: int = 32, motion_num_attention_heads: int = 8, concat_conditioning_mask: bool = True, use_simplified_condition_embedding: bool = True)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L97)

**Paramètres :**

in_channels (`int`, par défaut 4) : Le nombre de canaux dans l'échantillon d'entrée.
conditioning_channels (`int`, par défaut 4) : Le nombre de canaux d'entrée dans le module d'incorporation conditionnelle de controlnet. Si `concat_condition_embedding` est True, la valeur fournie ici est incrémentée de 1.

flip_sin_to_cos (`bool`, par défaut `True`) : Indique s'il faut inverser le sin en cos dans l'encodage temporel.
freq_shift (`int`, par défaut 0) : Le décalage de fréquence à appliquer à l'embedding temporel.

down_block_types (`tuple[str]`, par défaut `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : Le tuple de blocs de downsampling à utiliser.

only_cross_attention (`bool | tuple[bool]`, par défaut `False`) --

block_out_channels (`tuple[int]`, par défaut `(320, 640, 1280, 1280)`) : Le tuple des canaux de sortie pour chaque bloc.

layers_per_block (`int`, par défaut 2) : Le nombre de couches par bloc.

downsample_padding (`int`, par défaut 1) : Le padding à utiliser pour la convolution de downsampling.
mid_block_scale_factor (`float`, par défaut 1) : Le facteur d'échelle à utiliser pour le bloc intermédiaire.

act_fn (`str`, par défaut "silu") : La fonction d'activation à utiliser.
norm_num_groups (`int`, *facultatif*, valeur par défaut 32) : Le nombre de groupes à utiliser pour la normalisation. Si None, les couches de normalisation et d'activation sont ignorées lors du post-traitement.
norm_eps (`float`, par défaut 1e-5) : L'épsilon à utiliser pour la normalisation.

cross_attention_dim (`int`, par défaut 1280) : La dimension des fonctionnalités d'attention croisée.

transformer_layers_per_block (`int` ou `tuple[int]`, *facultatif*, valeur par défaut 1) : Le nombre de blocs de transformateur de type `BasicTransformerBlock`. Ne concerne que `~models.unet_2d_blocks.CrossAttnDownBlock2D`, `~models.unet_2d_blocks.CrossAttnUpBlock2D`, `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.
transformer_layers_per_mid_block (`int` ou `tuple[int]`, *facultatif*, valeur par défaut : 1) : Le nombre de couches de transformateur à utiliser dans chaque couche du bloc central.
attention_head_dim (`int` ou `tuple[int]`, par défaut 8) : La dimension des têtes d'attention.
num_attention_heads (`int` ou `tuple[int]`, *facultatif*) : Le nombre de têtes à utiliser pour l'attention multi-têtes.
use_linear_projection (`bool`, par défaut `False`) --
upcast_attention (`bool`, par défaut `False`) --

resnet_time_scale_shift (`str`, par défaut `"default"`) : Configuration du décalage de l'échelle temporelle pour les blocs ResNet (voir `ResnetBlock2D`). Choisissez entre `default` et `scale_shift`.

conditioning_embedding_out_channels (`tuple[int]`, par défaut `(16, 32, 96, 256)`) : Le tuple des canaux de sortie pour chaque bloc de la couche `conditioning_embedding`.

global_pool_conditions (`bool`, par défaut `False`) : TODO(Patrick) - paramètre non utilisé

controlnet_conditioning_channel_order (`str`, par défaut `rgb`) --
motion_max_seq_length (`int`, par défaut `32`) : La longueur de séquence maximale à utiliser dans le module de mouvement.

motion_num_attention_heads (`int` ou `tuple[int]`, par défaut `8`) : Le nombre de têtes à utiliser dans chaque couche d'attention du module de mouvement.
concat_conditioning_mask (`bool`, par défaut `True`) --
use_simplified_condition_embedding (`bool`, par défaut `True`) --

Un modèle SparseControlNet tel que décrit dans [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933).

#### forward[[diffusers.SparseControlNetModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, conditioning_mask: typing.Optional[torch.Tensor] = None, guess_mode: bool = False, return_dict: bool = True)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L534)

**Paramètres :**

sample (`torch.Tensor`) : Le tenseur d'entrée bruité.

timestep (`torch.Tensor | float | int`) : Le nombre de pas de temps pour débruitiser une entrée.

encoder_hidden_states (`torch.Tensor`) : Les états cachés de l'encodeur.

controlnet_cond (`torch.Tensor`) : Le tenseur d'entrée conditionnel de forme `(batch_size, sequence_length, hidden_size)`.

conditioning_scale (`float`, par défaut `1.0`) : Le facteur d'échelle pour les sorties de ControlNet.
timestep_cond (`torch.Tensor`, *facultatif*, valeur par défaut `None`) : Incrustations conditionnelles supplémentaires pour le pas de temps. Si fournies, les incrustations seront additionnées à la timestep_embedding transmise à travers la couche `self.time_embedding` pour obtenir les incrustations de pas de temps finales.

attention_mask (`torch.Tensor`, *facultatif*, par défaut `None`) : Un masque d'attention de forme `(batch, key_tokens)` est appliqué à `encoder_hidden_states`. Si la valeur est `1`, le masque est conservé ; sinon, si elle est `0`, il est ignoré. Le masque est converti en biais, qui ajoute de grandes valeurs négatives aux scores d'attention correspondant aux jetons « ignorés ».

conditioning_mask (`torch.Tensor`, *facultatif*, valeur par défaut `None`) : Masque facultatif indiquant quels cadres de `controlnet_cond` sont des cadres de conditionnement valides.

cross_attention_kwargs (`dict[str]`, *facultatif*, par défaut `None`) : Un dictionnaire de kwargs qui, s'il est spécifié, est transmis au `AttnProcessor`.

guess_mode (`bool`, par défaut `False`) : Dans ce mode, l'encodeur ControlNet fait de son mieux pour reconnaître le contenu de l'entrée, même si vous supprimez tous les prompts. Un `guidance_scale` compris entre 3,0 et 5,0 est recommandé.

return_dict (`bool`, par défaut `True`) : Indique s'il faut retourner un `~models.controlnet.ControlNetOutput` plutôt qu'un simple tuple.
**Retourne :** `~models.controlnet.ControlNetOutput` **ou** `tuple`
Si `return_dict` est `True`, un `~models.controlnet.ControlNetOutput` est renvoyé, sinon un tuple est renvoyé dont le premier élément est le tenseur d'échantillon.

La méthode forward du modèle [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).

#### from_unet[[diffusers.SparseControlNetModel.from_unet]]

```python
from_unet(unet: UNet2DConditionModel, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), load_weights_from_unet: bool = True, conditioning_channels: int = 3)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

**Paramètres :**

unet (`UNet2DConditionModel`) : Les poids du modèle UNet à copier vers le [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel). Toutes les options de configuration sont également copiées lorsque cela est applicable.

Instanciez un [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) à partir de [UNet2DConditionModel](/docs/diffusers/v0.43.0/fr/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.SparseControlNetModel.set_attention_slice]]

```python
set_attention_slice(slice_size: str | int | list[int])
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L469)

**Paramètres :**

slice_size (`str` ou `int` ou `list(int)`, *facultatif*, par défaut `"auto"`) : lorsque la valeur est `"auto"`, l’entrée des têtes d’attention est divisée par deux, de sorte que l’attention est calculée en deux étapes. Si la valeur est `"max"`, la quantité maximale de mémoire est économisée en n’exécutant qu’une seule tranche à la fois. Si un nombre est fourni, autant de tranches sont utilisées que `attention_head_dim // slice_size`. Dans ce cas, `attention_head_dim` doit être un multiple de `slice_size`.
Activer le calcul de l'attention par tranches.
Lorsque cette option est activée, le module d'attention divise le tenseur d'entrée en tranches pour calculer l'attention en plusieurs étapes. Cela est utile pour économiser de la mémoire au prix d'une légère diminution de la vitesse.
#### set_default_attn_processor[[diffusers.SparseControlNetModel.set_default_attn_processor]]
```python
set_default_attn_processor()
```
[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L453)
Désactive les processeurs d'attention personnalisés et définit l'implémentation d'attention par défaut.
## SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]
#### diffusers.models.controlnets.SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]
```python
diffusers.models.controlnets.SparseControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)
```
[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L44)
**Paramètres :**
down_block_res_samples (`tuple[torch.Tensor]`) : Un tuple d'activations de downsampling à différentes résolutions pour chaque bloc de downsampling. Chaque tenseur doit avoir la forme `(batch_size, channel * resolution, height //resolution, width // resolution)`. La sortie peut être utilisée pour conditionner les activations de downsampling du UNet d'origine.
mid_down_block_re_sample (`torch.Tensor`) : L'activation du bloc central (la résolution d'échantillonnage la plus basse). Chaque tenseur doit avoir la forme `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)`. La sortie peut être utilisée pour conditionner l'activation du bloc central du UNet d'origine.
La sortie de [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).

Xet Storage Details

Size:: 14.8 kB
Xet hash:: 4a2bd3eab87b399cd4f37f104b2cb378559c149c8fe2a16470e124043e79c292

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

	# SparseControlNetModel

	SparseControlNetModel est une implémentation de ControlNet pour [AnimateDiff](https://huggingface.co/papers/2307.04725).

	ControlNet a été introduit dans [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) par Lvmin Zhang, Anyi Rao et Maneesh Agrawala.

	La version SparseCtrl de ControlNet a été introduite dans [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) pour réaliser une génération contrôlée dans les modèles de diffusion texte-vers-vidéo, par Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin et Bo Dai.

	L'abstract de l'article est :

	Le développement du texte-vers-vidéo (T2V), c'est-à-dire la génération de vidéos à partir d'un prompt textuel donné, a connu des avancées significatives ces dernières années. Cependant, s'appuyer uniquement sur des prompts textuels conduit souvent à une composition d'images ambiguë en raison de l'incertitude spatiale. La communauté de recherche exploite donc les signaux de structure denses, par exemple des séquences de profondeur ou de contours par image, pour améliorer la contrôlabilité, ce qui augmente en conséquence la charge d'inférence. Dans ce travail, nous présentons SparseCtrl pour permettre un contrôle de structure flexible avec des signaux temporellement espacés, nécessitant uniquement une ou quelques entrées, comme le montre la Figure 1. Il intègre un encodeur de condition supplémentaire pour traiter ces signaux espacés tout en laissant le modèle T2V pré-entraîné inchangé. L'approche proposée est compatible avec diverses modalités, y compris les croquis, les cartes de profondeur et les images RGB, offrant un contrôle plus pratique pour la génération de vidéos et favorisant des applications telles que le storyboarding, le rendu de profondeur, l'animation par images clés et l'interpolation. Des expériences étendues démontrent la généralisation de SparseCtrl sur les générateurs T2V originaux et personnalisés. Les codes et les modèles seront disponibles publiquement à [cette URL https](https://guoyww.github.io/projects/SparseCtrl).

	## Exemple de chargement de SparseControlNetModel

	```python
	import torch
	from diffusers import SparseControlNetModel

	# fp32 variant in float16
	# 1. Scribble checkpoint
	controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-scribble", dtype=torch.float16)

	# 2. RGB checkpoint
	controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-rgb", dtype=torch.float16)

	# For loading fp16 variant, pass `variant="fp16"` as an additional parameter
	```

	## SparseControlNetModel[[diffusers.SparseControlNetModel]]

	#### diffusers.SparseControlNetModel[[diffusers.SparseControlNetModel]]

	```python
	diffusers.SparseControlNetModel(in_channels: int = 4, conditioning_channels: int = 4, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion'), only_cross_attention: bool \| tuple[bool] = False, block_out_channels: tuple[int, ...] = (320, 640, 1280, 1280), layers_per_block: int = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, act_fn: str = 'silu', norm_num_groups: int \| None = 32, norm_eps: float = 1e-05, cross_attention_dim: int = 768, transformer_layers_per_block: int \| tuple[int, ...] = 1, transformer_layers_per_mid_block: int \| tuple[int] \| None = None, temporal_transformer_layers_per_block: int \| tuple[int, ...] = 1, attention_head_dim: int \| tuple[int, ...] = 8, num_attention_heads: int \| tuple[int, ...] \| None = None, use_linear_projection: bool = False, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', conditioning_embedding_out_channels: tuple[int, ...] \| None = (16, 32, 96, 256), global_pool_conditions: bool = False, controlnet_conditioning_channel_order: str = 'rgb', motion_max_seq_length: int = 32, motion_num_attention_heads: int = 8, concat_conditioning_mask: bool = True, use_simplified_condition_embedding: bool = True)
	```

	[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L97)

	Paramètres :

	in_channels (`int`, par défaut 4) : Le nombre de canaux dans l'échantillon d'entrée.

	conditioning_channels (`int`, par défaut 4) : Le nombre de canaux d'entrée dans le module d'incorporation conditionnelle de controlnet. Si `concat_condition_embedding` est True, la valeur fournie ici est incrémentée de 1.

	flip_sin_to_cos (`bool`, par défaut `True`) : Indique s'il faut inverser le sin en cos dans l'encodage temporel.

	freq_shift (`int`, par défaut 0) : Le décalage de fréquence à appliquer à l'embedding temporel.

	down_block_types (`tuple[str]`, par défaut `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : Le tuple de blocs de downsampling à utiliser.

	only_cross_attention (`bool \| tuple[bool]`, par défaut `False`) --

	block_out_channels (`tuple[int]`, par défaut `(320, 640, 1280, 1280)`) : Le tuple des canaux de sortie pour chaque bloc.

	layers_per_block (`int`, par défaut 2) : Le nombre de couches par bloc.

	downsample_padding (`int`, par défaut 1) : Le padding à utiliser pour la convolution de downsampling.

	mid_block_scale_factor (`float`, par défaut 1) : Le facteur d'échelle à utiliser pour le bloc intermédiaire.

	act_fn (`str`, par défaut "silu") : La fonction d'activation à utiliser.

	norm_num_groups (`int`, facultatif, valeur par défaut 32) : Le nombre de groupes à utiliser pour la normalisation. Si None, les couches de normalisation et d'activation sont ignorées lors du post-traitement.

	norm_eps (`float`, par défaut 1e-5) : L'épsilon à utiliser pour la normalisation.

	cross_attention_dim (`int`, par défaut 1280) : La dimension des fonctionnalités d'attention croisée.

	transformer_layers_per_block (`int` ou `tuple[int]`, facultatif, valeur par défaut 1) : Le nombre de blocs de transformateur de type `BasicTransformerBlock`. Ne concerne que `~models.unet_2d_blocks.CrossAttnDownBlock2D`, `~models.unet_2d_blocks.CrossAttnUpBlock2D`, `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.

	transformer_layers_per_mid_block (`int` ou `tuple[int]`, facultatif, valeur par défaut : 1) : Le nombre de couches de transformateur à utiliser dans chaque couche du bloc central.

	attention_head_dim (`int` ou `tuple[int]`, par défaut 8) : La dimension des têtes d'attention.

	num_attention_heads (`int` ou `tuple[int]`, facultatif) : Le nombre de têtes à utiliser pour l'attention multi-têtes.

	use_linear_projection (`bool`, par défaut `False`) --

	upcast_attention (`bool`, par défaut `False`) --

	resnet_time_scale_shift (`str`, par défaut `"default"`) : Configuration du décalage de l'échelle temporelle pour les blocs ResNet (voir `ResnetBlock2D`). Choisissez entre `default` et `scale_shift`.

	conditioning_embedding_out_channels (`tuple[int]`, par défaut `(16, 32, 96, 256)`) : Le tuple des canaux de sortie pour chaque bloc de la couche `conditioning_embedding`.

	global_pool_conditions (`bool`, par défaut `False`) : TODO(Patrick) - paramètre non utilisé

	controlnet_conditioning_channel_order (`str`, par défaut `rgb`) --

	motion_max_seq_length (`int`, par défaut `32`) : La longueur de séquence maximale à utiliser dans le module de mouvement.

	motion_num_attention_heads (`int` ou `tuple[int]`, par défaut `8`) : Le nombre de têtes à utiliser dans chaque couche d'attention du module de mouvement.

	concat_conditioning_mask (`bool`, par défaut `True`) --

	use_simplified_condition_embedding (`bool`, par défaut `True`) --

	Un modèle SparseControlNet tel que décrit dans [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933).

	#### forward[[diffusers.SparseControlNetModel.forward]]

	```python
	forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, cross_attention_kwargs: dict[str, typing.Any] \| None = None, conditioning_mask: typing.Optional[torch.Tensor] = None, guess_mode: bool = False, return_dict: bool = True)
	```

	[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L534)

	Paramètres :

	sample (`torch.Tensor`) : Le tenseur d'entrée bruité.

	timestep (`torch.Tensor \| float \| int`) : Le nombre de pas de temps pour débruitiser une entrée.

	encoder_hidden_states (`torch.Tensor`) : Les états cachés de l'encodeur.

	controlnet_cond (`torch.Tensor`) : Le tenseur d'entrée conditionnel de forme `(batch_size, sequence_length, hidden_size)`.

	conditioning_scale (`float`, par défaut `1.0`) : Le facteur d'échelle pour les sorties de ControlNet.

	timestep_cond (`torch.Tensor`, facultatif, valeur par défaut `None`) : Incrustations conditionnelles supplémentaires pour le pas de temps. Si fournies, les incrustations seront additionnées à la timestep_embedding transmise à travers la couche `self.time_embedding` pour obtenir les incrustations de pas de temps finales.

	attention_mask (`torch.Tensor`, facultatif, par défaut `None`) : Un masque d'attention de forme `(batch, key_tokens)` est appliqué à `encoder_hidden_states`. Si la valeur est `1`, le masque est conservé ; sinon, si elle est `0`, il est ignoré. Le masque est converti en biais, qui ajoute de grandes valeurs négatives aux scores d'attention correspondant aux jetons « ignorés ».

	conditioning_mask (`torch.Tensor`, facultatif, valeur par défaut `None`) : Masque facultatif indiquant quels cadres de `controlnet_cond` sont des cadres de conditionnement valides.

	cross_attention_kwargs (`dict[str]`, facultatif, par défaut `None`) : Un dictionnaire de kwargs qui, s'il est spécifié, est transmis au `AttnProcessor`.

	guess_mode (`bool`, par défaut `False`) : Dans ce mode, l'encodeur ControlNet fait de son mieux pour reconnaître le contenu de l'entrée, même si vous supprimez tous les prompts. Un `guidance_scale` compris entre 3,0 et 5,0 est recommandé.

	return_dict (`bool`, par défaut `True`) : Indique s'il faut retourner un `~models.controlnet.ControlNetOutput` plutôt qu'un simple tuple.

	Retourne : `~models.controlnet.ControlNetOutput` ou `tuple`

	Si `return_dict` est `True`, un `~models.controlnet.ControlNetOutput` est renvoyé, sinon un tuple est renvoyé dont le premier élément est le tenseur d'échantillon.

	La méthode forward du modèle [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).

	#### from_unet[[diffusers.SparseControlNetModel.from_unet]]

	```python
	from_unet(unet: UNet2DConditionModel, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] \| None = (16, 32, 96, 256), load_weights_from_unet: bool = True, conditioning_channels: int = 3)
	```

	[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

	Paramètres :

	unet (`UNet2DConditionModel`) : Les poids du modèle UNet à copier vers le [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel). Toutes les options de configuration sont également copiées lorsque cela est applicable.

	Instanciez un [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) à partir de [UNet2DConditionModel](/docs/diffusers/v0.43.0/fr/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

	#### set_attention_slice[[diffusers.SparseControlNetModel.set_attention_slice]]

	```python
	set_attention_slice(slice_size: str \| int \| list[int])
	```

	[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L469)

	Paramètres :

	slice_size (`str` ou `int` ou `list(int)`, facultatif, par défaut `"auto"`) : lorsque la valeur est `"auto"`, l’entrée des têtes d’attention est divisée par deux, de sorte que l’attention est calculée en deux étapes. Si la valeur est `"max"`, la quantité maximale de mémoire est économisée en n’exécutant qu’une seule tranche à la fois. Si un nombre est fourni, autant de tranches sont utilisées que `attention_head_dim // slice_size`. Dans ce cas, `attention_head_dim` doit être un multiple de `slice_size`.

	Activer le calcul de l'attention par tranches.

	Lorsque cette option est activée, le module d'attention divise le tenseur d'entrée en tranches pour calculer l'attention en plusieurs étapes. Cela est utile pour économiser de la mémoire au prix d'une légère diminution de la vitesse.

	#### set_default_attn_processor[[diffusers.SparseControlNetModel.set_default_attn_processor]]

	```python
	set_default_attn_processor()
	```

	[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L453)

	Désactive les processeurs d'attention personnalisés et définit l'implémentation d'attention par défaut.

	## SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

	#### diffusers.models.controlnets.SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

	```python
	diffusers.models.controlnets.SparseControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)
	```

	[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L44)

	Paramètres :

	down_block_res_samples (`tuple[torch.Tensor]`) : Un tuple d'activations de downsampling à différentes résolutions pour chaque bloc de downsampling. Chaque tenseur doit avoir la forme `(batch_size, channel * resolution, height //resolution, width // resolution)`. La sortie peut être utilisée pour conditionner les activations de downsampling du UNet d'origine.

	mid_down_block_re_sample (`torch.Tensor`) : L'activation du bloc central (la résolution d'échantillonnage la plus basse). Chaque tenseur doit avoir la forme `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)`. La sortie peut être utilisée pour conditionner l'activation du bloc central du UNet d'origine.

	La sortie de [SparseControlNetModel](/docs/diffusers/v0.43.0/fr/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).