650 lines
13 KiB
Markdown
650 lines
13 KiB
Markdown
# 药店单品销售预测系统 - API参考手册
|
||
|
||
## 1. API概述
|
||
|
||
药店销售预测系统提供了完整的RESTful API服务，支持药店销售数据管理、模型训练、销售预测和模型管理等功能。API使用JSON格式进行数据交换，并通过Swagger UI提供交互式文档。
|
||
|
||
## 2. API基础信息
|
||
|
||
- **基础URL**: `http://localhost:5000/api`
|
||
- **内容类型**: `application/json`
|
||
- **认证方式**: 无认证(仅适用于测试环境)
|
||
- **状态码**:
|
||
- `200 OK`: 请求成功
|
||
- `400 Bad Request`: 请求参数错误
|
||
- `404 Not Found`: 资源不存在
|
||
- `500 Internal Server Error`: 服务器内部错误
|
||
|
||
## 3. 启动API服务
|
||
|
||
```bash
|
||
# 基本启动
|
||
python api.py
|
||
|
||
# 指定主机和端口
|
||
python api.py --host 127.0.0.1 --port 8080
|
||
|
||
# 禁用Swagger UI
|
||
python api.py --swagger false
|
||
|
||
# 禁用调试模式
|
||
python api.py --debug false
|
||
```
|
||
|
||
## 4. 数据管理API
|
||
|
||
### 4.1 获取所有产品列表
|
||
|
||
获取系统中所有产品的ID和名称。
|
||
|
||
- **URL**: `/products`
|
||
- **方法**: `GET`
|
||
- **URL参数**: 无
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"product_id": "P001",
|
||
"product_name": "布洛芬片"
|
||
},
|
||
{
|
||
"product_id": "P002",
|
||
"product_name": "阿司匹林"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.2 获取单个产品详情
|
||
|
||
获取特定产品的详细信息。
|
||
|
||
- **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"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 获取产品销售数据
|
||
|
||
获取指定产品在特定日期范围内的销售数据。
|
||
|
||
- **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
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.4 上传销售数据
|
||
|
||
上传新的销售数据文件。
|
||
|
||
- **URL**: `/data/upload`
|
||
- **方法**: `POST`
|
||
- **内容类型**: `multipart/form-data`
|
||
- **参数**:
|
||
- `file`: Excel文件(.xlsx)，包含销售数据
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "数据上传成功",
|
||
"data": {
|
||
"products": 5,
|
||
"rows": 1825
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 模型训练API
|
||
|
||
### 5.1 启动模型训练任务
|
||
|
||
启动一个新的模型训练任务。
|
||
|
||
- **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",
|
||
"task_id": "train_P001_mlstm_20230615123456",
|
||
"message": "模型训练任务已启动"
|
||
}
|
||
```
|
||
|
||
### 5.2 查询训练任务状态
|
||
|
||
查询训练任务的状态。
|
||
|
||
- **URL**: `/training/{task_id}`
|
||
- **方法**: `GET`
|
||
- **URL参数**:
|
||
- `task_id`: 任务ID，由启动训练任务时返回
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"task_id": "train_P001_mlstm_20230615123456",
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"status": "completed",
|
||
"progress": 100,
|
||
"created_at": "2023-06-15T12:34:56",
|
||
"completed_at": "2023-06-15T12:45:23",
|
||
"metrics": {
|
||
"mse": 35.67,
|
||
"rmse": 5.97,
|
||
"mae": 4.21,
|
||
"r2": 0.87
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 模型预测API
|
||
|
||
### 6.1 使用模型预测
|
||
|
||
使用指定的模型进行预测。
|
||
|
||
- **URL**: `/prediction`
|
||
- **方法**: `POST`
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"days": 7,
|
||
"version": "latest"
|
||
}
|
||
```
|
||
|
||
- **参数说明**:
|
||
- `product_id`: 产品ID
|
||
- `model_type`: 模型类型，可选值：`mlstm`, `transformer`, `kan`
|
||
- `days`: 预测天数，默认7
|
||
- `version`: 模型版本，默认"latest"
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"product_name": "布洛芬片",
|
||
"model_type": "mlstm",
|
||
"version": "20230615123456",
|
||
"prediction_dates": ["2023-07-01", "2023-07-02", "2023-07-03", "2023-07-04", "2023-07-05", "2023-07-06", "2023-07-07"],
|
||
"predicted_sales": [125.4, 118.2, 130.1, 142.3, 138.7, 129.5, 145.2],
|
||
"metrics": {
|
||
"mse": 35.67,
|
||
"rmse": 5.97,
|
||
"mae": 4.21,
|
||
"r2": 0.87
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 比较不同模型预测结果
|
||
|
||
比较不同模型对同一产品的预测结果。
|
||
|
||
- **URL**: `/prediction/compare`
|
||
- **方法**: `POST`
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"product_id": "P001",
|
||
"model_types": ["mlstm", "transformer", "kan"],
|
||
"days": 7
|
||
}
|
||
```
|
||
|
||
- **参数说明**:
|
||
- `product_id`: 产品ID
|
||
- `model_types`: 要比较的模型类型列表
|
||
- `days`: 预测天数，默认7
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"product_name": "布洛芬片",
|
||
"prediction_dates": ["2023-07-01", "2023-07-02", "2023-07-03", "2023-07-04", "2023-07-05", "2023-07-06", "2023-07-07"],
|
||
"predictions": {
|
||
"mlstm": {
|
||
"version": "20230615123456",
|
||
"predicted_sales": [125.4, 118.2, 130.1, 142.3, 138.7, 129.5, 145.2],
|
||
"metrics": {
|
||
"mse": 35.67,
|
||
"rmse": 5.97,
|
||
"mae": 4.21,
|
||
"r2": 0.87
|
||
}
|
||
},
|
||
"transformer": {
|
||
"version": "20230614152345",
|
||
"predicted_sales": [127.8, 119.5, 132.3, 139.7, 141.2, 130.8, 143.1],
|
||
"metrics": {
|
||
"mse": 38.24,
|
||
"rmse": 6.18,
|
||
"mae": 4.35,
|
||
"r2": 0.85
|
||
}
|
||
},
|
||
"kan": {
|
||
"version": "20230613110012",
|
||
"predicted_sales": [124.1, 117.6, 128.9, 143.5, 139.2, 128.7, 146.3],
|
||
"metrics": {
|
||
"mse": 33.21,
|
||
"rmse": 5.76,
|
||
"mae": 4.12,
|
||
"r2": 0.89
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. 模型管理API
|
||
|
||
### 7.1 获取模型列表
|
||
|
||
获取系统中所有可用的模型。
|
||
|
||
- **URL**: `/models`
|
||
- **方法**: `GET`
|
||
- **查询参数**:
|
||
- `product_id`: 按产品ID筛选（可选）
|
||
- `model_type`: 按模型类型筛选（可选）
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"version": "20230615123456",
|
||
"created_at": "2023-06-15T12:45:23",
|
||
"metrics": {
|
||
"mse": 35.67,
|
||
"rmse": 5.97,
|
||
"mae": 4.21,
|
||
"r2": 0.87
|
||
}
|
||
},
|
||
{
|
||
"product_id": "P001",
|
||
"model_type": "transformer",
|
||
"version": "20230614152345",
|
||
"created_at": "2023-06-14T15:32:11",
|
||
"metrics": {
|
||
"mse": 38.24,
|
||
"rmse": 6.18,
|
||
"mae": 4.35,
|
||
"r2": 0.85
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 7.2 获取模型详情
|
||
|
||
获取特定模型的详细信息。
|
||
|
||
- **URL**: `/models/{product_id}/{model_type}`
|
||
- **方法**: `GET`
|
||
- **URL参数**:
|
||
- `product_id`: 产品ID
|
||
- `model_type`: 模型类型
|
||
- **查询参数**:
|
||
- `version`: 模型版本（可选，默认为最新版本）
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"product_name": "布洛芬片",
|
||
"model_type": "mlstm",
|
||
"version": "20230615123456",
|
||
"created_at": "2023-06-15T12:45:23",
|
||
"file_size": "2.3 MB",
|
||
"parameters": {
|
||
"look_back": 14,
|
||
"future_days": 7,
|
||
"batch_size": 64,
|
||
"epochs": 100,
|
||
"learning_rate": 0.001
|
||
},
|
||
"metrics": {
|
||
"mse": 35.67,
|
||
"rmse": 5.97,
|
||
"mae": 4.21,
|
||
"r2": 0.87,
|
||
"mape": 3.45
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.3 删除模型
|
||
|
||
删除指定的模型。
|
||
|
||
- **URL**: `/models/{product_id}/{model_type}`
|
||
- **方法**: `DELETE`
|
||
- **URL参数**:
|
||
- `product_id`: 产品ID
|
||
- `model_type`: 模型类型
|
||
- **查询参数**:
|
||
- `version`: 模型版本（可选，默认为最新版本）
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "模型已成功删除"
|
||
}
|
||
```
|
||
|
||
### 7.4 导出模型
|
||
|
||
导出指定的模型。
|
||
|
||
- **URL**: `/models/{product_id}/{model_type}/export`
|
||
- **方法**: `GET`
|
||
- **URL参数**:
|
||
- `product_id`: 产品ID
|
||
- `model_type`: 模型类型
|
||
- **查询参数**:
|
||
- `version`: 模型版本（可选，默认为最新版本）
|
||
|
||
**响应**:
|
||
文件下载（模型文件）
|
||
|
||
### 7.5 导入模型
|
||
|
||
导入模型文件。
|
||
|
||
- **URL**: `/models/import`
|
||
- **方法**: `POST`
|
||
- **内容类型**: `multipart/form-data`
|
||
- **参数**:
|
||
- `file`: 模型文件
|
||
- `overwrite`: 是否覆盖同名模型（可选，默认为false）
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "模型已成功导入",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"version": "20230615123456"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8. 系统信息API
|
||
|
||
### 8.1 获取系统状态
|
||
|
||
获取系统当前状态。
|
||
|
||
- **URL**: `/system/status`
|
||
- **方法**: `GET`
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"version": "1.0.0",
|
||
"uptime": "3 days, 4 hours",
|
||
"gpu_available": true,
|
||
"models_count": 15,
|
||
"products_count": 5,
|
||
"system_load": {
|
||
"cpu": "32%",
|
||
"memory": "48%",
|
||
"gpu": "15%"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 获取正在进行的任务
|
||
|
||
获取当前正在进行的任务列表。
|
||
|
||
- **URL**: `/system/tasks`
|
||
- **方法**: `GET`
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"task_id": "train_P003_mlstm_20230618091234",
|
||
"type": "training",
|
||
"product_id": "P003",
|
||
"model_type": "mlstm",
|
||
"status": "in_progress",
|
||
"progress": 65,
|
||
"created_at": "2023-06-18T09:12:34"
|
||
},
|
||
{
|
||
"task_id": "predict_P002_kan_20230618093012",
|
||
"type": "prediction",
|
||
"product_id": "P002",
|
||
"model_type": "kan",
|
||
"status": "in_progress",
|
||
"progress": 80,
|
||
"created_at": "2023-06-18T09:30:12"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 9. API调用示例
|
||
|
||
### 9.1 使用curl调用API
|
||
|
||
#### 获取产品列表
|
||
```bash
|
||
curl -X GET "http://localhost:5000/api/products"
|
||
```
|
||
|
||
#### 获取特定产品销售数据
|
||
```bash
|
||
curl -X GET "http://localhost:5000/api/products/P001/sales?start_date=2023-01-01&end_date=2023-01-31"
|
||
```
|
||
|
||
#### 启动模型训练
|
||
```bash
|
||
curl -X POST "http://localhost:5000/api/training" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"product_id": "P001", "model_type": "mlstm", "parameters": {"epochs": 100}}'
|
||
```
|
||
|
||
#### 使用模型预测
|
||
```bash
|
||
curl -X POST "http://localhost:5000/api/prediction" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"product_id": "P001", "model_type": "mlstm", "days": 7}'
|
||
```
|
||
|
||
### 9.2 使用Python requests库调用API
|
||
|
||
```python
|
||
import requests
|
||
import json
|
||
|
||
# 基础URL
|
||
base_url = "http://localhost:5000/api"
|
||
|
||
# 获取产品列表
|
||
response = requests.get(f"{base_url}/products")
|
||
products = response.json()
|
||
print(json.dumps(products, indent=2))
|
||
|
||
# 启动模型训练
|
||
train_data = {
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"parameters": {
|
||
"epochs": 100,
|
||
"batch_size": 64
|
||
}
|
||
}
|
||
response = requests.post(f"{base_url}/training", json=train_data)
|
||
result = response.json()
|
||
print(json.dumps(result, indent=2))
|
||
|
||
# 使用模型预测
|
||
predict_data = {
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"days": 7
|
||
}
|
||
response = requests.post(f"{base_url}/prediction", json=predict_data)
|
||
predictions = response.json()
|
||
print(json.dumps(predictions, indent=2))
|
||
```
|
||
|
||
## 10. 错误处理
|
||
|
||
所有API响应都包含`status`字段，用于表示请求是否成功。如果请求失败，将返回一个包含错误信息的响应：
|
||
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"error": {
|
||
"code": "MODEL_NOT_FOUND",
|
||
"message": "找不到指定的模型"
|
||
}
|
||
}
|
||
```
|
||
|
||
常见错误代码：
|
||
|
||
- `INVALID_PARAMETERS`: 请求参数无效
|
||
- `PRODUCT_NOT_FOUND`: 找不到指定的产品
|
||
- `MODEL_NOT_FOUND`: 找不到指定的模型
|
||
- `TASK_NOT_FOUND`: 找不到指定的任务
|
||
- `FILE_UPLOAD_ERROR`: 文件上传失败
|
||
- `TRAINING_ERROR`: 模型训练失败
|
||
- `PREDICTION_ERROR`: 模型预测失败
|
||
- `SYSTEM_ERROR`: 系统内部错误 |