ServiceNow已于2021年1月8日完成对Element AI的收购。本项目相关材料中所有提及Element AI的内容，均应理解为指ServiceNow。

N-BEATS

此仓库提供了论文 https://arxiv.org/abs/1905.10437 中提出的N-BEATS算法的实现，并支持复现该论文中的实验结果。

N-BEATS是一种基于神经网络的单变量时间序列预测模型。

仓库结构

模型

N-BEATS的PyTorch实现位于 models/nbeats.py。

数据集

论文中使用的各数据集加载器位于 datasets/*.py。

实验

用于复现论文结果的实验代码位于 experiments/* 目录下，每个实验包包含一个 main.py 文件，其中实现了训练和预测逻辑，以及针对通用模型和可解释模型的两个配置文件。

结果

notebooks 目录下为每个实验提供了一个包含最终评分的笔记本。我们还包含了使用规模缩小至十分之一的集成模型的结果，可以看出差异并不显著。注意：这是原始N-BEATS的一个“轻量级”版本，其表现略有不同，有时更好，有时更差，但总体上仍处于当前最优水平。

如何复现结果

请确保已安装Docker。建议使用NVIDIA GPU，但并非必需。根据您的环境，可能需要调整Makefile中的Docker镜像名称，并编写额外的逻辑以并行训练模型。

默认配置为重复10次，这将为每个实验生成多达180个模型。如 notebooks 所示，大集合与小集合之间的差异并不显著。若要切换到小集合，请在您希望运行的实验对应的 *.gin 文件中设置 build.repeats = 1（这些文件位于 experiments/*/*.gin）。

1. 构建Docker镜像

   make init
   

2. 下载数据集

   make dataset
   

   此命令会将数据集下载到 ./storage/datasets 目录下。

3. （可选）测试指标。为确保所有数据集正确且指标计算正常工作，您可以运行测试。

   make test
   

4. 构建实验

   make build config=experiments/m4/interpretable.gin
   

   这将生成包含配置和每个多重模型指令的目录，存放于 ./storage/experiments/m4_interpretable。请注意，config 参数应为实际配置文件的相对路径。

5. 运行实验。 在以下命令中替换不同的 repeat 和 lookback 值，即可运行其他模型配置。

   CPU：

   make run command=storage/experiments/m4_interpretable/repeat=0,lookback=2,loss=MAPE/command
   

   GPU：

    make run command=storage/experiments/m4_interpretable/repeat=0,lookback=2,loss=MAPE/command gpu=<gpu-id>
   

   如果同一台机器上有多个GPU，则可以为每个GPU ID并行运行此命令。

   日志、损失值、快照及最终预测结果将存储在 storage/experiments/m4_interpretable/repeat=0,lookback=2,loss=MAPE 目录下。

   当然，您也可以通过以下脚本自动化地运行所有实验（假设使用BASH）：

   for instance in `/bin/ls -d storage/experiments/m4_interpretable/*`; do 
       echo $instance
       make run command=${instance}/command
   done
   

   如果您拥有可在云端扩展资源的环境，则可以考虑在Makefile中添加一个新的目标。以下是一个伪代码示例：

   run-all:
   rsync ${ROOT} ${network-share}
   for instance in $$(ls ${ROOT}/${experiment}); do \
       cloud submit \
               --image=${IMAGE} \
               -v ${network-share}:/experiment \
               -w /experiment \
               -e PYTHONPATH=/experiment \
               -e STORAGE=/experiment/storage \
               -- \
               bash -c "`cat ${ROOT}/${experiment}/$${instance}/command`"; \
   done
   

6. 获取实验统计信息。

   注意：如果实验是在云端运行的，请确保将结果下载到 storage/experiments 目录下。

   启动JupyterLab：make notebook port=<port>

   在 notebooks 目录下运行相应实验的笔记本，即可获取该实验的性能统计信息。

引用

如果您在任何场景下使用N-BEATS，请引用以下论文：

@inproceedings{
  Oreshkin2020:N-BEATS,
  title={{N-BEATS}: Neural basis expansion analysis for interpretable time series forecasting},
  author={Boris N. Oreshkin and Dmitri Carpov and Nicolas Chapados and Yoshua Bengio},
  booktitle={International Conference on Learning Representations},
  year={2020},
  url={https://openreview.net/forum?id=r1ecqn4YwB}
}

本项目是Element AI与Mila的合作成果。如果您使用了该模型或代码，请务必引用上述论文。

N-BEATS 快速上手指南

N-BEATS 是一种基于神经网络的单变量时间序列预测模型，以其可解释性和高精度的预测能力著称。本指南将帮助中国开发者快速搭建环境并复现论文实验结果。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux 或 macOS（Windows 用户建议使用 WSL2 或 Docker Desktop）。
• 核心依赖：必须安装 Docker。虽然推荐使用 NVIDIA GPU 加速训练，但非必需（CPU 亦可运行）。
• 硬件建议：若需复现完整论文结果（包含大量集成模型），建议具备多核 CPU 或多块 GPU；若仅进行轻量级测试或小型集成，普通单机即可。
• 网络环境：项目依赖从外部下载数据集，国内用户若遇到下载缓慢问题，建议配置全局代理或使用支持断点续传的下载工具辅助 make dataset 步骤。

安装步骤

本项目采用容器化部署，无需手动配置 Python 虚拟环境或安装 PyTorch 等依赖，所有操作通过 Makefile 完成。

1. 克隆仓库

   git clone https://github.com/ElementAI/nbeats.git
   cd nbeats
   

2. 构建 Docker 镜像 初始化并构建项目所需的 Docker 镜像：

   make init
   

3. 下载数据集 下载论文中使用的所有数据集到 ./storage/datasets 目录：

   make dataset
   

4. （可选）验证环境 运行测试以确保数据集加载正确且指标计算无误：

   make test
   

基本使用

以下示例展示如何构建并运行一个基于 M4 数据集的“可解释性（interpretable）”模型实验。

1. 构建实验配置

生成实验所需的目录结构和命令脚本。此处以 experiments/m4/interpretable.gin 配置为例：

make build config=experiments/m4/interpretable.gin

注：默认配置会生成 10 次重复实验（共约 180 个模型）。若仅需快速验证，可编辑对应的 .gin 文件，将 build.repeats 设置为 1 以启用小型集成模式。

2. 运行实验

根据机器资源选择 CPU 或 GPU 模式运行。

• CPU 模式：

  make run command=storage/experiments/m4_interpretable/repeat=0,lookback=2,loss=MAPE/command
  

• GPU 模式（请将 <gpu-id> 替换为实际显卡编号，如 0）：

  make run command=storage/experiments/m4_interpretable/repeat=0,lookback=2,loss=MAPE/command gpu=<gpu-id>
  

• 批量运行（适用于多卡或多配置并行）：

  for instance in `/bin/ls -d storage/experiments/m4_interpretable/*`; do 
      echo $instance
      make run command=${instance}/command
  done
  

运行产生的日志、损失值、模型快照及最终预测结果将保存在 storage/experiments/m4_interpretable/... 对应目录下。

3. 查看结果统计

实验完成后，启动 JupyterLab 查看性能统计笔记：

1. 启动服务（请将 <port> 替换为可用端口号）：

   make notebook port=<port>
   

2. 在浏览器中打开 JupyterLab，进入 notebooks 目录，运行对应实验的 Notebook 文件即可查看最终得分和分析图表。