TimesFM v1 实战指南基于 1.0-200m 与 2.0-500m 检查点的时序预测、协变量支持与微调全解析【免费下载链接】timesfmTimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.项目地址: https://gitcode.com/GitHub_Trending/ti/timesfmTimesFMTime Series Foundation Model是 Google Research 发布的预训练时序基础模型采用 decoder-only 架构直接用于时序预测。本文以仓库归档的v1/版本对应 1.0 与 2.0 系列检查点为主体完整讲解检查点能力差异、poetry/PyPI 双路径安装、TimesFmHparams与TimesFmCheckpoint初始化、forecast/forecast_on_df/forecast_with_covariates三大推理 API 及频率编码规则并结合仓库源码v1/src/timesfm/timesfm_base.py、v1/src/timesfm/timesfm_jax.py、v1/src/timesfm/timesfm_torch.py、v1/src/timesfm/xreg_lib.py揭示底层实现原理。读完本文你将能够独立完成检查点加载、点预测/分位数预测、DataFrame 批量预测、外生协变量静态动态预测以及 LoRA 微调的全流程。说明本文对应的是仓库中的v1/归档目录TimesFM 1.0 / 2.0 时代代码可pip install timesfm1.3.0安装对应版本包。TimesFM 2.5 等最新版本代码在仓库根目录API 已演进如取消 frequency 指示符使用 2.5 请参考根目录 README.md。TimesFM 1.0 / 2.0 检查点能力对比v1 README 明确说明了两个开放检查点的能力边界这是后续配置 hparams 的基础能力维度timesfm-1.0-200mtimesfm-2.0-500m预测类型单变量时序预测支持可选 frequency 指示符单变量时序预测支持可选 frequency 指示符最大上下文长度512 个时间点2048 个时间点4 倍于 1.0预测视界horizon任意长度任意长度概率预测不支持实验性提供 quantile heads但预训练后未校准不主打实验性提供 10 个 quantile heads未校准相对精度基线在领先 benchmark 上相比 v1.0 最高可提升约 25%两个检查点在 Hugging Face 上分别以-jax/-pytorch以及 1.0 的-pytorch后缀区分后端权重。需要注意1.0 只提供点预测为主分位数输出属于实验性、未校准能力生产使用前需自行评估。环境与安装PAX/JAX 与 PyTorch 双路径内存建议与 Python 版本约束v1 README 建议至少 32GB RAM来加载 TimesFM 依赖。安装上有严格的 Python 版本约束见 v1/pyproject.toml 中paxml、torch、jax的python声明PAXJAX版本必须运行在Python 3.10.xPyTorch 版本可在Python 3.11.x上运行。因此使用pyenv时需同时安装两个 Python 版本pyenv install 3.10 pyenv install 3.11 pyenv versions # 列出可用版本假设为 3.10.15 与 3.11.10PAX 版本安装pyenv local 3.10.15 poetry env use 3.10.15 poetry lock poetry install -E paxPyTorch 版本安装pyenv local 3.11.10 poetry env use 3.11.10 poetry lock poetry install -E torch安装完成后既可以在poetry shell下运行也可以用poetry run python3 ...执行脚本。从 v1/pyproject.toml 的 extras 定义看pax [paxml, jax, jaxlib]、torch [torch]其中paxml被限制在3.10,3.11这也是 PAX 必须用 3.10 的根源。从 PyPI 安装Python 3.11 下安装 torch 版pip install timesfm[torch]Python 3.10 下安装 pax 版pip install timesfm[pax]附加说明运行仓库内 benchmarks 需要额外依赖详见experiments目录如 v1/experiments/extended_benchmarks/run_timesfm.py、v1/experiments/long_horizon_benchmarks/run_eval.py。依赖lingvo不支持 ARM 架构Apple siliconM 系列机器上代码无法运行v1 时代已知问题。forecast_with_covariates需要 JAX 环境即使你安装的是 torch 基础版只要想用外生回归协变量预测就必须手动安装pip install jax jaxlib。原因是该方法依赖xreg_lib模块而xreg_lib依赖 JAX/jaxlib但得益于延迟导入机制标准forecast调用不需要 JAX/jaxlib不会报错见 v1/src/timesfm/timesfm_base.py 中forecast_with_covariates内的from . import xreg_lib延迟导入写法。初始化模型与加载检查点TimesFmHparams 字段速查源码默认值以下默认值直接取自 v1/src/timesfm/timesfm_base.py 中TimesFmHparams数据类理解它们才能正确配置字段默认值含义context_len512单次 decode 允许的最大上下文长度应设为检查点训练时的上下文长度horizon_len128预测视界长度input_patch_len32输入 patch 长度2.0/1.0 模型均需为 32 的倍数output_patch_len128单步自回归解码从多少个时间点取值可设为检查点训练视界num_layers20Transformer 层数500m 模型为 50num_heads16注意力头数model_dims1280模型维度per_core_batch_size32每个核心上的批大小数据并行backendcpu取值cpu/gpu/tpu大小写敏感quantiles(0.1…0.9)模型输出的分位数集合use_positional_embeddingTrue是否使用位置嵌入point_forecast_modemedian点预测取mean还是medianTimesFmCheckpoint支持path本地路径、huggingface_repo_idHugging Face 仓库 ID、version、step、local_dir等字段其中version决定工厂创建 JAX 还是 Torch 推理类。加载 2.0 检查点import timesfm # 加载 timesfm-2.0 检查点 # PAX 版本 tfm timesfm.TimesFm( hparamstimesfm.TimesFmHparams( backendgpu, per_core_batch_size32, horizon_len128, num_layers50, context_len2048, use_positional_embeddingFalse, ), checkpointtimesfm.TimesFmCheckpoint( huggingface_repo_idgoogle/timesfm-2.0-500m-jax), ) # PyTorch 版本 tfm timesfm.TimesFm( hparamstimesfm.TimesFmHparams( backendgpu, per_core_batch_size32, horizon_len128, num_layers50, use_positional_embeddingFalse, context_len2048, ), checkpointtimesfm.TimesFmCheckpoint( huggingface_repo_idgoogle/timesfm-2.0-500m-pytorch), )加载 1.0 检查点# 加载 timesfm-1.0 检查点 # PAX 版本 tfm timesfm.TimesFm( hparamstimesfm.TimesFmHparams( backendgpu, per_core_batch_size32, horizon_len128, ), checkpointtimesfm.TimesFmCheckpoint( huggingface_repo_idgoogle/timesfm-1.0-200m), ) # PyTorch 版本 tfm timesfm.TimesFm( hparamstimesfm.TimesFmHparams( backendgpu, per_core_batch_size32, horizon_len128, ), checkpointtimesfm.TimesFmCheckpoint( huggingface_repo_idgoogle/timesfm-1.0-200m-pytorch), )注意200m 与 500m 模型的部分参数是固定的context_len是模型的最大上下文长度2.0 最大 20481.0 最大 512且必须是input_patch_len32的倍数。你完全可以给tfm.forecast()传更短的序列模型会自动处理——输入序列可以是任意上下文长度需要时推理代码会自行 padding / truncation。这一点与 v1/src/timesfm/timesfm_base.py 中_preprocess的实现一致长度不足时在序列前部补零并打 padding 标记超出时截取最后context_len个点。horizon_len可设任意值。官方建议设为应用中最长预测视界一般推荐horizon_len context_len但这在函数调用层面不是硬性要求。backend取值cpu/gpu大小写敏感源码中Literal[cpu, gpu, tpu]。从 v1/src/timesfm/init.py 可以看到import timesfm时会根据当前 Python 环境自动优先尝试导入 JAX 版TimesFmJax失败则回退到TimesFmTorch并打印当前加载的后端——这也是版本匹配问题的常见排查点。执行推理forecast 与 forecast_on_dfv1 README 提供两类推理 API数组输入tfm.forecast()与 pandas DataFrame 输入tfm.forecast_on_df()。两者都需要① 输入时序上下文② 频率信息。完整文档见两个函数的 docstringv1/src/timesfm/timesfm_base.py。频率指示符frequency indicatorTimesFM 期望一个取值在{0, 1, 2}的分类指示符0默认高频、长视界时序建议用于日粒度及更细的数据T、MIN、H、D、B、U1中频时序建议用于周、月数据W、M2低频、短视界时序建议用于季度、年度等Q、Y。数组输入时直接传数值DataFrame 输入时freq_map会把常规字母编码映射为上述类别。源码 v1/src/timesfm/timesfm_base.py 中的freq_map实现细节以H、T、MIN、D、B、U、S结尾 → 0MS结尾 → 1以W、M结尾或以W-开头、两位M开头 → 1以Y、Q、A结尾或以Y-、Q-、A-开头 → 2其他情况抛出ValueError(fInvalid frequency: {freq})。重要提示你不必严格遵循上述建议。虽然这是模型训练时的设定、预期效果最佳但你可以把 frequency 当作自由参数根据具体场景自行调整。数组输入示例低/中/高频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, freqfrequency_input, )返回值是一个二元组point_forecast形状为(# inputs, horizon)experimental_quantile_forecast形状为(# inputs, horizon, 1 #quantiles)mean 各分位数。底层forecast()的完整调用链见 v1/src/timesfm/timesfm_base.py若输入含非有限值NaN会先strip_leading_nans去除开头的 NaN再用linear_interpolation线性插值填补可选normalizeTrue按每个序列独立做均值/标准差归一化预测输出后再反归一化回原尺度_normalize/_renormalize标准差小于1e-6时按 1.0 处理可选window_size做趋势残差分解moving_averagepoint_forecast_modemean时直接返回模型均值输出median时从分位数输出中取出 0.5 分位若 quantiles 不含 0.5 会抛出明确报错。DataFrame 输入示例月度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( inputsinput_df, freqM, # 月度 value_namey, num_jobs-1, )forecast_on_df要求 DataFrame 必须包含unique_id序列标识、ds时间戳和值列默认名values可通过value_name指定否则抛ValueError见源码校验逻辑。其他关键参数forecast_context_len非 0 时取每个序列最后该长度的点作为上下文否则用模型context_lennum_jobsDataFrame 预处理并行进程数-1表示使用全部 CPU 核内部通过multiprocessing.Pool按unique_id分组并行调用process_groupmodel_name写入输出 DataFrame 的列名前缀默认timesfm。输出 DataFrame 由utilsforecast.processing.make_future_dataframe生成包含unique_id、未来ds时间点以及model_name列点预测即 0.5 分位与model_name-q-{q}系列分位数列。Covariates 支持静态与动态协变量预测TimesFM 在基础模型之上提供了外生回归external regressors库可支持静态协变量与动态协变量。完整示例见 v1/notebooks/covariates.ipynb核心实现位于 v1/src/timesfm/xreg_lib.py。前提若在 torch 版上使用forecast_with_covariates必须手动安装 JAX 依赖pip install jax jaxlib概念静态 vs 动态协变量v1 README 用杂货店销售预测的玩具示例说明概念任务给定本周7 天的每日销售额预测下周7 天的每日销售额。以冰淇淋为例Product: ice cream Daily_sales: [30, 30, 4, 5, 7, 8, 10] Category: food Base_price: 1.99 Weekday: [0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6] Has_promotion: [Yes, Yes, No, No, No, Yes, Yes, No, No, No, No, No, No, No] Daily_temperature: [31.0, 24.3, 19.4, 26.2, 24.6, 30.0, 31.1, 32.4, 30.9, 26.0, 25.0, 27.8, 29.5, 31.2]防晒霜为例Product: sunscreen Daily_sales: [5, 7, 12, 13, 5, 6, 10] Category: skin product Base_price: 29.99 Weekday: [0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6] Has_promotion: [No, No, Yes, Yes, No, No, No, Yes, Yes, Yes, Yes, Yes, Yes, Yes] Daily_temperature: [31.0, 24.3, 19.4, 26.2, 24.6, 30.0, 31.1, 32.4, 30.9, 26.0, 25.0, 27.8, 29.5, 31.2]其中除目标Daily_sales外Category、Base_price、Weekday、Has_promotion、Daily_temperature都是协变量静态协变量static covariates每个时序一个值。Category是静态类别协变量Base_price是静态数值协变量动态协变量dynamic covariates每个时间戳一个值。日期/时间类特征通常视为动态协变量。Weekday、Has_promotion是动态类别协变量Daily_temperature是动态数值协变量。强制要求动态协变量必须同时覆盖预测的 context 与 horizon 两段。上例中所有动态协变量都有 14 个值前 7 个对应已观测的 7 天后 7 个对应要预测的 7 天。把两个产品的历史数据连同静态/动态协变量作为 batch 输入即可得到考虑协变量影响的预测。forecast_with_covariates 的参数与两种模式从 v1/src/timesfm/timesfm_base.py 的forecast_with_covariates签名可以看到inputs每个时序的上下文列表dynamic_numerical_covariates/dynamic_categorical_covariatesdict[str, Sequence[...]]每个协变量对所有序列提供覆盖 contexthorizon 的值内部按input_lens切分为 train/test 两段static_numerical_covariates/static_categorical_covariates每个序列一个值freq、window_size、forecast_context_len同forecastxreg_modexreg timesfm或timesfm xregxreg timesfm先在 TimesFM 预测的残差上拟合线性模型timesfm xreg先在目标值上拟合模型再用 TimesFM 预测残差normalize_xreg_target_per_input是否对每个输入单独归一化 xreg 目标ridge线性模型的岭惩罚0 时 one-hot 编码不 drop 首列见one_hot_encoder_dropNone if ridge 0 else firstmax_rows_per_col每列最多采样行数0 表示不采样max_rows_per_col_sample_seed控制采样种子见 v1/src/timesfm/xreg_lib.py 的BatchedInContextXRegLinear.fitforce_on_cpu是否强制线性模型在 CPU 上运行。返回值是二元组模型输出列表与 xreg 输出列表。为提升推理速度官方建议避免字符串类型的类别协变量尽量用整数编码。调用时若四个协变量参数均为空会抛出ValueError提示至少设置一个。若动态协变量暗示的视界超过horizon_len同样会抛出明确错误。完整示例见 v1/notebooks/covariates.ipynb。Finetuning在自己的数据上微调v1 README 提供 JAX 版微调示例 v1/notebooks/finetuning.ipynb。仓库内配套资源PyTorch 版微调示例v1/notebooks/finetuning_torch.ipynb命令行微调脚本v1/src/finetuning/finetuning_example.py支持 DDP 多 GPU 微调其他并行方案如 pipeline/model parallelism 可能后续加入LoRA / DoRA 适配层实现v1/src/adapter/lora_layers.py、v1/src/adapter/dora_layers.py微调推理工具v1/src/finetuning/finetuning_torch.py。PyTorch 微调支持DDP 多 GPU训练使用方式见 finetuning_example.py 中的步骤。微调加载的模型类如TimesFmTorch在load_from_checkpoint中会先构造权重再加载检查点JAX 侧流程见 v1/src/timesfm/timesfm_jax.py 的load_from_checkpoint与jit_decode其中通过jax.pmap对 decode 函数做数据并行编译。基准评测与问题排查BenchmarkingTimesFM 2.0 已加入 GIFT-Eval综合时序评测基准之一在聚合 MASE 与 CRPS 上排名靠前聚合 MASE 比次优模型好约 6%该结论来自 v1 README 的自述仅供参考。仓库内可复现脚本见 v1/experiments/extended_benchmarks/run_timesfm.py、v1/experiments/long_horizon_benchmarks/run_eval.py。常见问题安装与使用中遇到问题先查阅 v1/TROUBLESHOOTING.mdPython 版本与后端不匹配时注意 v1/src/timesfm/init.py 的后端自动选择逻辑与 v1/pyproject.toml 的版本约束Apple silicon 上lingvo依赖不可用v1 已知限制。测试用例参考仓库提供了针对推理、数据加载的单元测试v1/tests/test_timesfm.py、v1/tests/test_data_loader.py可作为 API 调用方式的直接参考。附代码风格约定若你希望为仓库提交 PR请遵循 v1/docs/contributing.md 与 v1 README 中说明的格式化风格使用yapfbased_on_style google、indent_width 2、spaces_before_comment 2并对受影响文件执行yapf --in-place --recursive filename。总结本文围绕 v1 版 TimesFM 的检查点加载、双后端安装、三类推理 API、频率编码与协变量预测展开并下沉到timesfm_base.py、timesfm_jax.py、xreg_lib.py等源码验证了默认参数、预处理逻辑与模式语义。如果你正在使用 2.5 及以后版本其 API 已迁移到根目录 src/timesfm/timesfm_2p5 体系如TimesFM_2p5_200M_torch与ForecastConfig本文的 v1 知识仍可作为理解其设计演进的基础。【免费下载链接】timesfmTimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.项目地址: https://gitcode.com/GitHub_Trending/ti/timesfm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考