# Кэширование

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

В этом руководстве показано, как использовать методы кэширования, поддерживаемые в Diffusers.

## Pyramid Attention Broadcast

[Pyramid Attention Broadcast (PAB)](https://huggingface.co/papers/2408.12588) основан на наблюдении о том, что выходные значения внимания не сильно различаются между последовательными шагами процесса генерации. Различия в значениях внимания минимальны в слоях кросс-внимания и, как правило, кэшируются на более длительном диапазоне временных шагов. За ними следуют слои временного и пространственного внимания.

> [!TIP]
> Не все видеомодели имеют три типа внимания (кросс-, временное и пространственное)!

PAB можно комбинировать с другими техниками, такими как параллелизм последовательностей и параллелизм classifier-free guidance (параллелизм данных), для генерации видео в режиме, близком к реальному времени.

Настройте и передайте [PyramidAttentionBroadcastConfig](/docs/diffusers/v0.43.0/ru/api/cache#diffusers.PyramidAttentionBroadcastConfig) в трансформер пайплайна, чтобы включить эту функцию. Параметр `spatial_attention_block_skip_range` определяет, как часто пропускать вычисления внимания в блоках пространственного внимания, а `spatial_attention_timestep_skip_range` задаёт диапазон шагов времени, которые нужно пропускать. Тщательно подбирайте диапазон: слишком малый интервал может привести к замедлению инференса, а слишком большой — к снижению качества генерации.

```python
import torch
from diffusers import CogVideoXPipeline, PyramidAttentionBroadcastConfig

pipeline = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-5b", dtype=torch.bfloat16)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

config = PyramidAttentionBroadcastConfig(
    spatial_attention_block_skip_range=2,
    spatial_attention_timestep_skip_range=(100, 800),
    current_timestep_callback=lambda: pipe.current_timestep,
)
pipeline.transformer.enable_cache(config)
```

## FasterCache

[FasterCache](https://huggingface.co/papers/2410.19355) кэширует и повторно использует признаки внимания по аналогии с [PAB](#pyramid-attention-broadcast), поскольку различия в выходных данных невелики для каждого последующего шага.

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

Настройте и передайте [FasterCacheConfig](/docs/diffusers/v0.43.0/ru/api/cache#diffusers.FasterCacheConfig) в трансформер пайплайна, чтобы включить эту функцию.

```python
import torch
from diffusers import CogVideoXPipeline, FasterCacheConfig

pipe line= CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-5b", dtype=torch.bfloat16)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

config = FasterCacheConfig(
    spatial_attention_block_skip_range=2,
    spatial_attention_timestep_skip_range=(-1, 681),
    current_timestep_callback=lambda: pipe.current_timestep,
    attention_weight_callback=lambda _: 0.3,
    unconditional_batch_skip_range=5,
    unconditional_batch_timestep_skip_range=(-1, 781),
    tensor_format="BFCHW",
)
pipeline.transformer.enable_cache(config)
```

## SeaCache

[SeaCache](https://huggingface.co/papers/2602.18993) сравнивает индикаторы Spectral-Evolution-Aware (SEA) между последовательными шагами шумоподавления. Если накопленное изменение индикатора остаётся ниже порога, модуль пропускает вычислительно затратный стек блоков трансформера и предсказывает его выход на основе кэшированных остатков. Формируйте индикатор из визуальных латентов, составляющих генерируемый вывод. Включайте чистые кадрами-условия, если они являются частью этой траектории вывода, как в генерации «изображение в видео» и «видео в видео». Исключайте отдельные визуальные подсказки, которые задают условия генерации, но не входят в состав вывода. Текстовые условия исключаются, поскольку они не являются визуальными латентами.

Пакеты Cosmos 3 Transfer обрабатывают подсказки управления как отдельные визуальные последовательности, поэтому их адаптер исключает их из индикатора. Ветви Control-CFG сравнивают одну и ту же траекторию вывода, сохраняя при этом собственные кэшированные остаточные значения. Подсказки управления по-прежнему задают условия для трансформера.

Реализация предоставляет встроенные адаптеры для следующих моделей:

- **Cosmos 3** — это основная оптимизированная и протестированная интеграция. Она кэширует полный стек декодера до границы постнормализации.
- **Wan T2V** использует общий путь с повторяющимися блоками в режиме eager. Эта интеграция демонстрирует, как другой однострочный видео-трансформер может передавать необработанные визуальные латенты в SeaCache; это не утверждение о том, что те же параметры кэша оптимальны для Wan или что поддерживаются другие варианты Wan.

Другие видео-трансформеры могут интегрироваться с общим путём, если они используют `CacheMixin`, предоставляют список повторяющихся блоков, распознаваемый системой, и регистрируют входную/выходную структуру блоков в `TransformerBlockRegistry`. Пайплайн должен входить в `cache_context` при каждом вызове трансформера, передавать `step_index`, `sigma` и `num_inference_steps`, а также использовать отдельные имена контекста для независимых траекторий, например для условного и безусловного управления. Передавайте `raw_vision_callback`, который возвращает визуальные латенты, формирующие итоговый вывод, если встроенный адаптер недоступен. Проверяйте качество вывода и настраивайте параметры кэша для каждой модели и планировщика; поддержка и результаты бенчмарков не переносятся автоматически из Cosmos 3.

### Cosmos 3

SeaCache отключён по умолчанию. Включите его на трансформере; цикл денойзинга Cosmos 3 привязывает активный шаг планировщика, сигму и количество шагов к каждому вызову `cache_context`, поэтому дополнительная настройка не требуется:

```python
from diffusers import Cosmos3OmniPipeline, SeaCacheConfig

pipe = Cosmos3OmniPipeline.from_pretrained("nvidia/Cosmos3-Nano")
pipe.transformer.enable_cache(SeaCacheConfig(threshold=0.2, max_consecutive_cached=2))
```

Этот API на уровне модели работает с [Cosmos3OmniPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline), [Cosmos3OmniModularPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) и [Cosmos3DistilledModularPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/cosmos3#diffusers.Cosmos3DistilledModularPipeline). SeaCache является приближённой оптимизацией и может изменять генерируемые результаты. Вызывайте `pipe.transformer.disable_cache()`, если вам необходимо, чтобы каждый шаг денойзинга выполнял полный проход через трансформер.

## FirstBlockCache

[FirstBlock Cache](https://huggingface.co/docs/diffusers/main/en/api/cache#diffusers.FirstBlockCacheConfig) проверяет, насколько сильно изменяются начальные слои денойзера от одного временного шага к другому. Если изменение незначительно, модель пропускает дорогостоящие последующие слои и повторно использует предыдущий вывод.

```py
import torch
from diffusers import DiffusionPipeline
from diffusers.hooks import apply_first_block_cache, FirstBlockCacheConfig

pipeline = DiffusionPipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16
)
apply_first_block_cache(pipeline.transformer, FirstBlockCacheConfig(threshold=0.2))
```
## Кэш TaylorSeer

[TaylorSeer Cache](https://huggingface.co/papers/2403.06923) ускоряет инференс диффузионных моделей, используя разложения в ряд Тейлора для аппроксимации и кэширования промежуточных активаций на шагах денуайзинга. Метод предсказывает будущие выходные значения на основе прошлых вычислений и повторно использует их через заданные интервалы, чтобы сократить избыточные вычисления.

Этот механизм кэширования обеспечивает высокие результаты при минимальных дополнительных затратах памяти. Для подробного анализа производительности см. [наши результаты здесь](https://github.com/huggingface/diffusers/pull/12648#issuecomment-3610615080).

Чтобы включить TaylorSeer Cache, создайте [TaylorSeerCacheConfig](/docs/diffusers/v0.43.0/ru/api/cache#diffusers.TaylorSeerCacheConfig) и передайте его в трансформер вашего конвейера:

- `cache_interval`: количество шагов, в течение которых переиспользуются кэшированные результаты, прежде чем выполняется полный прямой проход
- `disable_cache_before_step`: Начальные шаги, использующие полные вычисления для сбора данных для приближений
- `max_order`: точность аппроксимации (теоретически более высокие значения улучшают качество, но увеличивают потребление памяти; рекомендуем устанавливать значение `1`)

```python
import torch
from diffusers import FluxPipeline, TaylorSeerCacheConfig

pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    dtype=torch.bfloat16,
).to("cuda")  # or "mps", "xpu", "cpu"

config = TaylorSeerCacheConfig(
    cache_interval=5,
    max_order=1,
    disable_cache_before_step=10,
    taylor_factors_dtype=torch.bfloat16,
)
pipe.transformer.enable_cache(config)
```

## MagCache

[MagCache](https://github.com/Zehong-Ma/MagCache) ускоряет инференс, пропуская блоки трансформера на основе величины остаточного обновления. Он наблюдает, что величина обновлений (Output - Input) предсказуемо убывает в процессе диффузии. Накопливая «бюджет ошибки» на основе заранее вычисленных отношений величин, он динамически решает, когда пропускать вычисления и повторно использовать предыдущее остаточное значение.

MagCache опирается на **Magnitude Ratios** (`mag_ratios`), которые описывают эту кривую затухания. Эти коэффициенты специфичны для контрольной точки модели и планировщика. Встроенные `FLUX_MAG_RATIOS` были измерены для FLUX.1; другим моделям, включая Flux2 и Flux2 Klein, требуется собственный прогон калибровки.

Для использования MagCache обычно выполняется двухэтапный процесс: **Калибровка** и **Вывод**.

1.  **Калибровка**: выполните один проход инференса с `calibrate=True`. Хук измерит амплитуды остаточных сигналов и выведет рассчитанные соотношения в консоль.
2.  **Вывод**: передайте эти соотношения в `MagCacheConfig`, чтобы включить ускорение.

```python
import torch
from diffusers import FluxPipeline, MagCacheConfig

pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-schnell",
    dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"

# 1. Calibration Step
# Run full inference to measure model behavior.
calib_config = MagCacheConfig(calibrate=True, num_inference_steps=4)
pipe.transformer.enable_cache(calib_config)

# Run a prompt to trigger calibration
pipe("A cat playing chess", num_inference_steps=4)
# Logs will print something like: "MagCache Calibration Results: [1.0, 1.37, 0.97, 0.87]"

# 2. Inference Step
# Apply the specific ratios obtained from calibration for optimized speed.
# Note: For Flux models, you can also import defaults: 
# from diffusers.hooks.mag_cache import FLUX_MAG_RATIOS
mag_config = MagCacheConfig(
    mag_ratios=[1.0, 1.37, 0.97, 0.87],
    num_inference_steps=4
)

pipe.transformer.enable_cache(mag_config) 

image = pipe("A cat playing chess", num_inference_steps=4).images[0]
```

> [!NOTE]
> `mag_ratios` представляют собой кривую затухания амплитуды, присущую модели. Коэффициенты, откалиброванные для большого числа шагов (например, 50), можно повторно использовать для меньшего числа шагов (например, 20). В реализации используется интерполяция для отображения кривой на текущее количество шагов инференса.

> [!TIP]
> Для конвейеров, выполняющих Classifier-Free Guidance последовательно (например, Kandinsky 5.0), журнал калибровки может выводить два массива: один для прохода Conditional и один для прохода Unconditional. В большинстве случаев следует использовать первый массив (Conditional).

> [!TIP]
> Для конвейеров, выполняющих Classifier-Free Guidance в **пакетном** режиме (например, SDXL или Flux), `hidden_states`, обрабатываемые моделью, содержат как условные, так и безусловные ветви, объединённые в один массив. Процесс калибровки автоматически учитывает это, формируя единый массив коэффициентов, описывающий совместное поведение. Полученный массив можно использовать напрямую без каких-либо изменений.