BasicTS入门：从数据预处理到模型训练的时间序列预测全流程指南

时间序列预测大概是数据分析里最容易让人“看着结果简单、一动手就翻车”的方向之一。流量预测、销量预测、能耗预测……场景各不相同但落地前几乎都要做同一件事把历史数据切好、找一批基线模型跑通、对比各项指标。BasicTS 项目就是为了让这一连串重复劳动变得统一、可控而生的它不替你选择模型却能帮你把“数据读取—训练—评估—可视化”这条链路稳稳打通让整个分析过程回归到研究者真正关心的模型设计上。这篇入门指南适合刚接触时间序列分析的开发者也适合已经在手写训练代码、想快速搭建一套可复现基线流程的从业者。我会从环境准备、数据集构建、训练配置、结果解读几个方向展开把实际使用中踩过的坑和留下的经验一并写进来尽量让你看完就能动手跑通一个完整的时间序列预测实验。1. 项目概述与核心价值1.1 手撸时间序列训练通常死在四个地方我开始做时间序列预测时第一件事就是拿别人的仓库改数据结果发现每个仓库的“代码风格”差异极大有的把数据切分写在训练脚本里有的单独做数据集类有的直接在图神经网络模型里藏了一层归一化。每次换一个新仓库等于重新读一遍全部数据处理逻辑大量时间都花在理解“别人的习惯”上。第一个坑是数据处理的隐性假设。比如有些项目默认输入张量维度是[batch, length, channels]另一些是[length, batch, channels]一旦没注意模型跑起来不报错但输出的预测值完全是乱的。第二个坑是评估口径不统一同一批预测结果有人按每个预测步分别算 MAE有人把全部预测展平成一个整体再算一个全局 MAE两个数字差异很大拿来做模型对比很容易产生误判。第三个坑是随机性深度学习训练如果不固定种子同一个配置跑两遍指标差异可能超过 10%。第四个坑是设备差异CPU 与 GPU、不同型号 GPU 之间的浮点行为不同复现结果时会遇到微观层面的不一致。BasicTS 的价值在于把这些问题固定成默认流程统一的张量维度约定、统一的评估函数、统一的训练循环和配置入口。你不需要反复在基础设施上操心可以把精力放到模型设计和实验比较上。这也是我后来在多个预测场景中持续使用这类工具库的核心原因——让对比回归公平。1.2 它是什么不是什么BasicTS 从定位上看更像一个“时间序列预测基础工具库”。它提供数据集加载与切分、归一化、训练器、指标计算、可视化脚本等模块模型侧则保留相对简单的继承接口方便把新模型快速接入统一流程。它的命名里“基础”两个字很关键意味着它先把工程底座搭好把常用甚至琐碎的操作收敛成可复用的模块。但它不是自动机器学习平台不会帮你自动做特征工程、自动搜索结构和超参数。它也不内置成千上万种时间序列模型更不保证每种模型在任意数据集上都表现最好。把它理解成一套高度约定化的脚手架更合适脚手架本身决定施工规范具体盖成什么样的楼还得自己设计。不少初学者以为用 BasicTS 就等于“调包”其实不是。真正把项目用好恰恰需要你理解数据窗口怎么切、归一化为什么这么做、早停如何触发。工具库只是把重复流程标准化它不会替你思考业务场景。我见过太多人拿着同一个配置跑不同数据集结果指标差得离谱最后排查下来问题往往出在数据本身而不是模型。2. 环境准备与快速安装2.1 安装需要准备什么动手之前先确认两件事。第一Python 版本建议 3.8 及以上太低会导致部分依赖安装失败。第二深度学习框架版本建议与项目仓库里的 requirements 保持一致否则某些算子接口可能对不上。我通常会新建一个虚拟环境避免把系统 Python 环境搞乱这点在同时维护多个项目的人看来应该深有体会。安装方式我推荐源码安装。理由很简单这类工具库迭代较快PyPI 上发布的稳定包可能滞后从源码安装能直接阅读内部实现遇到问题可以快速定位而不是对着一段黑盒代码干瞪眼。具体步骤大致如下python -m venv venv source venv/bin/activate git clone 仓库地址 cd BasicTS pip install -e .如果你看到项目里提供了requirements.txt或environment.yml优先按官方文档安装依赖避免缺库。老实说我第一次安装时漏了某个可视化依赖训练能正常跑一到画图就报错浪费了不少时间排查。注意不要为了追求版本最新而随意升级 PyTorch 等核心依赖。时间序列模板库经常与特定框架版本耦合升级后可能触发隐藏 API 变更最常见的现象是原本能跑的配置文件突然报“字段不存在”或“算子未定义”。2.2 用内置示例任务验证安装安装完成后先别急着研究自己的数据我强烈建议先跑一个项目自带的示例任务。大多数这类模板库会提供一个 demo 配置和一份小规模示例数据通常是从某个城市流量数据里切出的子集体积小、跑得快作用就是验证整条链路没有坏。运行命令通常是python run.py --configs configs/demo_linear.yaml # 如果有多卡机器可以指定 GPU python run.py --configs configs/demo_linear.yaml --gpu 0第一次跑的时候看到终端开始打印 epoch、loss、验证指标基本就说明环境没问题。如果在这个阶段就报错多半是依赖版本问题或数据文件未下载优先看项目文档里的 Troubleshooting比自己到处搜效率高得多。我见过有人花一下午去翻社区历史帖子最后只是缺了一个pip install table就能解决的问题属实不值。我个人的习惯是在 demo 跑通之后看一眼最终输出目录里生成了什么文件通常包括 best model checkpoint、日志、结果表格。记住这些文件的位置后面换自己的数据时会频繁回来对照结构能少走不少弯路。3. 数据准备与数据集构建3.1 数据格式和目录结构时间序列预测的数据形态虽然多样但落到文件层面最常见的是二维或三维数值矩阵。二维矩阵[时间步, 特征数]适合单序列多特征场景三维矩阵[时间步, 节点数, 特征数]适合交通流、多传感器等场景。目录结构建议按下述方式组织datasets/ my_dataset/ train.npz val.npz test.npz如果没有拆分好的多个文件也可以只放一个原始数据文件由配置里的切分参数完成训练、验证、测试的划分。但无论采用哪种方式有一条原则必须守住先检查数据是否连续、是否有缺失值。时间序列对顺序极其敏感缺失值一旦简单填 0模型可能学到完全错误的模式。我埋过一个典型的坑原始数据里因为采集设备掉线出现了一段连续重复值我没做处理就直接切窗训练。结果模型在那个时段疯狂输出同一个预测值测试指标看起来不错但换到新数据完全失效。后来排查才发现是超过一整天的“重复片段”把模型带偏了。数据处理阶段宁可多花时间也不要跳过异常检测。3.2 滑动窗口、归一化与样本构建在模型眼里时间序列预测通常不是一个序列问题而是一个“给定历史窗口预测未来窗口”的监督学习问题。因此需要把长序列切成样本对。一个常见的切分逻辑如下import numpy as np def create_samples(X, input_len12, horizon3): samples, targets [], [] total len(X) for i in range(total - input_len - horizon 1): samples.append(X[i:i input_len]) targets.append(X[i input_len:i input_len horizon]) return np.stack(samples), np.stack(targets)input_len是历史窗口长度比如用过去 12 个时刻horizon是预测未来几个时刻。需要注意最后一个样本的右边界不能超过数据长度否则越界。训练时如果希望打乱样本顺序要把samples和targets一起混洗千万不要只打乱其中一个否则对应关系就错乱了。归一化方面我推荐使用 z-score原因很简单预测任务里不同特征量纲差别往往很大直接丢进模型会导致梯度更新不稳定。具体做法是用训练集的均值和标准差去标准化训练集、验证集和测试集mean X_train.mean(axis(0, 1), keepdimsTrue) std X_train.std(axis(0, 1), keepdimsTrue) X_train (X_train - mean) / (std 1e-8) X_val (X_val - mean) / (std 1e-8) X_test (X_test - mean) / (std 1e-8)关键点是验证集和测试集必须复用训练集的统计量不能在它们上面重新计算 mean 和 std。这不是代码洁癖而是防止数据泄漏的原则。测试阶段模拟的是“未知未来”的场景你不可能预先知道测试集的均值再去做归一化。在 BasicTS 这类工具库里这些操作通常已被数据集类封装你只需要在配置里指定window_size、horizon、normalizer等参数。不过理解底层逻辑能帮助你判断“报错到底是数据问题还是库的问题”。除了直接切分目标窗口还要想清楚预测目标是“直接多步”还是“滚动多步”。直接多步意味着模型一次输出未来 3 个时刻的预测滚动多步则是先预测第 1 步然后把它拼进输入窗口去预测第 2 步。两种方式各有取舍直接多步训练简单但长期预测误差可能积累滚动推理更灵活却会放大中间步骤的偏差。BasicTS 的基准流程通常会给出默认选择但我在自己的任务中会两者都跑一遍对比因为最终效果往往和数据本身的平稳性强相关。3.3 把自有数据接进来当你想换成自己的数据集时步骤可以收敛为三步。第一步把原始数据处理成连续、无 NaN 的数值矩阵并按时间顺序切成训练、验证、测试三份第二步按项目要求把文件放在datasets对应目录第三步新建一个 YAML 配置把data_root、dataset名称、window_size、horizon等字段改成自己的取值。三步里最值得提醒的是分割顺序。验证集和测试集一定要严格排在训练集之后的时间段不要随机抽样划分。随机抽样会让模型偷偷看到未来的信息训练时指标很高上线后大幅退化。时间序列领域把这件事叫“时间一致性”属于基本常识但新手很容易按照普通机器学习习惯去做随机划分。我接手过某内部流量预测任务最初版本用随机切分测试集 R² 高达 0.97部署后直接掉到 0.7 左右后来才发现是数据拆分方式出了问题。4. 模型训练与配置解析4.1 看懂一张 YAML 配置文件BasicTS 这类工具通常用 YAML 描述一次实验。一个典型的配置骨架如下data: dataset: demo_data data_root: ./datasets window_size: 12 horizon: 3 batch_size: 64 model: name: Linear input_len: 12 output_len: 3 training: epoch: 100 lr: 0.001 seed: 2024 patience: 10 device: 0 result_path: ./results/demo_linear不要被字段数量吓到真正关键的只有三类数据相关window_size、horizon、batch_size、模型相关name、输入输出维度、训练相关epoch、lr、seed、device。其他字段比如日志输出级别、学习率调度策略、是否早停通常都有默认值。命令行一般支持覆盖配置文件里的字段。我调试时经常这样用python run.py --configs configs/demo_linear.yaml --training.lr 0.003 --training.epoch 50这种“配置为主、命令行微调”的方式非常高效因为每次实验都会留下一个明确的 YAML事后可以准确还原当时跑了什么。不要靠改代码调参那样过两周连自己都不记得改过哪里。我见过一个同事在代码里硬改了一个学习率后来跑 ablation 时完全想不起来哪个实验用了哪个版本最后只能全部重跑教训很深。4.2 训练循环里到底发生了什么虽然你只需要运行一行命令但了解训练循环的逻辑会让排查问题顺畅很多。标准流程大致是读配置构建数据集和 dataloader实例化模型定义优化器和损失函数。然后每个 epoch 内完成前向传播、算 loss、反向传播、参数更新每个 epoch 结束后在验证集上评估一次当验证指标连续patience个 epoch 没有变好就早停最后保存最优 checkpoint。一条典型的训练日志长这样epoch1 lr1e-3 train_loss0.524 val_mae0.341 epoch2 lr1e-3 train_loss0.398 val_mae0.289 ... early stop at epoch50, best val_mae0.102看到 loss 在下降、验证指标在改善链路基本健康。如果训练初期 loss 就非常小要警惕是否数据泄漏或归一化出错如果 loss 一直不下降可能 lr 不合适或者模型结构有问题。此时不要急着换更复杂的模型先把线性基线调稳再逐步复杂化排查会容易很多。关于损失函数默认场景通常使用 MSE因为它对异常大误差敏感能够推动模型拟合整体形态。但如果你更在意预测的中位数表现或数据本身存在较多离群点换成 MAE 会更稳健。BasicTS 的配置里一般可以切换损失函数我自己的经验是先用 MSE 跑通再看误差分布决定是否切换。这里没有绝对正确只有合适不合适。我自己的习惯是第一轮训练不追求指标只看“链路能走通、loss 能下降”。确认没问题后再固定种子、固定 GPU把正式实验完整跑一遍。这样可以将调试阶段和正式实验分开后面汇报指标时更干净也更容易回溯。4.3 接入一个自己的简单模型BasicTS 的模型接口一般很薄。你只需要实现一个接受输入张量并返回预测张量的模块。作为入门可以先试着写一个最简化的多层感知机import torch import torch.nn as nn class SimpleMLP(nn.Module): def __init__(self, input_len, output_len, hidden64): super().__init__() self.net nn.Sequential( nn.Flatten(start_dim1), nn.Linear(input_len, hidden), nn.ReLU(), nn.Linear(hidden, output_len), ) def forward(self, x): # x 形状为 [batch, input_len, channels] x x.mean(dim-1) # 先对特征维求平均忽略多特征细节 return self.net(x)这个模型极其简单不是用来刷指标的而是帮你熟悉“注册一个模型”需要哪些步骤。在多数这类结构中你需要在模型注册表里加上register_model(SimpleMLP, SimpleMLP)之类的声明或者直接通过配置里的model.name指向你写的类。写自定义模型时最容易犯的错误是输入输出维度想当然。一定要在 forward 开头打印x.shape跑几轮确认维度符合预期再继续。否则模型可能直接报错或者更麻烦——不报错但维度被隐式变换结果一团糟。我遇到过在Linear层里写错输入维度模型前几轮居然还能跑loss 却一动不动查了很久才发现是输入被平均错了方向。5. 结果评估与可视化5.1 标准指标怎么选、怎么看模型训练完成后BasicTS 会在测试集上加载最优检查点输出一组评估指标。常用的预测指标有 MSE、MAE、MAPE 和 R²。MSE 对大误差非常敏感适合特别讨厌大幅偏差的场景MAE 更稳健是大多数对比实验里的默认指标MAPE 以百分比形式直观展示相对误差但真实值接近 0 时容易爆表R² 则可以快速判断模型是否优于“直接用均值预测”的基线。一份示意结果大致如下模型MSEMAEMAPE(%)R²线性基线0.00610.0627.80.92简单 MLP0.00580.0587.20.93看结果时不要只看指标高低还要结合业务场景判断误差是否可接受。我见过一个销量预测项目MAE 从 0.3 降到 0.28绝对值提升很小但对库存补货策略来说这个差距恰好决定了一批货要不要补。所以“指标够不够好”永远要回到业务目标去看。另外多步预测的指标还可以按 horizon 分别观察。如果第 1 步误差很小但第 3 步误差突然增大说明模型对长期依赖的建模不足。BasicTS 可能只输出一个平均结果但我会额外打印每个 horizon 上的指标这样能更清楚地看出模型在短期和长期预测上的能力边界。5.2 可视化预测曲线与误差分布指标之外强烈建议看一眼预测曲线。工具库一般会提供可视化脚本导出预测值和真实值之后可以像这样画一段简单对比import matplotlib.pyplot as plt plt.figure(figsize(10, 4)) plt.plot(true[:200], labelground truth) plt.plot(pred[:200], labelprediction) plt.legend() plt.show()如果预测曲线整体“向右平移”也就是预测值比真实值晚一拍变化大概率是模型在挪用一个滞后的解它倾向于把上一个窗口的走势搬过来而不是真正学习趋势。这种问题在强自相关的流量数据里很常见。遇到这种情况可以尝试加入差分特征、让窗口变长或者换用显式捕捉趋势的模型。误差分布也很值得看。把pred - true画成直方图如果分布明显不对称说明模型存在系统性高估或低估。此时检查训练数据里是否存在异常时间段、不均匀的样本分布往往比盲目调超参数更有效。我曾在某个数据集上看到正态的误差分布却忽视了一个细长的右尾后来发现那部分全是极端事件发生的日子。模型平均表现不错但最需要准确预测的时刻反而最差这在风控场景里是不可接受的。6. 常见问题与排查技巧实录6.1 数据维度对不上、NaN 或者 Inf这类报错是入门阶段最常见的。我在接入新数据时第一步永远是打印x.shape和y.shape确认 shape 与模型定义一致。第二检查原始数据里有没有 NaN 或 Inf。训练时 loss 突然变成 NaN十有八九是数据中混入了非法值归一化时除数为 0 也会导致这个问题。第三如果使用 z-score一定要给标准差加一个极小 epsilon如1e-8避免某列特征恒定导致除零。还有一个容易忽略的点是数据文件里的 dtype。如果从 CSV 读取时列类型不一致NumPy 会自动转成 object 类型后续计算会莫名变慢甚至报错。我会在加载后主动执行.astype(np.float32)一方面避免精度问题另一方面显存占用也更友好。6.2 模型不收敛loss 不降或乱跳loss 一直不降最常见的原因是学习率不合适其次是数据没有归一化或归一化出错。我先试lr1e-3如果 loss 稳定但下降很慢再降到1e-4如果 loss 直接爆炸成 NaN就降到1e-4甚至1e-5。loss 乱跳可能是 batch size 太小、样本顺序没打乱或者是任务本身难度不均。总之调参要一次只动一个变量否则你根本不知道是哪个动作起效。我在记录实验时习惯直接把 lr、batch size、窗口长度写进文件夹名比如exp_lr1e3_bs64_win12。这样跑完多个实验后只看目录就能快速对比出哪些参数组合更值得深入。6.3 显存不足如何减小显存占用深度学习模型在时间序列任务上的显存主要被 batch 内的长序列放大。优先减小 batch size其次缩短window_size或降低 hidden size再不行就使用梯度累积。梯度累积的意思是把一个大 batch 拆成多个小 batch 分别更新梯度累加后再执行一次参数更新。代码上并不复杂但要注意等价性并不完全严格BatchNorm 等模块的行为会因此改变。如果项目支持混合精度训练开启torch.cuda.amp也可以显著降低显存占用同时训练速度往往更快。我一般在 sequence 长度超过 512 时就直接开启混合精度因为 long sequence 在 Transformer 类模型里的显存开销是二次增长非常惊人。6.4 指标复现不了前后结果不一致复现实验需要在配置里固定随机种子并且让 Python 随机模块、NumPy、PyTorch 都使用同一个种子。在代码里一般要同时设置random.seed、np.random.seed和torch.manual_seed如果使用 CUDA还需要处理benchmark和deterministic开关。即便如此不同 GPU 上的浮点计算结果也可能存在微小差异所以追求 bit-level 复现不如固定设备、固定库版本更实际。我个人遇到过一个很隐蔽的情况第一次训练用--gpu 0第二次忘了指定--gpu结果代码默认选到了另一块 GPU模型指标出现小幅波动。后来我把设备信息直接写进输出目录名比如results/exp_20250430_gpu0这类问题才彻底避免。另外不同版本的 PyTorch 对同一个算子可能有不同的实现复现实验前最好把依赖版本也写进 requirements 或实验记录文件。最后分享一点个人的工作习惯。我在接手任何时间序列预测任务时都不会直接上复杂模型而是先用 BasicTS 这类工具库跑一个线性基线和一个小型 MLP。如果线性基线已经能到很低的 MAE说明数据本身的可预测性较强后续复杂模型提升空间有限如果线性基线惨不忍睹那要先回头检查数据质量而不是急着堆模型。遇到任何“字段不存在”或“接口变化”的问题时不要盲目去网上找老帖直接打开当前 clone 仓库下的examples或configs目录照着写一般都能解决。工具库版本迭代很快别人几年前的教程不一定还适用。把“先在自带数据跑通、再迁移自己的数据、最后才放开手脚调参”这个流程坚持下来你会发现时间序列分析的入门速度反而最快。