OneTree/ShopTRAINING
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ShopTRAINING/docs/输出文档/药店销售预测系统API文档.md

14 KiB
Raw Permalink Blame History

药店销售预测系统API文档

目录

概述

药店销售预测系统API提供了完整的RESTful接口，支持药店销售数据管理、模型训练、销售预测和模型管理等功能。API使用JSON格式进行数据交换，所有API响应都包含status字段，用于表示请求是否成功。

API基础信息

  • 基础URL: http://localhost:5000/api
  • 内容类型: application/json
  • 认证方式: 无认证(仅适用于测试环境)
  • 状态码:
    • 200 OK: 请求成功
    • 400 Bad Request: 请求参数错误
    • 404 Not Found: 资源不存在
    • 500 Internal Server Error: 服务器内部错误

数据管理API

获取所有产品列表

获取系统中所有产品的ID和名称。

  • URL: /products
  • 方法: GET
  • URL参数: 无

响应:

{
  "status": "success",
  "data": [
    {
      "product_id": "P001",
      "product_name": "布洛芬片"
    },
    {
      "product_id": "P002",
      "product_name": "阿司匹林"
    }
  ]
}

获取单个产品详情

获取特定产品的详细信息。

  • URL: /products/{product_id}
  • 方法: GET
  • URL参数:
    • product_id: 产品ID，例如"P001"

响应:

{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "data_points": 365,
    "date_range": {
      "start": "2023-01-01",
      "end": "2023-12-31"
    }
  }
}

获取产品销售数据

获取指定产品在特定日期范围内的销售数据。

  • URL: /products/{product_id}/sales
  • 方法: GET
  • URL参数:
    • product_id: 产品ID，例如"P001"
  • 查询参数:
    • start_date: 开始日期，格式为YYYY-MM-DD（可选）
    • end_date: 结束日期，格式为YYYY-MM-DD（可选）

响应:

{
  "status": "success",
  "data": [
    {
      "date": "2023-01-01",
      "product_id": "P001",
      "product_name": "布洛芬片",
      "sales": 120,
      "price": 15.5,
      "weekday": 6,
      "month": 1,
      "is_holiday": 1,
      "is_weekend": 1,
      "is_promotion": 0,
      "temperature": 5.2
    },
    {
      "date": "2023-01-02",
      "product_id": "P001",
      "product_name": "布洛芬片",
      "sales": 85,
      "price": 15.5,
      "weekday": 0,
      "month": 1,
      "is_holiday": 0,
      "is_weekend": 0,
      "is_promotion": 0,
      "temperature": 4.8
    }
  ]
}

上传销售数据

上传新的销售数据文件。

  • URL: /data/upload
  • 方法: POST
  • 内容类型: multipart/form-data
  • 参数:
    • file: Excel文件(.xlsx)，包含销售数据

响应:

{
  "status": "success",
  "message": "数据上传成功",
  "data": {
    "products": 5,
    "rows": 1825
  }
}

模型训练API

启动模型训练任务

启动一个新的模型训练任务。

  • URL: /training
  • 方法: POST
  • 请求体:
{
  "product_id": "P001",
  "model_type": "mlstm",
  "parameters": {
    "look_back": 14,
    "future_days": 7,
    "batch_size": 64,
    "epochs": 100,
    "learning_rate": 0.001
  }
}
  • 参数说明:
    • product_id: 产品ID
    • model_type: 模型类型，可选值：mlstm, transformer, kan
    • parameters: 训练参数（可选）
      • look_back: 回看天数，默认14
      • future_days: 预测天数，默认7
      • batch_size: 批大小，默认32
      • epochs: 训练轮次，默认50
      • learning_rate: 学习率，默认0.001

响应:

