AutoGluon 时间序列预测入门指南：TimeSeriesPredictor 完整教程索引与实战导航-平芜编程栈

AutoGluon 时间序列预测入门指南：TimeSeriesPredictor 完整教程索引与实战导航

【免费下载链接】autogluonFast and Accurate ML in 3 Lines of Code项目地址: https://gitcode.com/GitHub_Trending/au/autogluon

导读

本文是 AutoGluon 时间序列（Time Series）预测模块的入口指南。AutoGluon 只需调用TimeSeriesPredictor的fit()方法，即可在历史数据与相关协变量的基础上，训练出多个模型并生成高精度的概率预测结果，全程无需手动处理模型选择与超参数调优。阅读完本文，你将掌握 AutoGluon 时间序列模块的完整学习路径——从三行代码的快速上手，到进阶的深度教程、Chronos 零样本预测、模型清单、集成策略、评估指标与自定义模型接入，并了解各环节背后的源码实现。

什么是 AutoGluon 时间序列预测

时间序列预测的目标是：给定一段按固定时间间隔测量的历史观测序列，预测该序列未来若干步的值。AutoGluon 在底层组合了多种前沿预测算法，覆盖从经典统计方法到预训练基础模型的全谱系：

经典统计方法：基于StatsForecast库的 ETS、ARIMA 等（见 timeseries/src/autogluon/timeseries/models/local/statsforecast.py）；
高效树模型：基于 AutoGluon-Tabular 的 LightGBM 类预测器（见 timeseries/src/autogluon/timeseries/models/autogluon_tabular）；
灵活深度学习模型：来自 GluonTS 的 DeepAR、Temporal Fusion Transformer 等（见 timeseries/src/autogluon/timeseries/models/gluonts）；
预训练零样本模型：Chronos 系列（见 timeseries/src/autogluon/timeseries/models/chronos）与 Toto 系列（见 timeseries/src/autogluon/timeseries/models/toto）。

一次TimeSeriesPredictor.fit()调用即可完成多模型的训练与择优。从源码看，predictor.py 中的TimeSeriesPredictor同时拟合两类模型：在所有时间序列间共享参数的"全局"深度学习模型（如 DeepAR），以及逐条时间序列独立拟合的"局部"统计模型（如 ARIMA、ETS）。

学习路径总览

本节内容即 docs/tutorials/timeseries/index.md 提供的教程导航，覆盖从入门到进阶、从使用到自定义的完整链路：

教程	链接	内容要点
快速上手	forecasting-quick-start.ipynb	用三行代码在时间序列数据集上完成模型拟合与预测
深度教程	forecasting-indepth.ipynb	系统讨论 AutoGluon 时间序列预测的高级能力
Chronos 预测	forecasting-chronos.ipynb	使用预训练 Chronos-2 模型进行零样本预测
模型清单	model_zoo/index.md	AutoGluon-TimeSeries 提供的全部预测模型
集成模型	forecasting-ensembles.md	可用的集成模型清单与多层堆叠策略
评估指标	forecasting-metrics.md	可用的预测评估指标及选择方法
自定义模型	advanced/forecasting-custom-model.ipynb	如何将自定义预测模型接入 AutoGluon

快速上手：三行代码生成预测

forecasting-quick-start.ipynb 展示了用 AutoGluon 在 M4 预测竞赛数据集上生成逐小时预测的完整流程，仅需两个核心类：

TimeSeriesDataFrame：存储由多条时间序列组成的数据集；
TimeSeriesPredictor：负责拟合、调优、选择最佳预测模型并生成新预测。

首先将数据装载为pandas.DataFrame，再构造TimeSeriesDataFrame。AutoGluon 要求时间序列数据采用长格式（long format），每一行是某条时间序列在某一时刻的单次观测，至少包含三列：时间序列唯一 ID（item_id）、观测时间戳（timestamp）、目标数值（target）。列名可以任意，但构造时必须显式指定：

import pandas as pd from autogluon.timeseries import TimeSeriesDataFrame, TimeSeriesPredictor df = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_subset/train.csv") train_data = TimeSeriesDataFrame.from_data_frame( df, id_column="item_id", timestamp_column="timestamp", )

每条时间序列被称为一个item（条目），例如需求预测中的不同商品，或金融数据中的不同股票，这种多条序列并存的数据结构也叫panel（面板）。需要注意，这与多变量预测不同——AutoGluon 对每条时间序列独立生成预测，不建模不同 item 之间的相互作用。TimeSeriesDataFrame继承自pandas.DataFrame，因此 pandas 的全部属性和方法均可用。

