TimesFM 时间序列预测模型实战

本章要解决的是对 TimesFM 的基本理解及其应用场景，通过学习你可以掌握 TimesFM 的核心概念和适用范围。

前置条件：确保你已经熟悉 Python 编程，并且安装了必要的包管理工具如 pip 和虚拟环境工具如 uv。

我们先来看一下 TimesFM 的定义和特点：

• TimesFM 是由谷歌研究团队开发的时间序列预训练模型，专门用于时间序列预测任务。
• 使用解码器架构进行时间序列建模。
• 支持多种后端（如 Torch 和 Flax），并且可以通过 XReg 扩展支持协变量输入。

接下来是 TimesFM 的一些重要更新和特性：

• 最新版本：TimesFM 2.5，相比之前的版本参数量减少到 200M，同时支持更长的上下文长度（16k）和更远的预测视界（1k）。
• 新功能：包括连续分位数预测、XReg 协变量支持以及 Flax 后端加速等。

以下是 TimesFM 的主要应用场景：

应用场景	描述
企业级查询	可以在 BigQuery ML 中使用，适合大规模数据处理和可靠性要求高的场景。
日常表格分析	在 Google Sheets 中集成，方便日常的数据分析和预测需求。
模型部署	在 Vertex Model Garden 中部署，提供 Dockerized 接口便于调用。

推荐做法：

• 如果你需要快速上手，可以先尝试在 Google Sheets 或 BigQuery ML 中使用预构建的 TimesFM 模型。
• 如果有更高的定制需求，则可以选择本地安装并根据具体情况进行微调。

反例：

• 不要在不适合的大规模生产环境中使用默认配置的预训练模型，这可能导致性能瓶颈或精度不足。

最后举一个小例子来说明如何利用 TimesFM 进行简单的预测任务： 假设我们要预测两个不同模式的时间序列数据，在代码示例中可以看到如何加载模型、配置参数并执行预测。

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)),
    ],
)

print(point_forecast.shape)  # 输出: (2, 12)
print(quantile_forecast.shape)  # 输出: (2, 12, 10)

注意：

• 上述代码中的 inputs 是模拟生成的数据，请替换为你实际的时间序列数据。
• 需要根据你的硬件条件选择合适的后端（Torch 或 Flax），以获得最佳性能。

本章小结：

• 认识到了 TimesFM 的基本概念及最新发展。
• 明白了 TimesFM 在不同平台上的应用场景。
• 学会了如何加载和配置预训练模型进行简单的时间序列预测。

本章要解决的是如何安装 TimesFM 模型，读完后你可以轻松地通过 PyPI 或本地安装来使用这个强大的时间序列预测工具。

前置条件：

• Python 3.8 及以上版本已安装。
• pip 已更新到最新版本。
• Git 已安装（仅限本地安装）。

通过 PyPI 安装

我们先从最简单的 PyPI 安装开始：

1. 安装带有 Torch 后端的 TimesFM

   pip install timesfm[torch]

   预期结果：成功安装包含 Torch 后端的 TimesFM 包。

2. 安装带有 Flax 后端的 TimesFM

   pip install timesfm[flax]

   预期结果：成功安装包含 Flax 后端的 TimesFM 包。

3. 当需要 XReg 支持时

   pip install timesfm[xreg]

   预期结果：成功安装包含 XReg 支持的 TimesFM 包。

注意：

• 如果你在 Windows 上使用 Anaconda，可能需要额外配置 CUDA 来支持 GPU 加速。
• 如果遇到权限问题，可以尝试加上 --user 参数，例如 pip install --user timesfm[torch]。

本地安装

如果需要最新的开发版本或自定义修改，可以选择本地安装：

1. 克隆仓库

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

   预期结果：进入项目根目录。

2. 创建虚拟环境并激活

   python -m venv .venv
   source .venv/bin/activate  # Linux/MacOS
   .\.venv\Scripts\activate  # Windows

   预期结果：虚拟环境被创建并激活。

3. 在编辑模式下安装包

   pip install -e .[torch]  # 使用 Torch 后端
   # 或者
   pip install -e .[flax]   # 使用 Flax 后端
   # 或者当需要 XReg 支持时
   pip install -e .[xreg]

   预期结果：项目以可编辑模式安装完成。

4. 根据需求选择合适的深度学习框架后端
   如果你需要 GPU 加速，请确保正确安装了对应的库：

   • 对于 Torch 用户: PyTorch 官方文档

   • 对于 Flax/JAX 用户: JAX 安装指南

反例：

