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

TimesFM

Обзор

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

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

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

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

Для использования модели:

import numpy as np
import torch

from transformers import TimesFmModelForPrediction


model = TimesFmModelForPrediction.from_pretrained(
    "google/timesfm-2.0-500m-pytorch",
    attn_implementation="sdpa",
    device_map="auto"
)


 # Create dummy inputs
forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]

# Convert inputs to sequence of tensors
forecast_input_tensor = [
    torch.tensor(ts).to(model.device)
    for ts in forecast_input
]
frequency_input_tensor = torch.tensor(frequency_input, dtype=torch.long).to(model.device)

# Get predictions from the pre-trained model
with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, freq=frequency_input_tensor, return_dict=True)
    point_forecast_conv = outputs.mean_predictions.float().cpu().numpy()
    quantile_forecast_conv = outputs.full_predictions.float().cpu().numpy()

TimesFmConfig

класс transformers.TimesFmConfig

< 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 = 512horizon_length: int = 128freq_size: int = 3num_hidden_layers: int = 50hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16tolerance: float = 1e-06rms_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)pad_val: float = 1123581321.0attention_dropout: float | int = 0.0use_positional_embedding: bool = Falseinitializer_range: float = 0.02min_timescale: int = 1max_timescale: int = 10000 )

Параметры

patch_length (int, необязательный, по умолчанию 32) — Длина одного патча во входной последовательности.
context_length (int, необязательный, по умолчанию 512) — Длина входного контекста.
horizon_length (int, необязательный, по умолчанию 128) — Длина горизонта предсказания.
freq_size (int, необязательный, по умолчанию 3) — Количество частотных эмбеддингов.
num_hidden_layers (int, необязательный, по умолчанию 50) — Количество скрытых слоев в декодере 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.
tolerance (float, необязательный, по умолчанию 1e-06) — Допустимая погрешность для функции потерь квантилей.
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]) — Квантили, которые необходимо предсказать.
pad_val (float, необязательный, по умолчанию 1123581321.0) — Значение, используемое для дополнения предсказаний.
attention_dropout (float, необязательный, по умолчанию 0.0) — Вероятность dropout для оценок внимания.
use_positional_embedding (bool, необязательный, по умолчанию False) — Указывает, следует ли добавлять позиционные эмбеддинги.
initializer_range (float, необязательный, по умолчанию 0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов.
min_timescale (int, необязательный, по умолчанию 1) — Начало геометрического позиционного индекса. Определяет периодичность добавляемого сигнала.
max_timescale (int, необязательный, по умолчанию 10000) — Конец геометрического позиционного индекса. Определяет частоту добавляемого сигнала.

Это класс конфигурации для хранения настроек модели TimesFmModel. Он используется для создания модели Timesfm в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации google/timesfm-2.0-500m-pytorch

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

TimesFmModel

класс transformers.TimesFmModel

< source >

( config: TimesFmConfig )

Параметры

config (TimesFmConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().

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

Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

forward

< source >

( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)

Параметры

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

Возвращает

TimesFmOutput или tuple(torch.Tensor)

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

Метод forward модели TimesFmModel переопределяет специальный метод __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, )) — среднее значений входных временных рядов.
scale (torch.Tensor формы (batch_size,)) — масштаб входных временных рядов.

TimesFmModelForPrediction

класс transformers.TimesFmModelForPrediction

< source >

( config: TimesFmConfig )

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

forward

< source >

( past_values: Sequencefreq: collections.abc.Sequence[typing.Union[torch.Tensor, int]] | None = Nonewindow_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonereturn_forecast_on_context: bool = Falsetruncate_negative: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutputForPrediction or tuple(torch.Tensor)

Параметры

past_values (torch.Tensor формы (batch_size, sequence_length)) — Прошлые значения временного ряда, которые служат входом для модели.
freq (torch.LongTensor формы (batch_size,)) — Индексы частоты для данных временного ряда.
window_size (int, необязательный) — Размер окна для разложения на тренд и остаток. Если значение равно None, разложение не выполняется.
future_values (torch.Tensor, необязательный) — Необязательные будущие значения временного ряда, используемые для вычисления функции потерь.
forecast_context_len (int, необязательный) — Необязательная максимальная длина контекста.
return_forecast_on_context (bool, необязательный) — True, чтобы возвращать прогноз на контексте, когда он доступен, то есть после первого входного патча.
truncate_negative (bool, необязательный) — Обрезать до только неотрицательных значений, если в любом из контекстов есть неотрицательные значения, в противном случае ничего не делать.

Возвращает

TimesFmOutputForPrediction или tuple(torch.Tensor)

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

Метод forward модели TimesFmModelForPrediction переопределяет специальный метод __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, sequence_length)) — Средние предсказания временного ряда.
full_predictions (torch.Tensor формы (batch_size, sequence_length)) — Полные прогнозы временного ряда, включая среднее значение и квантили.
loss (torch.Tensor формы (1,), необязательный, возвращается, если передано future_values) — Потеря модели TimesFM.

Пример:

>>> from transformers import TimesFmModelForPrediction

>>> model = TimesFmModelForPrediction.from_pretrained("google/timesfm-2.0-500m-pytorch")

>>> forecast_input = [torch.linspace(0, 20, 100).sin(), torch.linspace(0, 20, 200).sin(), torch.linspace(0, 20, 400).sin()]
>>> frequency_input = torch.tensor([0, 1, 2], dtype=torch.long)

>>> # Generate
>>> with torch.no_grad():
>>>     outputs = model(past_values=forecast_input, freq=frequency_input, return_dict=True)
>>>     point_forecast_conv = outputs.mean_predictions
>>>     quantile_forecast_conv = outputs.full_predictions

Update on GitHub