638 lines
14 KiB
Markdown
638 lines
14 KiB
Markdown
# 药店销售预测系统API文档
|
||
|
||
## 目录
|
||
|
||
- [概述](#概述)
|
||
- [API基础信息](#api基础信息)
|
||
- [数据管理API](#数据管理api)
|
||
- [获取所有产品列表](#获取所有产品列表)
|
||
- [获取单个产品详情](#获取单个产品详情)
|
||
- [获取产品销售数据](#获取产品销售数据)
|
||
- [上传销售数据](#上传销售数据)
|
||
- [模型训练API](#模型训练api)
|
||
- [启动模型训练任务](#启动模型训练任务)
|
||
- [查询训练任务状态](#查询训练任务状态)
|
||
- [模型预测API](#模型预测api)
|
||
- [使用模型预测](#使用模型预测)
|
||
- [比较不同模型预测结果](#比较不同模型预测结果)
|
||
- [模型管理API](#模型管理api)
|
||
- [获取模型列表](#获取模型列表)
|
||
- [获取模型详情](#获取模型详情)
|
||
- [删除模型](#删除模型)
|
||
- [导出模型](#导出模型)
|
||
- [导入模型](#导入模型)
|
||
- [API调用示例](#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参数**: 无
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"product_id": "P001",
|
||
"product_name": "布洛芬片"
|
||
},
|
||
{
|
||
"product_id": "P002",
|
||
"product_name": "阿司匹林"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 获取单个产品详情
|
||
|
||
获取特定产品的详细信息。
|
||
|
||
- **URL**: `/products/{product_id}`
|
||
- **方法**: `GET`
|
||
- **URL参数**:
|
||
- `product_id`: 产品ID，例如"P001"
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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（可选）
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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)，包含销售数据
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "数据上传成功",
|
||
"data": {
|
||
"products": 5,
|
||
"rows": 1825
|
||
}
|
||
}
|
||
```
|
||
|
||
## 模型训练API
|
||
|
||
### 启动模型训练任务
|
||
|
||
启动一个新的模型训练任务。
|
||
|
||
- **URL**: `/training`
|
||
- **方法**: `POST`
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "模型训练任务已启动",
|
||
"data": {
|
||
"task_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 查询训练任务状态
|
||
|
||
查询特定训练任务的状态。
|
||
|
||
- **URL**: `/training/{task_id}`
|
||
- **方法**: `GET`
|
||
- **URL参数**:
|
||
- `task_id`: 训练任务ID
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"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）
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"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）
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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`: 按模型类型筛选（可选）
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "模型已成功导入",
|
||
"data": {
|
||
"model_path": "models/P001_mlstm_model_v20230615_143025.pt"
|
||
}
|
||
}
|
||
```
|
||
|
||
## API调用示例
|
||
|
||
以下是使用Python和requests库调用API的示例代码：
|
||
|
||
```python
|
||
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)) |