• 错误信息 ModuleNotFoundError: No module named 'timesfm' 提示未正确安装包，请检查是否在正确的环境中执行命令。
• 错误信息 ImportError: cannot import name 'XREG' from 'timesfm' 提示缺少 XReg 支持，请重新按照 [xreg] 选项进行安装。

示例验证

最后，我们可以通过一个小例子来验证我们的安装是否成功：

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)),
    ],
)
print(point_forecast.shape)  # 输出: (2, 12)
print(quantile_forecast.shape)  # 输出: (2, 12, 10)

如果你看到上述输出，则表示 TimesFM 成功安装并且可以正常工作！

本章小结：

• 掌握了通过 PyPI 和本地两种方式来安装 TimesFM。
• 学习了如何为不同的功能模块选择相应的依赖项。
• 理解了如何验证模型是否正确安装并通过了一个简单的测试用例。

本章要解决的问题是如何使用 TimesFM 进行基本的时间序列预测，并理解预测结果。读完本章后，你能掌握如何加载预训练模型、配置预测参数以及生成预测结果。

前置条件：确保已成功安装 TimesFM 并验证其正常工作。

我们先从加载预训练模型开始：

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

预期结果：模型配置完成，没有错误信息抛出。

如果你遇到 ModuleNotFoundError 错误，请检查是否正确安装了所有依赖项。推荐做法是在虚拟环境中安装所需的额外库，如 [torch], [flax], 或 [xreg]。

然后，我们可以进行实际的预测：

point_forecast, quantile_forecast = model.forecast(
    horizon=12,
    inputs=[
        np.linspace(0, 1, 100),
        np.sin(np.linspace(0, 20, 67)),
    ],
)
print(point_forecast.shape)  # 输出: (2, 12)
print(quantile_forecast.shape)  # 输出: (2, 12, 10)

预期结果：打印出点预测和分位数预测的结果形状，分别为 (2, 12) 和 (2, 12, 10)。

为了更好地理解这些输出，假设我们要预测两个不同时间序列未来12个时间步的数据。第一个时间序列是一个线性增长的数据集，第二个则是正弦波数据集。通过上述代码，我们可以得到每个时间序列在未来每个时间步上的点估计值以及对应的分位数区间估计值。

本章小结：

• 学习了如何加载 TimesFM 的预训练模型。
• 掌握了 ForecastConfig 的配置方法。
• 理解了如何使用 forecast 方法生成点预测和分位数预测。

本章要解决的问题是如何正确配置 ForecastConfig 参数来优化 TimesFM 模型的预测性能。读完本章，你将能够根据具体需求调整这些参数以获得更好的预测结果。

前置条件：确保你已经安装了 TimesFM 并加载了一个预训练模型。例如，你可以使用以下命令安装并加载模型：

pip install timesfm[torch]

import torch
import numpy as np
import timesfm

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

我们先来看一下 ForecastConfig 的基本用法。首先，我们需要创建一个 ForecastConfig 对象，并传入必要的参数：

config = 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,
)

预期结果：创建一个包含指定配置的 ForecastConfig 对象。

接着，我们将这个配置对象传递给模型的 compile 方法来编译模型：

model.compile(config)

预期结果：模型成功编译并应用了新的配置。

如果你遇到错误信息 "Invalid configuration parameter"，请检查是否有拼写错误或不支持的参数值。

推荐做法：在设置 max_context 和 max_horizon 时，应根据你的数据长度和预测范围合理选择数值。通常情况下，较大的 max_context 可以提供更多的历史信息，而较大的 max_horizon 则可以延长预测的时间跨度。

反例：如果设置的 max_context 过小，可能导致模型无法充分利用历史数据进行准确预测；反之，则可能增加计算复杂度。

下面是一个完整的示例代码，展示了如何使用 ForecastConfig 来进行时间序列预测：

import torch
import numpy as np
import timesfm

# 加载预训练模型
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")

# 创建 ForecastConfig 对象
config = 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,
)

# 编译模型
model.compile(config)

# 进行预测
point_forecast, quantile_forecast = model.forecast(
    horizon=12,
    inputs=[
        np.linspace(0, 1, 100),
        np.sin(np.linspace(0, 20, 67)),
    ],
)

# 打印预测结果形状
print(point_forecast.shape)  # 输出: (2, 12)
print(quantile_forecast.shape)  # 输出: (2, 12, 10)

本章小结：

• 学习了如何创建和配置 ForecastConfig 对象。
• 理解了各个参数的作用及其对模型的影响。
• 掌握了如何将配置应用到模型中进行编译和预测。

