Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

2 days ago

preview code

download

raw

19.2 kB

# SparseControlNetModel

SparseControlNetModel — это реализация ControlNet для [AnimateDiff](https://huggingface.co/papers/2307.04725).

ControlNet был представлен в статье [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) авторами Lvmin Zhang, Anyi Rao и Maneesh Agrawala.

Версия ControlNet SparseCtrl была представлена в статье [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) для достижения контролируемой генерации в диффузионных моделях «текст-в-видео» авторами Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin и Bo Dai.

Аннотация из статьи:

*Развитие технологий генерации видео по тексту (T2V), то есть создания видео по заданному текстовому запросу, значительно продвинулось в последние годы. Однако опора исключительно на текстовые запросы часто приводит к неоднозначной композиции кадров из-за пространственной неопределённости. В связи с этим исследовательское сообщество использует плотные структурные сигналы, например, последовательности глубины или контуров для каждого кадра, чтобы повысить управляемость, что, соответственно, увеличивает нагрузку на этап инференса. В данной работе мы представляем SparseCtrl, который обеспечивает гибкое структурное управление с помощью временных разреженных сигналов, требуя лишь одного или нескольких входных данных, как показано на рисунке 1. Он включает дополнительный кодировщик условий для обработки этих разреженных сигналов, при этом предварительно обученная T2V-модель остаётся неизменной. Предложенный подход совместим с различными модальностями, включая эскизы, карты глубины и RGB-изображения, что обеспечивает более практичное управление генерацией видео и способствует применению таких задач, как раскадровка, рендеринг глубины, анимация по ключевым кадрам и интерполяция. Обширные эксперименты демонстрируют обобщающую способность SparseCtrl как для оригинальных, так и для персонализированных T2V-генераторов. Код и модели будут общедоступны по [этой ссылке](https://guoyww.github.io/projects/SparseCtrl).*

## Пример загрузки 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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L97)

**Параметры:**

in_channels (`int`, по умолчанию 4) : Количество каналов во входном образце.
conditioning_channels (`int`, по умолчанию 4) : Количество входных каналов в модуле условного встраивания controlnet. Если `concat_condition_embedding` равно True, значение, указанное здесь, увеличивается на 1.

flip_sin_to_cos (`bool`, по умолчанию `True`) : Нужно ли заменить sin на cos во временном эмбеддинге.
freq_shift (`int`, по умолчанию 0) : Сдвиг частоты, применяемый к временному эмбеддингу.

down_block_types (`tuple[str]`, по умолчанию `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : Кортеж блоков downsampling, которые следует использовать.

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) : Отступ (padding), используемый для свёртки при уменьшении разрешения.
mid_block_scale_factor (`float`, по умолчанию 1) : Коэффициент масштабирования для среднего блока.

act_fn (`str`, по умолчанию "silu") : функция активации, которую следует использовать.
norm_num_groups (`int`, *optional*, по умолчанию 32) : Количество групп, используемых для нормализации. Если значение равно None, слои нормализации и активации пропускаются на этапе постобработки.
norm_eps (`float`, по умолчанию 1e-5) : Эпсилон, используемый для нормализации.

cross_attention_dim (`int`, по умолчанию 1280) : Размерность признаков кросс-внимания.

transformer_layers_per_block (`int` или `tuple[int]`, *необязательный*, по умолчанию 1) : Количество блоков трансформера типа `BasicTransformerBlock`. Актуально только для `~models.unet_2d_blocks.CrossAttnDownBlock2D`, `~models.unet_2d_blocks.CrossAttnUpBlock2D`, `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.
transformer_layers_per_mid_block (`int` или `tuple[int]`, *необязательный*, по умолчанию 1) : Количество трансформерных слоёв, используемых в каждом слое среднего блока.
attention_head_dim (`int` или `tuple[int]`, по умолчанию 8) : Размерность головок внимания.
num_attention_heads (`int` или `tuple[int]`, *необязательный*) : Количество голов, используемых для многоголовного внимания.
use_linear_projection (`bool`, по умолчанию `False`) --
upcast_attention (`bool`, по умолчанию `False`) --

resnet_time_scale_shift (`str`, по умолчанию `"default"`) : Настройка сдвига масштаба времени для блоков ResNet (см. `ResnetBlock2D`). Выберите `default` или `scale_shift`.

conditioning_embedding_out_channels (`tuple[int]`, по умолчанию `(16, 32, 96, 256)`) : Кортеж количества выходных каналов для каждого блока в слое `conditioning_embedding`.

global_pool_conditions (`bool`, по умолчанию `False`) : TODO(Patrick) - неиспользуемый параметр

controlnet_conditioning_channel_order (`str`, по умолчанию `rgb`) --
motion_max_seq_length (`int`, по умолчанию `32`) : Максимальная длина последовательности, используемая в модуле движения.

motion_num_attention_heads (`int` или `tuple[int]`, по умолчанию `8`) : Количество голок, используемых в каждом слое внимания motion-модуля.
concat_conditioning_mask (`bool`, по умолчанию `True`) --
use_simplified_condition_embedding (`bool`, по умолчанию `True`) --

Модель SparseControlNet, описанная в статье [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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L534)

**Параметры:**

sample (`torch.Tensor`) : Шумовой входной тензор.

timestep (`torch.Tensor | float | int`) : Количество шагов для денойзинга входных данных.

encoder_hidden_states (`torch.Tensor`) : Скрытые состояния энкодера.

controlnet_cond (`torch.Tensor`) : Условный входной тензор формы `(batch_size, sequence_length, hidden_size)`.

conditioning_scale (`float`, по умолчанию `1.0`) : Коэффициент масштабирования для выходов ControlNet.
timestep_cond (`torch.Tensor`, *необязательный*, по умолчанию `None`) : Дополнительные условные эмбеддинги для временного шага. Если предоставлены, эмбеддинги будут сложены с timestep_embedding, переданным через слой `self.time_embedding`, чтобы получить итоговые эмбеддинги временного шага.

attention_mask (`torch.Tensor`, *необязательный*, по умолчанию `None`) : маска внимания формы `(batch, key_tokens)` применяется к `encoder_hidden_states`. Если значение равно `1`, маска сохраняется, иначе, если равно `0`, она отбрасывается. Маска преобразуется в смещение (bias), которое добавляет большие отрицательные значения к оценкам внимания, соответствующим токенам, подлежащим отбрасыванию.

conditioning_mask (`torch.Tensor`, *необязательный*, по умолчанию `None`) : Необязательная маска, указывающая, какие кадры в `controlnet_cond` являются валидными кадрами для условного формирования.

cross_attention_kwargs (`dict[str]`, *необязательный*, по умолчанию `None`) : Словарь kwargs, который при указании передается в `AttnProcessor`.

guess_mode (`bool`, по умолчанию `False`) : В этом режиме энкодер ControlNet прилагает все усилия, чтобы распознать содержимое входных данных, даже если вы удалите все промпты. Рекомендуется значение `guidance_scale` от 3.0 до 5.0.

return_dict (`bool`, по умолчанию `True`) : Возвращать ли `~models.controlnet.ControlNetOutput` вместо обычного кортежа.
**Возвращает:** `~models.controlnet.ControlNetOutput` **или** `tuple`
Если `return_dict` равно `True`, возвращается `~models.controlnet.ControlNetOutput`, иначе возвращается кортеж, первым элементом которого является тензор сэмпла.

Метод forward модели [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

**Параметры:**

unet (`UNet2DConditionModel`) : веса модели UNet, которые необходимо скопировать в [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel). Все применимые параметры конфигурации также копируются.

Создайте экземпляр [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) из [UNet2DConditionModel](/docs/diffusers/v0.43.0/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L469)

**Параметры:**

slice_size (`str` или `int` или `list(int)`, *необязательный*, по умолчанию `"auto"`) : Если указано `"auto"`, вход для головок внимания уменьшается вдвое, и внимание вычисляется в два этапа. Если указано `"max"`, экономится максимальное количество памяти за счёт обработки только одного среза за раз. Если указано число, используется столько срезов, сколько получается от `attention_head_dim // slice_size`. В этом случае `attention_head_dim` должно быть кратным `slice_size`.
Включить вычисление внимания с нарезкой.
Когда эта опция включена, модуль внимания разбивает входной тензор на фрагменты, чтобы вычислять внимание в несколько шагов. Это полезно для экономии памяти ценой небольшого снижения скорости.
#### set_default_attn_processor[[diffusers.SparseControlNetModel.set_default_attn_processor]]
```python
set_default_attn_processor()
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L453)
Отключает пользовательские обработчики внимания и устанавливает реализацию внимания по умолчанию.
## 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)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L44)
**Параметры:**
down_block_res_samples (`tuple[torch.Tensor]`) : Кортеж активаций даунсемплинга на разных разрешениях для каждого блока даунсемплинга. Каждая тензор должна иметь форму `(batch_size, channel * resolution, height //resolution, width // resolution)`. Выходные данные можно использовать для условного формирования активаций даунсемплинга исходной UNet.
mid_down_block_re_sample (`torch.Tensor`) : Активация среднего блока (с наименьшим разрешением сэмпла). Каждая тензорная величина должна иметь форму `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)`. Выходные данные можно использовать для условного формирования активации среднего блока исходного UNet.
Вывод [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).

Xet Storage Details

Size:: 19.2 kB
Xet hash:: 697e2d5d2faf3737778f548d4e968d25eff57306983877734f97dc1bfe9af8ea

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

	# SparseControlNetModel

	SparseControlNetModel — это реализация ControlNet для [AnimateDiff](https://huggingface.co/papers/2307.04725).

	ControlNet был представлен в статье [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) авторами Lvmin Zhang, Anyi Rao и Maneesh Agrawala.

	Версия ControlNet SparseCtrl была представлена в статье [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) для достижения контролируемой генерации в диффузионных моделях «текст-в-видео» авторами Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin и Bo Dai.

	Аннотация из статьи:

	Развитие технологий генерации видео по тексту (T2V), то есть создания видео по заданному текстовому запросу, значительно продвинулось в последние годы. Однако опора исключительно на текстовые запросы часто приводит к неоднозначной композиции кадров из-за пространственной неопределённости. В связи с этим исследовательское сообщество использует плотные структурные сигналы, например, последовательности глубины или контуров для каждого кадра, чтобы повысить управляемость, что, соответственно, увеличивает нагрузку на этап инференса. В данной работе мы представляем SparseCtrl, который обеспечивает гибкое структурное управление с помощью временных разреженных сигналов, требуя лишь одного или нескольких входных данных, как показано на рисунке 1. Он включает дополнительный кодировщик условий для обработки этих разреженных сигналов, при этом предварительно обученная T2V-модель остаётся неизменной. Предложенный подход совместим с различными модальностями, включая эскизы, карты глубины и RGB-изображения, что обеспечивает более практичное управление генерацией видео и способствует применению таких задач, как раскадровка, рендеринг глубины, анимация по ключевым кадрам и интерполяция. Обширные эксперименты демонстрируют обобщающую способность SparseCtrl как для оригинальных, так и для персонализированных T2V-генераторов. Код и модели будут общедоступны по [этой ссылке](https://guoyww.github.io/projects/SparseCtrl).

	## Пример загрузки 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)
	```

	[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L97)

	Параметры:

	in_channels (`int`, по умолчанию 4) : Количество каналов во входном образце.

	conditioning_channels (`int`, по умолчанию 4) : Количество входных каналов в модуле условного встраивания controlnet. Если `concat_condition_embedding` равно True, значение, указанное здесь, увеличивается на 1.

	flip_sin_to_cos (`bool`, по умолчанию `True`) : Нужно ли заменить sin на cos во временном эмбеддинге.

	freq_shift (`int`, по умолчанию 0) : Сдвиг частоты, применяемый к временному эмбеддингу.

	down_block_types (`tuple[str]`, по умолчанию `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : Кортеж блоков downsampling, которые следует использовать.

	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) : Отступ (padding), используемый для свёртки при уменьшении разрешения.

	mid_block_scale_factor (`float`, по умолчанию 1) : Коэффициент масштабирования для среднего блока.

	act_fn (`str`, по умолчанию "silu") : функция активации, которую следует использовать.

	norm_num_groups (`int`, optional, по умолчанию 32) : Количество групп, используемых для нормализации. Если значение равно None, слои нормализации и активации пропускаются на этапе постобработки.

	norm_eps (`float`, по умолчанию 1e-5) : Эпсилон, используемый для нормализации.

	cross_attention_dim (`int`, по умолчанию 1280) : Размерность признаков кросс-внимания.

	transformer_layers_per_block (`int` или `tuple[int]`, необязательный, по умолчанию 1) : Количество блоков трансформера типа `BasicTransformerBlock`. Актуально только для `~models.unet_2d_blocks.CrossAttnDownBlock2D`, `~models.unet_2d_blocks.CrossAttnUpBlock2D`, `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.

	transformer_layers_per_mid_block (`int` или `tuple[int]`, необязательный, по умолчанию 1) : Количество трансформерных слоёв, используемых в каждом слое среднего блока.

	attention_head_dim (`int` или `tuple[int]`, по умолчанию 8) : Размерность головок внимания.

	num_attention_heads (`int` или `tuple[int]`, необязательный) : Количество голов, используемых для многоголовного внимания.

	use_linear_projection (`bool`, по умолчанию `False`) --

	upcast_attention (`bool`, по умолчанию `False`) --

	resnet_time_scale_shift (`str`, по умолчанию `"default"`) : Настройка сдвига масштаба времени для блоков ResNet (см. `ResnetBlock2D`). Выберите `default` или `scale_shift`.

	conditioning_embedding_out_channels (`tuple[int]`, по умолчанию `(16, 32, 96, 256)`) : Кортеж количества выходных каналов для каждого блока в слое `conditioning_embedding`.

	global_pool_conditions (`bool`, по умолчанию `False`) : TODO(Patrick) - неиспользуемый параметр

	controlnet_conditioning_channel_order (`str`, по умолчанию `rgb`) --

	motion_max_seq_length (`int`, по умолчанию `32`) : Максимальная длина последовательности, используемая в модуле движения.

	motion_num_attention_heads (`int` или `tuple[int]`, по умолчанию `8`) : Количество голок, используемых в каждом слое внимания motion-модуля.

	concat_conditioning_mask (`bool`, по умолчанию `True`) --

	use_simplified_condition_embedding (`bool`, по умолчанию `True`) --

	Модель SparseControlNet, описанная в статье [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)
	```

	[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L534)

	Параметры:

	sample (`torch.Tensor`) : Шумовой входной тензор.

	timestep (`torch.Tensor \| float \| int`) : Количество шагов для денойзинга входных данных.

	encoder_hidden_states (`torch.Tensor`) : Скрытые состояния энкодера.

	controlnet_cond (`torch.Tensor`) : Условный входной тензор формы `(batch_size, sequence_length, hidden_size)`.

	conditioning_scale (`float`, по умолчанию `1.0`) : Коэффициент масштабирования для выходов ControlNet.

	timestep_cond (`torch.Tensor`, необязательный, по умолчанию `None`) : Дополнительные условные эмбеддинги для временного шага. Если предоставлены, эмбеддинги будут сложены с timestep_embedding, переданным через слой `self.time_embedding`, чтобы получить итоговые эмбеддинги временного шага.

	attention_mask (`torch.Tensor`, необязательный, по умолчанию `None`) : маска внимания формы `(batch, key_tokens)` применяется к `encoder_hidden_states`. Если значение равно `1`, маска сохраняется, иначе, если равно `0`, она отбрасывается. Маска преобразуется в смещение (bias), которое добавляет большие отрицательные значения к оценкам внимания, соответствующим токенам, подлежащим отбрасыванию.

	conditioning_mask (`torch.Tensor`, необязательный, по умолчанию `None`) : Необязательная маска, указывающая, какие кадры в `controlnet_cond` являются валидными кадрами для условного формирования.

	cross_attention_kwargs (`dict[str]`, необязательный, по умолчанию `None`) : Словарь kwargs, который при указании передается в `AttnProcessor`.

	guess_mode (`bool`, по умолчанию `False`) : В этом режиме энкодер ControlNet прилагает все усилия, чтобы распознать содержимое входных данных, даже если вы удалите все промпты. Рекомендуется значение `guidance_scale` от 3.0 до 5.0.

	return_dict (`bool`, по умолчанию `True`) : Возвращать ли `~models.controlnet.ControlNetOutput` вместо обычного кортежа.

	Возвращает: `~models.controlnet.ControlNetOutput` или `tuple`

	Если `return_dict` равно `True`, возвращается `~models.controlnet.ControlNetOutput`, иначе возвращается кортеж, первым элементом которого является тензор сэмпла.

	Метод forward модели [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/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)
	```

	[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

	Параметры:

	unet (`UNet2DConditionModel`) : веса модели UNet, которые необходимо скопировать в [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel). Все применимые параметры конфигурации также копируются.

	Создайте экземпляр [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) из [UNet2DConditionModel](/docs/diffusers/v0.43.0/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

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

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

	[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L469)

	Параметры:

	slice_size (`str` или `int` или `list(int)`, необязательный, по умолчанию `"auto"`) : Если указано `"auto"`, вход для головок внимания уменьшается вдвое, и внимание вычисляется в два этапа. Если указано `"max"`, экономится максимальное количество памяти за счёт обработки только одного среза за раз. Если указано число, используется столько срезов, сколько получается от `attention_head_dim // slice_size`. В этом случае `attention_head_dim` должно быть кратным `slice_size`.

	Включить вычисление внимания с нарезкой.

	Когда эта опция включена, модуль внимания разбивает входной тензор на фрагменты, чтобы вычислять внимание в несколько шагов. Это полезно для экономии памяти ценой небольшого снижения скорости.

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

	```python
	set_default_attn_processor()
	```

	[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L453)

	Отключает пользовательские обработчики внимания и устанавливает реализацию внимания по умолчанию.

	## 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)
	```

	[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L44)

	Параметры:

	down_block_res_samples (`tuple[torch.Tensor]`) : Кортеж активаций даунсемплинга на разных разрешениях для каждого блока даунсемплинга. Каждая тензор должна иметь форму `(batch_size, channel * resolution, height //resolution, width // resolution)`. Выходные данные можно использовать для условного формирования активаций даунсемплинга исходной UNet.

	mid_down_block_re_sample (`torch.Tensor`) : Активация среднего блока (с наименьшим разрешением сэмпла). Каждая тензорная величина должна иметь форму `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)`. Выходные данные можно использовать для условного формирования активации среднего блока исходного UNet.

	Вывод [SparseControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).