{
  "status": "success",
  "message": "模型训练任务已启动",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

查询训练任务状态

查询特定训练任务的状态。

  • URL: /training/{task_id}
  • 方法: GET
  • URL参数:
    • task_id: 训练任务ID

响应:

{
  "status": "success",
  "data": {
    "product_id": "P001",
    "model_type": "mlstm",
    "parameters": {
      "look_back": 14,
      "future_days": 7
    },
    "status": "completed",
    "created_at": "2023-06-15 14:30:25",
    "model_path": "models/P001_mlstm_model_v20230615_143025.pt",
    "metrics": {
      "MSE": 12.45,
      "RMSE": 3.52,
      "MAE": 2.85,
      "R2": 0.92,
      "MAPE": 5.67
    },
    "model_details_url": "/api/models?product_id=P001&model_type=mlstm"
  }
}
  • 可能的状态值:
    • pending: 等待开始
    • running: 正在训练
    • completed: 训练完成
    • failed: 训练失败

模型预测API

使用模型预测

使用指定模型进行预测。

  • URL: /prediction
  • 方法: POST
  • 请求体:
{
  "product_id": "P001",
  "model_type": "mlstm",
  "version": "20230615_143025",
  "future_days": 7,
  "include_visualization": true
}
  • 参数说明:
    • product_id: 产品ID
    • model_type: 模型类型，可选值：mlstm, transformer, kan
    • version: 模型版本（可选，不指定则使用最新版本）
    • future_days: 预测天数（可选，默认为7）
    • include_visualization: 是否包含可视化结果（可选，默认为false）

响应:

{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "model_type": "mlstm",
    "predictions": [
      {
        "date": "2023-07-01",
        "predicted_sales": 105.8
      },
      {
        "date": "2023-07-02",
        "predicted_sales": 98.3
      },
      {
        "date": "2023-07-03",
        "predicted_sales": 112.5
      },
      {
        "date": "2023-07-04",
        "predicted_sales": 120.1
      },
      {
        "date": "2023-07-05",
        "predicted_sales": 125.6
      },
      {
        "date": "2023-07-06",
        "predicted_sales": 118.9
      },
      {
        "date": "2023-07-07",
        "predicted_sales": 130.4
      }
    ],
    "visualization": "base64_encoded_image_data"
  }
}

比较不同模型预测结果

比较不同模型的预测结果。

  • URL: /prediction/compare
  • 方法: POST
  • 请求体:
{
  "product_id": "P001",
  "model_types": ["mlstm", "transformer", "kan"],
  "versions": ["20230615_143025", null, null],
  "include_visualization": true
}
  • 参数说明:
    • product_id: 产品ID
    • model_types: 要比较的模型类型列表
    • versions: 对应每个模型的版本列表（可选，不指定则使用最新版本）
    • include_visualization: 是否包含可视化结果（可选，默认为false）

响应:

{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "model_types": ["mlstm", "transformer", "kan"],
    "comparison": [
      {
        "date": "2023-07-01",
        "mlstm_prediction": 105.8,
        "transformer_prediction": 108.2,
        "kan_prediction": 107.1
      },
      {
        "date": "2023-07-02",
        "mlstm_prediction": 98.3,
        "transformer_prediction": 101.5,
        "kan_prediction": 100.6
      },
      {
        "date": "2023-07-03",
        "mlstm_prediction": 112.5,
        "transformer_prediction": 115.8,
        "kan_prediction": 114.2
      },
      {
        "date": "2023-07-04",
        "mlstm_prediction": 120.1,
        "transformer_prediction": 122.4,
        "kan_prediction": 121.8
      },
      {
        "date": "2023-07-05",
        "mlstm_prediction": 125.6,
        "transformer_prediction": 127.3,
        "kan_prediction": 126.9
      },
      {
        "date": "2023-07-06",
        "mlstm_prediction": 118.9,
        "transformer_prediction": 121.2,
        "kan_prediction": 120.5
      },
      {
        "date": "2023-07-07",
        "mlstm_prediction": 130.4,
        "transformer_prediction": 132.8,
        "kan_prediction": 131.6
      }
    ],
    "visualization": "base64_encoded_image_data"
  }
}

模型管理API

获取模型列表

获取系统中的模型列表，可按产品ID和模型类型筛选。

  • URL: /models
  • 方法: GET
  • 查询参数:
    • product_id: 按产品ID筛选（可选）
    • model_type: 按模型类型筛选（可选）

响应:

{
  "status": "success",
  "data": [
    {
      "product_id": "P001",
      "model_type": "mlstm",
      "version": "20230615_143025",
      "file_path": "models/P001_mlstm_model_v20230615_143025.pt",
      "created_at": "2023-06-15 14:30:25",
      "file_size": "2.45 MB",
      "metrics": {
        "MSE": 12.45,
        "RMSE": 3.52,
        "MAE": 2.85,
        "R2": 0.92,
        "MAPE": 5.67
      }
    },
    {
      "product_id": "P001",
      "model_type": "transformer",
      "version": "20230615_150512",
      "file_path": "models/P001_transformer_model_v20230615_150512.pt",
      "created_at": "2023-06-15 15:05:12",
      "file_size": "3.12 MB",
      "metrics": {
        "MSE": 10.82,
        "RMSE": 3.29,
        "MAE": 2.73,
        "R2": 0.93,
        "MAPE": 5.21
      }
    }
  ]
}