本章要解决的问题是如何对 TimesFM 模型进行微调（fine-tuning）以及如何使用 LoRA 技术来优化模型性能。通过学习本章，你可以掌握如何根据具体需求调整模型参数，并提高预测精度。

前置条件：

• 已安装 TimesFM 库，建议使用最新版 timesfm=2.0.2。
• 熟悉基本的 Python 和机器学习知识。
• 安装了必要的依赖库如 transformers 和 peft。

我们先从安装所需的额外库开始：

pip install transformers peft

接着，下载并加载预训练的 TimesFM 模型：

from timesfm import TimesFM_2p5_200M_torch

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

预期结果：成功加载预训练模型。

然后，导入必要的模块并准备数据集用于微调：

from datasets import load_dataset
from transformers import Trainer, TrainingArguments

dataset = load_dataset('your-dataset-name')  # 替换为你的数据集名称
train_dataset = dataset['train']
test_dataset = dataset['test']

注意：确保数据集格式符合要求，通常需要包含特征列和标签列。

如果你遇到 ModuleNotFoundError 错误，请检查是否正确安装了 datasets 库。

接下来，定义一个简单的训练循环来进行微调：

training_args = TrainingArguments(
    output_dir='./results',
    evaluation_strategy='epoch',
    learning_rate=2e-5,
    per_device_train_batch_size=8,
    num_train_epochs=3,
    weight_decay=0.01,
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=test_dataset,
)
trainer.train()

预期结果：模型将在指定的数据集上进行微调，并保存训练结果到 ./results 目录下。

推荐做法：根据实际数据量和计算资源调整批量大小（batch size）和训练轮数（epochs）。

最后，介绍如何使用 LoRA 来进一步优化模型：

from peft import LoraConfig, get_peft_model

lora_config = LoraConfig(
    r=16, lora_alpha=32, target_modules=["q_proj", "v_proj"], lora_dropout=0.1
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()  # 查看可训练参数数量

预期结果：打印出经过 LoRA 处理后的可训练参数数量。

如果遇到 ImportError 错误，请确认已正确安装 peft 库。

一个小例子总结一下整个过程： 假设我们有一个名为 my_time_series_data 的时间序列数据集，其中包含两个字段：features 和 labels。我们可以按照以下步骤进行微调和 LoRA 优化：

# 加载数据集
dataset = load_dataset('my_time_series_data')
train_dataset = dataset['train']
test_dataset = dataset['test']

# 微调配置
training_args = TrainingArguments(
    output_dir='./results',
    evaluation_strategy='epoch',
    learning_rate=2e-5,
    per_device_train_batch_size=8,
    num_train_epochs=3,
    weight_decay=0.01,
)

# 创建 Trainer 并开始微调
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=test_dataset,
)
trainer.train()

# 使用 LoRA 进一步优化
lora_config = LoraConfig(r=16, lora_alpha=32, target_modules=["q_proj", "v_proj"], lora_dropout=0.1)
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()

本章小结：

• 学习了如何对 TimesFM 模型进行微调。
• 掌握了使用 HuggingFace Transformers 和 PEFT 进行微调的方法。
• 理解了如何利用 LoRA 技术减少参数量同时提升模型性能。

本章要解决的问题是如何使用 TimesFM 的 Flax 版本以及如何通过 XReg 扩展来增强模型功能。读完后你能掌握在不同后端运行 TimesFM，并利用外部协变量进行预测。

前置条件：

• 已经安装了 TimesFM 及其依赖项。
• 熟悉基本的 Python 编程和机器学习概念。

使用 Flax 版本

首先，确保已安装 Flax 版本的 TimesFM：

pip install timesfm[flax]

接着，加载并使用 Flax 版本的模型：

from jax import numpy as jnp
import timesfm

model = timesfm.TimesFM_2p5_200M_flax.from_pretrained("google/timesfm-2.5-200m-flax")

预期结果：成功加载 Flax 版本的 TimesFM 模型。

如果你遇到 ModuleNotFoundError 错误，请检查是否正确安装了 timesfm[flax]。

使用 XReg 扩展

XReg 允许你在预测时加入外部协变量。首先安装带有 XReg 支持的 TimesFM：

pip install timesfm[xreg]

然后，准备输入数据包括主时间和协变量：

import numpy as np
import timesfm

# 加载模型
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")

# 准备输入数据
main_time_series = np.array([np.linspace(0, 1, 100)])
covariates = np.array([
    np.sin(np.linspace(0, 20, 100)),  # 协变量1
    np.cos(np.linspace(0, 30, 100))   # 协变量2
])

# 设置 ForecastConfig 并包含协变量信息
config = timesfm.ForecastConfig(
    max_context=1024,
    max_horizon=256,
    normalize_inputs=True,
    use_xreg=True,
)

