TimesFM (Time Series Foundation Model) 是由 Google Research 开发的预训练时间序列基础模型，用于时间序列预测。

• 论文：A decoder-only foundation model for time-series forecasting，将发表于 ICML 2024。
• Google Research 博客
• Hugging Face 检查点库

本库包含加载公共 TimesFM 检查点并运行模型推理的代码。请访问我们的 Hugging Face 检查点库 下载模型检查点。

这不是 Google 官方支持的产品。

我们建议至少 16GB RAM 来加载 TimesFM 依赖项。

• 要安装 TimesFM，现在可以直接执行：pip install timesfm。
• 发布了 微调支持，允许您在自己的数据上微调预训练的 TimesFM 模型权重。
• 发布了 ~零-shot 协变量支持，支持外部回归器。更多细节请见 这里。

timesfm-1.0-200m 是第一个公开的模型检查点：

• 它执行单变量时间序列预测，支持最多 512 时间点的上下文长度和任意的预测期长度，且可选频率指示器。
• 它专注于点预测，不支持概率预测。我们实验性地提供了分位数头，但它们在预训练后尚未经过校准。
• 它要求上下文是连续的（即没有“空洞”），且上下文和预测期具有相同的频率。

请参考我们的扩展基准结果表和长周期基准。

请查看 experiments/ 目录中相应基准测试目录中的 README 文件，了解如何在各个基准测试上运行 TimesFM。

要将 TimesFM 安装为一个包，可以运行以下命令，无需克隆此库：

pip install timesfm

为了调用 TimesFM，我们提供了两个环境文件。在 timesfm 文件夹中，针对 GPU 安装（假设已设置 CUDA 12），您可以通过以下方式从基础文件夹创建 conda 环境 tfm_env：

conda env create --file=environment.yml

For a CPU setup please use,

conda env create --file=environment_cpu.yml

to create the environment instead.

Follow by

conda activate tfm_env
pip install -e .

to install the package.

Note:

1. 运行提供的基准测试需要额外的依赖项。 请使用 experiments 文件夹中的环境文件。

2. 依赖项 lingvo 不支持 ARM 架构，且该代码在 Apple Silicon 的机器上无法运行。我们已意识到此问题并正在寻找解决方案，请关注后续更新。

要从当前的仓库/本地版本安装（就像以前使用 pip -e . 一样），可以运行以下命令：

pip install poetry # optional
poetry install

这将把环境安装到本地的 .venv 文件夹中（取决于配置），并将 Python 命令匹配到 poetry 环境。如果不是这种情况，您可以使用 poetry run python 来使用本地环境。

1. 运行提供的基准测试需要额外的依赖项。 请使用 experiments 文件夹中的环境文件。

2. 依赖项 lingvo 不支持 ARM 架构，且该代码在 Apple Silicon 的机器上无法运行。我们已意识到此问题并正在寻找解决方案，请关注后续更新。

可以使用 poetry build 命令构建包。

要构建并发布到 PyPI，可以使用 poetry publish 命令。此命令要求用户具有将包发布到 PyPI 仓库的必要权限。

然后可以加载基类，如下所示：

import timesfm

tfm = timesfm.TimesFm(
    context_len=<context>,
    horizon_len=<horizon>,
    input_patch_len=32,
    output_patch_len=128,
    num_layers=20,
    model_dims=1280,
    backend=<backend>,
)
tfm.load_from_checkpoint(repo_id="google/timesfm-1.0-200m")

Note that the four parameters are fixed to load the 200m model

input_patch_len=32,
output_patch_len=128,
num_layers=20,
model_dims=1280,

1. 这里的 context_len 可以设置为模型的最大上下文长度。它需要是 input_patch_len 的倍数，即 32 的倍数。 您可以向 tfm.forecast() 函数提供较短的序列，模型会处理它。目前，模型处理的最大上下文长度为 512，后续版本中可以增加。输入时间序列可以具有 任何上下文长度。如果需要，推理代码将处理填充/截断。

2. 预测期长度可以设置为任意值。我们建议将其设置为您应用中所需的最大预测期长度。通常，我们建议预测期长度 <= 上下文长度，但这不是函数调用中的要求。

3. backend 是 "cpu"、"gpu" 或 "tpu" 中的一个，区分大小写。

我们提供了 API 用于从数组输入或 pandas 数据框进行预测。两种预测方法都需要以下内容：(1) 输入的时间序列上下文，(2) 以及它们的频率。请查阅函数 tfm.forecast() 和 tfm.forecast_on_df() 的文档以获取详细说明。

