大型时间序列模型

本仓库提供了 Timer: 生成式预训练 Transformer 是大型时间序列模型 的官方代码、数据集和检查点。[海报] [幻灯片] 以及我们后续的工作 [教程（中文）]、[教程（英文）]。

更新

:triangular_flag_on_post: 新闻 (2025.5) Sundial，一个生成式时间序列基础模型家族，已被接受为 ICML 2025 口头报告（前1%）。您可以在毫秒内获得零样本概率预测！[HuggingFace] [快速入门]。

:triangular_flag_on_post: 新闻 (2025.2) 我们发布了一个开源代码库 OpenLTM，其中包含了预训练和微调大型时间序列模型的完整流程。

:triangular_flag_on_post: 新闻 (2024.12) 用于统一预测的 Timer-XL 被接受为 ICLR 2025。我们发布了用于零样本预测的预训练模型 [HuggingFace] [快速入门] [检查点]。

:triangular_flag_on_post: 新闻 (2024.10) 我们在 HuggingFace 上发布了预训练数据集 UTSD，或者您也可以使用 numpy 格式的 UTSD 和这个 数据加载器。

:triangular_flag_on_post: 新闻 (2024.5) 被 ICML 2024 接受，提交了 31页 的 定稿版本。

:triangular_flag_on_post: 新闻 (2024.2) 发布了不同任务上的微调模型检查点和代码 [README]。

简介

Time Series Transformer (Timer) 是一个用于通用时间序列分析的预训练 Transformer。

快速入门

我们提供了开箱即用的零样本预测模型（无需训练，也不需要 GPU）。

Timer 示例（零样本预测）

import torch
from transformers import AutoModelForCausalLM

# 加载预训练模型
model = AutoModelForCausalLM.from_pretrained('thuml/timer-base-84m', trust_remote_code=True)

# 准备输入
batch_size, lookback_length = 1, 2880
seqs = torch.randn(batch_size, lookback_length)

# 生成预测
prediction_length = 96
normed_output = model.generate(normed_seqs, max_new_tokens=prediction_length)

print(output.shape)

Sundial 示例（生成式预测）

import torch
from transformers import AutoModelForCausalLM

# 加载预训练模型
# 支持不同的回看/预测长度
model = AutoModelForCausalLM.from_pretrained('thuml/sundial-base-128m', trust_remote_code=True) 

# 准备输入
batch_size, lookback_length = 1, 2880 
seqs = torch.randn(batch_size, lookback_length)

# 注意，Sundial 可以生成多个可能的预测
forecast_length = 96 
num_samples = 20

output = model.generate(seqs, max_new_tokens=forecast_length, num_samples=num_samples)

# 使用原始预测来计算均值/分位数/置信区间
print(output.shape)

更多使用示例请参见 这里。更多信息请访问我们的 HuggingFace。

模型适配

• 对于有兴趣 微调大型时间序列模型或在自定义数据集上进行预训练 的开发者，请使用 OpenLTM，其中包含各种模型的代码脚本和检查点。

• 对于有兴趣 将大型时间序列模型应用于其他时间序列分析任务（例如插补和异常检测）的开发者，本仓库包含脚本和检查点 [README]。

数据集

我们收集了统一时间序列数据集 (UTSD)，其中包含了精心整理的时间序列数据，以促进大型时间序列模型的研究。我们的数据集已在 HuggingFace 上发布。

使用方法

您可以从 HuggingFace 获取数据，并按照 TSLib 的方式加载数据：

# huggingface-cli login
# export HF_ENDPOINT=https://hf-mirror.com 

python ./scripts/UTSD/download_dataset.py

# 数据加载器
python ./scripts/UTSD/utsdataset.py

我们还提供了评估时间序列数据集的代码，您可以用来评估自己格式化的 HuggingFace 数据集：

python ./scripts/UTSD/dataset_evaluation.py --root_path <数据集根路径> --log_path <输出日志路径>

如果您在访问数据时遇到困难，也可以从 [清华大学云] 下载 UTSD 的 numpy 格式，并使用 UTSD_Npy 数据加载器 [这里]。

简介

ICML 2024

我们提出了 Timer，一种仅解码器的 预训练 时间序列 Transformer。我们提出了 单系列序列 (S3) 格式，将多种不同的序列转换为统一的 1D 序列。该预测模型还可以用于预测、插补和异常检测 [README]。

ICLR 2025

我们提出了 Timer-XL，用于统一时间序列预测。它可以用于 监督训练 或 大规模预训练，明确地对 多维 时间序列建模 [GitHub]。

ICML 2025 口头报告

我们提出了 Sundial，一个 生成式 时间序列基础模型家族，该模型在 一万亿 (10^12) 个时间点上进行了预训练。该模型既可用于 点预测，也可用于 概率预测，从而实现毫秒级的 零样本预测 [GitHub]。

引用

如果您觉得本仓库对您有帮助，请引用我们的论文。