# 进行预测
point_forecast, quantile_forecast = model.forecast(
    horizon=12,
    inputs=[main_time_series],
    xregs=covariates,
)

预期结果：成功生成包含协变量影响的预测结果。

如果遇到 ValueError 提示缺少 xregs 参数，请确认 ForecastConfig 中设置了 use_xreg=True。

示例：结合 Flax 和 XReg

假设我们要预测股票价格，并且有交易量作为协变量：

from jax import numpy as jnp
import timesfm

# 加载 Flax 版本模型
model = timesfm.TimesFM_2p5_200M_flax.from_pretrained("google/timesfm-2.5-200m-flax")

# 准备输入数据
stock_prices = jnp.array([[jnp.linspace(1, 1.5, 10)]])
trade_volumes = jnp.array([[jnp.linspace(1e6, 1.5e6, 10)]])

# 设置 ForecastConfig 并包含协变量信息
config = timesfm.ForecastConfig(
    max_context=10,
    max_horizon=3,
    normalize_inputs=True,
    use_xreg=True,
)

# 进行预测
point_forecast, _ = model.forecast(
    horizon=3,
    inputs=[stock_prices],
    xregs=trade_volumes,
)

print(point_forecast)

预期结果：输出未来三天的股票价格预测值。

本章小结：

• 学会了如何安装和使用 TimesFM 的 Flax 版本。
• 掌握了如何通过 XReg 扩展增加外部协变量的支持。
• 练习了一个结合 Flax 和 XReg 的实际预测任务。

本章要解决的问题是如何加速 TimesFM 的推理过程，并有效管理资源。读完后你能显著提升模型的运行效率，确保在生产环境中稳定运行。

前置条件：

• 已安装 TimesFM 的 Flax 或 Torch 版本。
• 理解基本的数据准备和 ForecastConfig 设置。
• 具备一定的 Python 编程能力。

我们先从优化推理速度开始。

加速推理

1. 使用合适的硬件

   • 使用 GPU 而不是 CPU 来加速计算。
   • 如果有 TPU 可以进一步提高性能。

2. 选择高效的库

   • 对于 Torch 用户，使用 torch.cuda.amp 启用混合精度训练。

     import torch
     scaler = torch.cuda.amp.GradScaler()
     
     with torch.cuda.amp.autocast():
         point_forecast, _ = model.forecast(horizon=3, inputs=[stock_prices], xregs=trade_volumes)

   • 对于 Flax 用户，确保 JAX 配置正确支持 GPU。

     import jax
     jax.config.update('jax_platform_name', 'gpu')

3. 批量处理数据

   • 尽量一次性处理多个样本而不是单个样本。

     batch_stock_prices = jnp.stack([jnp.linspace(1, 1.5, 10) for _ in range(32)])
     batch_trade_volumes = jnp.stack([jnp.linspace(1e6, 1.5e6, 10) for _ in range(32)])
     
     point_forecasts, _ = model.forecast(horizon=3, inputs=[batch_stock_prices], xregs=batch_trade_volumes)

4. 减少不必要的计算

   • 关闭不需要的功能如梯度计算。

     with torch.no_grad():
         point_forecast, _ = model.forecast(horizon=3, inputs=[stock_prices], xregs=trade_volumes)

接着看资源管理方面的优化策略。

资源管理

1. 内存优化

   • 使用 del 删除不再使用的变量来释放内存。
   • 使用垃圾回收模块手动清理内存。

     import gc
     
     del large_variable
     gc.collect()

2. 监控系统资源

   • 使用工具如 nvidia-smi 监控 GPU 内存使用情况。
   • 定期检查 CPU 和内存占用率。

3. 分布式计算

   • 如果数据集非常大，考虑使用分布式框架如 DDP（Distributed Data Parallel）进行并行计算。

4. 缓存中间结果

   • 对于多次使用的中间结果，可以考虑缓存起来避免重复计算。

如果你遇到常见的错误比如 CUDA OOM（Out Of Memory），可以通过减小批处理大小或启用混合精度来解决。如果出现梯度爆炸问题，则需要调整学习率或者使用梯度裁剪技术。

一个小例子总结一下这些优化方法：

import torch
import numpy as np
import timesfm

# 激活混合精度
scaler = torch.cuda.amp.GradScaler()

# 初始化模型和配置
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")
config = timesfm.ForecastConfig(max_context=10, max_horizon=3, normalize_inputs=True)

