时序预测模块使用教程¶
一、概述¶
时序预测旨在通过分析历史数据中的模式、趋势和周期性等特征，来预测未来某一时间点或时间段内可能发生的值或状态。这有助于企业和组织做出更加精准的决策，优化资源配置，减少风险，并抓住潜在的市场机会。这些时序数据通常来自于实际应用场景中的各种传感器、经济活动、社会行为等。例如，股票价格、气温变化、网站访问量、销售数据等都是典型的时序数据。
二、支持模型列表¶
| 模型名称 | 模型下载链接 | mse | mae | 模型存储大小（M) | 介绍 |
|---|---|---|---|---|---|
| DLinear | 推理模型/训练模型 | 0.382 | 0.394 | 72k | DLinear 是一个简单、高效且易于使用的时间序列预测模型。 |
| NLinear | 推理模型/训练模型 | 0.386 | 0.392 | 40k | NLinear 是一个简单、高效且易于使用的时间序列预测模型。 |
| RLinear | 推理模型/训练模型 | 0.385 | 0.392 | 40k | RLinear 是一个简单、高效且易于使用的时间序列预测模型。 |
| Nonstationary | 推理模型/训练模型 | 0.600 | 0.515 | 60.3M | 基于 Transformer 结构，该模型针对非平稳时间序列的长期预测进行了优化。 |
| PatchTST | 推理模型/训练模型 | 0.379 | 0.391 | 2.0M | PatchTST 是一个高精度的长期预测模型，能够平衡局部模式和全局依赖关系。 |
| TiDE | 推理模型/训练模型 | 0.407 | 0.414 | 31.7M | TiDE 是一个适合多变量、长期时间序列预测问题的高精度模型。 |
| TimesNet | 推理模型/训练模型 | 0.416 | 0.429 | 4.9M | 通过多周期分析，TimesNet 是一个稳健且高精度的时间序列分析模型。 |
测试环境说明：
- 性能测试环境
- 测试数据集：ETTH1测试数据集。
-
硬件配置：
- GPU：NVIDIA Tesla T4
- CPU：Intel Xeon Gold 6271C @ 2.60GHz
- 其他环境：Ubuntu 20.04 / cuDNN 8.6 / TensorRT 8.5.2.2
-
推理模式说明
| 模式 | GPU配置 | CPU配置 | 加速技术组合 |
|---|---|---|---|
| 常规模式 | FP32精度 / 无TRT加速 | FP32精度 / 8线程 | PaddleInference |
| 高性能模式 | 选择先验精度类型和加速策略的最优组合 | FP32精度 / 8线程 | 选择先验最优后端（Paddle/OpenVINO/TRT等） |
三、快速集成¶
❗ 在快速集成前，请先安装 PaddleX 的 wheel 包，详细请参考 PaddleX本地安装教程
完成 wheel 包的安装后，几行代码即可完成是时序预测模块的推理，可以任意切换该模块下的模型，您也可以将时序预测的模块中的模型推理集成到您的项目中。运行以下代码前，请您下载示例数据到本地。
from paddlex import create_model
model = create_model(model_name="DLinear")
output = model.predict("ts_fc.csv", batch_size=1)
for res in output:
res.print(json_format=False)
res.save_to_csv(save_path="./output/")
res.save_to_json(save_path="./output/res.json")
运行后，得到的结果为：
{'res': {'input_path': 'ts_fc.csv', 'forecast': OT
date
2018-06-26 20:00:00 9.586131
2018-06-26 21:00:00 9.379762
2018-06-26 22:00:00 9.252275
2018-06-26 23:00:00 9.249993
2018-06-27 00:00:00 9.164998
... ...
2018-06-30 15:00:00 8.830340
2018-06-30 16:00:00 9.291553
2018-06-30 17:00:00 9.097666
2018-06-30 18:00:00 8.905430
2018-06-30 19:00:00 8.993793
[96 rows x 1 columns]}}
运行结果参数含义如下：
- input_path：表示输入待预测的时序文件路径
- forecast：表示时序预测结果，可以通过res.save_to_csv()将预测结果保存为csv文件，通过res.save_to_json()将预测结果保存为json文件。
相关方法、参数等说明如下：
create_model实例化时序预测模型（此处以DLinear为例），具体说明如下：
| 参数 | 参数说明 | 参数类型 | 可选项 | 默认值 |
|---|---|---|---|---|
model_name |
模型名称 | str |
所有PaddleX支持的模型名称 | 无 |
model_dir |
模型存储路径 | str |
无 | 无 |
use_hpip |
是否启用高性能推理 | bool |
无 | False |
-
其中，
model_name必须指定，指定model_name后，默认使用 PaddleX 内置的模型参数，在此基础上，指定model_dir时，使用用户自定义的模型。 -
调用时序预测模型的
predict()方法进行推理预测，predict()方法参数有input和batch_size，具体说明如下：
| 参数 | 参数说明 | 参数类型 | 可选项 | 默认值 |
|---|---|---|---|---|
input |
待预测数据，支持多种输入类型 | Python Var/str/list |
|
无 |
batch_size |
批大小 | int |
大于0任意整数 | 1 |
- 对预测结果进行处理，每个样本的预测结果均为对应的Result对象，且支持打印、保存为
csv文件、保存为json文件的操作:
| 方法 | 方法说明 | 参数 | 参数类型 | 参数说明 | 默认值 |
|---|---|---|---|---|---|
print() |
打印结果到终端 | format_json |
bool |
是否对输出内容进行使用 JSON 缩进格式化 |
True |
indent |
int |
指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 |
4 | ||
ensure_ascii |
bool |
控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 |
False |
||
save_to_json() |
将结果保存为json格式的文件 | save_path |
str |
保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致 | 无 |
indent |
int |
指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效 |
4 | ||
ensure_ascii |
bool |
控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效 |
False |
||
save_to_csv() |
将结果保存为时序csv格式的文件 | save_path |
str |
保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致 | 无 |
- 此外，也支持通过属性获取带结果的可视化时序和预测结果，具体如下：
| 属性 | 属性说明 |
|---|---|
json |
获取预测的json格式的结果 |
csv |
获取格式为csv的时序预测预测结果 |
关于更多 PaddleX 的单模型推理的 API 的使用方法，可以参考PaddleX单模型Python脚本使用说明。
四、二次开发¶
如果你追求更高精度的现有模型，可以使用PaddleX的二次开发能力，开发更好的时序预测模型。在使用PaddleX开发时序预测模型之前，请务必安装 PaddleTS 插件，安装过程可以参考PaddleX本地安装教程。
4.1 数据准备¶
在进行模型训练前，需要准备相应任务模块的数据集。PaddleX 针对每一个模块提供了数据校验功能，只有通过数据校验的数据才可以进行模型训练。此外，PaddleX为每一个模块都提供了 Demo 数据集，您可以基于官方提供的 Demo 数据完成后续的开发。若您希望用私有数据集进行后续的模型训练，可以参考PaddleX时序预测任务模块数据标注教程。
4.1.1 Demo 数据下载¶
您可以参考下面的命令将 Demo 数据集下载到指定文件夹：
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ts_dataset_examples.tar -P ./dataset
tar -xf ./dataset/ts_dataset_examples.tar -C ./dataset/
4.1.2 数据校验¶
一行命令即可完成数据校验：
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=check_dataset \
-o Global.dataset_dir=./dataset/ts_dataset_examples
Check dataset passed !信息。校验结果文件保存在./output/check_dataset_result.json，同时相关产出会保存在当前目录的./output/check_dataset目录下，产出目录中包括示例时序数据。
👉 校验结果详情（点击展开）
校验结果文件具体内容为：
{
"done_flag": true,
"check_pass": true,
"attributes": {
"train_samples": 12194,
"train_table": [
[
"date",
"HUFL",
"HULL",
"MUFL",
"MULL",
"LUFL",
"LULL",
"OT"
],
[
"2016-07-01 00:00:00",
5.827000141143799,
2.009000062942505,
1.5989999771118164,
0.4620000123977661,
4.203000068664552,
1.3400000333786009,
30.5310001373291
],
[
"2016-07-01 01:00:00",
5.692999839782715,
2.075999975204468,
1.4919999837875366,
0.4259999990463257,
4.142000198364259,
1.371000051498413,
27.78700065612793
]
],
"val_samples": 3484,
"val_table": [
[
"date",
"HUFL",
"HULL",
"MUFL",
"MULL",
"LUFL",
"LULL",
"OT"
],
[
"2017-11-21 02:00:00",
12.994000434875488,
4.889999866485597,
10.055999755859377,
2.878000020980835,
2.559000015258789,
1.2489999532699585,
4.7129998207092285
],
[
"2017-11-21 03:00:00",
11.92199993133545,
4.554999828338623,
9.097000122070312,
3.0920000076293945,
2.559000015258789,
1.2790000438690186,
4.8540000915527335
]
]
},
"analysis": {
"histogram": ""
},
"dataset_path": "./dataset/ts_dataset_examples",
"show_type": "csv",
"dataset_type": "TSDataset"
}
上述校验结果中，check_pass 为 True 表示数据集格式符合要求，其他部分指标的说明如下：
attributes.train_samples：该数据集训练集样本数量为 12194；attributes.val_samples：该数据集验证集样本数量为 3484；attributes.train_table：该数据集训练集样本示例数据前10行信息；attributes.val_table：该数据集训练集样本示例数据前10行信息； 注：只有通过数据校验的数据才可以训练和评估。
4.1.3 数据集格式转换/数据集划分（可选）¶
在您完成数据校验之后，可以通过修改配置文件或是追加超参数的方式对数据集的格式进行转换，也可以对数据集的训练/验证比例进行重新划分。
👉 格式转换/数据集划分详情（点击展开）
（1）数据集格式转换
时序预测支持 xlsx 和 xls 格式的数据集转换为 csv 格式。
数据集校验相关的参数可以通过修改配置文件中 CheckDataset 下的字段进行设置，配置文件中部分参数的示例说明如下：
CheckDataset:convert:enable: 是否进行数据集格式转换，支持xlsx和xls格式的数据集转换为CSV格式，默认为False;src_dataset_type: 如果进行数据集格式转换，无需设置源数据集格式，默认为null，； 则需要修改配置如下：
......
CheckDataset:
......
convert:
enable: True
src_dataset_type: null
......
随后执行命令：
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=check_dataset \
-o Global.dataset_dir=./dataset/ts_dataset_examples
以上参数同样支持通过追加命令行参数的方式进行设置：
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=check_dataset \
-o Global.dataset_dir=./dataset/ts_dataset_examples \
-o CheckDataset.convert.enable=True
（2）数据集划分
数据集校验相关的参数可以通过修改配置文件中 CheckDataset 下的字段进行设置，配置文件中部分参数的示例说明如下：
CheckDataset:convert:enable: 是否进行数据集格式转换，为True时进行数据集格式转换，默认为False;src_dataset_type: 如果进行数据集格式转换，时序预测仅支持将xlsx标注文件转换为csv，无需设置源数据集格式，默认为null；split:enable: 是否进行重新划分数据集，为True时进行数据集格式转换，默认为False；train_percent: 如果重新划分数据集，则需要设置训练集的百分比，类型为0-100之间的任意整数，需要保证与val_percent的值之和为100；val_percent: 如果重新划分数据集，则需要设置验证集的百分比，类型为0-100之间的任意整数，需要保证与train_percent的值之和为100； 例如，您想重新划分数据集为 训练集占比90%、验证集占比10%，则需将配置文件修改为：
......
CheckDataset:
......
split:
enable: True
train_percent: 90
val_percent: 10
......
随后执行命令：
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=check_dataset \
-o Global.dataset_dir=./dataset/ts_dataset_examples
数据划分执行之后，原有标注文件会被在原路径下重命名为 xxx.bak。
以上参数同样支持通过追加命令行参数的方式进行设置：
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=check_dataset \
-o Global.dataset_dir=./dataset/ts_dataset_examples \
-o CheckDataset.split.enable=True \
-o CheckDataset.split.train_percent=90 \
-o CheckDataset.split.val_percent=10
4.2 模型训练¶
一条命令即可完成模型的训练，以此处高效率时序预测模型（DLinear）的训练为例：
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=train \
-o Global.dataset_dir=./dataset/ts_dataset_examples
- 指定模型的
.yaml配置文件路径（此处为DLinear.yaml，训练其他模型时，需要的指定相应的配置文件，模型和配置的文件的对应关系，可以查阅PaddleX模型列表（CPU/GPU）） - 指定模式为模型训练：
-o Global.mode=train - 指定训练数据集路径：
-o Global.dataset_dir其他相关参数均可通过修改.yaml配置文件中的Global和Train下的字段来进行设置，也可以通过在命令行中追加参数来进行调整。如指定前 2 卡 gpu 训练：-o Global.device=gpu:0,1；设置训练轮次数为 10：-o Train.epochs_iters=10。更多可修改的参数及其详细解释，可以查阅模型对应任务模块的配置文件说明PaddleX时序任务模型配置文件参数说明。
👉 更多说明（点击展开）
- 模型训练过程中，PaddleX 会自动保存模型权重文件，默认为
output，如需指定保存路径，可通过配置文件中-o Global.output字段进行设置。 - PaddleX 对您屏蔽了动态图权重和静态图权重的概念。在模型训练的过程中，会同时产出动态图和静态图的权重，在模型推理时，默认选择静态图权重推理。
-
在完成模型训练后，所有产出保存在指定的输出目录（默认为
./output/）下，通常有以下产出： -
train_result.json：训练结果记录文件，记录了训练任务是否正常完成，以及产出的权重指标、相关文件路径等； train.log：训练日志文件，记录了训练过程中的模型指标变化、loss 变化等；config.yaml：训练配置文件，记录了本次训练的超参数的配置；best_accuracy.pdparams.tar、scaler.pkl、.checkpoints、.inference：模型权重相关文件，包括网络参数、优化器、EMA、静态图网络参数、静态图网络结构等；
4.3 模型评估¶
在完成模型训练后，可以对指定的模型权重文件在验证集上进行评估，验证模型精度。使用 PaddleX 进行模型评估，一条命令即可完成模型的评估：
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=evaluate \
-o Global.dataset_dir=./dataset/ts_dataset_examples
- 指定模型的
.yaml配置文件路径（此处为DLinear.yaml） - 指定模式为模型评估：
-o Global.mode=evaluate - 指定验证数据集路径：
-o Global.dataset_dir其他相关参数均可通过修改.yaml配置文件中的Global和Evaluate下的字段来进行设置，详细请参考PaddleX时序任务模型配置文件参数说明。
👉 更多说明（点击展开）
在模型评估时，需要指定模型权重文件路径，每个配置文件中都内置了默认的权重保存路径，如需要改变，只需要通过追加命令行参数的形式进行设置即可，如-o Evaluate.weight_path=./output/best_model/model.pdparams。
在完成模型评估后，通常有以下产出：
在完成模型评估后，会产出evaluate_result.json，其记录了评估的结果，具体来说，记录了评估任务是否正常完成，以及模型的评估指标，包含 mse 和 mae。
4.4 模型推理和模型集成¶
在完成模型的训练和评估后，即可使用训练好的模型权重进行推理预测或者进行Python集成。
4.4.1 模型推理¶
通过命令行的方式进行推理预测，只需如下一条命令。运行以下代码前，请您下载示例数据到本地。
python main.py -c paddlex/configs/modules/ts_forecast/DLinear.yaml \
-o Global.mode=predict \
-o Predict.model_dir="./output/inference" \
-o Predict.input="ts_fc.csv"
- 指定模型的
.yaml配置文件路径（此处为DLinear.yaml） - 指定模式为模型推理预测：
-o Global.mode=predict - 指定模型权重路径：
-o Predict.model_dir="./output/inference" - 指定输入数据路径：
-o Predict.input="..."其他相关参数均可通过修改.yaml配置文件中的Global和Predict下的字段来进行设置，详细请参考PaddleX时序任务模型配置文件参数说明。
4.4.2 模型集成¶
模型可以直接集成到PaddleX产线中，也可以直接集成到您自己的项目中。
1.产线集成
时序预测模块可以集成的PaddleX产线有时序预测，只需要替换模型路径即可完成时序预测的模型更新。在产线集成中，你可以使用服务化部署来部署你得到的模型。
2.模块集成
您产出的权重可以直接集成到时序预测模块中，可以参考快速集成的 Python 示例代码，只需要将模型替换为你训练的到的模型路径即可。
您也可以利用 PaddleX 高性能推理插件来优化您模型的推理过程，进一步提升效率，详细的流程请参考PaddleX高性能推理指南。