mlforecast

安装

PyPI

pip install mlforecast

conda-forge

conda install -c conda-forge mlforecast

更多详细说明请参阅安装页面。

快速入门

1. 从这份快速指南开始。
2. 遵循这份端到端教程，了解最佳实践。

视频

• 概述

示例笔记本

• m5
• m5-polars
• m4
• m4-cv
• favorita
• VN1

为什么？

目前用于机器学习模型的 Python 替代方案速度慢、精度低且难以扩展。因此，我们开发了一个可在生产环境中使用的库。MLForecast 包含高效的时间序列特征工程功能，可用于训练任何具有 fit 和 predict 方法的机器学习模型（例如 sklearn），以适应数百万条时间序列。

特性

• Python 中最快的时间序列预测特征工程实现。
• 开箱即用，兼容 pandas、polars、Spark、Dask 和 Ray。
• 基于 Conformal Prediction 的概率预测。
• 支持外生变量和静态协变量。
• 熟悉的 sklearn 语法：.fit 和 .predict。

缺少某些功能？请提交问题或在Slack 上与我们交流。

示例与指南

📚 端到端教程：多时间序列的模型训练、评估和选择。

🔎 概率预测：使用 Conformal Prediction 生成预测区间。

👩‍🔬 交叉验证：稳健地评估模型性能。

🔁 M5：复用 CV 划分 + 全局/分组滚动均值：在调优全局和分组滚动特征时，利用缓存的 CV 窗口优化模型。

🔌 预测需求高峰：电力负荷预测，用于检测每日高峰并降低电费。

📈 迁移学习：先用一组时间序列预训练模型，再用该预训练模型预测另一组数据。

🌡️ 分布式训练：使用 Dask、Ray 或 Spark 集群大规模训练模型。

使用方法

以下提供非常基础的概述，更详细的说明请参阅文档。

数据准备

将您的时间序列存储在一个长格式的 pandas 数据框中，即每行代表特定序列和时间戳的一个观测值。

from mlforecast.utils import generate_daily_series

series = generate_daily_series(
    n_series=20,
    max_length=100,
    n_static_features=1,
    static_as_categorical=False,
    with_trend=True
)
series.head()

	unique_id	ds	y	static_0
0	id_00	2000-01-01	17.519167	72
1	id_00	2000-01-02	87.799695	72
2	id_00	2000-01-03	177.442975	72
3	id_00	2000-01-04	232.704110	72
4	id_00	2000-01-05	317.510474	72

注意：unique_id 用作您数据集中每个独立时间序列的标识符。如果您只使用数据集中的单个时间序列，请将此列设置为常量值。

模型

接下来定义您的模型，每个模型都将针对所有序列进行训练。这些可以是任何遵循 scikit-learn API 的回归器。

import lightgbm as lgb
from sklearn.linear_model import LinearRegression

models = [
    lgb.LGBMRegressor(random_state=0, verbosity=-1),
    LinearRegression(),
]

预测对象

现在实例化一个 MLForecast 对象，传入你想要使用的模型和特征。这些特征可以是滞后项、对滞后项的变换以及日期特征。你还可以定义在拟合之前应用于目标变量的变换，这些变换会在预测时被还原。

from mlforecast import MLForecast
from mlforecast.lag_transforms import ExpandingMean, RollingMean
from mlforecast.target_transforms import Differences

fcst = MLForecast(
    models=models,
    freq='D',
    lags=[7, 14],
    lag_transforms={
        1: [ExpandingMean()],
        7: [RollingMean(window_size=28)]
    },
    date_features=['dayofweek'],
    target_transforms=[Differences([1])],
)

训练

要计算特征并训练模型，只需在你的 Forecast 对象上调用 fit 方法。

fcst.fit(series)

MLForecast(models=[LGBMRegressor, LinearRegression], freq=D, lag_features=['lag7', 'lag14', 'expanding_mean_lag1', 'rolling_mean_lag7_window_size28'], date_features=['dayofweek'], num_threads=1)

预测

要获取未来 n 天的预测结果，可以在预测对象上调用 predict(n) 方法。该方法会自动使用递归策略处理特征所需的更新。

predictions = fcst.predict(14)
predictions

	unique_id	ds	LGBMRegressor	LinearRegression
0	id_00	2000-04-04	299.923771	311.432371
1	id_00	2000-04-05	365.424147	379.466214
2	id_00	2000-04-06	432.562441	460.234028
3	id_00	2000-04-07	495.628000	524.278924
4	id_00	2000-04-08	60.786223	79.828767
...	...	...	...	...
275	id_19	2000-03-23	36.266780	28.333215
276	id_19	2000-03-24	44.370984	33.368228
277	id_19	2000-03-25	50.746222	38.613001
278	id_19	2000-03-26	58.906524	43.447398
279	id_19	2000-03-27	63.073949	48.666783

共280行 × 4列

可视化结果

from utilsforecast.plotting import plot_series

fig = plot_series(series, predictions, max_ids=4, plot_random=False)

如何贡献

请参阅 CONTRIBUTING.md。

mlforecast 快速上手指南

mlforecast 是一个专为时间序列预测设计的机器学习框架，支持高效特征工程，可轻松扩展至百万级时间序列，并兼容 pandas、polars、spark、dask 和 ray。

环境准备

• 操作系统：Linux、macOS 或 Windows
• Python 版本：3.8 及以上
• 前置依赖：无需特殊系统依赖，核心依赖包括 scikit-learn、pandas、numpy 等，安装时会自动解决。

安装步骤

推荐使用国内镜像源加速安装（如清华源）：

pip install mlforecast -i https://pypi.tuna.tsinghua.edu.cn/simple

或使用 conda：

conda install -c conda-forge mlforecast

基本使用

以下是最简使用示例，展示如何构建模型、训练并预测未来 14 天。

1. 准备数据

数据需为长格式（long format），包含 unique_id（序列 ID）、ds（时间戳）、y（目标值）。

from mlforecast.utils import generate_daily_series

series = generate_daily_series(
    n_series=20,
    max_length=100,
    n_static_features=1,
    static_as_categorical=False,
    with_trend=True
)
print(series.head())

2. 定义模型

可使用任意遵循 scikit-learn 接口的回归模型。

import lightgbm as lgb
from sklearn.linear_model import LinearRegression

models = [
    lgb.LGBMRegressor(random_state=0, verbosity=-1),
    LinearRegression(),
]

3. 配置预测器

设置频率、滞后特征、日期特征及目标变换。

from mlforecast import MLForecast
from mlforecast.lag_transforms import ExpandingMean, RollingMean
from mlforecast.target_transforms import Differences

fcst = MLForecast(
    models=models,
    freq='D',
    lags=[7, 14],
    lag_transforms={
        1: [ExpandingMean()],
        7: [RollingMean(window_size=28)]
    },
    date_features=['dayofweek'],
    target_transforms=[Differences([1])],
)

4. 训练模型

fcst.fit(series)

5. 生成预测

预测未来 14 天：

predictions = fcst.predict(14)
print(predictions.head())

输出示例：

	unique_id	ds	LGBMRegressor	LinearRegression
0	id_00	2000-04-04	299.923771	311.432371
1	id_00	2000-04-05	365.424147	379.466214

6. 可视化结果（可选）

from utilsforecast.plotting import plot_series

fig = plot_series(series, predictions, max_ids=4, plot_random=False)

至此，你已完成一个完整的时间序列预测流程。更多高级用法（如分布式训练、概率预测、交叉验证）请参考官方文档。