Timesfm 1.0 200m

🚀 TimesFM

TimesFM（时间序列基础模型）是由谷歌研究团队开发的预训练时间序列基础模型，用于时间序列预测。它为时间序列预测任务提供了强大的支持，能帮助用户更准确地预测未来趋势。

资源与技术文档

• 论文：A decoder-only foundation model for time-series forecasting，即将发表于ICML 2024。
• 谷歌研究博客：Google Research blog
• GitHub仓库：GitHub repo

作者

谷歌研究团队

⚠️ 重要提示 这并非谷歌官方支持的产品。

📦 安装指南

此HuggingFace仓库托管了TimesFm的模型检查点。请访问我们的GitHub仓库，并按照其中的说明安装timesfm库以进行模型推理。

⚠️ 重要提示 依赖项lingvo不支持ARM架构，因此推理代码在配备Apple silicon的机器上无法运行。我们已注意到这个问题，正在努力解决，请持续关注。

💻 使用示例

基础用法

初始化模型并加载检查点

可以按以下方式加载基类：

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")

⚠️ 重要提示 加载200m模型时，以下四个参数是固定的：

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

💡 使用建议

1. 此处的context_len可以设置为模型的最大上下文长度。你可以向tfm.forecast()函数提供更短的序列，模型会自动处理。目前，模型处理的最大上下文长度为512，后续版本可能会增加。输入的时间序列可以是任意上下文长度。如果需要，推理代码会处理填充或截断操作。
2. 预测长度（horizon_len）可以设置为任意值。我们建议将其设置为应用程序预测任务中所需的最大预测长度。一般来说，我们建议预测长度 <= 上下文长度，但在函数调用中这不是必需的。

高级用法

进行推理

我们提供了从数组输入或pandas数据框进行预测的API。两种预测方法都需要（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”（每月）的pandas数据框输入示例：

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 - 1.0 - 200m

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

• 它可以对上下文长度达512个时间点和任意预测长度的单变量时间序列进行预测，并可选择使用频率指标。
• 它专注于点预测，不支持概率预测。我们实验性地提供了分位数头，但在预训练后尚未进行校准。
• 它要求上下文是连续的（即没有“空洞”），并且上下文和预测长度的频率必须相同。

基准测试

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

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

📄 许可证

本项目采用Apache - 2.0许可证。