google-research--timesfm
wehub-resource-sync
147 行
5.3 KiB
Markdown
147 行
5.3 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/google-research/timesfm) · [上游 README](https://github.com/google-research/timesfm/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# TimesFM
|
||
|
||
TimesFM（Time Series Foundation Model，时间序列基础模型）是 Google Research 开发的预训练时间序列基础模型，用于时间序列预测。
|
||
|
||
* 论文：
|
||
[A decoder-only foundation model for time-series forecasting](https://arxiv.org/abs/2310.10688),
|
||
ICML 2024。
|
||
* 全部检查点：
|
||
[TimesFM Hugging Face Collection](https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6).
|
||
* [Google Research blog](https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/).
|
||
* TimesFM 在 Google 第一方产品中的应用：
|
||
* [BigQuery ML](https://cloud.google.com/bigquery/docs/timesfm-model): 企业级 SQL 查询，兼具可扩展性与可靠性。
|
||
* [Google Sheets](https://workspaceupdates.googleblog.com/2026/02/forecast-data-in-connected-sheets-BigQueryML-TimesFM.html): 适用于日常电子表格场景。
|
||
* [Vertex Model Garden](https://pantheon.corp.google.com/vertex-ai/publishers/google/model-garden/timesfm): 容器化端点，支持 agent 式调用。
|
||
|
||
此开源版本并非 Google 官方支持的产品。
|
||
|
||
**最新模型版本：** TimesFM 2.5
|
||
|
||
**已归档模型版本：**
|
||
|
||
- 1.0 和 2.0：相关代码已归档至子目录 `v1`。你可以 `pip
|
||
install timesfm==1.3.0` 安装该软件包的旧版本以加载
|
||
它们。
|
||
## 更新 - 2026 年 7 月 2 日
|
||
|
||
已将 PyPI 更新至 `timesfm=2.0.2`。参见 [Install](https://github.com/google-research/timesfm#from-pypi).
|
||
|
||
## 更新 - 2026 年 4 月 9 日
|
||
|
||
新增使用 HuggingFace Transformers + PEFT（LoRA）的微调示例 — 参见
|
||
[`timesfm-forecasting/examples/finetuning/`](timesfm-forecasting/examples/finetuning/)。
|
||
同时新增单元测试（`tests/`），并纳入多项社区修复。
|
||
|
||
特别鸣谢 [@kashif](https://github.com/kashif) 与 [@darkpowerxo](https://github.com/darkpowerxo).
|
||
|
||
## 更新 - 2026 年 3 月 19 日
|
||
|
||
大力感谢 [@borealBytes](https://github.com/borealBytes) 添加了对 [AGENTS](https://github.com/google-research/timesfm/blob/master/AGENTS.md)! 的支持；TimesFM [SKILL.md](https://github.com/google-research/timesfm/tree/master/timesfm-forecasting) 已发布。
|
||
|
||
## 更新 - 2025 年 10 月 29 日
|
||
|
||
通过 XReg 为 TimesFM 2.5 重新加入协变量（covariate）支持。
|
||
|
||
|
||
## 更新 - 2025 年 9 月 15 日
|
||
|
||
TimesFM 2.5 正式发布！
|
||
|
||
与 TimesFM 2.0 相比，全新的 2.5 模型：
|
||
|
||
- 参数量为 200M，较此前的 500M 有所减少。
|
||
- 支持最长 16k 上下文长度，较此前的 2048 大幅提升。
|
||
- 通过可选的 30M quantile head，支持最长 1k 预测步长的连续分位数（quantile）预测。
|
||
- 移除了 `frequency` 指示器。
|
||
- 新增若干预测相关标志位。
|
||
|
||
自 2025 年 9 月发布以来，已完成以下改进：
|
||
|
||
1. ✅ 提供 Flax 版本模型，推理更快。
|
||
2. ✅ 通过 XReg 支持协变量（参见 2025 年 10 月更新）。
|
||
3. ✅ 文档、示例与 agent skill（参见 `timesfm-forecasting/`）。
|
||
4. ✅ 基于 HuggingFace Transformers + PEFT 的 LoRA 微调示例（参见 `timesfm-forecasting/examples/finetuning/`）。
|
||
5. ✅ 核心层、配置与工具函数的单元测试（参见 `tests/`）。
|
||
|
||
### 安装
|
||
|
||
#### 通过 `PyPI` 安装
|
||
|
||
```shell
|
||
# Install the package with torch
|
||
pip install timesfm[torch]
|
||
# Or with Flax
|
||
pip install timesfm[flax]
|
||
# And when XReg is needed
|
||
pip install timesfm[xreg]
|
||
```
|
||
|
||
#### 本地安装
|
||
|
||
1. 克隆仓库：
|
||
```shell
|
||
git clone https://github.com/google-research/timesfm.git
|
||
cd timesfm
|
||
```
|
||
|
||
2. 使用 `uv` 创建虚拟环境并安装依赖：
|
||
```shell
|
||
# Create a virtual environment
|
||
uv venv
|
||
|
||
# Activate the environment
|
||
source .venv/bin/activate
|
||
|
||
# Install the package in editable mode with torch
|
||
uv pip install -e .[torch]
|
||
# Or with flax
|
||
uv pip install -e .[flax]
|
||
# And when XReg is needed
|
||
uv pip install -e .[xreg]
|
||
```
|
||
|
||
3. [可选] 根据你的操作系统与加速器（CPU、GPU、TPU 或 Apple Silicon）安装偏好的 `torch` / `jax` 后端：
|
||
|
||
- [Install PyTorch](https://pytorch.org/get-started/locally/).
|
||
- [Install Jax](https://docs.jax.dev/en/latest/installation.html#installation)
|
||
用于 Flax。
|
||
|
||
### 代码示例
|
||
|
||
```python
|
||
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)),
|
||
], # Two dummy inputs
|
||
)
|
||
point_forecast.shape # (2, 12)
|
||
quantile_forecast.shape # (2, 12, 10): mean, then 10th to 90th quantiles.
|
||
```
|