长短期神经网络 LSTM

实际接口：175.24.232.91:8060

在线调用

健康状态：

项目简介

基于 FastAPI 构建的LSTM神经网络训练和预测服务，专门用于时间序列预测任务。支持异步模型训练、实时预测、模型管理等功能。

核心功能特性

✅ 异步模型训练 - 支持后台训练，实时跟踪训练进度
✅ 时序预测 - 基于历史数据的迭代预测
✅ 模型管理 - 完整的模型生命周期管理（训练、保存、加载、删除）
✅ 丰富配置 - 支持多种损失函数、优化器、Dropout、早停等
✅ 训练监控 - 实时训练进度、损失曲线、验证指标

所有接口均采用 JSON 格式进行数据传输，并提供完整的 OpenAPI 文档。

如何部署

方式一：Docker Compose 部署（推荐）

1. 确保已安装 Docker 和 Docker Compose

访问 Docker 官网下载并安装 Docker。

2. 在项目根目录下执行部署命令：

# 构建并启动服务
docker-compose up -d --build

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f lstm-service

3. 访问服务

API 服务地址: http://localhost:8060
API 交互文档: http://localhost:8060/docs
ReDoc 文档: http://localhost:8060/redoc
健康检查: http://localhost:8060/health

4. 停止服务

docker-compose down

方式二：直接 Docker 部署

# 构建镜像
docker build -t lstm-prediction-service .

# 启动容器
docker run -d -p 8060:8000 --name lstm-service lstm-prediction-service

# 查看日志
docker logs -f lstm-service

API 接口详细说明

接口一：模型训练

接口路径：POST /train
接口说明：启动LSTM模型异步训练任务，支持自定义模型配置和训练参数。

✅ 请求体参数格式

{
  "historical_target": [23.5, 24.2, 25.1, 26.3, 25.8,23.5, 24.2, 25.1, 26.3, 25.8],
  "historical_features": [
    [12.3, 4.5, 67.8, 2.1],
    [15.7, 5.2, 72.4, 2.8], 
    [11.9, 4.1, 65.3, 1.9],
    [18.2, 6.1, 78.9, 3.2],
    [16.5, 5.8, 70.2, 2.5],
    [12.3, 4.5, 67.8, 2.1],
    [15.7, 5.2, 72.4, 2.8], 
    [11.9, 4.1, 65.3, 1.9],
    [18.2, 6.1, 78.9, 3.2],
    [16.5, 5.8, 70.2, 2.5]
  ],
  "sequence_length": 3,
  "hidden_size": 64,
  "num_layers": 2,
  "batch_size": 32,
  "epochs": 150,
  "learning_rate": 0.001,
  "enable_dropout": false,
  "dropout_rate": 0.2,
  "enable_early_stopping": false,
  "early_stopping_patience": 10,
  "train_val_split": 0.8,
  "loss_function": "MSE",
  "optimizer": "Adam",
  "model_name": "渗压预测模型_v1",
  "model_description": "基于水位、降雨等特征预测渗压变化"
}

📋 参数详细说明

参数名	类型	必填	默认值	说明
`historical_target`	List[float]	✅	-	历史目标值序列（如渗压值）
`historical_features`	List[List[float]]	✅	-	历史特征矩阵（如水位、降雨等）
`sequence_length`	int	❌	30	需要修改，如3、5更小的值
`hidden_size`	int	❌	64	LSTM隐藏层单元数
`num_layers`	int	❌	2	LSTM层数
`batch_size`	int	❌	32	批次大小
`epochs`	int	❌	150	训练轮数
`learning_rate`	float	❌	0.001	学习率
`enable_dropout`	bool	❌	false	是否启用Dropout
`dropout_rate`	float	❌	0.2	Dropout比率
`enable_early_stopping`	bool	❌	false	是否启用早停
`early_stopping_patience`	int	❌	10	早停耐心值
`train_val_split`	float	❌	0.8	训练集比例
`loss_function`	str	❌	“MSE”	损失函数(MSE/MAE/Huber/SmoothL1)
`optimizer`	str	❌	“Adam”	优化器(Adam/SGD/RMSprop/AdamW)
`model_name`	str	❌	自动生成	模型名称
`model_description`	str	❌	null	模型描述

✅ 返回结构

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "训练任务已成功提交，正在后台处理",
  "status": "accepted"
}

接口二：预测