# 数据准备（批量）
batch_stock_prices = jnp.stack([jnp.linspace(1, 1.5, 10) for _ in range(32)])
batch_trade_volumes = jnp.stack([jnp.linspace(1e6, 1.5e6, 10) for _ in range(32)])

# 使用混合精度进行预测
with torch.cuda.amp.autocast(), torch.no_grad():
    point_forecasts, _ = model.forecast(horizon=3, inputs=[batch_stock_prices], xregs=batch_trade_volumes)

print(point_forecasts)

预期结果：输出一批次的未来三天股票价格预测值。

本章小结：

• 学会了通过硬件升级和高效库的选择来加速推理过程。
• 掌握了批量处理、关闭无用功能等具体的技术手段来提高性能。
• 实践了内存管理和监控系统资源的方法。

本章要比较 TimesFM 与其他时间序列模型，帮助你选择最适合你的项目需求的模型。

前置条件：

• 已经安装了 TimesFM 并完成了基本配置。
• 熟悉 Python 编程和时间序列分析的基础知识。

模型对比

模型名称	主要特点	适用场景
TimesFM	预训练基础模型，支持长上下文长度，连续分位数预测	大规模、复杂的时间序列预测任务
Prophet	Facebook 开发，适合业务指标预测，自动处理季节性和趋势成分	小到中规模的数据集，易于理解和解释
ARIMA	统计方法，基于自回归和移动平均组合模型	线性关系明显的时间序列数据
LSTM	循环神经网络的一种变体，擅长捕捉长期依赖关系	复杂非线性时间序列数据

示例：使用不同模型进行预测

我们先加载一些示例数据：

import numpy as np
import pandas as pd
from fbprophet import Prophet
from statsmodels.tsa.arima.model import ARIMA
import torch
import timesfm

# 创建示例时间序列数据
dates = pd.date_range(start='2023-01-01', periods=100, freq='D')
values = np.sin(np.linspace(0, 20, 100)) + np.random.normal(scale=0.1, size=100)
data = pd.DataFrame({'ds': dates, 'y': values})

接着使用 Prophet 进行预测：

# 初始化并拟合 Prophet 模型
prophet_model = Prophet()
prophet_model.fit(data)

# 准备未来日期的数据框
future_dates = prophet_model.make_future_dataframe(periods=30)
forecast_prophet = prophet_model.predict(future_dates)

# 提取预测结果
predicted_values_prophet = forecast_prophet[['ds', 'yhat']].tail(30)
print(predicted_values_prophet.head())

预期结果：输出未来 30 天的预测值。

然后使用 ARIMA 进行预测：

# 初始化并拟合 ARIMA 模型
arima_model = ARIMA(values, order=(5, 1, 0))
arima_result = arima_model.fit()

# 获取未来 30 天的预测值
predicted_values_arima = arima_result.get_forecast(steps=30).predicted_mean
print(predicted_values_arima.head())

预期结果：输出未来 30 天的预测值。

最后使用 TimesFM 进行预测：

# 加载预训练的 TimesFM 模型
model_timesfm = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")

# 配置 ForecastConfig 参数
config_timesfm = timesfm.ForecastConfig(max_context=10, max_horizon=3, normalize_inputs=True)

# 使用混合精度进行预测
with torch.cuda.amp.autocast(), torch.no_grad():
    point_forecasts_timesfm, _ = model_timesfm.forecast(horizon=3, inputs=[values[-10:]])

print(point_forecasts_timesfm)

预期结果：输出未来三天的预测值。

如果你遇到 ModuleNotFoundError 错误，请确保已正确安装所需的库。例如对于 Prophet 和 Statsmodels 可以通过以下命令安装：

pip install fbprophet statsmodels

注意事项

• Prophet 对于包含缺失值的数据处理较好，但在处理非常大规模的数据时可能较慢。
• ARIMA 要求数据平稳且有明显的线性特征，在复杂模式下表现不佳。
• LSTM 需要大量的计算资源，并且对超参数调优要求较高。
• TimesFM 具备强大的泛化能力和高效的预训练机制，适合复杂的现实世界场景。

本章小结：

• 对比了 TimesFM、Prophet、ARIMA 和 LSTM 四种时间序列模型的特点和适用场景。
• 实现了在相同数据集上的三种不同模型的简单预测流程。
• 强调了选择合适模型的重要性以及各自的局限性。

本章要解决如何在 Google Sheets 中应用 TimesFM 进行时间序列预测。完成本章后，你将能够在 Google Sheets 中利用 TimesFM 模型进行实时数据分析和预测。

前置条件：

• 已经安装并配置好 TimesFM 库。
• 熟悉基本的 Python 编程和 Google Sheets 使用方法。

