ai-ml-timeseries

时间序列预测——生产实践

建模前先定义预测截止时间：只有届时可用的信息才能进入特征或基线。针对决策时域，将模型与当前驱动决策的预测进行比较。

范围边界

• 通用 EDA、表格建模、实验设计或可复用的 DS 工作流 -> ai-ml-data-science
• 部署架构、监控技术栈、发布门禁、事件处理手册 -> ai-mlops
• 通用 LLM 生命周期、提示词编写或提供商选择 -> ai-llm
• RAG 和搜索系统 -> ai-rag

工作流

1. 首先定义预测目标、时域、截止时间戳、粒度和业务损失形态。
2. 如果主要需求并非深入时间序列预测，则将通用 DS 工作流或完整的生产运维工作转交给相邻技能。
3. 根据决策树选择基线、特征模式和模型系列。
4. 运行防泄漏回测，比较考虑时域的指标；如果决策需要衡量不确定性，则增加区间或校准检查。
5. 在选择软件包或检查点之前，先打开 data/sources.json 中的官方文档，并检查已安装的 API、支持的协变量、上下文／时域限制和权重许可证。比较 TSFM 时，加载模型角色和查询步骤；引用排名时，在旁边记录基准测试快照。使用 MAPIE 代码时，加载概率预测模式，并将示例与已安装版本的文档进行比较。

快速参考

选择预测模式

Need to build or review a forecast:
    ├─ One series or a small local portfolio?
    │   ├─ Few covariates, interpretability first -> naive/seasonal naive + ETS/SARIMAX baseline
    │   └─ Nonlinear effects or richer covariates -> feature-based boosting
    │
    ├─ Many related series?
    │   ├─ Need one shared model with covariates -> global/panel forecasting
    │   └─ Need rollups to add up across levels -> hierarchical forecasting + reconciliation
    │
    ├─ Intermittent or zero-heavy demand?
    │   ├─ Very sparse and operationally simple -> Croston/SBA/ADIDA baseline
    │   └─ Need richer covariates or scale -> global boosting with zero-aware features
    │
    ├─ Need uncertainty, service levels, or inventory decisions?
    │   └─ Add quantiles, conformal intervals, or distributional forecasts
    │
    ├─ Long horizon or low-feature setup?
    │   ├─ Need strong zero-shot baseline -> TS foundation models
    │   └─ Need supervised optimization on many series -> global/deep forecasting
    │
    └─ Need production handoff?
        └─ Record cutoff timestamp, feature contract, fallback, lineage, and retraining trigger

核心原则

1. 特征构建前确定截止时间戳

• 在构建标签或特征前，定义准确的预测时间戳。
• 每个滞后值、滚动聚合、日历标记和外部信号，都必须根据该截止时间戳时已知的信息进行合理性说明。
• 对已知的未来协变量和未来未知的协变量必须区别处理。

2. 先建立基线

• 始终将朴素基线和季节性朴素基线作为比较对象，并基于每个起点已知的值，在相同预测时域上评分；任何基于之后实际值构建的基线都会泄漏未来信息。
• 如果可解释性很重要，则增加 ETS/SARIMAX 或其他局部经典基线。
• 候选模型若仅略微优于简单基线，就不应获准部署。
• 朴素基线和季节性朴素基线是最低门槛。晋升标准是当前驱动决策的预测（包括规划人员的人工调整），并在相同起点上评分。将人工调整记录为单独的预测，以便衡量其价值。
• 点预测表现胜出只是初筛，并不意味着可以晋升。只有在决策时域上的逐起点损失差异配对检验排除零值时，才可晋升（配对晋升检验）。

3. 按时域和切片评估