接下来创建预测器并拟合。AutoGluon 预测的是未来多步的值，步数即prediction_length（预测长度/预测视界）。由于数据集是小时频率，设置prediction_length = 48即训练预测未来 48 小时的模型：

predictor = TimeSeriesPredictor( prediction_length=48, # 预测未来 48 个小时 path="autogluon-m4-hourly", # 模型保存目录 target="target", # 目标列名 eval_metric="MASE", # 按 MASE 指标排名模型 ) predictor.fit( train_data, presets="medium_quality", time_limit=600, # 训练时间上限 10 分钟 )

presets决定了 AutoGluon 尝试拟合哪些模型。对于medium_quality，包括：简单基线（SeasonalNaive）、统计模型（ETS、Theta）、基于 LightGBM 的树模型（RecursiveTabular、DirectTabular）、预训练的 Chronos-2（small）与 Toto-2（4m）模型，以及一个加权集成。TimeSeriesPredictor还提供"high_quality"与"best_quality"预设，质量越高通常预测越准，但训练时间越长。

从源码看，presets 在 predictor_presets.py 中定义，并支持别名（medium/mq、high/hq、best/bq，fast_training已弃用并回退到medium_quality）。而各 preset 对应的模型集合在 hyperparameter_presets.py 中定义：

# "light"（对应 medium_quality） { "SeasonalNaive": {}, "ETS": {}, "Theta": {}, "RecursiveTabular": {}, "DirectTabular": {}, "Chronos2": {"model_path": "autogluon/chronos-2-small"}, "Toto2": {"model_path": "Toto-2.0-4m"}, }

# "default"（对应 high_quality / best_quality） { "SeasonalNaive": {}, "AutoETS": {}, "DynamicOptimizedTheta": {}, "RecursiveTabular": {}, "DirectTabular": {}, "TemporalFusionTransformer": {}, "DeepAR": {}, "Chronos2": [{}, {"model_path": "autogluon/chronos-2-small", "fine_tune": True, "eval_during_fine_tune": True, "ag_args": {"name_suffix": "SmallFineTuned"}}], "Toto2": {"model_path": "Toto-2.0-22m"}, }

fit()会在给定的时间限制内尽可能多地训练模型，随后基于内部验证集对模型排序。默认情况下，验证集通过将每条时间序列最后prediction_length个时间步留出构建。

生成预测与评估

训练完成后，用predict()生成预测。默认使用内部验证集上得分最高的模型，预测覆盖每条时间序列末端之后的prediction_length个时间步：

predictions = predictor.predict(train_data)

AutoGluon 生成的是概率预测：除预测均值（期望值）外，还提供预测分布的分位数。例如"0.1"分位数为500.0，意味着模型预测目标值有 10% 概率低于 500。可以加载测试数据并用plot()可视化均值预测以及 10%、90% 分位数：

import matplotlib.pyplot as plt test_data = TimeSeriesDataFrame.from_path("https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_subset/test.csv") predictor.plot(test_data, predictions, quantile_levels=[0.1, 0.9], max_history_length=200, max_num_item_ids=4)

用leaderboard()查看各模型的验证得分与测试得分。注意测试数据同时包含预测视界（每条序列最后prediction_length个值）与历史数据。AutoGluon 的排行榜遵循分数越高越好的原则，因此 MASE 会被乘以-1，以"负 MASE"的形式呈现，越接近 0 越准确。

深度教程：概率预测与特征工程

forecasting-indepth.ipynb 系统介绍了 AutoGluon 时间序列预测的高级能力，覆盖以下主题：

概率预测的两种输出

TimeSeriesPredictor输出两类预测：

均值预测（mean forecast）：预测视界内每个时间步的时间序列期望值；
分位数预测（quantile forecast）：预测分布的分位数。例如0.1分位数（P10，第 10 百分位）等于x，表示时间序列值有 10% 的概率低于x；0.5分位数（P50）即中位数预测。根据分位数定义，时间序列落在 P10 与 P90 之间的概率为 80%。

默认输出的分位数为[0.1, 0.2, ..., 0.9]，可通过quantile_levels自定义：

predictor = TimeSeriesPredictor(quantile_levels=[0.05, 0.5, 0.95])

prediction_length决定预测视界长度，例如对每日购买数据可设置 14，预测未来 14 天的需求。

静态特征与协变量

真实场景中常有超越原始序列值的附加信息，AutoGluon 支持两类：

静态特征（static features）：与时间无关的序列属性，如记录地点（国家/州/城市）、商品固定属性（品牌、颜色、尺寸、重量）、门店 ID 或商品 ID。静态特征作为TimeSeriesDataFrame对象的属性存储；
时变协变量（time-varying covariates）：包括已知协变量（预测视界内提前可知，如节假日、促销、天气预报）与过去协变量（仅有历史值）。已知协变量通过TimeSeriesPredictor的known_covariates_names参数声明，predict()时以known_covariates关键字传入未来值。

并非所有模型都支持全部特征类型，支持矩阵见 forecasting-model-zoo.md 的"Additional features"小节。

手动配置模型与超参数调优

hyperparameters参数允许手动指定要训练的模型，模型名无需"Model"后缀：

predictor = TimeSeriesPredictor().fit( train_data, hyperparameters={ "DeepAR": {}, "ETS": {}, }, )

部分模型的超参数名称与默认值与原始库不同，详见 Model Zoo。此外还可为各模型定义搜索空间进行超参数调优。

模型清单（Model Zoo）

model_zoo/index.md 列出了 AutoGluon 全部可用的时间序列预测模型，按类别划分如下：

基线模型：NaiveModel、SeasonalNaiveModel、AverageModel、SeasonalAverageModel、ZeroModel，使用最少历史数据做简单预测，作为复杂方法的基准；
统计模型：ETSModel、AutoARIMAModel、AutoETSModel、AutoCESModel、ThetaModel、NPTSModel，捕捉趋势与季节性等简单模式；
稀疏数据统计模型：ADIDAModel、CrostonModel、IMAPAModel，专为稀疏、非负数据（尤其是间歇性需求预测）设计；
深度学习模型：DeepARModel、DLinearModel、PatchTSTModel、SimpleFeedForwardModel、TemporalFusionTransformerModel、TiDEModel、WaveNetModel；
表格模型：DirectTabularModel、PerStepTabularModel、RecursiveTabularModel，将时间序列预测转化为表格回归问题（见 timeseries/src/autogluon/timeseries/models/autogluon_tabular）；
预训练模型：Chronos2Model、ChronosModel、TotoModel、Toto2Model，在大规模时间序列数据集上预训练，支持零样本预测。

所有模型共享一组超参数（详见 forecasting-model-zoo.md 的 "Hyperparameters shared by all models" 小节）：

target_scaler：("standard", "mean_abs", "robust", "min_max", None)，默认None。若设置，每条时间序列在训练/预测前按(y - loc) / scale缩放，预测后做逆变换。四种缩放器分别以均值/标准差、0/平均绝对值、中位数/四分位距、最小值/极差计算loc与scale，且逐条序列独立计算；
covariate_scaler：("global", None)，对协变量与静态特征做缩放。GluonTS 模型默认"global"，其余模型默认None；
covariate_regressor：("LR", "GBM", "CAT", "XGB", "RF", None)，默认None。若设置，先用选定的表格回归模型在已知协变量与静态特征上预测同时间步的目标，再从目标列中减去回归预测，让预测模型拟合残差；预测时再加回回归预测。启用它建议同时启用target_scaler。

需注意，MXNet 的 GluonTS 模型因依赖冲突已被弃用。

集成模型与多层堆叠

forecasting-ensembles.md 说明 AutoGluon 通过集成组合多个基模型预测以提升精度。集成模型在**留出的验证数据（回测窗口）**上训练，学习如何最佳组合基模型预测。默认使用单个GreedyEnsemble学习各基模型的最优权重，可通过TimeSeriesPredictor.fit()的ensemble_hyperparameters参数配置。

可用集成模型包括：简单平均类（SimpleAverageEnsemble、MedianEnsemble）、线性集成类（GreedyEnsemble、PerItemGreedyEnsemble、LinearStackerEnsemble）、非线性集成类（TabularEnsemble、PerQuantileTabularEnsemble）。模型名同样无需"Ensemble"后缀。

多层堆叠（multi-layer stacking）通过多阶段训练集成扩展基础集成：每一层集成在不同回测窗口上训练，并使用上一层集成的预测作为输入，使后层能纠正前层误差。例如num_val_windows=(3, 2)与两层集成时：基模型生成全部 5 个窗口的预测；第 2 层集成在窗口 1-3 上训练；第 3 层集成在窗口 4-5 上训练并以第 2 层预测为输入；最终验证分数在窗口 4-5 上计算：

predictor = TimeSeriesPredictor(prediction_length=prediction_length, eval_metric="MASE") predictor.fit( train_data, hyperparameters={"SeasonalNaive": {}, "Theta": {}, "DirectTabular": {}, "ETS": {}, "RecursiveTabular": {}}, ensemble_hyperparameters=[ {"WeightedEnsemble": {}, "Median": {}, "LinearStacker": {"weights_per": "mt"}}, # 第 2 层 {"WeightedEnsemble": {}}, # 第 3 层 ], num_val_windows=(3, 2), # 3 个窗口拟合 L2，2 个窗口拟合 L3 refit_every_n_windows="auto", )

训练后可通过backtest_targets()与backtest_predictions()访问用于训练集成的验证预测与目标值。

评估指标体系

forecasting-metrics.md 指出，选择正确的评估指标是使用 AutoML 框架时最重要的决策之一。指标通过eval_metric参数指定，AutoGluon 用它调优模型超参数、对模型排名并构建最终集成：

predictor = TimeSeriesPredictor(eval_metric="MASE")

AutoGluon 始终以越高越好的格式报告所有指标，因此部分指标会乘以-1（如报告-MASE，test_score介于 0 与负无穷之间）。

内置指标包括：概率指标MQL、SQL、WQL；点预测指标MAE、MAEB、MAPE、MASE、MSE、RMSE、RMSLE、RMSSE、SMAPE、WAPE、WAPEB，另有仅用于评估的BIAS。源码实现见 timeseries/src/autogluon/timeseries/metrics。

指标选择三问

文档给出三个决策问题：

关注点预测还是概率预测？目标是概率预测应使用WQL、MQL或SQL（基于分位数损失）；点预测指标则始终在预测的"mean"列上评估；
是否更关心大值序列的准确性？是——用尺度相关指标WQL、MQL、MAE、RMSE、WAPE（也适合含大量零值的稀疏序列），系统性偏差惩罚可选MAEB、WAPEB，度量偏差用BIAS；否——用缩放指标SQL、MASE、RMSSE或百分比指标MAPE、SMAPE（后者有文档记录的局限，不推荐实际使用）；
（点预测）估计均值还是中位数？中位数用MAE、MASE、WAPE；均值用MSE、RMSE、RMSSE；稀疏序列可用MAEB、WAPEB平衡中位数精度项与均值偏差惩罚。

自定义评估指标

可通过继承TimeSeriesScorer并实现compute_metric定义自定义指标。以下是一个自定义 MSE 指标：

import sklearn.metrics from autogluon.timeseries.metrics import TimeSeriesScorer class MeanSquaredError(TimeSeriesScorer): greater_is_better_internal = False optimum = 0.0 def compute_metric(self, data_future, predictions, target, **kwargs): return sklearn.metrics.mean_squared_error(y_true=data_future[target], y_pred=predictions["mean"])

compute_metric返回越低越好的内部指标，故设置greater_is_better_internal=False，AutoGluon 会将其乘以-1转为越高越好格式。调用时TimeSeriesScorer负责把test_data切分为过去与未来部分、校验预测时间戳、按越高越好格式报告分数。自定义指标必须定义在独立 Python 文件中并支持 pickle 序列化，否则开启超参数调优时可能崩溃。

此外，对 GluonTS 深度学习模型，可通过distr_output超参数修改训练损失，例如用NormalOutput（高斯分布 + 负对数似然损失）或QuantileOutput（分位数损失）训练 PatchTST，默认多数 GluonTS 模型使用对离群点更鲁棒的厚尾StudentTOutput。

延伸资源

Chronos 零样本预测：forecasting-chronos.ipynb 介绍如何在 AutoGluon 中使用预训练的 Chronos-2 模型进行零样本预测。仓库还内置了chronos2、chronos2_small、chronos2_ensemble等 preset，以及 Chronos-Bolt 系列的bolt_tiny/bolt_mini/bolt_small/bolt_base（见 predictor_presets.py）；
自定义预测模型：advanced/forecasting-custom-model.ipynb 演示如何将自定义时间序列模型接入 AutoGluon；
模型注册机制：模型注册与加载逻辑见 models/registry.py；
测试用例：可从 timeseries/tests/unittests 中查看预测器、指标、数据集的单元测试，理解各功能的预期行为。

总结

AutoGluon 时间序列模块以TimeSeriesPredictor.fit()为核心入口，一次调用即可完成多模型训练、验证集构建、模型排名与加权集成，输出多步概率预测。本文梳理了从 index.md 出发的完整学习路径：快速上手掌握三行代码流程，深度教程理解概率预测、静态特征/协变量与手动配置，模型清单了解五类模型与共享超参数，集成文档掌握多层堆叠，指标文档学会选择与自定义评估指标。无论需求预测、金融序列还是运维监控，都可以按此路径快速落地。

【免费下载链接】autogluonFast and Accurate ML in 3 Lines of Code项目地址: https://gitcode.com/GitHub_Trending/au/autogluon

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考