TimesFM

TimesFM（时间序列基础模型）是由Google Research开发的用于时间序列预测的预训练时间序列基础模型。

• 论文：用于时间序列预测的仅解码器基础模型，将发表于ICML 2024。
• Google Research博客
• Hugging Face检查点仓库

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

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

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

更新 - 2024年8月6日

• 感谢@tanmayshishodia检入了LoRA和DoRA等PEFT方法。
• 现在安装TimesFM，你可以简单地执行：pip install timesfm。
• 推出了微调支持，允许你在自己的数据上微调预训练的TimesFM模型权重。
• 推出了近零样本协变量支持，支持外部回归变量。更多详情在此。

检查点 timesfm-1.0-200m

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

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

基准测试

请参考我们在扩展基准测试和长期预测基准测试上的结果表。

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

安装

作为软件包安装

要将TimesFM作为软件包安装，无需克隆此仓库，可以运行以下命令：

pip install timesfm

使用conda安装

对于调用TimesFM，我们有两个环境文件。在timesfm中，对于GPU安装（假设已设置CUDA 12），你可以通过以下方式从基本文件夹创建conda环境tfm_env：

conda env create --file=environment.yml

对于CPU设置，请使用：

conda env create --file=environment_cpu.yml

来创建环境。

然后执行：

conda activate tfm_env
pip install -e .

以安装软件包。

注意：

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

2. 依赖项lingvo不支持ARM架构，代码不适用于Apple Silicon机器。我们知道这个问题，正在寻求解决方案。敬请关注。

使用poetry进行本地安装

要从当前仓库/本地版本安装（类似于之前使用pip -e .的方式），你可以运行以下命令：

pip install poetry # 可选
poetry install

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

注意事项

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

2. 依赖项lingvo不支持ARM架构，代码不适用于Apple Silicon机器。我们知道这个问题，正在寻求解决方案。敬请关注。

构建软件包并发布到PyPI

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

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

使用方法

初始化模型并加载检查点

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

import timesfm

tfm = timesfm.TimesFm(
    context_len=<上下文>,
    horizon_len=<预测期>,
    input_patch_len=32,
    output_patch_len=128,
    num_layers=20,
    model_dims=1280,
    backend=<后端>,
)
tfm.load_from_checkpoint(repo_id="google/timesfm-1.0-200m")

注意，以下四个参数是固定的，用于加载200m模型：

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

请注意，你不必严格遵循我们的建议。尽管这是我们在模型训练期间的设置，我们期望它能提供最佳预测结果，但你也可以将频率输入视为自由参数，并根据你的具体用例进行修改。

示例：

数组输入，频率分别设置为低、中、高。

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数据框，频率设置为"M"月度。

import pandas as pd
# 例如input_df为
#       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",  # 月度
    value_name="y",
    num_jobs=-1,
)

协变量支持

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

让我们以预测杂货店销售额为例：

任务： 给定本周观察到的每日销售额（7天），预测下周的每日销售额（7天）。

产品：冰激凌
每日销售额：[30, 30, 4, 5, 7, 8, 10]
类别：食品
基础价格：1.99
星期几：[0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6]
是否促销：[是, 是, 否, 否, 否, 是, 是, 否, 否, 否, 否, 否, 否, 否]
每日温度：[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]

产品：防晒霜
每日销售额：[5, 7, 12, 13, 5, 6, 10]
类别：护肤产品
基础价格：29.99
星期几：[0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6]
是否促销：[否, 否, 是, 是, 否, 否, 否, 是, 是, 是, 是, 是, 是, 是]
每日温度：[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]

在这个例子中，除了"每日销售额"，我们还有协变量"类别"、"基础价格"、"星期几"、"是否促销"、"每日温度"。让我们介绍一些概念：

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

• 在我们的例子中，"类别"是一个静态分类协变量，
• "基础价格"是一个静态数值协变量。

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

• 日期/时间相关的特征通常可以被视为动态协变量。
• 在我们的例子中，"星期几"和"是否促销"是动态分类协变量。
• "每日温度"是一个动态数值协变量。

**注意：**这里我们强制要求动态协变量需要覆盖预测上下文和预测范围。例如，示例中的所有动态协变量都有14个值：前7个对应观察到的7天，后7个对应接下来的7天。

现在我们可以将两种产品的过去数据以及静态和动态协变量作为批量输入提供给TimesFM，并生成考虑了协变量的预测结果。要了解更多信息，请查看notebooks/covariates.ipynb中的示例。

微调

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

贡献风格指南

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

[style]
based_on_style = google
# 在此添加自定义风格规则
indent_width = 2
spaces_before_comment = 2

请对所有受影响的文件运行yapf --in-place --recursive <filename>。