diffusers/v0.43.0/ru/optimization/cache.md

Кэширование

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

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

Pyramid Attention Broadcast

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

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

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

Настройте и передайте PyramidAttentionBroadcastConfig в трансформер пайплайна, чтобы включить эту функцию. Параметр spatial_attention_block_skip_range определяет, как часто пропускать вычисления внимания в блоках пространственного внимания, а spatial_attention_timestep_skip_range задаёт диапазон шагов времени, которые нужно пропускать. Тщательно подбирайте диапазон: слишком малый интервал может привести к замедлению инференса, а слишком большой — к снижению качества генерации.

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 кэширует и повторно использует признаки внимания по аналогии с PAB, поскольку различия в выходных данных невелики для каждого последующего шага.

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

Настройте и передайте FasterCacheConfig в трансформер пайплайна, чтобы включить эту функцию.

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 сравнивает индикаторы 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, поэтому дополнительная настройка не требуется:

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, Cosmos3OmniModularPipeline и Cosmos3DistilledModularPipeline. SeaCache является приближённой оптимизацией и может изменять генерируемые результаты. Вызывайте pipe.transformer.disable_cache(), если вам необходимо, чтобы каждый шаг денойзинга выполнял полный проход через трансформер.

FirstBlockCache

FirstBlock Cache проверяет, насколько сильно изменяются начальные слои денойзера от одного временного шага к другому. Если изменение незначительно, модель пропускает дорогостоящие последующие слои и повторно использует предыдущий вывод.

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 ускоряет инференс диффузионных моделей, используя разложения в ряд Тейлора для аппроксимации и кэширования промежуточных активаций на шагах денуайзинга. Метод предсказывает будущие выходные значения на основе прошлых вычислений и повторно использует их через заданные интервалы, чтобы сократить избыточные вычисления.

Этот механизм кэширования обеспечивает высокие результаты при минимальных дополнительных затратах памяти. Для подробного анализа производительности см. наши результаты здесь.

Чтобы включить TaylorSeer Cache, создайте TaylorSeerCacheConfig и передайте его в трансформер вашего конвейера:

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

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 ускоряет инференс, пропуская блоки трансформера на основе величины остаточного обновления. Он наблюдает, что величина обновлений (Output - Input) предсказуемо убывает в процессе диффузии. Накопливая «бюджет ошибки» на основе заранее вычисленных отношений величин, он динамически решает, когда пропускать вычисления и повторно использовать предыдущее остаточное значение.

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

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

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

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]

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

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

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