664 lines
13 KiB
Markdown
664 lines
13 KiB
Markdown
# 装备成本估算系统 API 文档
|
|
|
|
这个 API 文档提供了完整的接口说明，包括：
|
|
|
|
- 每个端点的详细描述
|
|
- 请求和响应的具体示例
|
|
- 清晰的参数格式要求
|
|
- 统一的错误处理说明
|
|
- 重要的注意事项
|
|
|
|
文档使用 Markdown 格式编写，请使用支持 Markdown 的工具查看。
|
|
|
|
## 基本信息
|
|
|
|
- 基础URL: `http://localhost:5001/api`
|
|
- 版本: 1.0.0
|
|
- 响应格式: JSON
|
|
|
|
## API 端点列表
|
|
|
|
### 1. 获取 API 信息
|
|
|
|
获取 API 版本信息和可用端点列表。
|
|
|
|
- **URL**: `/`
|
|
- **方法**: `GET`
|
|
- **响应示例**:
|
|
json
|
|
{
|
|
"name": "装备成本估算系统 API",
|
|
"version": "1.0.0",
|
|
"endpoints": {
|
|
"predict": {
|
|
"url": "/api/predict",
|
|
"method": "POST",
|
|
"description": "成本预测"
|
|
},
|
|
"analyze-features": {
|
|
"url": "/api/analyze-features",
|
|
"method": "POST",
|
|
"description": "特征分析"
|
|
},
|
|
"train": {
|
|
"url": "/api/train",
|
|
"method": "POST",
|
|
"description": "模型训练"
|
|
},
|
|
"evaluate": {
|
|
"url": "/api/evaluate",
|
|
"method": "POST",
|
|
"description": "模型评估"
|
|
}
|
|
}
|
|
}
|
|
|
|
### 2. 单模型预测
|
|
|
|
使用当前激活的最优模型进行成本预测。
|
|
|
|
- **URL**: `/predict`
|
|
- **方法**: `POST`
|
|
- **请求体示例** (巡飞弹):
|
|
|
|
```json
|
|
{
|
|
"type": "巡飞弹",
|
|
"length_m": 1.3,
|
|
"width_m": 0.23,
|
|
"height_m": 0.23,
|
|
"weight_kg": 12.5,
|
|
"max_range_km": 40,
|
|
"max_speed_ms": 50,
|
|
"cruise_speed_kmh": 100,
|
|
"flight_time_min": 60,
|
|
"folded_length_mm": 1300,
|
|
"folded_width_mm": 230,
|
|
"folded_height_mm": 230,
|
|
"warhead_type": "破片杀伤战斗部",
|
|
"launch_mode": "凭自身动力起飞"
|
|
}
|
|
```
|
|
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"predicted_cost": 150000.0,
|
|
"model_info": {
|
|
"type": "xgboost",
|
|
"name": "巡飞弹_20241111_model",
|
|
"r2_score": 0.95,
|
|
"mae": 5000.0,
|
|
"rmse": 7500.0
|
|
},
|
|
"confidence_interval": {
|
|
"lower": 135000.0,
|
|
"upper": 165000.0
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. PLS 模型预测
|
|
|
|
使用 PLS 回归模型进行预测。
|
|
|
|
- **URL**: `/pls/predict`
|
|
- **方法**: `POST`
|
|
- **请求体**: 与单模型预测相同
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"predicted_cost": 148000.0,
|
|
"confidence_interval": {
|
|
"lower": 133000.0,
|
|
"upper": 163000.0
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. 多模型预测
|
|
|
|
使用所有激活的模型进行预测并返回综合结果。
|
|
|
|
- **URL**: `/predict/all`
|
|
- **方法**: `POST`
|
|
- **请求体**: 与单模型预测相同
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"individual_predictions": {
|
|
"xgboost": {
|
|
"predicted_cost": 150000.0,
|
|
"model_info": {
|
|
"name": "巡飞弹_xgboost_model",
|
|
"type": "xgboost",
|
|
"r2_score": 0.95,
|
|
"mae": 5000.0,
|
|
"rmse": 7500.0
|
|
},
|
|
"confidence_interval": {
|
|
"lower": 135000.0,
|
|
"upper": 165000.0
|
|
}
|
|
},
|
|
"pls": {
|
|
"predicted_cost": 148000.0,
|
|
"model_info": {
|
|
"name": "巡飞弹_pls_model",
|
|
"type": "pls",
|
|
"r2_score": 0.92,
|
|
"mae": 5500.0,
|
|
"rmse": 8000.0
|
|
},
|
|
"confidence_interval": {
|
|
"lower": 133000.0,
|
|
"upper": 163000.0
|
|
}
|
|
}
|
|
},
|
|
"ensemble_prediction": {
|
|
"predicted_cost": 149000.0,
|
|
"standard_deviation": 1414.21,
|
|
"confidence_interval": {
|
|
"lower": 146228.15,
|
|
"upper": 151771.85
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5. 特征分析
|
|
|
|
分析数据集中特征的重要性和相关性。
|
|
|
|
- **URL**: `/analyze-features`
|
|
- **方法**: `POST`
|
|
- **请求体示例**:
|
|
|
|
```json
|
|
{
|
|
"dataset_id": 1,
|
|
"equipment_type": "巡飞弹"
|
|
}
|
|
```
|
|
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"important_features": [
|
|
{
|
|
"name": "最大射程(km)",
|
|
"importance": 0.35
|
|
},
|
|
{
|
|
"name": "重量(kg)",
|
|
"importance": 0.25
|
|
}
|
|
],
|
|
"correlation_analysis": {
|
|
"features": ["最大射程(km)", "重量(kg)"],
|
|
"matrix": [[1.0, 0.8], [0.8, 1.0]]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 6. 模型训练
|
|
|
|
训练新的模型。
|
|
|
|
- **URL**: `/train`
|
|
- **方法**: `POST`
|
|
- **请求体示例**:
|
|
|
|
```json
|
|
{
|
|
"type": "巡飞弹",
|
|
"train_dataset_id": 1,
|
|
"validation_dataset_id": 2,
|
|
"models": ["xgboost", "lightgbm", "rf"]
|
|
}
|
|
```
|
|
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"metrics": {
|
|
"xgboost": {
|
|
"train": {
|
|
"r2": 0.95,
|
|
"mae": 5000.0,
|
|
"rmse": 7500.0
|
|
},
|
|
"validation": {
|
|
"r2": 0.92,
|
|
"mae": 5500.0,
|
|
"rmse": 8000.0
|
|
}
|
|
}
|
|
},
|
|
"best_model": {
|
|
"type": "xgboost",
|
|
"r2": 0.92,
|
|
"mae": 5500.0,
|
|
"rmse": 8000.0
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7. 数据集管理
|
|
|
|
#### 7.1 获取数据集列表
|
|
|
|
- **URL**: `/datasets`
|
|
- **方法**: `GET`
|
|
- **响应示例**:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "训练数据集",
|
|
"description": "用于训练的数据集",
|
|
"equipment_type": "巡飞弹",
|
|
"equipment_count": 10,
|
|
"equipment_names": ["设备1", "设备2"],
|
|
"purpose": "训练",
|
|
"created_at": "2024-11-11T10:00:00"
|
|
}
|
|
]
|
|
```
|
|
|
|
#### 7.2 获取数据集详情
|
|
|
|
- **URL**: `/datasets/{id}`
|
|
- **方法**: `GET`
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"name": "训练数据集",
|
|
"description": "用于训练的数据集",
|
|
"equipment_type": "巡飞弹",
|
|
"purpose": "训练",
|
|
"created_at": "2024-11-11T10:00:00",
|
|
"equipment": [
|
|
{
|
|
"id": 1,
|
|
"name": "设备1",
|
|
"type": "巡飞弹",
|
|
"manufacturer": "制造商1",
|
|
"actual_cost": 150000
|
|
}
|
|
],
|
|
"statistics": {
|
|
"equipment_count": 10,
|
|
"total_cost": 1500000,
|
|
"average_cost": 150000
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 7.3 创建数据集
|
|
|
|
- **URL**: `/datasets`
|
|
- **方法**: `POST`
|
|
- **请求体示例**:
|
|
|
|
```json
|
|
{
|
|
"name": "测试数据集",
|
|
"description": "用于测试的数据集",
|
|
"equipment_type": "巡飞弹",
|
|
"purpose": "训练",
|
|
"equipment_ids": [1, 2, 3]
|
|
}
|
|
```
|
|
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"id": 2,
|
|
"message": "数据集创建成功"
|
|
}
|
|
```
|
|
|
|
#### 7.4 更新数据集
|
|
|
|
- **URL**: `/datasets/{id}`
|
|
- **方法**: `PUT`
|
|
- **请求体示例**:
|
|
|
|
```json
|
|
{
|
|
"name": "更新后的数据集名称",
|
|
"description": "更新后的描述",
|
|
"equipment_type": "巡飞弹",
|
|
"purpose": "验证",
|
|
"equipment_ids": [1, 2, 3, 4]
|
|
}
|
|
```
|
|
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "数据集更新成功"
|
|
}
|
|
```
|
|
|
|
#### 7.5 删除数据集
|
|
|
|
- **URL**: `/datasets/{id}`
|
|
- **方法**: `DELETE`
|
|
- **描述**: 删除指定的数据集及其关联关系
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "数据集删除成功"
|
|
}
|
|
```
|
|
|
|
注意事项：
|
|
|
|
1. 数据集删除后不会删除关联的装备数据
|
|
2. 不能删除正在被模型使用的数据集
|
|
3. 更新数据集时会重新计算统计信息
|
|
4. 数据集的装备类型一旦创建后不能更改
|
|
|
|
### 8. 模型管理
|
|
|
|
#### 8.1 获取模型列表
|
|
|
|
- **URL**: `/models`
|
|
- **方法**: `GET`
|
|
- **响应示例**:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": 1,
|
|
"model_name": "巡飞弹_xgboost_model",
|
|
"model_type": "xgboost",
|
|
"equipment_type": "巡飞弹",
|
|
"r2_score": 0.95,
|
|
"mae": 5000.0,
|
|
"rmse": 7500.0,
|
|
"is_active": true,
|
|
"training_date": "2024-11-11T10:00:00"
|
|
}
|
|
]
|
|
```
|
|
|
|
#### 8.2 获取最新模型
|
|
|
|
- **URL**: `/models/{equipment_type}/latest`
|
|
- **方法**: `GET`
|
|
- **响应示例**: 与模型列表的单个模型格式相同
|
|
|
|
#### 8.3 获取模型详情
|
|
|
|
- **URL**: `/models/{id}`
|
|
- **方法**: `GET`
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"model_name": "巡飞弹_xgboost_model",
|
|
"model_type": "xgboost",
|
|
"equipment_type": "巡飞弹",
|
|
"r2_score": 0.95,
|
|
"mae": 5000.0,
|
|
"rmse": 7500.0,
|
|
"is_active": true,
|
|
"training_date": "2024-11-11T10:00:00",
|
|
"feature_importance": {
|
|
"max_range_km": 0.35,
|
|
"weight_kg": 0.25,
|
|
"length_m": 0.20
|
|
},
|
|
"training_data_size": 100,
|
|
"created_by": "system"
|
|
}
|
|
```
|
|
|
|
#### 8.4 激活模型
|
|
|
|
- **URL**: `/models/{id}/activate`
|
|
- **方法**: `POST`
|
|
- **描述**: 激活指定模型，同时会将同类型的其他模型设置为非激活状态
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "模型已激活"
|
|
}
|
|
```
|
|
|
|
#### 8.5 删除模型
|
|
|
|
- **URL**: `/models/{id}`
|
|
- **方法**: `DELETE`
|
|
- **描述**: 删除指定模型，包括模型文件和数据库记录
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "模型已删除"
|
|
}
|
|
```
|
|
|
|
注意事项：
|
|
|
|
1. 删除模型时会同时删除相关的文件和数据库记录
|
|
2. 不能删除当前正在使用（已激活）的模型
|
|
3. 激活模型时会自动取消同类型其他模型的激活状态
|
|
4. 模型详情包含了更多的训练相关信息，如特征重要性等
|
|
|
|
### 9. 数据管理
|
|
|
|
#### 9.1 获取装备数据列表
|
|
|
|
- **URL**: `/data`
|
|
- **方法**: `GET`
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"rocket_artillery": [
|
|
{
|
|
"id": 1,
|
|
"name": "BM-21",
|
|
"type": "火箭炮",
|
|
"manufacturer": "俄罗斯",
|
|
"length_m": 7.35,
|
|
"width_m": 2.4,
|
|
"height_m": 3.1,
|
|
"weight_kg": 13700,
|
|
"max_range_km": 20.4,
|
|
"actual_cost": 800000
|
|
}
|
|
],
|
|
"loitering_munition": [
|
|
{
|
|
"id": 8,
|
|
"name": "Hero-120",
|
|
"type": "巡飞弹",
|
|
"manufacturer": "以色列",
|
|
"length_m": 1.3,
|
|
"width_m": 0.23,
|
|
"height_m": 0.23,
|
|
"weight_kg": 12.5,
|
|
"max_range_km": 40,
|
|
"actual_cost": 150000
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### 9.2 获取装备详情
|
|
|
|
- **URL**: `/data/details/{id}`
|
|
- **方法**: `GET`
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"id": 8,
|
|
"name": "Hero-120",
|
|
"type": "巡飞弹",
|
|
"manufacturer": "以色列",
|
|
"common_params": {
|
|
"length_m": 1.3,
|
|
"width_m": 0.23,
|
|
"height_m": 0.23,
|
|
"weight_kg": 12.5,
|
|
"max_range_km": 40
|
|
},
|
|
"specific_params": {
|
|
"wingspan_m": 2.1,
|
|
"warhead_weight_kg": 3.5,
|
|
"max_speed_ms": 50,
|
|
"cruise_speed_kmh": 100,
|
|
"flight_time_min": 60,
|
|
"warhead_type": "破片杀伤战斗部",
|
|
"launch_mode": "箱式发射",
|
|
"power_system": "电动机",
|
|
"guidance_system": "GPS/INS"
|
|
},
|
|
"cost_data": {
|
|
"actual_cost": 150000,
|
|
"prediction_date": "2024-11-11T10:00:00",
|
|
"predicted_cost": 148000
|
|
},
|
|
"custom_params": [
|
|
{
|
|
"id": 1,
|
|
"param_name": "续航时间",
|
|
"param_value": "2小时",
|
|
"param_unit": "小时",
|
|
"description": "最大续航时间"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### 9.3 更新装备数据
|
|
|
|
- **URL**: `/data/{id}`
|
|
- **方法**: `PUT`
|
|
- **请求体示例**:
|
|
|
|
```json
|
|
{
|
|
"name": "Hero-120",
|
|
"manufacturer": "以色列",
|
|
"length_m": 1.3,
|
|
"width_m": 0.23,
|
|
"height_m": 0.23,
|
|
"weight_kg": 12.5,
|
|
"max_range_km": 40,
|
|
"wingspan_m": 2.1,
|
|
"warhead_weight_kg": 3.5,
|
|
"max_speed_ms": 50,
|
|
"cruise_speed_kmh": 100,
|
|
"flight_time_min": 60,
|
|
"actual_cost": 150000,
|
|
"custom_params": [
|
|
{
|
|
"id": 1,
|
|
"param_value": "2.5小时"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "装备数据更新成功"
|
|
}
|
|
```
|
|
|
|
#### 9.4 删除装备数据
|
|
|
|
- **URL**: `/data/{id}`
|
|
- **方法**: `DELETE`
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "装备数据删除成功"
|
|
}
|
|
```
|
|
|
|
#### 9.5 下载数据模板
|
|
|
|
- **URL**: `/data/template`
|
|
- **方法**: `GET`
|
|
- **描述**: 下载Excel格式的数据导入模板
|
|
- **响应**: Excel文件下载
|
|
|
|
#### 9.6 导入数据
|
|
|
|
- **URL**: `/data/import`
|
|
- **方法**: `POST`
|
|
- **请求体**:
|
|
- Content-Type: multipart/form-data
|
|
- 参数名: file
|
|
- 文件类型: .xlsx 或 .xls
|
|
- **响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "数据导入成功",
|
|
"imported_count": {
|
|
"rocket_artillery": 3,
|
|
"loitering_munition": 5
|
|
}
|
|
}
|
|
```
|
|
|
|
注意事项：
|
|
|
|
1. 导入数据时必须使用系统提供的模板
|
|
2. 更新装备数据时会同时更新关联的参数表
|
|
3. 删除装备数据会同时删除相关的参数和成本数据
|
|
4. 导入的Excel文件大小不应超过10MB
|
|
5. 所有数值字段必须符合指定的单位和范围要求
|
|
6. 特殊参数的值必须包含单位信息
|
|
|
|
## 错误响应
|
|
|
|
所有接口在发生错误时都会返回以下格式的响应：
|
|
|
|
```json
|
|
{
|
|
"error": "错误描述信息"
|
|
}
|
|
```
|
|
|
|
## 注意事项
|
|
|
|
1. 所有数值参数必须大于0
|
|
2. 所有单位必须按照参数名称中指定的单位提供
|
|
3. 预测结果中的成本单位为元
|
|
4. 置信区间表示预测结果的95%置信水平范围
|
|
5. 所有请求和响应的编码均为 UTF-8
|