步骤 1：准备数据

首先，你需要准备好时间序列数据，并将其导入到 Google Sheets 中。

1. 打开 Google Sheets 并创建一个新的工作表。
2. 将你的时间序列数据粘贴到工作表中。假设你的数据位于 A 列（日期）和 B 列（数值）。

步骤 2：编写 Python 脚本连接 Google Sheets

我们需要编写一个脚本来从 Google Sheets 获取数据，并使用 TimesFM 进行预测。

1. 安装必要的库：

pip install gspread oauth2client pandas

2. 创建一个服务账户并在 Google Cloud Platform 上启用 API 访问权限，然后下载 JSON 密钥文件。

3. 编写 Python 脚本连接到 Google Sheets 并获取数据：

import gspread
from oauth2client.service_account import ServiceAccountCredentials
import pandas as pd

scope = ["https://spreadsheets.google.com/feeds", "https://www.googleapis.com/auth/drive"]
creds = ServiceAccountCredentials.from_json_keyfile_name('path/to/your/service-account-file.json', scope)
client = gspread.authorize(creds)

sheet = client.open("Your Sheet Name").sheet1
data = sheet.get_all_records()
df = pd.DataFrame(data)

步骤 3：加载 TimesFM 模型并进行预测

接下来，我们加载 TimesFM 模型并对获取的数据进行预测。

1. 加载模型并配置 ForecastConfig：

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

config = 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,
)
model.compile(config)

2. 准备输入数据并进行预测：

inputs = df['数值'].tolist()[-10:]  # 取最近的 10 条记录作为输入
point_forecast, quantile_forecast = model.forecast(horizon=3, inputs=[inputs])

print(point_forecast)
print(quantile_forecast)

预期结果：输出未来三天的点估计和分位数估计值。

示例：天气温度预测

假设我们在 Google Sheets 中有一个记录了过去一个月每日最高气温的工作表，我们可以使用上述步骤来预测未来的三天最高气温。

注意事项

• 确保你的 Google Sheets 数据格式正确，没有空缺值或异常值。
• 如果遇到 gspread.exceptions.SpreadsheetNotFound 错误，请检查工作表名称是否正确。
• 如果遇到 ModuleNotFoundError 错误，请确保所有依赖库都已正确安装。

本章小结

• 学习了如何从 Google Sheets 获取数据并通过 Python 脚本访问这些数据。
• 掌握了如何加载和配置 TimesFM 模型进行时间序列预测。
• 实践了一个简单的天气温度预测案例。

本章要解决的问题是如何在 BigQuery ML 中集成 TimesFM，实现企业级的时间序列预测。

前置条件：

• 已经安装了 TimesFM 库。
• 具有 Google Cloud 平台账户，并且已经设置了 BigQuery 项目。
• 熟悉基本的 SQL 查询语法。

第一步操作：创建 BigQuery 数据集和表

CREATE DATASET IF NOT EXISTS my_timeseries_dataset;

CREATE TABLE IF NOT EXISTS my_timeseries_dataset.temperature_data (
    date DATE,
    temperature FLOAT64
);

预期结果：成功创建数据集和表。

第二步操作：导入历史数据到 BigQuery 表中

INSERT INTO my_timeseries_dataset.temperature_data (date, temperature)
VALUES ('2023-01-01', 23.5), ('2023-01-02', 24.0), ..., ('2023-12-31', 19.8);

预期结果：数据成功插入到表中。

第三步操作：编写 SQL 查询调用 TimesFM 进行预测

SELECT *
FROM ML.PREDICT(MODEL `my_timeseries_dataset.timesfm_model`,
                (SELECT ARRAY_AGG(temperature ORDER BY date ASC LIMIT 10) AS recent_temperatures FROM my_timeseries_dataset.temperature_data))

预期结果：返回未来几天的温度预测结果。

第四步操作：创建自定义模型并关联 TimesFM 首先，在 Google Cloud Console 中启用 BigQuery ML API。 然后，创建一个自定义模型：

CREATE OR REPLACE MODEL my_timeseries_dataset.timesfm_model
OPTIONS(model_type='TIMES_FM',
        input_label_cols=['recent_temperatures'],
        horizon=3)
AS
SELECT ARRAY_AGG(temperature ORDER BY date ASC LIMIT 10) AS recent_temperatures
FROM my_timeseries_dataset.temperature_data;

预期结果：成功创建并训练模型。

第五步操作：评估模型性能

SELECT *
FROM ML.EVALUATE(MODEL `my_timeseries_dataset.timesfm_model`);

预期结果：显示模型的评估指标。

