TimesFM Agent Skill 实战指南让 Cursor / Claude Code 等 AI Agent 零样本完成时间序列预测【免费下载链接】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本文围绕仓库根目录下的 AGENTS.md 展开它定义了 TimesFM 面向 AI 智能体的官方入口一份随仓库发布的第一方Agent Skill位于 timesfm-forecasting/SKILL.md。读完本文你将掌握如何把该 Skill 安装进 Cursor、Claude Code、OpenCode、Codex 等支持 Agent Skills 标准的工具理解其强制预检系统检查机制并上手零样本时间序列预测、分位数预测区间、XReg 协变量预测与异常检测等完整工作流同时结合src/timesfm/源码与tests/测试用例弄清底层实现原理。AGENTS.md 是什么TimesFM 为智能体预留的入口TimesFMTime Series Foundation Model是 Google Research 发布的预训练时间序列基础模型以 decoder-only 架构实现零样本预测。随着 AI 编码 Agent 的普及仓库在主 README 之外新增了 AGENTS.md专门回答一个关键问题Agent 该如何使用 TimesFMAGENTS.md 的核心结论有三点仓库随附一份官方维护的Agent Skill完整定义位于timesfm-forecasting/SKILL.md——AGENTS.md 明确指出 read this for the full skill阅读该文件获取完整技能说明因此 SKILL.md 是本文档的实质内容主体Skill 目录timesfm-forecasting/可直接复制到主流 Agent 的 skills 目录中任何支持开放 Agent Skills 标准 的 Agent 都会自动发现它若你是在开发 TimesFM 本身而非使用它源码位于src/timesfm/历史版本v1/v2代码与 notebook 归档在v1/开发时可运行pytest v1/tests/执行测试。从仓库结构可以印证这一分工README.md 面向人类开发者讲解安装与调用而 AGENTS.md 面向 Agent 提供可消费、可自动执行的技能定义两者通过timesfm-forecasting/目录下丰富的脚本、参考文档与可运行示例相互支撑。把 Skill 装进你的 Agent安装与自动发现AGENTS.md 给出的安装方式非常简单——Skill 就是一个目录复制到 Agent 的 skills 文件夹即可。全局安装适用于 Cursor / Claude Code / OpenCode / Codexcp -r timesfm-forecasting/ ~/.cursor/skills/ cp -r timesfm-forecasting/ ~/.claude/skills/项目级安装只在当前项目生效cp -r timesfm-forecasting/ .cursor/skills/安装后任何实现了开放 Agent Skills 标准的 Agent 都会自动发现该 Skill。SKILL.md 的 YAML frontmatter 定义了技能的元数据name: timesfm-forecastingdescription中明确声明其能力边界零样本单变量时间序列预测、XReg 协变量预测、自动系统检查、CSV/DataFrame/数组输入、带校准预测区间的点预测并标注license: Apache-2.0与作者、版本信息。Agent 正是通过这段description判断何时该调用该技能。Skill 能力全景什么时候用、什么时候不用SKILL.md 对使用场景做了清晰界定这也是 Agent 决策的依据适用场景任意单变量时间序列预测销售、需求、传感器、生命体征、价格、天气、科研测量需要零样本预测且不想训练定制模型需要带校准预测区间的概率预测上下文长度 116,384 点的任意长度序列需要高效批量预测成百上千条序列希望通过基础模型替代手工调参的 ARIMA/ETS需要价格、促销、节假日、星期效应等外生变量的协变量预测需 TimesFM 2.5 pip install timesfm[xreg]使用forecast_with_covariates()。不适用场景需要系数解释的经典统计模型用statsmodels时间序列分类或聚类用aeon多元 VAR 或格兰杰因果用statsmodels非时序的表格数据用scikit-learn无法安装可选依赖XReg 依赖 scikit-learn 与 JAX。需要特别说明的是TimesFM 本身没有内置异常检测能力但可以利用分位数预测作为预测区间——落在 90% 置信区间q10–q90之外的值在统计上视为异常。完整示例见 timesfm-forecasting/examples/anomaly-detection/。强制预检理解 check_system.py 的设计与实现SKILL.md 用 ⚠️ CRITICAL — ALWAYS 强调加载模型前必须运行系统检查器避免 Agent 直接压垮用户的机器。这是该 Skill 区别于普通示例代码的核心设计。python scripts/check_system.py对应源码位于 timesfm-forecasting/scripts/check_system.py。它按模型档案做检查MODEL_PROFILES定义了三个版本的硬件基线版本参数最低 RAM推荐 RAM最低 VRAM推荐 VRAM磁盘权重开销v2.5200M200M2.0 GB4.0 GB2.0 GB4.0 GB2.0 GBv2.0500M已归档500M8.0 GB16.0 GB4.0 GB8.0 GB4.0 GBv1.0200M已归档200M4.0 GB8.0 GB2.0 GB4.0 GB2.0 GB脚本逐项执行 5 类检查对应源码中的check_ram、check_gpu、check_disk、check_python、check_package可用 RAM——总内存低于 2 GB 直接判定fail阻止低于 4 GB 给出warn建议调低per_core_batch_sizeGPU 可用性——依次探测 CUDA 设备读取设备名与 VRAM、Apple Silicon MPS 后端无 GPU 时降级为 CPU 模式可用但较慢若连 torch 都未安装则提示先安装磁盘空间——检查 HuggingFace 缓存目录可通过HF_HOME环境变量覆盖默认~/.cache/huggingface/所在卷的剩余空间Python 版本——要求 ≥ 3.10现有安装——检查timesfm与torch是否已安装。脚本还会根据检测结果给出推荐批大小recommend_batch_sizeVRAM ≥ 24 GB 推荐 256、≥ 16 GB 推荐 128、≥ 8 GB 推荐 64纯 CPU 下按总内存 32/16/8 GB 分档推荐 64/32/8。全部检查通过后输出类似✅ System is ready for TimesFM 2.5 (200M) (CPU mode)的结论与建议的per_core_batch_size。数据集预检防止加载数据就 OOM除系统检查外脚本还新增了数据集感知的内存估算。先看估算命令python scripts/check_system.py \ --num-series 1000 \ --context-length 1024 \ --horizon 24 \ --batch-size 32 \ --estimate-only--estimate-only会跳过系统检查、只输出内存估算。估算逻辑在源码estimate_memory_gb()中逐项累加模型权重约 0.8 GBPython 运行时与库开销约 0.5 GB输入数据num_series × context_length × 4 字节float32批处理峰值batch_size × context_length × 4 字节输出数据horizon 0 时num_series × horizon × 10 个分位数 × 4 字节最后整体追加 20% 缓冲供中间张量与操作系统开销使用。SKILL.md 给出的简写公式为RAM ≈ 0.8 GB模型 0.5 GB开销 (0.2 MB × num_series × context_length / 1000)。check_dataset_fit()会进一步与系统总内存、可用内存比较预留 10% 给系统并返回可舒适容纳 / 内存偏高建议调小 batch / 放不下建议分块三档结论。典型输出✅ Dataset fits comfortably: 2.34 GB needed, 8.0 GB available. Dataset requires ~12.5 GB RAM but system has 8.0 GB. Try: context_length512 or process in chunks of 50 series.硬件要求速查SKILL.md 汇总了各版本硬件的横向对比RAM 均为 CPU 推理需求VRAM 为 GPU 推理需求模型参数RAMCPUVRAMGPU磁盘上下文长度TimesFM 2.5推荐200M≥ 4 GB≥ 2 GB~800 MB至多 16,384TimesFM 2.0已归档500M≥ 16 GB≥ 8 GB~2 GB至多 2,048TimesFM 1.0已归档200M≥ 8 GB≥ 4 GB~800 MB至多 2,048注意模型权重不随仓库分发约 800 MB首次使用时从 HuggingFace 按需下载并缓存到~/.cache/huggingface/。SKILL.md 给出的关键数字是TimesFM 2.5 权重约 800 MBCPU 推理约占用 1.5 GB 内存GPU 推理约占用 1 GB 显存而归档的 v1/v2 500M 模型在 CPU 上约需 32 GB 内存——因此先跑系统检查是硬性要求。安装 TimesFM三条命令的完整链路SKILL.md 规定的安装流程分三步第一步永远是预检# Step 1: 验证系统永远最先执行 python scripts/check_system.py # Step 2: 安装 TimesFM uv pip install timesfm[torch] # 或 pip install timesfm[torch] uv pip install timesfm[flax] # JAX/Flax 后端TPU/GPU 上更快 # 需要协变量XReg时追加 pip install timesfm[xreg] # Step 3: 为你的硬件安装匹配的 PyTorch pip install torch2.0.0 --index-url https://download.pytorch.org/whl/cu121 # CUDA 12.1 pip install torch2.0.0 --index-url https://download.pytorch.org/whl/cpu # 纯 CPU pip install torch2.0.0 # Apple Silicon内置 MPS从源码角度看torch 与 flax 两套实现分别位于 src/timesfm/timesfm_2p5/timesfm_2p5_torch.py 与 src/timesfm/timesfm_2p5/timesfm_2p5_flax.pyXReg 协变量逻辑在 src/timesfm/utils/xreg_lib.py。README 中还给出了基于uv的本地可编辑安装方式uv venv source .venv/bin/activate uv pip install -e .[torch]。快速开始从加载权重到产出预测SKILL.md 的最小示例体现了完整调用链from_pretrained→compile→forecast。import torch, numpy as np, 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_context1024, max_horizon256, normalize_inputsTrue, use_continuous_quantile_headTrue, force_flip_invarianceTrue, infer_is_positiveTrue, fix_quantile_crossingTrue, )) point, quantiles model.forecast(horizon24, inputs[ np.sin(np.linspace(0, 20, 200)), # 任意 1-D 数组 ]) # point.shape (1, 24) —— 中位数预测 # quantiles.shape (1, 24, 10) —— 第 1090 百分位区间源码视角三个方法背后的实现在 timesfm_2p5_torch.py 中可以看到from_pretrained()由PyTorchModelHubMixin提供_from_pretrained会先下载config.json与model.safetensors若传入本地目录则直接读取目录下的model.safetensors随后torch.compile编译前向过程compile()会做三项输入校验max_context会被向上取整为 patch 大小 32 的倍数max_horizon向上取整为输出 patch 大小 128 的倍数若整除失败校验max_context max_horizon ≤ context_limit2.5 版本上限 16,384当启用连续分位数头且max_horizon 1024output_quantile_len时抛出ValueError。模型定义中的关键常量输入 patch 32、输出 patch 128、20 层 Transformer、16 头注意力、模型维度 1280、头维度 80forecast()未编译时抛出RuntimeError: Model is not compiled输入序列过长时只保留最后max_context个点过短则补零mask 标记前导 NaN 自动剥离、内部 NaN 线性插值。ForecastConfig本身是冻结 dataclass定义于 src/timesfm/configs.py不可变特性由 tests/test_configs.py 中的test_frozen_prevents_mutation显式验证——因为compile()会把配置对象捕获进编译闭包任何运行期改动都会破坏推理一致性。同一测试文件还锁定了一组保守默认值normalize_inputsFalse、use_continuous_quantile_headFalse等防止静默的默认值漂移。协变量预测XRegTimesFM 2.5 通过forecast_with_covariates()支持外生变量需要timesfm[xreg]point, quantiles model.forecast_with_covariates( inputsinputs, dynamic_numerical_covariates{price: price_arrays}, dynamic_categorical_covariates{holiday: holiday_arrays}, static_categorical_covariates{region: region_labels}, xreg_modexreg timesfm, # 或 timesfm xreg )关键约束动态协变量必须覆盖完整长度context horizon即每条序列的协变量数组长度等于输入上下文与预测窗口之和。完整可运行示例见 timesfm-forecasting/examples/covariates-forecasting/demo_covariates.py。用分位数区间做异常检测point, q model.forecast(horizonH, inputs[values]) lower_90 q[0, :, 1] # 第 10 百分位 upper_90 q[0, :, 9] # 第 90 百分位 actual test_values anomalies (actual lower_90) | (actual upper_90)严重度分级落在 80% 置信区间内视为正常超出 80% 区间属警告不寻常但可能超出 90% 区间q10–q90为严重统计上概率低于 10%。SKILL.md 提醒对带趋势的上下文数据做异常检测时应先去除趋势再做 Z-score否则原始 Z-score 会产生误导——完整的两阶段去趋势 Z-score 分位数区间示例见 timesfm-forecasting/examples/anomaly-detection/detect_anomalies.py。理解输出点预测与 10 个分位切片forecast()返回(point_forecast, quantile_forecast)二元组point_forecast形状(batch, horizon)即 0.5 分位中位数quantile_forecast形状(batch, horizon, 10)10 个切片含义固定索引分位用途0均值平均预测10.180% 预测区间下界20.260% 预测区间下界50.5中位数point_forecast80.860% 预测区间上界90.980% 预测区间上界point, q model.forecast(horizonH, inputsdata) lower_80 q[:, :, 1] # 第 10 百分位 upper_80 q[:, :, 9] # 第 90 百分位 median q[:, :, 5]SKILL.md 特别强调这是最常见的 off-by-one 陷阱索引 0 是均值而非 q0q10 对应索引 1q90 对应索引 9。这一 10 分位布局与源码中q len(quantiles) 19 个分位 1 个均值及aridx 5中位数索引完全对应。ForecastConfig 完整参数参考SKILL.md 给出的推荐配置timesfm.ForecastConfig( max_context1024, # 最大上下文窗口 max_horizon256, # 最大预测步数 normalize_inputsTrue, # 推荐开启——防止尺度不稳定 per_core_batch_size32, # 按内存调节 use_continuous_quantile_headTrue, # 长 horizon 下分位数更准 force_flip_invarianceTrue, # 保证 f(-x) -f(x) infer_is_positiveTrue, # 输入全正时把预测钳制到 ≥ 0 fix_quantile_crossingTrue, # 保证 q10 ≤ q20 ≤ ... ≤ q90 return_backcastFalse, # 返回回测协变量工作流用 )各参数的关键决策点参数源码默认值何时调整max_context0用满模型上限 16,384设为最长历史窗口长度追求速度设 5122048注意会被向上取整到 32 的倍数max_horizon0设为预期最大预测长度注意会被向上取整到 128 的倍数normalize_inputsFalse务必设 True逐序列 z 归一化仅当序列本已归一化时才可不开per_core_batch_size1内存紧张时调小吞吐优先时调大use_continuous_quantile_headFalse推荐 True用 30M 参数连续分位数头提升长 horizon 区间校准horizon 1024 不可用force_flip_invarianceTrue默认 True 即满足符号翻转不变性关闭略快但可能不对称infer_is_positiveTrue温度、收益率、PNL 等可为负的序列必须设 Falsefix_quantile_crossingFalse推荐 True保证分位数单调有序return_backcastFalse协变量工作流与诊断时设 True源码实现细节可以印证这几个开关的真实作用均位于compile()生成的_compiled_decode闭包内见 timesfm_2p5_torch.pynormalize_inputsTrue时对输入求均值/标准差做 RevIN 归一化预测后再反归一化还原到原始尺度force_flip_invarianceTrue时对-inputs再跑一次解码将两次结果相减取半得到严格满足f(-x) -f(x)的输出infer_is_positiveTrue时若整条输入all(inputs 0)则预测值通过torch.maximum钳制到非负fix_quantile_crossingTrue时分别沿低分位侧索引 4→1与高分位侧索引 6→9做单调化修正消除分位交叉。完整参数文档见 timesfm-forecasting/references/api_reference.md其中还包含各版本可用 checkpoint 列表PyTorch / Flax / Transformers 三种后端与输出形状对照。三个高频工作流单序列预测并可视化import torch, numpy as np, pandas as pd, timesfm, matplotlib matplotlib.use(Agg) # 无头环境必须先于 pyplot import 设置 import matplotlib.pyplot as plt 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_context512, max_horizon52, normalize_inputsTrue, use_continuous_quantile_headTrue, fix_quantile_crossingTrue, )) df pd.read_csv(weekly_demand.csv, parse_dates[week]) values df[demand].values.astype(np.float32) point, quantiles model.forecast(horizon52, inputs[values]) fig, ax plt.subplots(figsize(12, 5)) ax.plot(values[-104:], labelHistorical) x_fc range(len(values[-104:]), len(values[-104:]) 52) ax.plot(x_fc, point[0], labelForecast, colortab:orange) ax.fill_between(x_fc, quantiles[0, :, 1], quantiles[0, :, 9], alpha0.2, colortab:orange, label80% PI) ax.legend(); ax.set_title(52-Week Demand Forecast) plt.tight_layout(); plt.savefig(forecast.png, dpi150)批量预测多序列并导出 JSONdf pd.read_csv(all_stores.csv, parse_dates[date], index_coldate) inputs [df[col].dropna().values.astype(np.float32) for col in df.columns] point, quantiles model.forecast(horizon30, inputsinputs) import json results {col: {forecast: point[i].tolist(), lower_80: quantiles[i, :, 1].tolist(), upper_80: quantiles[i, :, 9].tolist()} for i, col in enumerate(df.columns)} with open(batch_forecasts.json, w) as f: json.dump(results, f, indent2)预测精度评估H 24 train, actual values[:-H], values[-H:] point, quantiles model.forecast(horizonH, inputs[train]) pred point[0] mae np.mean(np.abs(actual - pred)) rmse np.sqrt(np.mean((actual - pred) ** 2)) mape np.mean(np.abs((actual - pred) / actual)) * 100 coverage np.mean((actual quantiles[0, :, 1]) (actual quantiles[0, :, 9])) * 100 print(fMAE: {mae:.2f} | RMSE: {rmse:.2f} | MAPE: {mape:.1f}% | 80% PI Coverage: {coverage:.1f}%)其中coverage衡量 80% 预测区间的实际覆盖率是评估分位数校准质量的关键指标。性能调优要点矩阵乘法精度Ampere 及以上 GPUA100、RTX 3090务必设置torch.set_float32_matmul_precision(high)批大小参考8 GB 显存 GPU 用per_core_batch_size6416 GB 显存用 1288 GB 内存 CPU 用 816 GB 内存 CPU 用 32与check_system.py的推荐逻辑一致内存受限时分块处理CHUNK 50 results [] for i in range(0, len(inputs), CHUNK): p, q model.forecast(horizonH, inputsinputs[i:iCHUNK]) results.append((p, q))Skill 自带的脚本与示例scripts/forecast_csv.pyCSV 端到端预测 CLIpython scripts/forecast_csv.py input.csv \ --horizon 24 \ --date-col date \ --value-cols sales,revenue \ --output forecasts.csv参考文档文件内容references/system_requirements.md硬件分级、GPU/CPU 选择、内存估算references/api_reference.md完整ForecastConfig文档、输出形状、模型选项references/data_preparation.md输入格式、NaN 处理、CSV 加载、协变量配置示例与验收标准示例目录演示内容全球温度预测examples/global-temperature/基础model.forecast()CSV → PNG → GIF 完整流水线异常检测examples/anomaly-detection/两阶段去趋势 Z-score 分位数区间双面板可视化协变量XRegexamples/covariates-forecasting/forecast_with_covariates()2×2 共享坐标轴可视化运行方式cd timesfm-forecasting/examples/global-temperature python run_forecast.py python visualize_forecast.py cd timesfm-forecasting/examples/anomaly-detection python detect_anomalies.py cd timesfm-forecasting/examples/covariates-forecasting python demo_covariates.py验收标准即示例输出应满足的硬性条件global-temperature 的output/forecast_output.json中point_forecast有 12 个值output/forecast_visualization.png需同时呈现上下文、预测与区间带anomaly-detection 的输出须在 2023 年 9 月标记为 CRITICALz ≥ 3.0covariates-forecasting 的output/sales_with_covariates.csv应有 108 行3 家门店 × 36 周且每家门店的价格数组各不相同。下图即为全球温度示例产出的可视化上下文 预测 区间带质量检查清单与高频错误SKILL.md 要求 Agent 每次执行完预测任务、宣布成功之前逐项核对输出形状point_fc为(n_series, horizon)quant_fc为(n_series, horizon, 10)分位索引索引 0 均值1 q10 … 9 q90不是0 q0频率参数TimesFM 1.0/2.0 对月度数据需传freq[0]TimesFM 2.5 已移除频率标志直接省略序列长度上下文至少 32 个数据点无 NaNnp.isnan(point_fc).any()必须为 False共享坐标轴多面板共享数据时使用sharexTrue无头绘图matplotlib.use(Agg)必须在任何 pyplot import 之前设置正数约束温度、金融收益率等可为负的序列须将infer_is_positive设为 False。六个高频错误来自 SKILL.md分位索引 off-by-one——索引 0 是均值不是 q0建议定义IDX_Q10, IDX_Q90 1, 9协变量循环中的变量遮蔽——构建逐序列协变量 dict 时推导式内变量不要与外层循环变量重名CSV 列名写错——global-temperature 数据用的是anomaly_c而非anomaly先打印df.columns确认版本方法缺失——forecast_with_covariates()只有 TimesFM 2.5 有1.0 没有该方法未来协变量未覆盖完整 horizon——动态协变量需要同时覆盖上下文窗口与预测窗口上下文异常检测未去趋势——先 detrend 再 Z-score带趋势数据直接算 Z-score 会误导。验证与回归让 Agent 结果可被自动检验SKILL.md 内置了两条回归验证命令Agent 可在任务收尾时自动断言输出符合预期# 异常检测回归2023 年 9 月必须为 CRITICAL python -c import json d json.load(open(timesfm-forecasting/examples/anomaly-detection/output/anomaly_detection.json)) assert d[context_summary][critical] 1, Sep 2023 must be CRITICAL print(Anomaly detection: PASS) # 协变量回归sales_with_covariates.csv 必须为 108 行 python -c import pandas as pd df pd.read_csv(timesfm-forecasting/examples/covariates-forecasting/output/sales_with_covariates.csv) assert len(df) 108, fExpected 108 rows, got {len(df)} print(Covariates: PASS)模型版本速查版本参数上下文状态HuggingFace checkpoint2.5200M16,384最新google/timesfm-2.5-200m-pytorch2.0500M2,048已归档google/timesfm-2.0-500m-pytorch1.0200M2,048已归档google/timesfm-1.0-200m-pytorch2.5 版本相比 2.0 的核心变化README 明示参数量从 500M 降至 200M上下文长度从 2,048 提升到 16,384支持通过可选的 30M 分位头输出最长 1,000 步的连续分位数预测移除了frequency指示器并新增若干预测开关即上文ForecastConfig中的use_continuous_quantile_head、force_flip_invariance、fix_quantile_crossing等。SKILL.md 的建议是除非有特定理由使用旧版 checkpoint否则始终使用 TimesFM 2.5——它更小、更快且支持 8 倍更长的上下文。若需加载 v1/v2 归档版本可按 README 说明通过pip install timesfm1.3.0安装旧版包。小结从 AGENTS.md 出发TimesFM 为 AI Agent 提供了一条完整的技能化使用路径Skill 目录即装即用、预检脚本兜底硬件风险、ForecastConfig覆盖全部推理行为、示例与回归断言保证输出可验证。对开发者而言无论是让 Agent 自动完成日常预测任务还是自己写代码调用 TimesFM_2p5_200M_torch本文梳理的调用链、参数语义与源码实现都能作为一份可直接落地的实践参考。【免费下载链接】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），仅供参考