获取模型详情

获取特定模型的详细信息。

  • URL: /models/{model_id}
  • 方法: GET
  • URL参数:
    • model_id: 模型ID，格式为{product_id}_{model_type}_v{version}，例如P001_mlstm_v20230615_143025

响应:

{
  "status": "success",
  "data": {
    "product_id": "P001",
    "model_type": "mlstm",
    "version": "20230615_143025",
    "created_at": "2023-06-15 14:30:25",
    "file_path": "models/P001_mlstm_model_v20230615_143025.pt",
    "file_size": "2.45 MB",
    "features": ["sales", "price", "weekday", "month", "is_holiday", "is_weekend", "is_promotion", "temperature"],
    "look_back": 14,
    "T": 7,
    "metrics": {
      "MSE": 12.45,
      "RMSE": 3.52,
      "MAE": 2.85,
      "R2": 0.92,
      "MAPE": 5.67
    }
  }
}

删除模型

删除特定模型。

  • URL: /models/{model_id}
  • 方法: DELETE
  • URL参数:
    • model_id: 模型ID，格式为{product_id}_{model_type}_v{version}，例如P001_mlstm_v20230615_143025

响应:

{
  "status": "success",
  "message": "模型已成功删除"
}

导出模型

导出特定模型文件。

  • URL: /models/{model_id}/export
  • 方法: GET
  • URL参数:
    • model_id: 模型ID，格式为{product_id}_{model_type}_v{version}，例如P001_mlstm_v20230615_143025

响应: 直接下载模型文件

导入模型

导入模型文件。

  • URL: /models/import
  • 方法: POST
  • 内容类型: multipart/form-data
  • 参数:
    • file: PyTorch模型文件(.pt)

响应:

{
  "status": "success",
  "message": "模型已成功导入",
  "data": {
    "model_path": "models/P001_mlstm_model_v20230615_143025.pt"
  }
}

API调用示例

以下是使用Python和requests库调用API的示例代码：

import requests
import json
import matplotlib.pyplot as plt
import base64
from io import BytesIO

# API基础URL
API_BASE_URL = 'http://localhost:5000/api'

# 获取所有产品
def get_products():
    response = requests.get(f'{API_BASE_URL}/products')
    return response.json()

# 训练模型
def train_model(product_id, model_type='mlstm'):
    data = {
        'product_id': product_id,
        'model_type': model_type,
        'parameters': {
            'look_back': 14,
            'future_days': 7,
            'epochs': 50
        }
    }
    response = requests.post(f'{API_BASE_URL}/training', json=data)
    return response.json()

# 查询训练状态
def check_training_status(task_id):
    response = requests.get(f'{API_BASE_URL}/training/{task_id}')
    return response.json()

# 使用模型预测
def predict_sales(product_id, model_type='mlstm', include_visualization=True):
    data = {
        'product_id': product_id,
        'model_type': model_type,
        'future_days': 7,
        'include_visualization': include_visualization
    }
    response = requests.post(f'{API_BASE_URL}/prediction', json=data)
    result = response.json()
    
    # 如果包含可视化图表，显示它
    if include_visualization and 'data' in result and 'visualization' in result['data']:
        img_data = base64.b64decode(result['data']['visualization'])
        img = plt.imread(BytesIO(img_data))
        plt.figure(figsize=(12, 6))
        plt.imshow(img)
        plt.axis('off')
        plt.show()
    
    return result

# 比较不同模型
def compare_models(product_id, model_types=['mlstm', 'transformer', 'kan']):
    data = {
        'product_id': product_id,
        'model_types': model_types,
        'include_visualization': True
    }
    response = requests.post(f'{API_BASE_URL}/prediction/compare', json=data)
    return response.json()

# 调用示例
if __name__ == '__main__':
    # 获取所有产品
    products = get_products()
    print(json.dumps(products, indent=2))
    
    if products['status'] == 'success' and len(products['data']) > 0:
        # 选择第一个产品
        product_id = products['data'][0]['product_id']
        
        # 训练模型
        training_result = train_model(product_id, 'mlstm')
        print(json.dumps(training_result, indent=2))
        
        # 如果训练任务启动成功，检查状态
        if training_result['status'] == 'success':
            task_id = training_result['data']['task_id']
            
            # 这里实际使用时可以轮询检查状态
            status = check_training_status(task_id)
            print(json.dumps(status, indent=2))
            
            # 使用模型预测（实际使用时应等待训练完成）
            predictions = predict_sales(product_id)
            print(json.dumps(predictions, indent=2))