示例：股票价格预测

假设我们有一个记录了过去一年内某股票每日收盘价的数据集，可以按照上述步骤将其导入 BigQuery 并使用 TimesFM 进行未来一周的价格预测。

注意事项

• 确保日期字段按升序排列并且没有缺失值。
• 如果遇到权限错误，请检查你的 IAM 角色是否有足够的权限访问和修改 BigQuery 资源。
• 如果遇到 Syntax error 错误，请仔细检查 SQL 语句中的拼写和语法问题。

本章小结

• 学会了如何在 BigQuery 中准备和存储时间序列数据。
• 掌握了如何在 BigQuery ML 中创建、训练和评估基于 TimesFM 的时间序列预测模型。
• 实践了一个股票价格预测的实际案例。

本章要解决的问题是在 Vertex Model Garden 中部署 TimesFM 模型，通过实际操作学会如何将训练好的模型发布到云端，并提供一个预测服务。

前置条件：

• 已经安装并配置好了 TimesFM。
• 有 Google Cloud Platform (GCP) 账号，并且已启用 Vertex AI API。
• 安装了 Google Cloud SDK 并进行了身份验证。
• 准备好一个训练好的 TimesFM 模型文件。

第一步操作：上传模型到 GCS（Google Cloud Storage）

gsutil cp path/to/your/trained/model gs://your-bucket-name/timesfm-model/

预期结果：模型文件被上传到指定的 GCS 存储桶中。

第二步操作：创建 Vertex Model

gcloud ai models upload tft \
  --region=us-central1 \
  --display-name="timesfm-model" \
  --artifact-uri=gs://your-bucket-name/timesfm-model/

预期结果：Vertex Model 创建成功，并返回模型 ID。

第三步操作：部署模型为 Endpoint

gcloud ai endpoints create \
  --region=us-central1 \
  --display-name="timesfm-endpoint"

预期结果：Endpoint 创建成功，并返回 Endpoint ID。

第四步操作：将模型部署到 Endpoint 上

gcloud ai models deploy-timeseries-forecasting-job create \
  --region=us-central1 \
  --endpoint-resource-name=projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_ENDPOINT_ID \
  --model-resource-name=projects/YOUR_PROJECT_ID/locations/us-central1/models/YOUR_MODEL_ID \
  --input-config=input_config.json

预期结果：模型成功部署到 Endpoint 上，可以接收请求进行预测。

示例：电力需求预测

假设我们有一个记录了过去几年内某地区每日电力消耗量的数据集，可以通过以下步骤将其上传至 GCS、创建 Vertex Model 并部署为 Endpoint。之后可以通过发送 HTTP 请求来获取未来的电力需求预测结果。

注意事项

• 确保输入数据格式正确，符合 TimesFM 的要求。
• 如果遇到 PERMISSION_DENIED 错误，请检查你的 IAM 角色是否有足够的权限访问和修改 GCS 和 Vertex AI 资源。
• 如果遇到 NOT_FOUND 错误，请确认提供的资源名称是否正确无误。

本章小结

• 学会了如何将训练好的 TimesFM 模型上传至 GCS。
• 掌握了如何在 Vertex Model Garden 中创建和部署 Time Series Forecasting 模型。
• 实践了一个电力需求预测的实际案例。

本章要解决你在使用 TimesFM 过程中可能遇到的各种问题，并提供相应的调试技巧，帮助你快速定位和解决问题。

前置条件：

• 已经成功安装了 TimesFM 及相关依赖。
• 熟悉基本的 Python 编程和命令行操作。
• 有简单的机器学习和时间序列分析基础。

常见问题

1. 安装时报错

问题描述：安装过程中出现 ModuleNotFoundError 或其他依赖缺失错误。 解决办法：

pip install timesfm[torch]
# 或者
pip install timesfm[flax]
# 如果需要 XReg 支持
pip install timesfm[xreg]

确保所有依赖都已正确安装。

2. 导入模块失败

问题描述：导入 timesfm 模块时报错。 解决办法： 检查是否在正确的虚拟环境中运行，并且已经激活该环境。

source .venv/bin/activate

3. 配置参数错误

问题描述：使用 ForecastConfig 设置参数时出现错误。 解决办法： 参考文档中的示例进行配置，确保参数名称和类型正确。

from timesfm import ForecastConfig

config = 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,
)

4. 数据输入格式不匹配

问题描述：传入的数据格式不符合要求导致预测失败。 解决办法： 确保输入数据是 NumPy 数组，并且维度符合模型的要求。

import numpy as np

