Transformers documentation
Autoformer
Эта модель была опубликована в HF papers 24.06.2021 и добавлена в Hugging Face Transformers 30.05.2023.
Autoformer
Обзор
Модель Autoformer была предложена в статье Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting авторами 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 и kashif. Исходный код можно найти здесь.
Ресурсы
Список официальных ресурсов Hugging Face и ресурсов сообщества (отмечены значком 🌎), которые помогут вам начать работу. Если вы хотите предложить ресурс для включения в этот список, пожалуйста, создайте Pull Request — мы его рассмотрим! В идеале ресурс должен демонстрировать что-то новое, а не дублировать уже имеющийся.
- Ознакомьтесь с блогом Autoformer в блоге HuggingFace: Да, Transformers эффективны для прогнозирования временных рядов (+ Autoformer)
AutoformerConfig
класс transformers.AutoformerConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0id2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneis_encoder_decoder: bool = Trueprediction_length: int | None = Nonecontext_length: int | None = Nonedistribution_output: str = 'student_t'loss: str = 'nll'input_size: int = 1lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7)scaling: bool | str = Truenum_time_features: int = 0num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32activation_function: str = 'gelu'dropout: float | int = 0.1encoder_layerdrop: float | int = 0.1decoder_layerdrop: float | int = 0.1attention_dropout: float | int = 0.1activation_dropout: float | int = 0.1num_parallel_samples: int = 100init_std: float = 0.02use_cache: bool = Truelabel_length: int = 10moving_average: int = 25autocorrelation_factor: int = 3 )
Параметры
- is_encoder_decoder (
bool, необязательный, по умолчаниюTrue) — Указывает, используется ли модель в качестве энкодера/декодера. - prediction_length (
int, необязательный) — Длина прогноза для декодера. Иными словами, горизонт прогноза модели. - 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, необязательный, по умолчанию 1) — Размер целевой переменной, который по умолчанию равен 1 для одномерных целей. В случае многомерных целей значение будет > 1. - lags_sequence (
list[int], необязательный, по умолчанию[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, необязательный, по умолчанию 0) — Количество динамических признаков с вещественными значениями. - num_static_categorical_features (
int, необязательный, по умолчанию 0) — Количество статических категориальных признаков. - num_static_real_features (
int, необязательный, по умолчанию 0) — Количество статических признаков с вещественными значениями. - cardinality (
list[int], необязательный) — Кардинальность (количество различных значений) для каждой из статических категориальных признаков. Должно быть списком целых чисел, имеющим ту же длину, что иnum_static_categorical_features. Не может бытьNone, еслиnum_static_categorical_features> 0. - embedding_dimension (
list[int], необязательный) — Размерность эмбеддингов и скрытых состояний. - d_model (
int, необязательный, по умолчанию64) — Размер слоев кодировщика и пулер-слоя. - encoder_attention_heads (
int, необязательный, по умолчанию2) — Количество головок внимания в каждом слое внимания в кодере Transformer. - decoder_attention_heads (
int, необязательный, по умолчанию2) — Количество головок внимания в каждом слое внимания декодера Transformer. - encoder_layers (
int, необязательный, по умолчанию2) — Количество скрытых слоев в кодере Transformer. Если не задано, используется то же значение, что и уnum_layers. - decoder_layers (
int, необязательный, по умолчанию2) — Количество скрытых слоев в декодере Transformer. Если не задано, используется то же значение, что и уnum_layers. - encoder_ffn_dim (
int, необязательный, по умолчанию32) — Размерность «промежуточного» (часто называемого feed-forward) слоя в энкодере. - decoder_ffn_dim (
int, необязательный, по умолчанию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](см. https://huggingface.co/papers/1909.11556). - decoder_layerdrop (
Union[float, int], необязательный, по умолчанию0.1) — Вероятность LayerDrop для декодера. Подробности — в [статье о LayerDrop](см. 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, необязательный, по умолчанию 100) — Количество образцов, генерируемых параллельно для каждого временного шага инференса. - init_std (
float, необязательный, по умолчанию0.02) — Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов. - use_cache (
bool, необязательный, по умолчаниюTrue) — Указывает, должен ли модель возвращать последние ключи/значения внимания (не используется во всех моделях). Актуально только еслиconfig.is_decoder=Trueили если модель является генеративной моделью только с декодером. - label_length (
int, необязательный, по умолчанию 10) — Длина стартового токена декодера Autoformer, используемая для прямого многошагового прогнозирования (т. е. неавто-регрессивной генерации). - moving_average (
int, необязательный, по умолчанию 25) — Размер окна скользящего среднего. На практике это размер ядра в AvgPool1d слоя Decomposition. - autocorrelation_factor (
int, необязательный, по умолчанию 3) — коэффициент «Attention» (механизм AutoCorrelation), используемый для поиска задержек топ-k автокорреляций. В статье рекомендуется устанавливать значение от 1 до 5.
Это класс конфигурации для хранения конфигурации модели AutoformerModel. Он используется для создания модели Autoformer в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации huggingface/autoformer-tourism-monthly
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Пример:
>>> 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.configAutoformerModel
класс transformers.AutoformerModel
< source >( config: AutoformerConfig )
Параметры
- config (AutoformerConfig) — Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
Модель Autoformer без дополнительных слоёв, выводящая необработанные скрытые состояния.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → AutoformerModelOutput or tuple(torch.Tensor)
Параметры
- 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), , необязательный) — Маска типа bool, указывающая, какие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_valuesTransformer должен научиться выводить, получив на вход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, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован 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) и входных данных.
Метод forward модели 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. Подробнее см. в нашем руководстве по кэшу kv.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход
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), необязательный) — Статические признаки каждого временного ряда в батче, которые копируются в ковариаты во время инференса.
Примеры:
>>> 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_stateAutoformerForPrediction
класс transformers.AutoformerForPrediction
< source >( config: AutoformerConfig )
Параметры
- config (AutoformerConfig) — Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
Модель Autoformer с распределительным слоем (distribution head) для прогнозирования временных рядов.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonefuture_observed_mask: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSPredictionOutput or tuple(torch.Tensor)
Параметры
- 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), , необязательный) — Маска типа bool, указывающая, какие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_valuesTransformer должен научиться выводить, получив на вход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, заменённых нулями). Эта маска используется для отфильтровывания отсутствующих значений при вычислении итоговой функции потерь.[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, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован 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 или tuple(torch.Tensor)
Объект Seq2SeqTSPredictionOutput или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (AutoformerConfig) и входных данных.
Метод forward класса 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. Подробнее см. в нашем руководстве по кэшу kv.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход
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), необязательный) — Статические признаки каждого временного ряда в батче, которые копируются в ковариаты во время инференса.
Примеры:
>>> 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"], ... )