Эта модель была опубликована в HF papers 14.10.2023 и добавлена в Hugging Face Transformers 27.02.2026.

TimesFM 2.5

Обзор

TimesFM 2.5 (Time Series Foundation Model) — это предобученная фундаментальная модель для временных рядов, предложенная в работе A decoder-only foundation model for time-series forecasting авторами Abhimanyu Das, Weihao Kong, Rajat Sen и Yichen Zhou. Она основана на исходной архитектуре TimesFM и дополнена механизмами rotary attention, нормализацией QK, масштабированием внимания по каждому измерению и непрерывным предсказанием квантилей.

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

Вдохновлённые недавними достижениями в области больших языковых моделей для обработки естественного языка (NLP), мы разработали фундаментальную модель для прогнозирования временных рядов, чья «из коробки» zero-shot производительность на разнообразных публичных наборах данных приближается к точности передовых моделей с учителем, обученных на каждом конкретном наборе данных. Наша модель основана на предварительном обучении декодерной модели внимания с использованием входных патчей, на большом корпусе временных рядов, включающем как реальные, так и синтетические данные. Эксперименты на разнообразном наборе ранее невиданных данных для прогнозирования показывают, что модель способна давать точные zero-shot прогнозы в различных областях, с разными горизонтами прогнозирования и временными гранулярностями.

Эта модель была предоставлена пользователем kashif. Исходный код можно найти здесь.

Чекпоинт можно найти по адресу google/timesfm-2.5-200m-transformers.

Пример использования

import numpy as np
import torch

from transformers import TimesFm2_5ModelForPrediction


model = TimesFm2_5ModelForPrediction.from_pretrained(
    "google/timesfm-2.5-200m-transformers",
    device_map="auto",
)

forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
forecast_input_tensor = [torch.tensor(ts, dtype=torch.float32, device=model.device) for ts in forecast_input]

with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, return_dict=True)
    point_forecast = outputs.mean_predictions
    quantile_forecast = outputs.full_predictions

TimesFm2_5Config

класс transformers.TimesFm2_5Config

< 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 = 0is_encoder_decoder: bool = Falseid2label: 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 = Nonepatch_length: int = 32context_length: int = 16384horizon_length: int = 128num_hidden_layers: int = 20hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16rms_norm_eps: float = 1e-06quantiles: list[float] | tuple[float, ...] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9)attention_dropout: float | int = 0.0initializer_range: float = 0.02num_key_value_heads: int = 16attention_bias: bool = Falseoutput_quantile_len: int = 1024decode_index: int = 5use_bias: bool = Falseactivation: str = 'swish'use_continuous_quantile_head: bool = Trueforce_flip_invariance: bool = Trueinfer_is_positive: bool = Truemax_position_embeddings: int = 16384rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )

Параметры

patch_length (int, необязательный, по умолчанию 32) — Длина одного патча во входной последовательности.
context_length (int, необязательный, по умолчанию 16384) — Длина входного контекста.
horizon_length (int, необязательный, по умолчанию 128) — Длина горизонта предсказания.
num_hidden_layers (int, необязательный, по умолчанию 20) — Количество скрытых слоев в декодере Transformer.
hidden_size (int, необязательный, по умолчанию 1280) — Размерность скрытых представлений.
intermediate_size (int, необязательный, по умолчанию 1280) — Размерность представлений MLP.
head_dim (int, необязательный, по умолчанию 80) — Размерность головы внимания. Если значение равно None, по умолчанию используется hidden_size // num_attention_heads
num_attention_heads (int, необязательный, по умолчанию 16) — Количество головок внимания в каждом слое внимания декодера Transformer.
rms_norm_eps (float, необязательный, по умолчанию 1e-06) — Значение epsilon, используемое слоями нормализации rms.
quantiles (list[float], необязательный, по умолчанию [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) — Квантили, которые необходимо предсказать.
attention_dropout (Union[float, int], необязательный, по умолчанию 0.0) — Коэффициент dropout для вероятностей внимания.
initializer_range (float, необязательный, по умолчанию 0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов.
num_key_value_heads (int, необязательный, по умолчанию 16) — Это количество ключевых и value-голов, используемых для реализации Grouped Query Attention. Если num_key_value_heads=num_attention_heads, модель использует Multi Head Attention (MHA); если num_key_value_heads=1 — Multi Query Attention (MQA); в остальных случаях применяется GQA. При конвертации мультиголовного чекпоинта в GQA-чекпоинт каждая групповая ключевая и value-голова должна построиться путём усреднения (meanpooling) всех исходных голов в этой группе. Дополнительные сведения см. в этой статье. Если значение не указано, по умолчанию используется num_attention_heads.
attention_bias (bool, необязательный, по умолчанию False) — Использовать ли смещение (bias) в слоях проекции query, key, value и output при само-внимании.
output_quantile_len (int, необязательный, по умолчанию 1024) — Длина размерности проекции выходных квантилей.
decode_index (int, необязательный, по умолчанию 5) — Индекс в размерности квантилей, используемый для извлечения точечного (медианного) прогноза.
use_bias (bool, необязательный, по умолчанию False) — Использовать ли смещение (bias) в линейных слоях MLP и трансформера.
activation (str, необязательный, по умолчанию swish) — Нелинейная функция активации (функция или строка) в декодере. Например, "gelu", "relu", "silu" и т. д.
use_continuous_quantile_head (bool, необязательный, по умолчанию True) — Определяет, следует ли использовать непрерывную квантильную головку для предсказаний квантилей, отличных от медианы.
force_flip_invariance (bool, необязательный, по умолчанию True) — Определяет, следует ли применять усреднение с инвариантностью к отражению при прогнозировании.
infer_is_positive (bool, необязательный, по умолчанию True) — Определяет, следует ли ограничивать прогнозы неотрицательными значениями, если минимальное значение входных данных неотрицательно.
max_position_embeddings (int, необязательный, по умолчанию 16384) — Максимальная длина последовательности, с которой может использоваться эта модель.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], необязательный) — Словарь, содержащий параметры конфигурации для эмбеддингов RoPE. Словарь должен содержать значение для rope_theta и, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длинными max_position_embeddings.