特别是关于频率，TimesFM 期望一个值为 {0, 1, 2} 的类别指示符：

• 0（默认）：高频，长时间序列。我们建议将此用于每日粒度的时间序列。
• 1：中频时间序列。我们建议将此用于每周和每月的数据。
• 2：低频，短期时间序列。我们建议将此用于超过每月的时间序列，例如季度或年度。

此类别值应直接与数组输入一起提供。对于数据框输入，我们将传统的频率字母编码转换为我们预期的类别，如下所示：

• 0：T, MIN, H, D, B, U
• 1：W, M
• 2：Q, Y

请注意，您不必严格按照我们的建议来设置。虽然这是我们在模型训练过程中使用的设置，并且我们期望它提供最佳的预测结果，但您也可以将频率输入视为一个自由参数，根据您的具体使用场景进行修改。

Examples:

Array inputs, with the frequencies set to low, medium and high respectively.

import numpy as np
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]

point_forecast, experimental_quantile_forecast = tfm.forecast(
    forecast_input,
    freq=frequency_input,
)

pandas dataframe, with the frequency set to "M" monthly.

import pandas as pd

# e.g. input_df is
#       unique_id  ds          y
# 0     T1         1975-12-31  697458.0
# 1     T1         1976-01-31  1187650.0
# 2     T1         1976-02-29  1069690.0
# 3     T1         1976-03-31  1078430.0
# 4     T1         1976-04-30  1059910.0
# ...   ...        ...         ...
# 8175  T99        1986-01-31  602.0
# 8176  T99        1986-02-28  684.0
# 8177  T99        1986-03-31  818.0
# 8178  T99        1986-04-30  836.0
# 8179  T99        1986-05-31  878.0

forecast_df = tfm.forecast_on_df(
    inputs=input_df,
    freq="M",  # monthly
    value_name="y",
    num_jobs=-1,
)

我们现在在 TimesFM 基础上提供了一个外部回归器库，可以支持静态协变量以及未来可用的动态协变量。我们在 notebooks/covariates.ipynb 中提供了一个使用示例。

让我们以一个简单的例子来预测一个杂货店的销售额：

任务： 给定这周（7天）的每日销售数据，预测下周（7天）的每日销售额。

Product: ice cream
Daily_sales: [30, 30, 4, 5, 7, 8, 10]
Category: food
Base_price: 1.99
Weekday: [0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6]
Has_promotion: [Yes, Yes, No, No, No, Yes, Yes, No, No, No, No, No, No, No]
Daily_temperature: [31.0, 24.3, 19.4, 26.2, 24.6, 30.0, 31.1, 32.4, 30.9, 26.0, 25.0, 27.8, 29.5, 31.2]

Product: sunscreen
Daily_sales: [5, 7, 12, 13, 5, 6, 10]
Category: skin product
Base_price: 29.99
Weekday: [0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6]
Has_promotion: [No, No, Yes, Yes, No, No, No, Yes, Yes, Yes, Yes, Yes, Yes, Yes]
Daily_temperature: [31.0, 24.3, 19.4, 26.2, 24.6, 30.0, 31.1, 32.4, 30.9, 26.0, 25.0, 27.8, 29.5, 31.2]

在这个例子中，除了 Daily_sales 外，我们还具有协变量 Category、Base_price、Weekday、Has_promotion 和 Daily_temperature。让我们介绍一些概念：

静态协变量 是每个时间序列的协变量。

• 在我们的例子中，Category 是一个 静态分类协变量，
• Base_price 是一个 静态数值协变量。

动态协变量 是每个时间戳的协变量。

• 与日期/时间相关的特征通常可以视为动态协变量。
• 在我们的例子中，Weekday 和 Has_promotion 是 动态分类协变量，
• Daily_temperature 是 动态数值协变量。

注意： 在此，我们要求动态协变量必须覆盖预测上下文和预测期。例如，例子中的所有动态协变量都有 14 个值：前 7 个值对应观察到的 7 天，后 7 个值对应接下来的 7 天。

我们现在可以将两种产品的历史数据与静态和动态协变量作为批量输入提供给 TimesFM，并生成考虑协变量的预测。想了解更多内容，请查看 notebooks/covariates.ipynb 中的示例。

我们在 notebooks/finetuning.ipynb 中提供了一个在新数据集上微调模型的示例。

如果您希望提交 PR，请确保使用我们的格式化风格。我们使用 yapf 进行格式化，使用以下选项：

[style]
based_on_style = google
# Add your custom style rules here
indent_width = 2
spaces_before_comment = 2

Please run yapf --in-place --recursive <filename> on all affected files.