# Autoformer

## Обзор

Модель Autoformer была предложена в статье [Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting](https://huggingface.co/papers/2106.13008) авторами Haixu Wu, Jiehui Xu, Jianmin Wang, Mingsheng Long.

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

Аннотация из статьи следующая:

*Расширение горизонта прогноза является критически важным требованием для реальных приложений, таких как раннее предупреждение об экстремальных погодных явлениях и долгосрочное планирование энергопотребления. В данной статье рассматривается задача долгосрочного прогнозирования временных рядов. Предыдущие модели на основе Transformer используют различные механизмы self-attention для выявления зависимостей на больших временных масштабах. Однако сложные временные паттерны, характерные для отдалённого будущего, препятствуют модели в поиске надёжных зависимостей. Кроме того, для обеспечения эффективности работы с длинными рядами Transformer вынуждены использовать разреженные версии point-wise self-attention, что приводит к узкому месту в использовании информации. Выходя за рамки архитектуры Transformer, мы предлагаем Autoformer — новую архитектуру на основе декомпозиции с механизмом Auto-Correlation. Мы отказываемся от устоявшейся практики предобработки в виде декомпозиции ряда и превращаем её в базовый внутренний блок глубоких моделей. Такой подход наделяет Autoformer способностью к прогрессивной декомпозиции сложных временных рядов. Кроме того, вдохновлённые теорией стохастических процессов, мы разработали механизм Auto-Correlation, основанный на периодичности ряда, который выполняет выявление зависимостей и агрегацию представлений на уровне подрядов. Auto-Correlation превосходит self-attention как по эффективности, так и по точности. В задаче долгосрочного прогнозирования Autoformer демонстрирует наилучшую известную точность, обеспечив относительное улучшение на 38% на шести бенчмарках, охватывающих пять практических областей: энергетика, транспорт, экономика, погода и заболеваемость.*

Эта модель была добавлена [elisim](https://huggingface.co/elisim) и [kashif](https://huggingface.co/kashif). Исходный код можно найти [здесь](https://github.com/thuml/Autoformer).

## Ресурсы

Список официальных ресурсов Hugging Face и сообщества (отмечены 🌎), которые помогут вам начать работу. Если вы хотите предложить ресурс для включения в этот список, пожалуйста, создайте Pull Request, и мы его рассмотрим! В идеале ресурс должен демонстрировать что-то новое, а не дублировать существующий.

- Ознакомьтесь с блогом Autoformer в блоге HuggingFace: [Да, Transformers эффективны для прогнозирования временных рядов (+ Autoformer)](https://huggingface.co/blog/autoformer)

## AutoformerConfig[[transformers.AutoformerConfig]]

#### transformers.AutoformerConfig[[transformers.AutoformerConfig]]

```python
transformers.AutoformerConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, prediction_length: int | None = None, context_length: int | None = None, distribution_output: str = 'student_t', loss: str = 'nll', input_size: int = 1, lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7), scaling: bool | str = True, num_time_features: int = 0, num_dynamic_real_features: int = 0, num_static_categorical_features: int = 0, num_static_real_features: int = 0, cardinality: list[int] | None = None, embedding_dimension: list[int] | None = None, d_model: int = 64, encoder_attention_heads: int = 2, decoder_attention_heads: int = 2, encoder_layers: int = 2, decoder_layers: int = 2, encoder_ffn_dim: int = 32, decoder_ffn_dim: int = 32, activation_function: str = 'gelu', dropout: float | int = 0.1, encoder_layerdrop: float | int = 0.1, decoder_layerdrop: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.1, num_parallel_samples: int = 100, init_std: float = 0.02, use_cache: bool = True, label_length: int = 10, moving_average: int = 25, autocorrelation_factor: int = 3)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/autoformer/configuration_autoformer.py#L24)

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

is_encoder_decoder (`bool`, *необязательный*, по умолчанию `True`) : Используется ли модель в качестве энкодера/декодера.

prediction_length (`int`, *optional*) : Длина предсказания для декодера. Иными словами, горизонт предсказания модели.

context_length (`int`, *необязательный*, по умолчанию `prediction_length`) : Длина контекста для кодировщика. Если не задано, длина контекста будет такой же, как `prediction_length`.

distribution_output (`string`, *необязательный*, по умолчанию `"student_t"`) : Распределение выходного слоя модели. Может принимать значения "student_t", "normal" или "negative_binomial".

loss (`string`, *необязательный*, по умолчанию `"nll"`) : Функция потерь для модели, соответствующая голове `distribution_output`. Для параметрических распределений это отрицательная логарифмическая правдоподобность (nll) — на данный момент это единственный поддерживаемый вариант.

input_size (`int`, *optional*, по умолчанию 1) : Размер целевой переменной, который по умолчанию равен 1 для одномерных целей. Для многомерных целей значение будет > 1.

lags_sequence (`list[int]`, *optional*, по умолчанию `[1, 2, 3, 4, 5, 6, 7]`) : Задержки входного временного ряда в качестве ковариат, часто определяемые частотой. По умолчанию `[1, 2, 3, 4, 5, 6, 7]`.

scaling (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли масштабировать входные целевые значения.

num_time_features (`int`, *необязательный*, по умолчанию 0) : количество временных признаков во входном временном ряду.

num_dynamic_real_features (`int`, *optional*, по умолчанию 0) : Количество динамических вещественных признаков.

num_static_categorical_features (`int`, *optional*, по умолчанию 0) : Количество статических категориальных признаков.

num_static_real_features (`int`, *optional*, по умолчанию 0) : Количество статических вещественных признаков.

cardinality (`list[int]`, *optional*) : Кардинальность (количество различных значений) для каждой из статических категориальных признаков. Должно быть списком целых чисел, длина которого совпадает с `num_static_categorical_features`. Не может быть `None`, если `num_static_categorical_features` > 0.

embedding_dimension (`list[int]`, *необязательный*) : Размерность эмбеддингов и скрытых состояний.

d_model (`int`, *необязательный*, по умолчанию `64`) : Размер слоев кодировщика и пулера.

encoder_attention_heads (`int`, *optional*, по умолчанию `2`) : Количество голок внимания для каждого слоя внимания в кодере Transformer.

decoder_attention_heads (`int`, *необязательный*, по умолчанию `2`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

encoder_layers (`int`, *необязательный*, по умолчанию `2`) : Количество скрытых слоев в кодере Transformer. Если не задано, будет использовано то же значение, что и у `num_layers`.

decoder_layers (`int`, *optional*, по умолчанию `2`) : Количество скрытых слоев в декодере Transformer. Если не задано, будет использовано то же значение, что и у `num_layers`.

encoder_ffn_dim (`int`, *optional*, по умолчанию `32`) : Размерность «промежуточного» (часто называемого feed-forward) слоя в энкодере.

decoder_ffn_dim (`int`, *optional*, по умолчанию `32`) : Размерность «промежуточного» (часто называемого feed-forward) слоя в декодере.

activation_function (`str`, *необязательный*, по умолчанию `gelu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Доля для всех слоёв dropout.

encoder_layerdrop (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Вероятность LayerDrop для энкодера. Подробнее см. в [статье о LayerDrop](see https://huggingface.co/papers/1909.11556).

decoder_layerdrop (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Вероятность LayerDrop для декодера. Подробнее см. в [статье о LayerDrop](see https://huggingface.co/papers/1909.11556).

attention_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Доля dropout для вероятностей внимания.

activation_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Коэффициент dropout для активаций внутри полносвязного слоя.

num_parallel_samples (`int`, *optional*, по умолчанию 100) : Количество образцов, генерируемых параллельно для каждого шага времени при выводе.

init_std (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

use_cache (`bool`, *необязательный*, по умолчанию `True`) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только при `config.is_decoder=True` или если модель является генеративной моделью только с декодером.

label_length (`int`, *optional*, по умолчанию 10) : Начальная длина токенов декодера Autoformer, используемая для прямого многошагового прогнозирования (т. е. неавто регрессивной генерации).

moving_average (`int`, *optional*, по умолчанию 25) : Размер окна скользящего среднего. На практике это размер ядра в AvgPool1d слоя Decomposition Layer.

autocorrelation_factor (`int`, *optional*, по умолчанию 3) : фактор «Attention» (т.е. механизм AutoCorrelation), используемый для поиска задержек топ-k автокорреляций. В статье рекомендуется устанавливать значение от 1 до 5.

Это класс конфигурации для хранения настроек модели AutoformerModel. Он используется для создания модели Autoformer в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [huggingface/autoformer-tourism-monthly](https://huggingface.co/huggingface/autoformer-tourism-monthly)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:

```python
>>> from transformers import AutoformerConfig, AutoformerModel

>>> # Initializing a default Autoformer configuration
>>> configuration = AutoformerConfig()

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = AutoformerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## AutoformerModel[[transformers.AutoformerModel]]

#### transformers.AutoformerModel[[transformers.AutoformerModel]]

```python
transformers.AutoformerModel(config: AutoformerConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/autoformer/modeling_autoformer.py#L1013)

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

config ([AutoformerConfig](/docs/transformers/v5.23.0/ru/model_doc/autoformer#transformers.AutoformerConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Autoformer без дополнительных слоёв, выводящая необработанные скрытые состояния.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.AutoformerModel.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/autoformer/modeling_autoformer.py#L1181)

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

past_values (`torch.Tensor` формы `(batch_size, sequence_length)`) : Прошлые значения временного ряда, которые служат контекстом для прогнозирования будущего. Эти значения могут содержать лаги, то есть дополнительные значения из прошлого, добавляемые в качестве «дополнительного контекста». `past_values` — это то, что получает кодировщик Transformer на вход (с возможными дополнительными признаками, такими как `static_categorical_features`, `static_real_features`, `past_time_features`).  Длина последовательности здесь равна `context_length` + `max(config.lags_sequence)`.  Пропущенные значения необходимо заменить нулями.

past_time_features (`torch.Tensor` формы `(batch_size, sequence_length, num_features)`, *необязательный*) : Необязательные временные признаки, которые модель внутренним образом добавит к `past_values`. К ним могут относиться, например, «месяц года», «день месяца» и т. д., закодированные в виде векторов (например, в виде признаков Фурье). Также сюда могут относиться так называемые признаки «возраста», которые по сути помогают модели понимать, «на каком этапе жизни» находится временной ряд. У признаков «возраста» значения малы для временных шагов в далёком прошлом и монотонно возрастают по мере приближения к текущему временному шагу. Эти признаки выполняют роль «позиционных кодирований» для входных данных. В отличие от модели вроде BERT, где позиционные кодирования обучаются с нуля как параметры модели, Time Series Transformer требует предоставления дополнительных временных признаков. Autoformer обучает дополнительные эмбеддинги только для `static_categorical_features`.

past_observed_mask (`torch.BoolTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Булева маска, указывающая, какие значения `past_values` были наблюдаемы, а какие отсутствуют. Значения маски выбираются из `[0, 1]`:  - 1 для значений, которые **наблюдаемы**, - 0 для значений, которые **отсутствуют** (т. е. NaN, заменённые нулями).

static_categorical_features (`torch.LongTensor` формы `(batch_size, number of static categorical features)`, *необязательный*) : Необязательные статические категориальные признаки, для которых модель обучит эмбеддинг, который будет добавляться к значениям временного ряда. Статические категориальные признаки — это признаки, которые имеют одинаковое значение для всех временных шагов (статичны во времени). Типичным примером статического категориального признака является идентификатор временного ряда.

static_real_features (`torch.Tensor` формы `(batch_size, number of static real features)`, *необязательный*) : Необязательные статические вещественные признаки, которые модель добавит к значениям временного ряда. Статические вещественные признаки — это признаки, имеющие одинаковое значение для всех временных шагов (статичные во времени). Типичным примером статического вещественного признака является информация о промоакциях.

future_values (`torch.Tensor` формы `(batch_size, prediction_length)`) : Будущие значения временного ряда, которые служат метками для модели. `future_values` — это то, что Transformer должен научиться выводить, получая на вход `past_values`. Подробности — в демонстрационном ноутбуке и фрагментах кода. Пропущенные значения необходимо заменить нулями.

future_time_features (`torch.Tensor` формы `(batch_size, prediction_length, num_features)`, *необязательный*) : Необязательные временные признаки, которые модель внутренним образом добавит к `future_values`. К ним могут относиться, например, «месяц года», «день месяца» и т. д., закодированные в виде векторов (например, в виде признаков Фурье). Также сюда могут относиться так называемые признаки «возраста», которые по сути помогают модели понимать, «на каком этапе жизни» находится временной ряд. Признаки возраста имеют малые значения для временных шагов в далёком прошлом и монотонно возрастают по мере приближения к текущему временному шагу. Эти признаки выполняют роль «позиционных кодирований» для входных данных. В отличие от модели вроде BERT, где позиционные кодирования обучаются с нуля как параметры модели, Time Series Transformer требует предоставления дополнительных признаков. Autoformer обучает дополнительные эмбеддинги только для `static_categorical_features`.

decoder_attention_mask (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Маска для исключения внимания к определённым индексам токенов. По умолчанию используется каузальная маска, чтобы модель могла учитывать только предыдущие входные данные при прогнозировании будущих.

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Кортеж состоит из `last_hidden_state`, `hidden_states` (*optional*) и `attentions` (*optional*) `last_hidden_state` формы `(batch_size, sequence_length, hidden_size)` (*optional*) представляет собой последовательность скрытых состояний на выходе последнего слоя кодировщика. Используется в кросс-внимании декодера.

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

use_cache (`bool`, *необязательный*) : Если установлено в `True`, состояния ключей и значений `past_key_values` возвращаются и могут использоваться для ускорения декодирования (см. `past_key_values`).

**Возвращает:** `AutoformerModelOutput` или `tuple(torch.Tensor)`

Объект `AutoformerModelOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([AutoformerConfig](/docs/transformers/v5.23.0/ru/model_doc/autoformer#transformers.AutoformerConfig)) и входных данных.

Метод forward модели [AutoformerModel](/docs/transformers/v5.23.0/ru/model_doc/autoformer#transformers.AutoformerModel) переопределяет специальный метод `__call__`.

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя декодера модели.

  Если используется `past_key_values`, выводится только последнее скрытое состояние последовательностей формы `(batch_size, 1, hidden_size)`.
- **trend** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Тензор тренда для каждого временного ряда.
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
- **decoder_attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **cross_attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кросс-внимания декодера, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах кросс-внимания.
- **encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя энкодера модели.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **encoder_attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **loc** (`torch.Tensor` формы `(batch_size,)` или `(batch_size, input_size)`, *необязательный*) -- Сдвиг значений контекстного окна каждого временного ряда, используемый для приведения входных данных модели к одинаковому масштабу, после чего значения возвращаются к исходному масштабу.
- **scale** (`torch.Tensor` формы `(batch_size,)` или `(batch_size, input_size)`, *необязательный*) -- Значения масштабирования для контекстного окна каждого временного ряда, используемые для приведения входных данных модели к одинаковому порядку величины, а затем для обратного масштабирования до исходной величины. static_features: (`torch.Tensor` формы `(batch_size, feature size)`, *необязательный*): Статические признаки каждого временного ряда в батче, которые копируются в ковариаты во время инференса.
- **static_features** (`torch.Tensor` формы `(batch_size, feature size)`, *необязательный*) -- Статические признаки каждого временного ряда в батче, которые копируются в ковариаты во время инференса.

Примеры:

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = AutoformerModel.from_pretrained("huggingface/autoformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state
```

## AutoformerForPrediction[[transformers.AutoformerForPrediction]]

#### transformers.AutoformerForPrediction[[transformers.AutoformerForPrediction]]

```python
transformers.AutoformerForPrediction(config: AutoformerConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/autoformer/modeling_autoformer.py#L1379)

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

config ([AutoformerConfig](/docs/transformers/v5.23.0/ru/model_doc/autoformer#transformers.AutoformerConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Autoformer с распределительным слоем (distribution head) для прогнозирования временных рядов.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.AutoformerForPrediction.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, future_observed_mask: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/autoformer/modeling_autoformer.py#L1413)

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

past_values (`torch.Tensor` формы `(batch_size, sequence_length)`) : Прошлые значения временного ряда, которые служат контекстом для прогнозирования будущего. Эти значения могут содержать лаги, то есть дополнительные значения из прошлого, добавляемые в качестве «дополнительного контекста». `past_values` — это то, что получает кодировщик Transformer на вход (с возможными дополнительными признаками, такими как `static_categorical_features`, `static_real_features`, `past_time_features`).  Длина последовательности здесь равна `context_length` + `max(config.lags_sequence)`.  Пропущенные значения необходимо заменить нулями.

past_time_features (`torch.Tensor` формы `(batch_size, sequence_length, num_features)`, *необязательный*) : Необязательные временные признаки, которые модель внутренним образом добавит к `past_values`. К ним могут относиться, например, «месяц года», «день месяца» и т. д., закодированные в виде векторов (например, в виде признаков Фурье). Также сюда могут относиться так называемые признаки «возраста», которые по сути помогают модели понимать, «на каком этапе жизни» находится временной ряд. У признаков «возраста» значения малы для временных шагов в далёком прошлом и монотонно возрастают по мере приближения к текущему временному шагу. Эти признаки выполняют роль «позиционных кодирований» для входных данных. В отличие от модели вроде BERT, где позиционные кодирования обучаются с нуля как параметры модели, Time Series Transformer требует предоставления дополнительных временных признаков. Autoformer обучает дополнительные эмбеддинги только для `static_categorical_features`.

past_observed_mask (`torch.BoolTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Булева маска, указывающая, какие значения `past_values` были наблюдаемы, а какие отсутствуют. Значения маски выбираются из `[0, 1]`:  - 1 для значений, которые **наблюдаемы**, - 0 для значений, которые **отсутствуют** (т. е. NaN, заменённые нулями).

static_categorical_features (`torch.LongTensor` формы `(batch_size, number of static categorical features)`, *необязательный*) : Необязательные статические категориальные признаки, для которых модель обучит эмбеддинг, который будет добавляться к значениям временного ряда. Статические категориальные признаки — это признаки, которые имеют одинаковое значение для всех временных шагов (статичны во времени). Типичным примером статического категориального признака является идентификатор временного ряда.

static_real_features (`torch.Tensor` формы `(batch_size, number of static real features)`, *необязательный*) : Необязательные статические вещественные признаки, которые модель добавит к значениям временного ряда. Статические вещественные признаки — это признаки, имеющие одинаковое значение для всех временных шагов (статичные во времени). Типичным примером статического вещественного признака является информация о промоакциях.

future_values (`torch.Tensor` формы `(batch_size, prediction_length)`) : Будущие значения временного ряда, которые служат метками для модели. `future_values` — это то, что Transformer должен научиться выводить, получая на вход `past_values`. Подробности — в демонстрационном ноутбуке и фрагментах кода. Пропущенные значения необходимо заменить нулями.

future_time_features (`torch.Tensor` формы `(batch_size, prediction_length, num_features)`, *необязательный*) : Необязательные временные признаки, которые модель внутренним образом добавит к `future_values`. К ним могут относиться, например, «месяц года», «день месяца» и т. д., закодированные в виде векторов (например, в виде признаков Фурье). Также сюда могут относиться так называемые признаки «возраста», которые по сути помогают модели понимать, «на каком этапе жизни» находится временной ряд. Признаки возраста имеют малые значения для временных шагов в далёком прошлом и монотонно возрастают по мере приближения к текущему временному шагу. Эти признаки выполняют роль «позиционных кодирований» для входных данных. В отличие от модели вроде BERT, где позиционные кодирования обучаются с нуля как параметры модели, Time Series Transformer требует предоставления дополнительных признаков. Autoformer обучает дополнительные эмбеддинги только для `static_categorical_features`.

future_observed_mask (`torch.BoolTensor` формы `(batch_size, sequence_length)` или `(batch_size, sequence_length, input_size)`, *необязательный*) : Булева маска, указывающая, какие значения `future_values` были наблюдаемы, а какие отсутствуют. Значения маски выбираются из диапазона `[0, 1]`:  - 1 для **наблюдаемых** значений, - 0 для **отсутствующих** значений (т. е. NaN, заменённых нулями).  Эта маска используется для исключения отсутствующих значений при вычислении итоговой функции потерь.

decoder_attention_mask (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Маска для исключения внимания к определённым индексам токенов. По умолчанию используется каузальная маска, чтобы модель могла учитывать только предыдущие входные данные при прогнозировании будущих.

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Кортеж состоит из `last_hidden_state`, `hidden_states` (*optional*) и `attentions` (*optional*) `last_hidden_state` формы `(batch_size, sequence_length, hidden_size)` (*optional*) представляет собой последовательность скрытых состояний на выходе последнего слоя кодировщика. Используется в кросс-внимании декодера.

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

use_cache (`bool`, *необязательный*) : Если установлено в `True`, состояния ключей и значений `past_key_values` возвращаются и могут использоваться для ускорения декодирования (см. `past_key_values`).

**Возвращает:** [Seq2SeqTSPredictionOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.Seq2SeqTSPredictionOutput) или `tuple(torch.Tensor)`

Объект [Seq2SeqTSPredictionOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.Seq2SeqTSPredictionOutput) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([AutoformerConfig](/docs/transformers/v5.23.0/ru/model_doc/autoformer#transformers.AutoformerConfig)) и входных данных.

Метод forward класса [AutoformerForPrediction](/docs/transformers/v5.23.0/ru/model_doc/autoformer#transformers.AutoformerForPrediction) переопределяет специальный метод `__call__`.

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается при указании `future_values`) -- Дистрибуционное значение функции потерь.
- **params** (`torch.Tensor` формы `(batch_size, num_samples, num_params)`) -- Параметры выбранного распределения.
- **past_key_values** (`EncoderDecoderCache`, *необязательный*, возвращается при передаче `use_cache=True` или при `config.use_cache=True`) -- это экземпляр [EncoderDecoderCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.EncoderDecoderCache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
- **decoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **cross_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кросс-внимания декодера, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах кросс-внимания.
- **encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя энкодера модели.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **encoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **loc** (`torch.Tensor` формы `(batch_size,)` или `(batch_size, input_size)`, *необязательный*) -- Сдвиг значений контекстного окна каждого временного ряда, используемый для приведения входных данных модели к одинаковому масштабу, после чего значения возвращаются к исходному масштабу.
- **scale** (`torch.Tensor` формы `(batch_size,)` или `(batch_size, input_size)`, *необязательный*) -- Значения масштабирования для контекстного окна каждого временного ряда. Используются для приведения входных данных модели к одинаковому порядку величины, после чего применяются для обратного масштабирования к исходной величине.
- **static_features** (`torch.Tensor` формы `(batch_size, feature size)`, *необязательный*) -- Статические признаки каждого временного ряда в батче, которые копируются в ковариаты во время инференса.

Примеры:

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = AutoformerForPrediction.from_pretrained("huggingface/autoformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     future_time_features=batch["future_time_features"],
... )

>>> mean_prediction = outputs.sequences.mean(dim=1)
```

Класс AutoformerForPrediction также может использовать static_real_features. Для этого установите num_static_real_features в AutoformerConfig на основе количества таких признаков в наборе данных (в случае набора данных tourism_monthly это

равен 1), инициализируйте модель и вызовите, как показано ниже:

```
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerConfig, AutoformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> # check number of static real features
>>> num_static_real_features = batch["static_real_features"].shape[-1]

>>> # load configuration of pretrained model and override num_static_real_features
>>> configuration = AutoformerConfig.from_pretrained(
...     "huggingface/autoformer-tourism-monthly",
...     num_static_real_features=num_static_real_features,
... )
>>> # we also need to update feature_size as it is not recalculated
>>> configuration.feature_size += num_static_real_features

>>> model = AutoformerForPrediction(configuration)

>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )
```

