doc--添加--接口文档描述的code版本
This commit is contained in:
parent
85e6b17038
commit
a3255c53a8
461
doc/接口文档code.md
Normal file
461
doc/接口文档code.md
Normal file
@ -0,0 +1,461 @@
|
||||
# 机器学习平台接口文档
|
||||
|
||||
## 1. 数据处理模块
|
||||
### 1.1 获取数据预处理方法列表
|
||||
```http
|
||||
GET /api/data/preprocessing/methods
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"methods": [
|
||||
{
|
||||
"name": "missing_value_handler",
|
||||
"description": "缺失值处理",
|
||||
"category": "data_cleaning"
|
||||
},
|
||||
{
|
||||
"name": "outlier_detector",
|
||||
"description": "异常值检测",
|
||||
"category": "data_cleaning"
|
||||
},
|
||||
{
|
||||
"name": "standardizer",
|
||||
"description": "标准化处理",
|
||||
"category": "feature_scaling"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 获取预处理方法详情
|
||||
```http
|
||||
GET /api/data/preprocessing/methods/{method_name}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"method": {
|
||||
"name": "missing_value_handler",
|
||||
"description": "缺失值处理",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "strategy",
|
||||
"type": "string",
|
||||
"options": ["mean", "median", "mode", "constant"],
|
||||
"default": "mean",
|
||||
"description": "填充策略"
|
||||
},
|
||||
{
|
||||
"name": "fill_value",
|
||||
"type": "float",
|
||||
"required": false,
|
||||
"description": "当strategy为constant时的填充值"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 获取特征工程方法列表
|
||||
```http
|
||||
GET /api/data/feature/methods
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"methods": [
|
||||
{
|
||||
"name": "standard_scaler",
|
||||
"description": "标准化缩放",
|
||||
"category": "scaling"
|
||||
},
|
||||
{
|
||||
"name": "polynomial_features",
|
||||
"description": "多项式特征",
|
||||
"category": "feature_creation"
|
||||
},
|
||||
{
|
||||
"name": "pca",
|
||||
"description": "主成分分析",
|
||||
"category": "dimension_reduction"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 1.4 获取特征工程方法详情
|
||||
```http
|
||||
GET /api/data/feature/methods/{method_name}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"method": {
|
||||
"name": "standard_scaler",
|
||||
"description": "标准化缩放",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "with_mean",
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "是否减去均值"
|
||||
},
|
||||
{
|
||||
"name": "with_std",
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "是否除以标准差"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.5 处理数据集
|
||||
```http
|
||||
POST /api/data/process
|
||||
Content-Type: application/json
|
||||
|
||||
Request:
|
||||
{
|
||||
"input_file": "dataset/dataset_raw/data.csv",
|
||||
"output_path": "dataset/dataset_processed/",
|
||||
"preprocessing": [
|
||||
{
|
||||
"method": "missing_value_handler",
|
||||
"params": {
|
||||
"strategy": "mean"
|
||||
}
|
||||
},
|
||||
{
|
||||
"method": "standard_scaler",
|
||||
"params": {
|
||||
"with_mean": true,
|
||||
"with_std": true
|
||||
}
|
||||
}
|
||||
],
|
||||
"split_ratio": {
|
||||
"train": 0.7,
|
||||
"val": 0.15,
|
||||
"test": 0.15
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"process_id": "proc_20230820_001",
|
||||
"output_files": {
|
||||
"train": "dataset/dataset_processed/train_20230820_001.csv",
|
||||
"val": "dataset/dataset_processed/val_20230820_001.csv",
|
||||
"test": "dataset/dataset_processed/test_20230820_001.csv"
|
||||
},
|
||||
"process_log": "logs/process_20230820_001.log"
|
||||
}
|
||||
```
|
||||
|
||||
### 1.6 查看可用数据集
|
||||
```http
|
||||
GET /api/data/datasets
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"datasets": [
|
||||
{
|
||||
"id": "dataset_001",
|
||||
"name": "breast_cancer",
|
||||
"created_at": "2023-08-20T10:00:00",
|
||||
"files": {
|
||||
"raw": "dataset/dataset_raw/breast_cancer.csv",
|
||||
"processed": {
|
||||
"train": "dataset/dataset_processed/breast_cancer_train.csv",
|
||||
"val": "dataset/dataset_processed/breast_cancer_val.csv",
|
||||
"test": "dataset/dataset_processed/breast_cancer_test.csv"
|
||||
}
|
||||
},
|
||||
"process_history": [
|
||||
{
|
||||
"step": "missing_value_handler",
|
||||
"params": {"strategy": "mean"}
|
||||
},
|
||||
{
|
||||
"step": "standard_scaler",
|
||||
"params": {"with_mean": true}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 模型接口
|
||||
### 2.1 获取可用模型列表
|
||||
```http
|
||||
GET /api/models/available
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"models": [
|
||||
{
|
||||
"name": "xgboost",
|
||||
"type": "classification",
|
||||
"description": "XGBoost分类器",
|
||||
"tags": ["tree", "ensemble", "classification"]
|
||||
},
|
||||
{
|
||||
"name": "lightgbm",
|
||||
"type": "classification",
|
||||
"description": "LightGBM分类器",
|
||||
"tags": ["tree", "ensemble", "classification"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 获取模型详情
|
||||
```http
|
||||
GET /api/models/{model_name}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"model": {
|
||||
"name": "xgboost",
|
||||
"description": "XGBoost分类器",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "max_depth",
|
||||
"type": "int",
|
||||
"range": [3, 10],
|
||||
"default": 6,
|
||||
"description": "树的最大深度"
|
||||
},
|
||||
{
|
||||
"name": "learning_rate",
|
||||
"type": "float",
|
||||
"range": [0.01, 0.3],
|
||||
"default": 0.1,
|
||||
"description": "学习率"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 获取评价指标列表
|
||||
```http
|
||||
GET /api/metrics
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"metrics": {
|
||||
"classification": [
|
||||
{
|
||||
"name": "accuracy",
|
||||
"description": "准确率",
|
||||
"range": [0, 1]
|
||||
},
|
||||
{
|
||||
"name": "f1",
|
||||
"description": "F1分数",
|
||||
"range": [0, 1]
|
||||
}
|
||||
],
|
||||
"regression": [
|
||||
{
|
||||
"name": "mse",
|
||||
"description": "均方误差",
|
||||
"range": [0, null]
|
||||
},
|
||||
{
|
||||
"name": "mae",
|
||||
"description": "平均绝对误差",
|
||||
"range": [0, null]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 模型训练
|
||||
```http
|
||||
POST /api/train
|
||||
Content-Type: application/json
|
||||
|
||||
Request:
|
||||
{
|
||||
"model": "xgboost",
|
||||
"dataset": {
|
||||
"train": "dataset/dataset_processed/train.csv",
|
||||
"val": "dataset/dataset_processed/val.csv",
|
||||
"test": "dataset/dataset_processed/test.csv"
|
||||
},
|
||||
"parameters": {
|
||||
"max_depth": 6,
|
||||
"learning_rate": 0.1
|
||||
},
|
||||
"metrics": ["accuracy", "f1"]
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"task_id": "train_20230820_001",
|
||||
"status_url": "/api/train/status/train_20230820_001"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.5 获取训练状态
|
||||
```http
|
||||
GET /api/train/status/{task_id}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"task": {
|
||||
"id": "train_20230820_001",
|
||||
"status": "running",
|
||||
"progress": 0.75,
|
||||
"current_epoch": 15,
|
||||
"total_epochs": 20,
|
||||
"metrics": {
|
||||
"train_loss": 0.234,
|
||||
"val_loss": 0.245
|
||||
},
|
||||
"start_time": "2023-08-20T10:00:00",
|
||||
"estimated_completion": "2023-08-20T10:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.6 模型预测
|
||||
```http
|
||||
POST /api/predict
|
||||
Content-Type: application/json
|
||||
|
||||
Request:
|
||||
{
|
||||
"model_id": "model_20230820_001",
|
||||
"data": "dataset/dataset_processed/test.csv",
|
||||
"output_path": "predictions/pred_20230820_001.csv"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"prediction_id": "pred_20230820_001",
|
||||
"output_file": "predictions/pred_20230820_001.csv",
|
||||
"metrics": {
|
||||
"accuracy": 0.95,
|
||||
"f1": 0.94
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 系统监控
|
||||
### 3.1 获取资源使用情况
|
||||
```http
|
||||
GET /api/system/resources
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"resources": {
|
||||
"gpu": [
|
||||
{
|
||||
"id": 0,
|
||||
"name": "NVIDIA T4",
|
||||
"memory_used": 8542,
|
||||
"memory_total": 16384,
|
||||
"utilization": 75
|
||||
}
|
||||
],
|
||||
"cpu": {
|
||||
"usage_percent": 65,
|
||||
"memory_used": 32768,
|
||||
"memory_total": 65536
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 获取训练历史
|
||||
```http
|
||||
GET /api/system/history
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"history": [
|
||||
{
|
||||
"task_id": "train_20230820_001",
|
||||
"model": "xgboost",
|
||||
"dataset": "breast_cancer",
|
||||
"start_time": "2023-08-20T10:00:00",
|
||||
"end_time": "2023-08-20T10:30:00",
|
||||
"status": "completed",
|
||||
"metrics": {
|
||||
"accuracy": 0.95,
|
||||
"f1": 0.94
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 获取系统日志
|
||||
```http
|
||||
GET /api/system/logs?level=error&start_time=2023-08-20T00:00:00
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "success",
|
||||
"logs": [
|
||||
{
|
||||
"timestamp": "2023-08-20T10:15:00",
|
||||
"level": "ERROR",
|
||||
"module": "training",
|
||||
"message": "Out of memory error in GPU 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 补充说明
|
||||
|
||||
1. 所有接口返回格式统一：
|
||||
```json
|
||||
{
|
||||
"status": "success/error",
|
||||
"data/error": {
|
||||
// 具体数据或错误信息
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 错误处理：
|
||||
- HTTP 400: 请求参数错误
|
||||
- HTTP 401: 未授权访问
|
||||
- HTTP 404: 资源不存在
|
||||
- HTTP 500: 服务器内部错误
|
||||
|
||||
3. 认证方式：
|
||||
- 使用Bearer Token认证
|
||||
- Token在请求头中携带：
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
4. 数据格式要求：
|
||||
- 所有请求和响应均使用JSON格式
|
||||
- 文件上传使用multipart/form-data
|
||||
- 时间格式统一使用ISO 8601标准
|
||||
|
||||
5. 接口版本控制：
|
||||
- 在URL中包含版本号：/api/v1/...
|
||||
- 在请求头中指定版本：API-Version: 1.0
|
||||
Loading…
Reference in New Issue
Block a user