Это класс конфигурации для хранения настроек модели TimesFm2_5Model. Он используется для создания модели Timesfm2 5 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации google/timesfm-2.5-200m-transformers

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Пример:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

>>> configuration = TimesFm2_5Config()
>>> model = TimesFm2_5ModelForPrediction(configuration)
>>> configuration = model.config

TimesFm2_5Model

класс transformers.TimesFm2_5Model

< source >

( config: TimesFm2_5Config )

forward

< source >

( past_values: Tensorpast_values_padding: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5Output or tuple(torch.Tensor)

Параметры

past_values (torch.Tensor формы (batch_size, sequence_length)) — Прошлые значения временного ряда, используемые в качестве входных данных для модели.
past_values_padding (torch.LongTensor формы (batch_size, sequence_length), необязательный) — Маска заполнения для входных данных. 1 обозначает заполненные (замаскированные) временные шаги, 0 — действительные значения.

Возвращает

TimesFm2_5Output или tuple(torch.Tensor)

TimesFm2_5Output или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (TimesFm2_5Config) и входных данных.

Метод forward модели TimesFm2_5Model переопределяет специальный метод __call__.

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

last_hidden_state (torch.Tensor формы (batch_size, sequence_length, hidden_size)) — Последовательность скрытых состояний на выходе последнего слоя модели.
hidden_states (tuple(torch.Tensor), optional, возвращается, если передано output_hidden_states=True или если config.output_hidden_states=True) — кортеж из torch.Tensor (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы (batch_size, sequence_length, hidden_size).

Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
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), необязательный) — значения масштабирования для контекстного окна каждого временного ряда, используемые для приведения входных данных модели к одинаковому порядку величины, а затем для обратного масштабирования к исходной величине.
context_mu (torch.Tensor формы (batch_size, num_patches)) — Вычисляемые на каждом входном патче во время нормализации средние значения.
context_sigma (torch.Tensor формы (batch_size, num_patches)) — Стандартные отклонения, вычисленные для каждого входного патча в процессе нормализации.

TimesFm2_5ModelForPrediction

класс transformers.TimesFm2_5ModelForPrediction

< source >

( config: TimesFm2_5Config )

Модель TimesFm2_5 для предсказания квантилей и среднего значения.

forward

< source >

( past_values: collections.abc.Sequence[torch.Tensor]window_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonetruncate_negative: bool | None = Noneforce_flip_invariance: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5OutputForPrediction or tuple(torch.Tensor)

Параметры

past_values (collections.abc.Sequence[torch.Tensor]) — Прошлые значения временного ряда, которые используются в качестве входных данных для модели. Каждый тензор представляет собой одномерный временной ряд.
window_size (int, необязательный) — Размер окна для разложения на тренд и остаток. Если None, разложение не применяется.
future_values (torch.Tensor, необязательный) — Необязательные будущие значения, используемые для вычисления функции потерь.
forecast_context_len (int, необязательный) — Необязательное переопределение длины контекста, используемое при прогнозировании.
truncate_negative (bool, необязательный) — Определяет, следует ли ограничивать выходные значения неотрицательными. Если None, по умолчанию используется config.infer_is_positive.
force_flip_invariance (bool, необязательный) — Указывает, следует ли применять комбинацию flip-invariance. Если None, по умолчанию используется config.force_flip_invariance.

Возвращает

TimesFm2_5OutputForPrediction или tuple(torch.Tensor)

TimesFm2_5OutputForPrediction или кортеж torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (TimesFm2_5Config) и входных данных.

Метод forward модели TimesFm2_5ModelForPrediction переопределяет специальный метод __call__.

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

last_hidden_state (torch.Tensor формы (batch_size, sequence_length, hidden_size)) — Последовательность скрытых состояний на выходе последнего слоя модели.
hidden_states (tuple(torch.Tensor), optional, возвращается, если передано output_hidden_states=True или если config.output_hidden_states=True) — кортеж из torch.Tensor (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы (batch_size, sequence_length, hidden_size).

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

Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
mean_predictions (torch.Tensor формы (batch_size, horizon_length)) — Детерминированные прогнозы после денормализации.
full_predictions (torch.Tensor формы (batch_size, horizon_length, quantiles)) — Прогнозы квантилей, включая медиану, после денормализации.
loss (torch.Tensor формы (1,), необязательный, возвращается, если передано future_values) — Потери обучения, объединяющие MSE и квантильные потери, если предоставлены целевые значения.

Update on GitHub