• 按时域报告准确度，而非只报告单一全局分数。
• 按细分群体、地理区域、SKU 系列、销量区间或任何与业务相关的群组进行切片分析。
• 存在零值或接近零的值时，优先使用 MASE/WAPE/MAE，而非 MAPE；间歇性序列除外。
• 当超过一半的周期为零时，MAE、WAPE 和 MASE 都会奖励全零预测（它们以中位数为最小值）。选择均值预测时使用 RMSSE，制定库存决策时使用 pinball loss；切勿仅依据 MAE 或 WAPE（间歇性指标）。
• 根据各时域上相对于基线的技能水平评判每个时域。误差随时域增加而增大是预期现象，本身并不构成缺陷。

4. 全局／面板方法优先于逐序列复杂建模

• 当存在许多相关序列时，默认先采用共享的全局／面板方法，再构建单独定制的模型。
• 当预测必须在各层级之间保持一致时，使用层级协调。
• 只有在复杂度能提升准确性、校准效果或运维简便性时，才增加复杂度。

5. 决策对风险敏感时采用概率预测

• 当下游操作取决于不确定性时，使用分位数、保形区间或完整的预测分布。
• 同时评估覆盖率和锐度；达到名义覆盖率的宽区间并非自动有用。
• 仅当覆盖命中相互独立且具有相同概率时，才使用 Wilson 区间按各预测步长检验覆盖率；仅有不同的预测起点并不能证明相互独立。对于存在依赖性的残差，在提升方案前需要基于区块或序列的证据。将汇总覆盖率作为描述性指标，并检查聚类式漏判（噪声下的覆盖率）。
• 根据成本设定决策分位数 q* = c_u / (c_u + c_o)，并使用 pinball 损失和各预测步长的覆盖率进行评分（根据成本设定决策分位数）。
• 每次重新训练或重大模型变更后，重新评估校准情况。

6. 预测专用交接

• 预测包必须包含截止时间戳、预测步长定义、特征约定、指标定义、回退规则和沿袭元数据，否则就不完整。
• 在此处保留预测专用的交接指南；完整的部署架构请参阅 ai-mlops。

预测决策关卡

为每个回测折创建截止时间台账：训练结束时间、预测起点、预测步长、特征可用性、重新训练策略，以及任何修订或发布延迟。在汇总前，按预测步长和对决策至关重要的细分项报告误差和区间质量。只有当预测在业务加权损失上优于当前使用的预测（包括规划人员的覆盖调整），且跨预测起点的配对检验确认了这一提升，同时没有掩盖任何阻碍性细分项时，才予以采用。还必须测试协变量缺失或延迟时的回退方案。优于朴素或季节性朴素基准是必要条件，但绝非充分条件。

已知陷阱

• 将未来已知和未来未知的协变量混在同一特征路径中，却不说明哪些值在预测时实际可用。
• 当不同预测步长的误差表现差异显著时，仍用一个全局回测分数作为部署依据。
• 在零值较多、间歇性或接近零值的序列上使用 MAPE，随后又依据不稳定的百分比比较模型。
• 尚未在相关序列上测试强全局或面板基准，就为每个序列构建定制模型。
• 忽视层级和一致性，而下游使用方又期望汇总结果能够相加。

常见反模式

• 沿用通用表格机器学习中的 IID 验证习惯，而不采用滚动起点或扩展窗口评估。
• 将分解图表视为生产信号的证据，却没有针对实际决策步长进行回测。
• 使用特征丰富的模型，但其未来协变量不可用，或运维成本过高。
• 将 TS 基础模型与较弱的基准比较，并把结果称为战略性证据。
• 未查阅检查点的权重许可证，也未使用私有数据或截止时间之后的数据重新测试，就相信 TSFM 的零样本优势（TSFM 信任关卡）。

导航：核心参考资料

数据完整性与特征

• TS EDA 最佳实践 - 时间戳完整性、缺失情况、分解和稳定性检查
• 滞后与滚动模式 - 避免数据泄漏的滞后特征、滚动窗口和日历模式
• 全局与面板预测模式 - 共享模型、面板架构、已知未来协变量、分组评估

模型与策略选择

• 模型选择指南 - 模型系列决策矩阵
• LightGBM TS 模式 - 基于特征的全局提升模式、MLForecast/skforecast 工作流
• 多步预测模式 - 直接、递归和 seq2seq 方案的权衡
• 间歇性需求模式 - 稀疏需求基线和零值感知建模