接口路径：POST /predict
接口说明：使用已训练的LSTM模型进行迭代预测，支持基于历史目标值的滞后特征预测。

✅ 请求体参数格式

{
  "future_features": [
    [19.5, 6.3, 82.1, 3.5],
    [20.1, 6.8, 85.2, 4.1], 
    [18.9, 5.9, 79.8, 2.9]
  ],
  "recent_historical_features": [
    [12.3, 4.5, 67.8, 2.1],
    [15.7, 5.2, 72.4, 2.8],
    [11.9, 4.1, 65.3, 1.9],
    [18.2, 6.1, 78.9, 3.2]
  ],
  "recent_historical_target": [23.5, 24.2, 25.1, 26.3, 25.8],
  "model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

📋 参数详细说明

参数名	类型	必填	说明
`future_features`	List[List[float]]	✅	未来时间步的特征数据
`recent_historical_features`	List[List[float]]	✅	最近的历史特征（至少sequence_length个）
`recent_historical_target`	List[float]	✅	最近的历史目标值（至少sequence_length+1个）
`model_id`	str	❌	虽然不是必填，但是因为监测类型、模型太多，必须指定模型ID

✅ 返回结构

{
  "predictions": [27.2, 28.1, 26.8],
  "model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_info": {
    "model_name": "渗压预测模型_v1",
    "created_at": "2025-08-12T10:30:00",
    "sequence_length": 30,
    "input_features": 5,
    "original_feature_size": 4,
    "has_lag_features": true,
    "final_training_loss": 0.0234,
    "prediction_method": "iterative_with_lag_target"
  }
}

接口三：训练状态查询

接口路径：GET /training-status/{task_id}
接口说明：查询训练任务的实时状态和进度。

✅ 返回结构

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "training",
  "progress": 65.3,
  "message": "训练进度: 65.3% (Epoch 98/150) - 训练损失: 0.0156, 验证损失: 0.0189",
  "model_id": null,
  "created_at": null
}

📋 状态说明

状态值	说明
`pending`	任务已创建，等待开始
`training`	正在训练中
`completed`	训练完成
`failed`	训练失败

接口四：模型列表

接口路径：GET /models
接口说明：获取所有已训练模型的详细信息，包括训练指标和验证结果。

✅ 返回结构

[
  {
    "model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "model_name": "渗压预测模型_v1",
    "created_at": "2024-01-15T10:30:00",
    "status": "available",
    "config": {
      "input_size": 5,
      "hidden_size": 64,
      "num_layers": 2,
      "sequence_length": 30,
      "epochs": 150,
      "learning_rate": 0.001,
      "loss_function": "MSE",
      "optimizer": "Adam"
    },
    "training_metrics": {
      "final_loss": 0.0234,
      "epochs": 150,
      "training_time": 45.678,
      "train_samples": 1200,
      "val_samples": 300,
      "validation_metrics": {
        "mse": 0.0189,
        "rmse": 0.1375,
        "mae": 0.1092,
        "correlation": 0.9567
      }
    }
  }
]

接口五：模型删除

接口路径：DELETE /models/{model_id}
接口说明：删除指定的训练模型及其相关文件。

✅ 返回结构

{
  "message": "模型 a1b2c3d4-e5f6-7890-abcd-ef1234567890 已成功删除"
}

接口六：损失曲线

接口路径：GET /model/{model_id}/loss-curve
接口说明：获取指定模型的训练和验证损失曲线数据。

✅ 返回结构

{
  "model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_name": "渗压预测模型_v1",
  "train_losses": [0.245, 0.189, 0.156, 0.134, 0.098, 0.067, 0.045, 0.0234],
  "validation_losses": [0.267, 0.201, 0.178, 0.145, 0.112, 0.089, 0.056, 0.0189],
  "validation_metrics": {
    "mse": 0.0189,
    "rmse": 0.1375,
    "mae": 0.1092,
    "correlation": 0.9567,
    "predictions": [27.2, 28.1, 26.8],
    "actuals": [27.1, 28.3, 26.9]
  }
}

接口七：健康检查

接口路径：GET /health
接口说明：检查服务运行状态和基本信息。

✅ 返回结构

{
  "status": "healthy",
  "service": "LSTM训练预测服务",
  "version": "2.0.0",
  "models_count": 5
}

开发调试

本地开发环境

# 克隆项目
cd 大型水库

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器
python fastapi_lstm_service.py

API 文档访问

启动服务后，可以通过以下地址访问API文档：

