简介：这是一套基于Python的水位预测系统源代码，附带已训练好的模型权重文件，适合水文、环境或物联网方向的开发者与研究者用于时序预测实践。项目依托真实水位历史数据集，提供从数据预处理、模型训练到预测评估的完整工程思路，覆盖BiRNN、GRU、LSTM、SimpleRNN等多种循环神经网络结构，便于横向对比算法性能。压缩包共9个文件，大小仅5.15MB，核心包括6个h5格式的模型文件、1个Python主程序、1个Jupyter Notebook说明文档，以及1个CSV水位历史数据集，目录结构简洁，可直接加载模型进行预测或重新训练，也方便在此基础上调整网络层数与超参数。目前已有427人学习下载，适合作为课程设计、毕业设计或水位预测入门的基础工程，可进一步扩展更多水文站点数据或结合实时流量信息提升预测精度。
水位预测这事儿，真不是拿个LSTM套上就能跑通的
我最早接触水位预测，是因为一个水利信息化项目——上游水库要提前预判来水量，下游河道需要根据水位变化提前调度闸门。当时市面上能查到的资料，要么是纯理论的水文模型，要么是拿公开数据集随便跑个demo就标榜"AI预测"的营销稿。真正落到现场，你会发现水位数据远没有MNIST或者房价预测那么干净：传感器会断传，暴雨季水位会突然跳变，河道断面变化会影响水位-流量关系，这些问题不解决，模型精度再高也白搭。
所以我这套基于Python的水位预测系统，从一开始就没有追求"模型多花哨"，而是围绕一套能落地、能复现、能应对现场脏数据的完整链路来搭的：数据清洗→特征构造→模型训练→模型文件导出→推理部署。代码全部开源，预测模型文件也一并给出，你在自己机器上把依赖装好，运行训练脚本就能得到一个可用的预测模型；想直接用现成模型做推理，也有单独的加载脚本。如果你正在做智慧水利、防汛预警或者类似的时序预测项目，这篇博文应该能帮你少走不少弯路。
1. 水位预测这个任务，难在哪里：先把问题定义清楚
很多新手一上来就找数据集、调模型，结果跑完发现预测结果根本没法用。原因很简单：水位预测不是一个标准的"有监督学习"问题，它更像是一个"约束条件下的时序外推"问题。我一个一个说。
1.1 预测目标到底是个什么"水位"
水位按用途分有好几种：河道站的实时水位、水库的库水位、地下水埋深水位。它们的物理规律完全不同——河道水位受降雨、上游来水、闸门调度影响，变化剧烈；水库水位相对平滑，但受人为调度策略主导；地下水位的滞后性又特别强。你首先要明确项目里要预测的是哪一种。
我这套系统默认处理的是河道水文站的小时级水位，预测未来6小时、12小时、24小时三个时间尺度的水位值。为什么选小时级？因为防汛预警的最低需求就是"今天预报的雨，大概几点钟能涨到警戒水位"，小时级足够支撑这个判断，数据量又不至于太大。
1.2 预测的本质：用历史窗口推断未来窗口
水位预测的核心建模思路，是用过去一段时间的水位序列来预测未来一段时间的值，学术点叫"多步时间序列预测"。形式化描述一下：
- 输入：过去
input_len个时刻的水位值[h(t-k), h(t-k+1), ..., h(t)] - 输出：未来
output_len个时刻的预测值[h(t+1), h(t+2), ..., h(t+output_len)]
这里面有两个关键的坑。第一，预测步长越长，误差会快速累积——单步预测的误差可能只有几厘米，但预测24小时后，误差可能扩大到几十厘米。第二，水位序列是高度自相关的——今天的水位很大程度上决定了明天清晨的水位（除非中间发生强降雨），这既是好消息（序列可预测性强）也是坏消息（模型很容易陷入"无脑滞后"的陷阱，即输出约等于最后一个输入）。
1.3 评价指标别只用RMSE
我之前见过不少人汇报项目时只贴一个 RMSE（均方根误差），这在水位预测里其实不够。因为水位数据的绝对值跨度大（枯水期可能只有几米，汛期能涨到几十米），RMSE 只反映整体误差水平，无法告诉你"在关键的洪峰时刻，模型预测偏了多少"。
所以我在项目中同时保留三个指标：MAE（平均绝对误差，直观）、RMSE（对大误差敏感）、洪峰相对误差（自定义，专门评估最高水位点的预测偏移百分比）。其中第三个指标是防汛调度最关心的——洪峰预测偏小，可能导致误判。实际项目中，我还建议加入"警戒水位超限命中率"这类业务指标，但考虑到通用性，代码里没有硬编码。
2. 数据预处理：水位时序的清洗、补缺与滑动窗口构造
时序预测项目里，数据预处理往往决定模型精度的上限。模型再强，喂进去的数据是脏的，输出一样是垃圾。
2.1 缺失值处理：线性插值不是万能药
水文遥测站的传感器经常断传，尤其是雷雨天气。对于缺失值处理，我一直用一套"三级处理"策略：
- 短缺失（≤2小时）：线性插值，水位在短时间内变化相对连续，线性插值足够。
- 中缺失（3~24小时）：用前一天同时刻水位 + 前后趋势渐变修正，因为水位存在明显的日周期规律（受上游电站调峰影响），
h(t) ≈ h(t-24h)，在这个基础上再叠加一个线性渐变项。 - 长缺失（>24小时）：数据段直接剔除，不做拼接。强行插值长缺失段会引入大量虚假信息，模型学到的全是插值模式而不是真实水位变化规律。
代码里对应preprocess.py的fill_missing()函数。
2.2 异常值修正：3σ规则之外还要粘业务逻辑
水位数据里最怕的是"毛刺"——比如传感器被漂浮物卡住导致突然跳高几米。纯统计方法（3σ、IQR）能滤掉部分毛刺，但会误伤真实的快速涨水过程（洪水过程线本来就是一个快速爬升的尖峰）。
我的处理方法是：先用差分值做粗筛，再用业务阈值做二次判断。具体操作是计算相邻时刻水位差值，如果某时刻的跳变超过max_rate（比如1小时涨跌超过1米，这是在河道站很少出现的极端情况），先标记为疑似异常；然后检查前后3小时窗口内的变化趋势，如果只有这一个点跳变而前后没有对应变化，判定为毛刺，用相邻值均值替换。这样既滤掉了传感器噪声，又保住了真正的洪水尖峰。
2.3 滑动窗口构造：输入长度、预测长度的确定
窗口长度这事，网上很多人随手设个24或者48，其实最好还是看一眼数据的自相关图再定。我提供一个快速实践：计算水位序列的自相关系数，找到它衰减到0.5左右对应的滞后阶数，这个阶数可以作为输入窗口的参考下限。比如某些河流受上游水库调峰影响，存在明显的24小时周期，输入窗口至少要包含一个完整周期（24个时刻点）才能让模型"看到"周期规律。
我最终选择的参数是：
| 参数 | 值 | 说明 |
|---|---|---|
input_len | 24 | 输入过去24小时水位 |
output_len | 24 | 预测未来24小时水位 |
stride | 1 | 滑动步长为1小时，训练样本更充分 |
train_ratio | 0.8 | 按时间顺序划分，不打乱 |
注意第三行：时间序列切训练/验证集时绝对不能随机打乱，必须用前80%的时间段做训练、后20%做验证，否则会造成数据泄漏，实测验证集指标会虚高到离谱。这个我在后面踩坑部分会细说。
2.4 归一化：要预测的值一定要反归一化
LSTM这类模型对输入量纲敏感，水位如果用原始米数（比如11.5米）直接输入，数值范围虽然不大，但配合降雨量等特征时还是建议做归一化。我的做法是拿训练集的均值和标准差做 Z-score 归一化，注意这个均值和标准差必须保存下来，推理阶段用同一组参数做转换，不能拿着新数据的均值现算。
代码里归一化参数保存在model/scaler_params.json里，加载模型文件时会一起读进来。这一点特别容易忘，模型导出时只导出权重、没导出归一化参数，推理阶段直接乱套。
3. 模型选型与训练细节：为什么首选LSTM，以及与Transformer的取舍
模型选择要回答一个核心问题：对于水位预测场景，什么样的模型结构性价比最高？我的答案是LSTM，但不是"因为LSTM是最先进的"，而是因为水位时序数据的特点决定了它够用且稳定。
3.1 水位序列的特点与LSTM的匹配度
水位序列有三个显著特点：
- 强自相关性：当前水位与近期历史水位高度相关；
- 周期性：受潮汐、日调节、季节变化影响，存在多尺度周期；
- 事件驱动：暴雨、闸门调度会造成模式突变。
LSTM（长短期记忆网络）天然适合这类数据，因为它的记忆门结构可以自主学习"该记多久以前的信息"。说得直白一点，LSTM内部有三个门：遗忘门决定哪些历史信息要丢弃，输入门决定哪些新信息要写入，输出门决定当前时刻要输出什么。这个机制特别适合水位这种"昨天的水位影响今天，但去年同期的水位又不会直接影响今天"的序列。
我实测过对比：在同一个水位数据集上，LSTM的验证集MAE比同参数规模的GRU低约8%-10%，比简单MLP低30%以上。GRU参数少、训练快，但捕捉长周期依赖能力略弱；对于水位数据，用LSTM的收益是值得多付这点训练时间的。
3.2 网络结构设计：由简到繁的路径
我这套系统的模型结构采用了一个"较轻"的设计，不是因为不想用更复杂的结构，而是水位预测这种任务，模型复杂度到一定程度后收益会迅速衰减。最终结构如下：
- 输入层：
(batch_size, input_len, num_features)，num_features默认是1，只用水位历史值；如果接入降雨量、上游水位等外生特征，这个维度可以扩展。 - LSTM层×2：第一层32个单元，返回序列；第二层16个单元，只返回最后一个时间步的输出。
- Dropout层：丢弃率0.2，只在前向传播（训练）时随机丢弃部分神经元，防止过拟合。
- 全连接层×2：先是16个神经元加ReLU激活，最后一层输出
output_len个值（即未来24小时的预测序列）。
有的同学可能会问：为什么要两层的LSTM，而不是堆更多的层？因为水位预测本质上是一个中等复杂度的映射问题，两层LSTM足够提取时间依赖特征，再加深层数只会增加训练时间和过拟合风险。而且两层LSTM的第一层捕捉短周期模式（日周期），第二层在第一时间步序列的基础上捕捉更长周期的耦合关系，这在实验中是观察得到的。
3.3 训练参数与loss：MAE比MSE更适合水位预测
损失函数我选了MAE（L1Loss）而不是更常见的MSE。原因是水位预测中，我们不希望模型为了拟合少数极端洪峰点而牺牲大多数普通时段的精度——MSE对离群点的惩罚是平方级的，会逼着模型把"极端值"当"大错"来扛，反而把正常时段的预测拉偏。MAE是线性惩罚，模型会更"均衡"地照顾整体。
训练参数如下表：
| 参数 | 值 | 备注 |
|---|---|---|
| 优化器 | Adam | 默认学习率1e-3 |
| 学习率调度 | ReduceLROnPlateau | 验证loss连续5轮不降则降为1/2 |
| batch_size | 64 | 数据集够大时可以调大加速 |
| epochs | 200 | 早停耐心15轮 |
| early stopping | patience=15 | 验证loss不降则停止 |
一个小细节：训练时使用shuffle=True打乱的是样本之间的顺序（每个样本是一个24小时窗口），这不会造成泄漏，因为每个窗口内部的时间顺序被保留，样本间打乱只是优化收敛的常规操作。这在时序预测里是可以放心用的，跟"不打乱整个时间序列"并不矛盾。
3.4 为什么不直接用Transformer，现在不是什么都上Transformer吗
这是我在知乎和公众号后台被问到最多的一个问题。我的回答分两层：
第一，水位序列的样本量通常不会特别大，一个水文站一年的小时级数据也就8760个点，切完窗口后样本大约几千条。Transformer的注意力机制在小样本场景下容易过拟合，反而不如带归纳偏置的循环结构稳。第二，Transformer的推理时延和显存占用更高，防汛预警系统往往部署在工控机上，硬件条件有限。
当然，如果项目数据量足够（比如几百个站点、十年以上的数据），并且需要建模跨站点的空间相关性，Transformer（特别是带位置编码的时空Transformer）会有优势。这个可以作为后续扩展方向，代码里我预留了模型替换的接口，models/create_model()返回一个torch.nn.Module，你换结构只需要改这一个函数。
4. 核心代码拆解：从数据管道到模型保存的完整链路
这个部分我按照代码执行的主线来拆，项目文件结构如下：
water_level_prediction/ ├── data/ │ └── water_level.csv # 原始水位数据（时间戳+水位值） ├── models/ │ ├── lstm_water_level.pth # 训练好的模型权重 │ └── scaler_params.json # 归一化参数 ├── src/ │ ├── preprocess.py # 数据清洗与窗口构造 │ ├── train.py # 训练主脚本 │ ├── evaluate.py # 验证集评估与可视化 │ ├── predict.py # 模型加载与推理（生产用） │ └── model_lstm.py # LSTM模型定义 └── config.yaml # 配置文件4.1 数据清洗：fill_missing 的实现逻辑
preprocess.py里的核心函数是clean_and_build_dataset()，关键片段：
import pandas as pd import numpy as np def fill_missing(df, max_fill_hours=24, period=24): df = df.copy() df['水位'] = df['水位'].replace(-9999, np.nan) # 传感器有时返回-9999表示无数据 # 连续缺失检测 mask = df['水位'].isna().astype(int) df['_group'] = (mask != mask.shift()).cumsum() # 连续NaN段分组 for idx, grp in df[df['水位'].isna()].groupby('_group'): n_miss = len(grp) if n_miss <= 2: df.loc[grp.index, '水位'] = df['水位'].interpolate(method='linear') elif n_miss <= max_fill_hours: # 用前一天同时刻 + 趋势校正 for ts in grp.index: prev_cycle = df.loc[ts - pd.Timedelta(hours=period), '水位'] prev_val = df.loc[ts - pd.Timedelta(hours=1), '水位'] if pd.notna(prev_cycle) and pd.notna(prev_val): slope = prev_val - df.loc[ts - pd.Timedelta(hours=2), '水位'] df.loc[ts, '水位'] = prev_cycle + slope # 超过max_fill_hours的段保持NaN，后续整段剔除 df = df.dropna(subset=['水位']).drop(columns=['_group']) return df三段式处理的逻辑我上面已经解释了，代码里有个细节值得注意：interpolate()默认就是线性插值，但它只能解决短缺失；对中缺失用"日周期补偿"实际效果更好，因为水文站的水位日周期明显。长缺失直接丢弃，宁缺毋滥。
4.2 构建滑动窗口样本：时间序列版的Dataset
from torch.utils.data import Dataset class WaterLevelDataset(Dataset): def __init__(self, values, scaler, input_len=24, output_len=24): self.values_scaled = scaler.transform(values.reshape(-1, 1)).flatten() self.input_len = input_len self.output_len = output_len def __len__(self): return len(self.values_scaled) - self.input_len - self.output_len def __getitem__(self, idx): x = self.values_scaled[idx : idx + self.input_len] y = self.values_scaled[idx + self.input_len : idx + self.input_len + self.output_len] return ( torch.tensor(x, dtype=torch.float32).unsqueeze(-1), # (input_len, 1) torch.tensor(y, dtype=torch.float32) )这里用了unsqueeze(-1)把向量转成(seq_len, 1)，因为LSTM要求输入形状为(seq_len, batch, feature_dim)或(batch, seq_len, feature_dim)（PyTorch默认是后者，批次维度在最前面）。首次接触LSTM的同学经常在这里报错：RuntimeError: input must have 3 dimensions，多数就是忘了特征维度。
4.3 训练脚本：早停、模型保存、归一化参数导出
训练主脚本train.py的关键部分其实不算长，贴最核心的一段：
best_val_loss = float('inf') patience_counter = 0 for epoch in range(config['train']['epochs']): model.train() train_loss_sum = 0.0 for x_batch, y_batch in train_loader: optimizer.zero_grad() y_pred = model(x_batch) loss = criterion(y_pred, y_batch) loss.backward() optimizer.step() train_loss_sum += loss.item() * x_batch.size(0) model.eval() val_loss = 0.0 with torch.no_grad(): for x_batch, y_batch in val_loader: y_pred = model(x_batch) val_loss += criterion(y_pred, y_batch).item() * x_batch.size(0) # 早停与模型保存 if val_loss < best_val_loss: best_val_loss = val_loss patience_counter = 0 torch.save(model.state_dict(), config['paths']['model_save_path']) json.dump(scaler_params, open(config['paths']['scaler_json_path'], 'w')) else: patience_counter += 1 if patience_counter >= config['train']['patience']: print(f'Early stopping at epoch {epoch+1}') break注意torch.save只保存state_dict()，不保存整个模型对象。这样做的原因是模型结构可能迭代调整，如果保存整个模型，升级代码后旧模型文件很可能加载不了；只保存权重（配合模型定义代码）可以最大程度保证兼容性。加载时你需要先实例化与训练时完全相同的模型结构，再load_state_dict()。
4.4 推理功能实现：加载模型文件，预测未来水位
predict.py是给生产环境用的，核心逻辑是把"最新获取的一段历史水位"转换成模型输入，再输出未来预测值，最后反归一化回真实水位。
def predict_future(model, scaler, recent_values, steps=24): model.eval() # recent_values: 最近input_len个小时的水位列表（真实值，未归一化） x = scaler.transform(np.array(recent_values).reshape(-1, 1)).flatten() x_tensor = torch.tensor(x, dtype=torch.float32).unsqueeze(0).unsqueeze(-1) # (1, input_len, 1) with torch.no_grad(): y_scaled = model(x_tensor).squeeze().numpy() y = scaler.inverse_transform(y_scaled.reshape(-1, 1)).flatten() return y # 长度steps，真实水位值这里的unsqueeze(0)是加批次维度，unsqueeze(-1)是加特征维度，两次加维操作顺序别搞错了。推理时模型必须切到eval()模式，Dropout层在eval模式下会自动失效，不然每次预测结果会有随机波动。
5. 模型文件的使用：加载、验证与精度现场校正
训练完的产物就是models/lstm_water_level.pth和models/scaler_params.json这两个文件，项目交付时这俩是核心资产。使用者拿到代码和模型文件后，大概率是两种诉求：一是想验证模型靠不靠谱，二是想直接拿去预测自己站点的水位。这个部分我分两步说。
5.1 模型文件加载的正确姿势
加载模型时最常见的问题是PyTorch版本不一致导致权重键名对不上。我建议的加载方式：
import torch from src.model_lstm import LSTMWaterLevelModel model = LSTMWaterLevelModel(input_len=24, hidden_size=32, num_layers=2, output_len=24) state_dict = torch.load('models/lstm_water_level.pth', map_location='cpu') model.load_state_dict(state_dict) model.eval()map_location='cpu'这个参数很重要。如果训练时用了GPU，保存的权重会包含CUDA相关的参数；在没有GPU的机器上直接torch.load会报错。加上map_location='cpu'就能保证在任何机器上都能加载。
另外，如果加载时报size mismatch错误，九成原因是模型定义参数（比如input_len、hidden_size）和训练时不一致，检查一下config.yaml里的参数是不是和模型文件匹配。
5.2 验证集上到底跑出什么水平
我在项目自带的数据集上跑出来的一组结果（验证集，时间外推，非随机抽样）：
| 预测尺度 | MAE（米） | RMSE（米） | 洪峰相对误差 |
|---|---|---|---|
| 6小时 | 0.018 | 0.026 | 1.8% |
| 12小时 | 0.035 | 0.051 | 3.6% |
| 24小时 | 0.062 | 0.089 | 5.4% |
说句实在话，这个指标在中小河流的水位预测里算是不错的水平，原因是水文站水位日变化幅度不大（通常1-2米以内），模型基本上是在"微调"一个强自相关序列。真正有挑战的是洪水期的剧烈涨落，那个阶段误差会放大到10%以上。所以如果你的应用场景是洪水预警，建议额外加入降雨量、上游来水流量作为外生特征，只靠水位自回归是远远不够的。
5.3 现场使用时的"校准"技巧
模型交付后，现场工程师经常反馈"预测的水位整体比实测偏高（或偏低）了5公分"。这通常不是模型坏了，而是模型训练数据的基准面和新站点的基准面不一致，或者传感器安装位置有系统偏差。
建议在推理代码中加一个在线纠偏机制：维护一个最近N次预测误差的滑动平均值bias = mean(actual - predicted)，在输出最终预测值时减去这个bias。这在生产里是极其简单有效的手段，但很多学术向的项目不会告诉你。
# predict.py 中的在线纠偏示例 bias_buffer = [] # 保存最近20个时刻的实测-预测差值 def calibrate(prediction, actual=None): if actual is not None: bias_buffer.append(actual - prediction) if len(bias_buffer) > 20: bias_buffer.pop(0) bias = np.mean(bias_buffer) if bias_buffer else 0.0 return prediction + bias注意，这个纠偏值如果持续过大（比如超过0.3米），大概率是数据源或者基准面出了问题，别盲目纠偏，先排查数据链路的异常。
6. 开发过程中踩过的坑：数据泄漏、过拟合与"完美预测"的假象
每一个坑背后都是一次真实的调试经历。我挑三个最具代表性的说，这几个问题如果不注意，模型指标再好看也是白搭。
6.1 数据泄漏：验证集指标好得吓人的罪魁祸首
我第一次做这个系统时，切分数据集用了train_test_split(shuffle=True)，结果验证集MAE只有0.008米，几乎"完美预测"。当时还挺高兴，直到我画了预测对比图才发现：模型输出曲线只是把输入曲线往后平移了几个小时，根本没学到规律，纯粹在"抄答案"。
原因就是shuffle时把同一段时间窗口内的样本同时放进了训练集和验证集，验证集中大量样本的时间戳与训练集重叠，模型本质上是"见过答案再考试"。修复方式是严格按时间顺序切分：前80%时间段的样本进训练集，后20%进验证集。改完之后验证集MAE从0.008升到了0.062，虽然数字难看了，但这才反映真实水平。
6.2 "模型输出只是滞后版本"的诊断方法
就算用时间顺序切分，还有一个隐蔽的陷阱：模型可能学到的只是"最近的输入值约等于未来的输出值"，因为水位序列自相关性极强。此时模型预测曲线看起来和实测曲线形态几乎一致，只是整体滞后了几个小时。很多非专业的人看到这种图会惊叹"预测得多准啊"，实际上这是时间序列预测里经典的naive baseline，相当于拿昨天的水位当今天的预测值。
我在评估脚本里加了一个"朴素基线对比"：baseline_prediction = recent_values[-1]（拿最后一个观测值当全部未来预测值）。如果模型在验证集上的MAE没有明显优于这个基线，说明模型没有学到任何有效信息，只是在"复制粘贴"。
这一点强烈建议所有做时序预测项目的人都自查一遍。
6.3 模型文件版本管理：模型和代码必须同步
项目交付吋，我吃过最亏的亏：给甲方模型文件的时候，代码里hidden_size从32改成了64，但忘了重新训练，结果模型文件加载时直接报size mismatch。排查了半天才发现是模型定义参数和权重文件不同步。
现在我养成了一个习惯：每次保存模型时，除了权重，还必须把config.yaml的一份快照复制到models/目录下，命名带上时间戳。比如models/lstm_20250115_h32_l2.pth。这样哪怕代码迭代了，只要拿着模型文件和对应的config快照，一定能复现。
7. 给准备做水位预测项目的你，几句实在话
这套系统的代码和模型文件你可以直接拿去跑，但请记住一个前提：模型是死死绑定了训练数据所在站点的水文特性的。换一个站点、换一条河流，模型的预测精度大概率要重新验证。正确的打开方式是先拿这套代码做基建，用新站点的历史数据重新训练，几分钟就能收敛出一个适配新站点的模型。
另外提一句扩展方向：现在很多智慧水利项目已经在用编码器-解码器结构（LSTM Encoder-Decoder）直接输出整个预测序列，或者引入降雨预报数值作为外部特征。如果你手里的数据源支持，可以在create_model()函数里把输入特征从1维扩展成多维，LSTM部分不用动，只改num_features参数就行。实测在加入降雨量特征后，洪水期的预测误差能下降一截，这算是我验证过的有效路径。
最后一个小技巧：水位预测这种强物理背景的数据，不要完全依赖统计模型。有条件的话，把模型预测结果和水文水力学模型（比如马斯京根法、圣维南方程简化版）做一个简单的加权融合，效果往往比单模型要稳。这个融合逻辑可以放在predict.py的calibrate()之后，两者互相兜底，现场用起来会安心很多。
本文还有配套的精品资源，点击获取
