google-research timesfm

以下是根据您的要求翻译的中文版本，保留原文结构、技术术语和代码块，并输出为 Markdown 格式。

google-research timesfm

TimesFM（Time Series Foundation Model）是由 Google Research 开发的一个预训练时间序列基础模型，用于时间序列预测。论文：*A decoder-only foundation model for time-series forecasting*，ICML 2024。所有检查点：TimesFM Hugging Face 集合。 Google Research 博客。 TimesFM 在 Google 1P 产品中的应用：

BigQuery ML：企业级 SQL 查询，具备可扩展性和可靠性。
Google Sheets：用于日常电子表格操作。
Vertex Model Garden：支持代理调用的 Docker 化端点。

此开放版本并非 Google 官方支持的产品。

最新模型版本：TimesFM 2.5

已归档模型版本：1.0 和 2.0：相关代码已归档在子目录 v1 中。您可以通过 pip install timesfm==1.3.0 安装旧版包来加载它们。

更新 - 2026 年 6 月 5 日 将 PyPI 更新为 timesfm=2.0.0。请参阅安装说明。

更新 - 2026 年 4 月 9 日 新增了使用 HuggingFace Transformers + PEFT（LoRA）的微调示例 — 请参见 timesfm-forecasting/examples/finetuning/。同时新增了单元测试（tests/）并整合了多项社区修复。特别感谢 @kashif 和 @darkpowerxo。

更新 - 2026 年 3 月 19 日 特别感谢 @borealBytes 添加了对 AGENTS 的支持！TimesFM SKILL.md 已发布。

更新 - 2025 年 10 月 29 日 通过 XReg 为 TimesFM 2.5 重新添加了协变量支持。

更新 - 2025 年 9 月 15 日 TimesFM 2.5 发布！与 TimesFM 2.0 相比，新的 2.5 模型：

使用 2 亿参数，从 5 亿参数减少。
支持最多 16k 上下文长度，从 2048 提升。
通过可选的 3000 万参数分位数头，支持最多 1k 预测范围的连续分位数预测。
移除了频率指示器。
新增了几个预测标志。

自 2025 年 9 月发布以来，已完成以下改进：

✅ 用于更快推理的 Flax 版本模型。
✅ 通过 XReg 的协变量支持（参见 2025 年 10 月更新）。
✅ 文档、示例和代理技能（参见 timesfm-forecasting/）。
✅ 通过 HuggingFace Transformers + PEFT 使用 LoRA 的微调示例（参见 timesfm-forecasting/examples/finetuning/）。
✅ 核心层、配置和工具的单元测试（参见 tests/）。

安装

从 PyPI 安装

# 使用 torch 安装包
pip install timesfm[torch]

# 或使用 Flax
pip install timesfm[flax]

# 当需要 XReg 时
pip install timesfm[xreg]

本地安装

克隆仓库：

git clone https://github.com/google-research/timesfm.git
cd timesfm

创建虚拟环境并使用 uv 安装依赖：

# 创建虚拟环境
uv venv

# 激活环境
source .venv/bin/activate

# 以可编辑模式安装包（使用 torch）
uv pip install -e .[torch]

# 或使用 flax
uv pip install -e .[flax]

# 当需要 XReg 时
uv pip install -e .[xreg]

[可选] 根据您的操作系统和加速器（CPU、GPU、TPU 或 Apple Silicon）安装首选的 torch / jax 后端：

安装 PyTorch。
安装用于 Flax 的 Jax。

代码示例

import torch
import numpy as np
import timesfm

torch.set_float32_matmul_precision("high")

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)

model.compile(
    timesfm.ForecastConfig(
        max_context=1024,
        max_horizon=256,
        normalize_inputs=True,
        use_continuous_quantile_head=True,
        force_flip_invariance=True,
        infer_is_positive=True,
        fix_quantile_crossing=True,
    )
)

point_forecast, quantile_forecast = model.forecast(
    horizon=12,
    inputs=[
        np.linspace(0, 1, 100),
        np.sin(np.linspace(0, 20, 67)),
    ],  # 两个虚拟输入
)

point_forecast.shape  # (2, 12)
quantile_forecast.shape  # (2, 12, 10): 均值，然后是第10到第90分位数