# TimesFM

## Обзор

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

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

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

Эта модель была предоставлена пользователем [kashif](https://huggingface.co/kashif). Исходный код можно найти [здесь](https://github.com/google-research/timesfm).

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

```python
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]]

#### transformers.TimesFmConfig[[transformers.TimesFmConfig]]

```python
transformers.TimesFmConfig(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, is_encoder_decoder: bool = False, 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, patch_length: int = 32, context_length: int = 512, horizon_length: int = 128, freq_size: int = 3, num_hidden_layers: int = 50, hidden_size: int = 1280, intermediate_size: int = 1280, head_dim: int = 80, num_attention_heads: int = 16, tolerance: float = 1e-06, rms_norm_eps: float = 1e-06, quantiles: 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.0, attention_dropout: float | int = 0.0, use_positional_embedding: bool = False, initializer_range: float = 0.02, min_timescale: int = 1, max_timescale: int = 10000)
```

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

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

patch_length (`int`, *необязательный*, по умолчанию 32) : Длина одного патча во входной последовательности.

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

horizon_length (`int`, *optional*, по умолчанию 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`, *optional*, по умолчанию 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`, *optional*, по умолчанию 1) : Начало геометрического позиционного индекса. Определяет периодичность добавляемого сигнала.

max_timescale (`int`, *optional*, по умолчанию 10000) : Конец геометрического позиционного индекса. Определяет частоту добавляемого сигнала.

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

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

## TimesFmModel[[transformers.TimesFmModel]]

#### transformers.TimesFmModel[[transformers.TimesFmModel]]

```python
transformers.TimesFmModel(config: TimesFmConfig)
```

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

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

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

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

Эта модель наследуется от [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.TimesFmModel.forward]]

```python
forward(past_values: Tensor, past_values_padding: LongTensor, freq: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

past_values (`torch.Tensor` формы `(batch_size, sequence_length)`) : Предыдущие значения временного ряда, используемые в качестве входных данных для модели.

past_values_padding (`torch.LongTensor` формы `(batch_size, sequence_length)`) : Индикатор заполнения (padding) временного ряда.

freq (`torch.LongTensor` формы `(batch_size,)`) : Индексы частот для данных временного ряда.

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

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `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]]

#### transformers.TimesFmModelForPrediction[[transformers.TimesFmModelForPrediction]]

```python
transformers.TimesFmModelForPrediction(config: TimesFmConfig)
```

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

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

#### forward[[transformers.TimesFmModelForPrediction.forward]]

```python
forward(past_values: collections.abc.Sequence[torch.Tensor], freq: collections.abc.Sequence[typing.Union[torch.Tensor, int]] | None = None, window_size: int | None = None, future_values: typing.Optional[torch.Tensor] = None, forecast_context_len: int | None = None, return_forecast_on_context: bool = False, truncate_negative: bool = False, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

past_values (`torch.Tensor` формы `(batch_size, sequence_length)`) : Предыдущие значения временного ряда, используемые в качестве входных данных для модели.

freq (`torch.LongTensor` формы `(batch_size,)`) : Индексы частот для данных временного ряда.

window_size (`int`, *optional*) : Размер окна для разложения на тренд и остаток. Если значение равно None, разложение не выполняется.

future_values (`torch.Tensor`, *необязательный*) : Необязательные будущие значения временного ряда, используемые для вычисления функции потерь.

forecast_context_len (`int`, *optional*) : Необязательная максимальная длина контекста.

return_forecast_on_context (`bool`, *необязательный*) : True, чтобы возвращать прогноз на контексте, когда он доступен, то есть после первого входного патча.

truncate_negative (`bool`, *необязательный*) : Если в одном из контекстов есть неотрицательные значения, обрезать до только неотрицательных значений, иначе ничего не делать.

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

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `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.

Пример:

```python
>>> 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
```