@inproceedings{liutimer,
  title={Timer: Generative Pre-trained Transformers Are Large Time Series Models},
  author={刘勇、张浩然、李晨宇、黄向东、王建民、龙明胜},
  booktitle={第四十一届国际机器学习大会}
}

@article{liu2024timer,
  title={Timer-XL: 面向统一时间序列预测的长上下文Transformer},
  author={刘勇、秦果、黄向东、王建民、龙明胜},
  journal={arXiv预印本 arXiv:2410.04803},
  year={2024}
}

@article{liu2025sundial,
  title={Sundial: 一类高性能的时间序列基础模型},
  author={刘勇、秦果、史志远、陈智、杨彩银、黄向东、王建民、龙明胜},
  journal={arXiv预印本 arXiv:2502.00816},
  year={2025}
}

致谢

我们非常感谢以下GitHub仓库提供的宝贵代码和数据集：

• Time-Series-Library (https://github.com/thuml/Time-Series-Library)
• AutoTimes (https://github.com/thuml/AutoTimes)
• LoTSA Data (https://huggingface.co/datasets/Salesforce/lotsa_data)
• UCR异常档案 (https://arxiv.org/pdf/2009.13807)

贡献者

如果您有任何问题或希望使用这些代码，欢迎随时联系：

• 刘勇 (liuyong21@mails.tsinghua.edu.cn)
• 张浩然 (zhang-hr24@mails.tsinghua.edu.cn)
• 李晨宇 (lichenyu20@mails.tsinghua.edu.cn)
• 秦果 (qinguo24@mails.tsinghua.edu.cn)

Large-Time-Series-Model 快速上手指南

本指南基于清华团队开源的 Large-Time-Series-Model 系列（包含 Timer, Timer-XL, Sundial），帮助开发者快速体验零样本（Zero-Shot）时间序列预测与生成能力。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux / macOS / Windows
• Python 版本: >= 3.8
• 核心依赖:
  • torch (PyTorch)
  • transformers (Hugging Face Transformers)
• 网络环境: 由于模型托管在 Hugging Face，国内用户建议配置镜像源以加速下载。

推荐依赖安装命令

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install transformers

提示: 若访问 Hugging Face 受阻，请在终端设置环境变量使用国内镜像：

export HF_ENDPOINT=https://hf-mirror.com

安装步骤

本项目无需复杂的源码编译安装，直接通过 transformers 库加载预训练模型即可使用。

1. 安装基础依赖（如上所示）。
2. 验证安装：确保能正常导入库。

   import torch
   from transformers import AutoModelForCausalLM
   

基本使用

以下提供两个最核心的零样本（Zero-Shot）使用示例，无需训练且无需 GPU 即可运行（CPU 亦可，但推荐 GPU 加速）。

示例 1：Timer / Timer-XL (确定性预测)

适用于标准的零样本点预测任务。

import torch
from transformers import AutoModelForCausalLM

# 1. 加载预训练模型 (Timer-XL base 84m)
# 国内用户若下载慢，请确保已设置 export HF_ENDPOINT=https://hf-mirror.com
model = AutoModelForCausalLM.from_pretrained('thuml/timer-base-84m', trust_remote_code=True)

# 2. 准备输入数据
# batch_size=1, lookback_length=2880 (例如过去 2880 个时间点的数据)
batch_size, lookback_length = 1, 2880
seqs = torch.randn(batch_size, lookback_length)

# 3. 生成预测
prediction_length = 96  # 预测未来 96 个点
# 注意：实际使用时请将 seqs 替换为您的真实归一化数据 (normed_seqs)
normed_output = model.generate(seqs, max_new_tokens=prediction_length)

print(f"输出形状：{normed_output.shape}")

示例 2：Sundial (概率性生成预测)

适用于需要不确定性估计、生成多种可能未来路径的场景（ICML 2025 Oral 成果）。

import torch
from transformers import AutoModelForCausalLM

# 1. 加载 Sundial 预训练模型 (支持不同长度的回溯与预测)
model = AutoModelForCausalLM.from_pretrained('thuml/sundial-base-128m', trust_remote_code=True) 

# 2. 准备输入数据
batch_size, lookback_length = 1, 2880 
seqs = torch.randn(batch_size, lookback_length)

# 3. 生成概率预测
forecast_length = 96 
num_samples = 20  # 生成 20 条可能的未来路径，用于计算均值、分位数或置信区间

output = model.generate(seqs, max_new_tokens=forecast_length, num_samples=num_samples)

# 输出形状通常为 [batch_size, num_samples, forecast_length]
print(f"输出形状：{output.shape}")

进阶资源

• 更多示例代码: 查看项目根目录下的 ./examples/ 文件夹。
• 模型集合: 访问 HuggingFace Collection 获取所有可用模型。
• 微调与预训练: 如需在自定义数据集上进行微调或从头预训练，请使用配套仓库 OpenLTM。