inputs = [
    np.linspace(0, 1, 100),
    np.sin(np.linspace(0, 20, 67)),
]

5. 预测结果异常

问题描述：得到的预测结果明显不合理或为空。 解决办法： 检查输入数据的质量，确保没有噪声或异常值。同时验证模型是否正确加载和配置。

point_forecast, quantile_forecast = model.forecast(horizon=12, inputs=inputs)
print(point_forecast.shape)  # (2, 12)
print(quantile_forecast.shape)  # (2, 12, 10)

调试技巧

使用日志记录信息

启用详细的日志记录可以帮助你更好地理解程序执行过程中的情况。

import logging

logging.basicConfig(level=logging.DEBUG)

单元测试验证代码逻辑

编写单元测试可以有效发现代码中的潜在问题。

pytest tests/

渐进式调试方法

分步骤逐步验证每个部分的功能，而不是一次性尝试完整流程。 例如，首先单独测试数据加载部分，再测试模型预测部分。

示例：调试电力消耗预测模型

假设我们在之前的章节中部署了一个电力消耗预测模型。现在我们需要调试这个模型以提高其准确性。

我们先检查数据预处理步骤是否有误：

import pandas as pd

data = pd.read_csv('electricity_consumption.csv')
assert data.isnull().sum().sum() == 0, "数据中有缺失值"
assert 'date' in data.columns and 'consumption' in data.columns, "列名不正确"

接着验证模型是否正确加载并配置：

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

最后检查预测结果是否合理：

horizon = 12
inputs = [np.array(data['consumption'].values[-1024:])]
point_forecast, _ = model.forecast(horizon=horizon, inputs=inputs)
assert point_forecast.shape == (1, horizon), "预测结果形状不正确"
print(point_forecast)

如果仍然有问题，可以查看具体的日志输出以进一步诊断。

注意事项

• 确保所有依赖项都是最新版本，避免兼容性问题。
• 使用虚拟环境隔离不同项目的依赖关系，防止冲突。
• 经常备份重要文件和代码，以防意外丢失。

本章小结

• 解决了常见的安装、导入、配置等问题。
• 提供了详细的调试技巧，包括日志记录、单元测试和渐进式调试方法。
• 结合实际案例演示了如何逐步排查和修复电力消耗预测模型的问题。

安装时报错：ModuleNotFoundError: No module named 'uv'

在本地安装时，如果遇到 No module named 'uv' 错误，是因为缺少 uv 工具。请先安装 uv：

pip install uv

然后重新按照README中的步骤创建虚拟环境并激活。

如何选择使用 Torch 还是 Flax 后端？

根据你的需求和硬件条件来选择后端。如果你有NVIDIA GPU并且希望利用其加速计算，推荐使用Torch后端。如果你想尝试更快速的推理性能，可以考虑Flax后端（需要JAX库）。安装时可以通过指定选项来选择：

# 使用 Torch
pip install timesfm[torch]

# 或者使用 Flax
pip install timesfm[flax]

配置中 max_context 和 max_horizon 参数如何设置？

max_context 表示模型能够处理的最大历史时间步数输入长度，而 max_horizon 是指模型预测未来的时间步数长度。这些参数应根据具体的数据集大小和任务需求进行调整。例如，对于较长的历史数据或需要较远未来的预测，可能需要增加这两个值。

在使用 TimesFM 时常见的误区是什么？

一个常见的误区是在没有对数据进行适当预处理的情况下直接输入到模型中。TimesFM 对输入数据的质量要求较高，通常建议对时间序列数据进行归一化或其他形式的标准化处理，并确保数据格式符合模型的要求。

如何与 Prophet 等其他时间序列预测工具比较？

TimesFM 作为预训练的基础模型，在大规模多变的时间序列上具有优势，并且支持连续分位数预测等多种高级功能。相比之下，Prophet 更适合于单个时间序列的趋势建模和异常检测场景。选择哪个工具取决于具体的应用场景和数据特性。

是否可以在 Google Sheets 中直接使用 TimesFM？

目前 TimesFM 并未内置集成到 Google Sheets 的功能模块中，但你可以通过 BigQuery ML 调用 TimesFM 模型来进行复杂的时间序列分析，并将结果导出至 Google Sheets 中进一步操作和展示。相关文档可参考 Google Sheets Forecast Integration。

如何进行模型微调以适应特定数据集？

要微调 TimesFM 模型以适应特定的数据集，请参考项目提供的示例代码 timesfm-forecasting/examples/finetuning/。该示例展示了如何结合 Hugging Face Transformers 库以及 PEFT（如 LoRA）技术对预训练模型进行定制化训练的过程。