Swagger UI: http://localhost:8060/docs
ReDoc: http://localhost:8060/redoc
OpenAPI JSON: http://localhost:8060/openapi.json

测试接口示例

测试模型训练

curl -X POST http://localhost:8060/train \
  -H "Content-Type: application/json" \
  -d '{
    "historical_target": [23.5, 24.2, 25.1, 26.3, 25.8, 27.1, 26.9, 28.2, 29.1, 28.7],
    "historical_features": [
      [12.3, 4.5, 67.8, 2.1],
      [15.7, 5.2, 72.4, 2.8],
      [11.9, 4.1, 65.3, 1.9],
      [18.2, 6.1, 78.9, 3.2],
      [16.5, 5.8, 70.2, 2.5],
      [19.1, 6.3, 82.1, 3.8],
      [14.2, 4.9, 68.7, 2.3],
      [17.8, 5.7, 75.6, 3.1],
      [20.4, 6.8, 85.2, 4.2],
      [18.9, 5.9, 79.8, 2.9]
    ],
    "model_name": "测试模型",
    "epochs": 50
  }'

测试预测

curl -X POST http://localhost:8060/predict \
  -H "Content-Type: application/json" \
  -d '{
    "future_features": [
      [19.5, 6.3, 82.1, 3.5],
      [20.1, 6.8, 85.2, 4.1]
    ],
    "recent_historical_features": [
      [12.3, 4.5, 67.8, 2.1],
      [15.7, 5.2, 72.4, 2.8],
      [11.9, 4.1, 65.3, 1.9],
      [18.2, 6.1, 78.9, 3.2]
    ],
    "recent_historical_target": [23.5, 24.2, 25.1, 26.3, 25.8]
  }'

测试健康检查

# 服务健康检查
curl http://localhost:8060/health

# 查看所有模型
curl http://localhost:8060/models

# 查询训练状态
curl http://localhost:8060/training-status/{task_id}

系统要求

运行环境

操作系统: Linux (推荐) / Windows / macOS
Python: 3.8+
内存: 建议 8GB 以上（支持GPU训练需要更多显存）
CPU: 多核处理器（支持并发训练任务）
存储: 至少 2GB 可用空间（用于模型存储）

依赖包

fastapi>=0.104.0
uvicorn[standard]>=0.24.0
torch>=1.12.0
numpy>=1.21.0
pandas>=1.3.0
scikit-learn>=1.0.0
joblib>=1.1.0
pydantic>=2.0.0

硬件支持

CPU训练: 支持所有平台
GPU训练: 需要CUDA兼容的GPU和相应驱动
内存要求: 训练大型模型时需要足够内存

Docker 配置说明

环境变量

在 docker-compose.yml 中可以配置以下环境变量：

environment:
  - PYTHONUNBUFFERED=1     # Python 输出不缓冲
  - WORKERS=4              # Worker 进程数
  - HOST=0.0.0.0          # 绑定主机
  - PORT=8000             # 服务端口  
  - LOG_LEVEL=info        # 日志级别
  - MODEL_STORAGE_PATH=/app/models  # 模型存储路径

端口映射

默认映射配置："8060:8000"

容器内服务运行在 8000 端口
对外暴露 8060 端口

数据持久化

挂载模型存储目录以保持数据持久性：

    volumes:
      - "/data/linhai_models_v2:/app/models"
      - "/logs:/app/logs"

注意事项

数据要求

训练数据完整性：历史目标值和特征量长度必须匹配
数据长度要求：历史数据长度尽可能长，因为需要创建滞后特征
预测数据要求：历史目标值需要比历史特征多1个时间点（用于构造滞后特征）
数据类型：所有数值必须为 float 类型，避免字符串混入
特征一致性：训练和预测时的特征维度必须保持一致

训练优化

早停机制：建议启用早停避免过拟合，patience设置为10-20
验证集划分：建议按时间顺序划分，保持80%-20%的比例
Dropout：对于小数据集建议关闭，大数据集可启用（0.1-0.3）

预测使用

模型选择：必须指定模型id进行预测
滞后特征：系统自动处理滞后特征，无需手动添加
预测长度：理论上可以预测任意长度，但长期预测准确性会下降

故障处理

训练失败：检查数据格式和参数设置
预测错误：确认使用的模型支持滞后特征
内存不足：减小batch_size或模型大小

如需调试接口，请访问: http://localhost:8060/docs