验证、不确定性与高级预测

• 回测模式 - 滚动起点评估、面板感知回测和指标设计
• 概率预测 - 分位数、保形方法、校准和评分规则
• 层级预测 - 一致性预测和协调方法
• 时间序列基础模型模式 - TSFM 的作用、信任门槛（许可证、污染）、零样本基准测试
• 异常检测模式 - 基于残差和区间的异常检测工作流

交接与预测运维

• 预测治理模式 - 截止时间戳、数据沿袭、回退规则和预测契约
• 生产预测运维 - 按预测时域与回测匹配的实时监控、实际值延迟、正式预测、回退阶梯

模板

数据准备

• TS EDA 模板 - 用于时间戳和季节性审查的可复现结构
• 重采样与填充模板 - 重采样、间隔规则和填充策略

特征与模型设计

• 滞后与滚动特征 - 避免数据泄漏的特征规范
• 日历特征 - 已知未来的业务日历与事件特征规范
• 预测模型模板 - 适用于局部、全局或层级模型的预测包契约
• 多步策略 - 直接、递归和 seq2seq 策略契约

评估与不确定性

• 回测模板 - 滚动起点或扩展窗口评估规范
• TS 指标模板 - 预测时域、切片、业务损失和概率指标契约

基础模型

• TS 基础模型模板 - 零样本 TSFM 基准测试与评估框架

脚本

脚本	用途
scripts/ts_evaluator.py	仅使用标准库的 CLI：从 origin_value 计算各预测时域的指标，以及相对于朴素/季节性朴素基线的技能（少于 6 个起点时不作判断）；假设独立性的逐预测时域 Wilson 筛查、描述性汇总覆盖率、Markdown 报告。输入无效、区间级别仅部分提供，或 --output 不可写时退出码为 2。“优于基线”仅是筛查结果；晋级前请运行配对检验

# Horizon-wise accuracy: MAE, RMSE, MAPE, MASE, skill vs the baseline at the same horizon (invalid input exits 2)
python scripts/ts_evaluator.py backtest --input data/sample-forecast-results.json

# Per-horizon calibration screen for 50%, 80%, 90% prediction intervals; pooled coverage is descriptive
python scripts/ts_evaluator.py calibration --input data/sample-forecast-results.json

# Full Markdown evaluation report written to file
python scripts/ts_evaluator.py report --input data/sample-forecast-results.json --output /tmp/ts-eval-report.md

数据文件

文件	描述
data/sources.json	精选的经典预测、MLForecast、skforecast、AutoGluon、TSFM 仓库、fev-bench 和 MAPIE 主要来源
data/sample-forecast-results.json	每日收入预测的合成滚动起点回测：预测范围为 1、7、14、30 天，共 48 行、12 个起点，包含 origin_value 和用于计算 MASE 的样本内历史数据

外部来源

请参阅 data/sources.json，了解以下领域的最新主要来源：

• 经典预测参考资料
• MLForecast、HierarchicalForecast、skforecast、AutoGluon TimeSeries、LightGBM 和 MAPIE 的官方文档
• TSFM 官方仓库和模型卡
• 高影响部署所用的 fev-bench 基准测试和治理参考资料

相关技能

• ai-ml-data-science - 通用数据科学工作流、实验设计和更广泛的建模模式
• ai-mlops - 部署架构、监控和发布运维
• ai-llm - 时间序列预测之外的提供商／模型生命周期问题
• data-sql-optimization - 时间序列数据集市的存储和查询设计

经验总结循环

如果以往的决策或陷阱与当前任务相关，请在文件存在时查阅 learnings.consolidated.md；仅在需要了解历史或将其作为可用的后备资料时使用 learnings.md。否则跳过这两个文件。

应用后，如果你遇到了值得记住的模式、值得避免的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目符号。请勿修改 SKILL.md 本身。