简介面向水文预测学习与实践的Python项目包围绕水位时序预测任务整理源代码、训练数据与多类循环神经网络模型文件适合具备Python基础的学生、课程设计或毕业设计开发者以及希望对比RNN、LSTM、GRU、BiRNN等模型效果的算法入门者。压缩包共9个文件约5.15MB包含1个py源码、1个ipynb交互式笔记本、1个csv水位数据文件和6个h5模型文件其中h5模型覆盖简单循环网络、LSTM变体、GRU与双向RNN等结构便于直接加载复现预测流程。已有448人学习下载可作为时序建模的完整小样本案例。读者可据此梳理数据读取、特征处理、模型训练与结果评估环节并通过替换数据或调整网络结构开展对照实验积累水位预测项目的排错与调参经验。1. 水位预测系统源码拆包一份能训能跑的 Python 预测模型长什么样凌晨两点某水文站的值班员盯着屏幕等未来 24 小时的水位曲线而你手里只有一份基于 Python 的水位预测系统源代码和一个已经训练好的预测模型文件。这类资源的价值不在代码行数而在于它把数据清洗、特征构造、模型训练、推理输出这条链路完整串起来了拿到手能先把流程跑通再把自己的站点数据替换进去。它适合三类人做水利信息化、需要快速搭原型的开发者手上有几年历史水位序列、想验证 LSTM 或 ARIMA 到底能压到多少误差的数据分析人员以及要把预测结果接进现有业务系统的后端工程师。翻车点通常不在模型本身而在数据对齐和模型文件加载这两步后面几章会逐个拆开。2. 数据接入与特征工程水位序列的缺失值、周期项与滑窗怎么搭拿到源码包先别急着跑train.py。水位预测模型对输入序列的形态极其敏感同一份 LSTM 代码特征工程做错和做对验证集 RMSE 能差出一倍。我一般会先把原始数据画出来看清楚它到底由哪几层结构叠在一起再决定怎么造特征。2.1 先认清水位序列的三类结构水文站的水位序列不是一条干净的正弦波它至少由三部分叠加第一是季节性趋势汛期和枯水期水位基线完全不同北方河流尤其明显同一套权重在 7 月和 1 月表现会差很远第二是短周期受潮汐影响的河段有半日和全日周期受水库调度影响的站点有固定的日调节节律第三是随机扰动主要来自降雨径流和上游来水这部分才是模型真正难拟合的。这三类结构决定了特征怎么造季节性靠时间编码月份、年内天数或分段建模解决短周期靠 sin/cos 时间特征和滞后项解决随机扰动只能靠滑动窗口把近期变化趋势喂给模型。如果只把原始水位序列一股脑塞进 LSTM模型会把季节性和短期波动混在一个隐状态里学结果就是汛期整体偏高、枯水期整体偏低误差看着不大但曲线形状全歪了。源码包里通常有一个features.py或类似的模块负责把单列水位变成监督学习样本。先确认它有没有做时间编码没有的话自己补上这是性价比最高的一步。2.2 缺失值与异常值的处理顺序真实水位数据没有不缺的。传感器掉线、通讯中断、设备检修都会造成整段连续缺失单点跳变则多半是信号干扰或短时淤积。处理顺序必须是先标异常、再插值反过来的话插值会把异常点抹平后面就再也找不回来了。连续缺失的处理要看长度。缺 1 到 2 个点线性插值或前后向填充都行缺半天到一天可以用同时段的历史均值做参考填充缺超过三天我的做法是不插值直接在该位置加一个缺失指示列或者把这段切掉让模型在训练时跳过。硬插一段常数进去模型会学出一个虚假的平稳段预测时遇到类似形态就往外推错。异常值判断我用两条线一条是物理上下界水位不可能低于河底高程、也不可能超过警戒线太多超出直接标异常另一条是统计线对一阶差分做 3σ 或 IQR 检验差分突变往往对应跳变。两条线都过不了的才处理避免把真实的洪峰削掉——洪峰恰恰是水位预测最该保住的部分。import pandas as pd import numpy as np def clean_water_level(df, collevel, low_boundNone, high_boundNone): 清洗单站水位序列返回带异常标记的 DataFrame s df[col].astype(float) # 1) 物理上下界超出范围直接置为 NaN后续统一插值 if low_bound is not None: s s.where(s low_bound, np.nan) if high_bound is not None: s s.where(s high_bound, np.nan) # 2) 一阶差分做 IQR 检验找出单点跳变 diff s.diff() q1, q3 diff.quantile(0.25), diff.quantile(0.75) iqr q3 - q1 jump (diff q1 - 3 * iqr) | (diff q3 3 * iqr) df[is_outlier] jump.fillna(False) s s.mask(jump, np.nan) # 3) 标记连续缺失段长度长缺失不硬插 na_group (s.isna() ! s.isna().shift()).cumsum() na_len s.isna().groupby(na_group).transform(sum) df[na_run] na_len.where(s.isna(), 0) # 4) 短缺失线性插值长缺失保持 NaN 交给下游截断 short_gap s.isna() (df[na_run] 3) s s.interpolate(methodlinear, limit_directionboth).where(~short_gap | s.notna(), np.nan) # 说明limit3 控制插值跨度超过三个点的缺失沿用 NaN df[col] s return df这段函数的逻辑是分层清洗先削掉物理上不可能的读数再用差分 IQR 抓跳变最后只对短缺失插值。low_bound和high_bound按站点实测范围填一般取历史最低减 0.5 米、历史最高加 1 米limit参数控制插值最大跨度填 3 意味着超过三个连续缺失点的段不插下游按缺失段切开训练。参数别照抄先看自己数据的采样频率日尺度数据limit3偏保守小时尺度可以放到 6。2.3 滑窗样本与时间编码的构造监督学习样本的构造方式决定了模型能看到多少历史信息。水位预测常用滑窗用过去 N 个时刻的观测预测未来 M 个时刻的值。N 一般取 24 到 72取决于你的采样粒度和预见期要求M 取 1 是单步预测取 6 或 24 是短期多步预测。N 太小模型看不到完整周期N 太大训练样本数锐减而且 LSTM 对过长序列的记忆衰减很明显。时间编码不能省。月份做 sin/cos 变换保留周期性年内天数同理小时尺度数据再加一日内小时编码。直接把月份当数值 1 到 12 喂进去模型会以为 12 月和 1 月相隔很远实际上它们是相邻的枯水段。sin/cos 编码把周期映射到单位圆上距离关系就对了。如果站点受上游水库调度影响还可以把上游站水位或下泄流量作为外生特征拼进窗口。这类多变量输入在源码包里通常留了接口feature_cols列表里加字段即可但要注意外生特征本身也得做同样的清洗和归一化否则漏一个 NaN 进去整个窗口就废了。2.4 归一化的位置很关键归一化不是可有可无的装饰。LSTM 对输入尺度敏感水位原始值在不同站点从几米到几十米不等不归一化的话梯度更新会被大数值主导。常用做法是 MinMaxScaler 把训练集水位缩到 0 到 1 区间测试和推理时用同一套 scaler 参数变换。这里有个必须强调的顺序scaler 只能在训练集上fit然后用transform处理验证集、测试集和线上输入。如果在全量数据上 fit测试集的信息就泄漏进训练过程了评估指标会虚高上线后误差突然变大。源码包里如果没把 scaler 单独保存成文件一定要补上模型文件和 scaler 必须配对使用缺一个推理结果就是错的。注意外生特征流量、降雨、上游水位要各自独立 fit 一个 scaler水位和流量的量纲差几个数量级混在一个 scaler 里会把水位的相对变化压扁。3. 模型选型与训练从 ARIMA 基线到 LSTM 的水位预测模型落地模型文件不是凭空来的得先知道它是怎么训出来的才不会在推理阶段被输入格式坑住。这类系统通常以 LSTM 为主模型但合格的实现一定会先跑一个简单基线用基线误差判断深度模型到底有没有带来增益。3.1 为什么先用基线再用深度模型在水位预测里基线不是走过场。最朴素的 persistence 基线——直接用当前时刻水位当下一时刻预测——在预见期很短时误差可能低得惊人因为水位变化是连续且缓慢的。如果 LSTM 连这个基线都打不过问题不在模型复杂度而在特征或数据对齐。第二档基线是 ARIMA 或季节性 ARIMA用 statsmodels 几行代码就能跑。它对线性自相关结构建模很稳适合平稳或近似平稳的序列段但对汛期突变的响应慢长期预测容易回到均值。第三档才是 LSTM 或 GRU优势在于能吃多变量输入、能拟合非线性关系。我的习惯是先跑 persistence 和 SARIMA把 RMSE 记下来当标尺再上 LSTM。如果 LSTM 的提升低于 10%先别调网络层数回头查特征工程大概率是滑窗跨越了汛枯转换边界或者归一化泄漏。这个顺序在源码包里不一定写死但训练脚本里通常会留一个baseline.py跑一遍能省很多盲调时间。XGBoost 或 LightGBM 也是可选项把滑窗展平成特征向量喂进去训练快、可解释性比 LSTM 好适合样本量不大的站点。3.2 LSTM 网络结构与训练配置结构不用堆太深。水位序列的样本量通常只有几千到几万条两层 LSTM 加 dropout 已经够用再深就是过拟合的重灾区。我一般这么搭第一层 LSTM 64 或 128 个单元、return_sequencesTrue把序列传给下一层第二层 LSTM 32 或 64 个单元、只返回最后一步接 dropout 0.2 到 0.3最后 Dense 输出预见期长度。损失函数选 MSE 是最常见的默认但它对峰值不敏感洪峰段会被平滑掉。如果业务更在意峰值可以换 MAE 或 Huber或者在 MSE 上给高水位样本加权。优化器用 Adam学习率 1e-3 起步配 ReduceLROnPlateau 在验证损失停滞时降一半。早停 patience 设 10 到 20 个 epoch恢复最佳权重。批次大小 32 或 64 都行取决于显存和样本量。训练轮数不用预设太多靠早停截断。验证集必须按时间切不能用随机切分——随机切分会让模型在训练时见过未来形态验证指标好看但没意义。这是时间序列任务最经典的一课。from tensorflow.keras.models import Sequential from tensorflow.keras.layers import LSTM, Dense, Dropout from tensorflow.keras.callbacks import EarlyStopping, ReduceLROnPlateau def build_lstm(window_size, n_features, horizon): window_size: 回看步数; n_features: 特征列数; horizon: 预见期步数 model Sequential([ LSTM(64, return_sequencesTrue, input_shape(window_size, n_features)), Dropout(0.2), LSTM(32, return_sequencesFalse), Dropout(0.2), Dense(horizon) # 直接输出多步避免递归累积误差 ]) model.compile(optimizeradam, lossmse, metrics[mae]) return model callbacks [ EarlyStopping(monitorval_loss, patience15, restore_best_weightsTrue), ReduceLROnPlateau(monitorval_loss, factor0.5, patience5, min_lr1e-5), ] model build_lstm(window_size48, n_features4, horizon24) history model.fit( X_train, y_train, validation_data(X_val, y_val), # 验证集按时间在后 20% 切 epochs200, batch_size64, callbackscallbacks, verbose1, )网络部分的参数含义window_size48表示回看 48 个时间步小时数据就是两天n_features4对应水位、流量、降雨、时间编码四列horizon24是直接输出未来 24 步用多输出结构替代递归预测能显著减少误差累积。Dropout(0.2)放在两层 LSTM 之后防止隐状态记忆训练集噪声。早停patience15和降学习率patience5是配合用的先降学习率再早停避免学习率还没调到位就被截断。3.3 训练脚本与模型文件保存训练完别只存权重。推理时需要三样东西对齐模型结构、权重、scaler 参数。常见做法是保存完整模型.h5或.keras同时把 scaler 用 joblib 或 pickle 单独存一份文件名带版本号或训练日期避免新旧模型混用。如果源码包里只有权重文件没有结构定义加载时就得在代码里重建网络这时网络层参数必须和训练时一字不差改一个单元数就报形状不匹配。保存路径我一般按models/lstm_water_level_v1.h5和models/scaler_water_level_v1.pkl成对命名配置文件里写清楚当前生效的版本。别用model_final.h5这种名字过两周你自己都分不清 final 是第几版。提示训练日志里的验证损失曲线建议留下来后面排查“线上误差比离线大”时第一件事就是比对线上输入的分布和训练集验证段是否一致。4. 预测模型文件加载与推理接口、输入输出与批量预测怎么接模型文件能加载不代表能预测。推理阶段最常见的故障是输入形状对不上、归一化参数没接上、输出没反归一化三条里中任意一条返回的数字都毫无意义。4.1 模型加载与 scaler 配对加载时先把 scaler 读进来确认它的n_features_in_和模型输入特征数一致。Keras 的load_model对自定义层敏感如果源码包里用了自定义激活或损失加载时要通过custom_objects传进去否则会报 unknown layer。用标准 LSTM 加 Dense 的结构没这个问题但换成带注意力层的实现就要留意。scalers 我建议存成一个字典key 是特征名value 是对应的 scaler 对象一起打包成 pkl。推理时按特征名取比按位置取稳后面加特征也不用改索引。加载完先做一次自检拿训练集最后一段输入跑一遍输出应该和训练时的验证预测对得上对不上说明 scaler 或特征顺序有问题。4.2 单步与多步预测的实现差别单步预测每次只输出下一个时刻要用递归方式往前推把预测值拼回输入窗口、去掉最老的一步、再喂进去。这种方式实现简单但误差会随步数累积推到 24 步时曲线容易发散或趋于平缓。多步直接输出在训练时就学好了多输出映射推理一次拿到整个预见期误差不累积代价是模型输出层维度固定改预见期要重训。源码包如果是多输出结构推理时输入一个窗口就能拿到整段结果注意输出数组的形状是(batch, horizon)别把 horizon 当成特征维度处理。两种方式的选择标准很简单预见期短于 6 步用递归也行长于 12 步优先多输出。推理前还要校验输入窗口的完整性。缺值、长度不足 window_size、特征列顺序错位这几种情况都应该在进入模型前拦掉并返回明确错误而不是让模型输出一个看似正常的数字。4.3 包一层 HTTP 接口给业务用业务系统不会直接调 Python 函数包一层轻量接口最省事。Flask 够用接口设计成接收一个时间窗口的观测数组返回预见期水位数组同时带上模型版本和输入校验结果。响应里把单位、时间戳、版本号都写清楚下游对账时能少吵很多架。from flask import Flask, request, jsonify import numpy as np import joblib from tensorflow.keras.models import load_model app Flask(__name__) MODEL load_model(models/lstm_water_level_v1.h5, compileFalse) SCALERS joblib.load(models/scaler_water_level_v1.pkl) WINDOW 48 FEATURES [level, flow, rain, hour_sin] app.route(/predict, methods[POST]) def predict(): payload request.get_json() seq np.array(payload[sequence], dtypefloat) # shape: (T, len(FEATURES)) if seq.shape[0] WINDOW or seq.shape[1] ! len(FEATURES): return jsonify({error: fneed {WINDOW} steps x {len(FEATURES)} features}), 400 if np.isnan(seq).any(): return jsonify({error: input contains NaN}), 400 window seq[-WINDOW:] scaled np.column_stack([ SCALERS[f].transform(window[:, i].reshape(-1, 1)).ravel() for i, f in enumerate(FEATURES) ]) pred MODEL.predict(scaled.reshape(1, WINDOW, len(FEATURES)), verbose0) # 反归一化只对水位列做其他特征不回填 level SCALERS[level].inverse_transform(pred.reshape(-1, 1)).ravel() return jsonify({ model_version: v1, horizon: int(level.shape[0]), level: level.round(3).tolist(), }) if __name__ __main__: app.run(host0.0.0.0, port8000)接口里做了三层校验长度、特征数、NaN任何一层不过直接返回 400不让脏数据进模型。compileFalse加载是为了跳过优化器状态推理用不到能加快启动。反归一化只对水位列做因为其他特征只是输入辅助不需要还原。model_version字段是给下游做灰度对比用的新模型上线先并行跑一段比对了再切流量。批量预测把单条循环换成一次predict传(batch, WINDOW, F)的大数组注意显存或内存上限几千条以上分批跑。批量场景下输入校验要更严一条坏数据污染整个 batch 的情况我见过不止一次。5. 避坑与排查水位预测系统上线前必须过的五道关下面五条都是我在类似系统里真实踩过或帮人排查过的按出现频率排序。每条按现象、原因、解决三步写照着对能省掉大半天。5.1 模型文件加载报 unknown layer现象是load_model抛 ValueError提示某个层不认识。原因通常有两个训练和推理环境的库版本不一致或者模型里用了自定义层、自定义损失函数而加载时没注册。解决方式是先锁定依赖把训练环境的pip freeze导成 requirements 文件推理环境严格照装自定义层则通过custom_objects{MyLayer: MyLayer}传入或者在保存时改成标准层等价实现。跨环境迁移模型文件前先在一台干净机器上试加载别等部署到线上才发现。5.2 预测曲线是一条平线现象是接口返回的 24 个值几乎一样或者都贴近某个常数。原因八成是归一化参数没配对推理时用了重新 fit 的 scaler或者 scaler 的特征顺序和训练时不一致模型收到的输入全被压到同一个区间。还有一种可能是输入窗口里绝大部分是填充值。解决方式是加载训练时保存的 scaler按特征名取值并在推理前打印输入窗口的 min/max 和训练集对比。对不上就查特征列顺序和单位别急着改模型。5.3 离线指标很好上线误差偏大现象是验证集 RMSE 很小接入实时数据后误差明显变大。最常见原因是数据泄漏滑窗构造时跨越了训练集和验证集的边界验证段的前 WINDOW 步其实来自训练段模型等于见过答案。解决方式是切分时在边界处留出至少一个 window_size 的隔离带训练段末尾的样本不参与验证。另一个原因是线上数据分布和训练集不同比如汛期数据训练、枯水期上线这种情况要靠持续回灌新数据重训光调参救不回来。5.4 洪峰段系统性低估现象是平水期预测很准一到涨水段预测值明显低于实测。原因是 MSE 损失对大误差惩罚重但对高水位样本没有额外权重模型倾向于输出接近均值的保守预测。解决办法有三条损失换成 MAE 或 Huber降低对峰值误差的过度惩罚对高水位样本加权采样或者对水位做对数变换再建模把峰值段的相对误差拉平。我一般先试加权改动最小效果不够再换损失函数。5.5 推理输入窗口长度和训练不一致现象是接口不报错但输出形状或数值异常或者直接抛形状不匹配。原因很直接训练时 window_size 是 48推理代码里写成了 24 或 72模型按训练时的固定形状解释输入长度不对就错位。解决方式是把 window_size、horizon、特征列表全部抽到配置文件里训练和推理读同一份代码里不出现魔法数字。改预见期时同步改配置和重训别只改一边。注意这五条里有三条和“训练/推理不一致”有关。我的经验是上线前做一次端到端回归——用同一段历史数据分别走训练脚本的评估分支和线上接口两条路径的输出必须逐位对得上对不上就说明中间有环节没对齐。6. 精度验证与调优用 NSE 和分段回测把预测模型逼到可用RMSE 是回归任务的通用指标但在水位预测里它有个盲区不同站点的水位变幅差很多同一个 RMSE 在变幅 2 米的站算差在变幅 10 米的站可能算好。水文学界更常用纳什效率系数 NSE公式是 1 减去预测残差平方和与实测方差之比取值越接近 1 越好等于 0 表示模型效果和直接用均值预测一样为负说明还不如均值。把 NSE 和 RMSE 一起看才能判断模型是真的学到了序列结构还是只是数值上碰巧接近。分段回测比整体回测更能暴露问题。按汛期、枯水期、涨水段、退水段分别算指标你大概率会发现某一段特别差。我的做法是先用整段数据跑一遍拿到基线指标再按水文季节切四段分别评估落差超过 30% 的那一段单独拎出来看特征和样本分布。指标计算口径关注阈值主要用途RMSE预测与实测残差平方均值开方相对水位变幅小于 10%绝对误差量级MAE残差绝对值均值与 RMSE 差距大说明有离群大误差稳健性参考NSE1 - 残差平方和 / 实测方差大于 0.8 可用大于 0.9 较好水文业务验收峰值误差洪峰时刻预测值与实测值之差相对误差小于 15%防汛场景关键调优的顺序我建议从数据侧往模型侧推先补外生特征上游站水位、降雨预报再调窗口长度和预见期最后才动网络结构和超参。很多精度问题在特征层面就解决了直接调 LSTM 层数往往是在拟合噪声。如果多步预测的尾部误差明显大于首步考虑换成直接多输出或加一个残差修正模型用简单模型拟合主模型的残差比继续加深网络划算。验证脚本别只跑一次。每次换数据、换特征、换模型版本都重跑一遍分段回测把 NSE 和峰值误差记进一张表版本之间横向对比。后面再有人问“新模型到底比旧的好在哪”你直接甩表就行不用靠感觉争论。从那以后我每次交付预测模型都强制走一遍分段回测加端到端对齐少这两步的模型我不签字。希望帮到你。本文还有配套的精品资源点击获取