tian/CostPrediction

Fork 0

Tian jianyong 30d4b58cdf 增加了部署文档，调整了前端代码

2024-11-11 18:04:22 +08:00

13 KiB

Raw Blame History

装备成本估算系统 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
请求体示例 (巡飞弹):

{
    "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": "凭自身动力起飞"
}

响应示例:

{
    "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
请求体: 与单模型预测相同
响应示例:

{
    "predicted_cost": 148000.0,
    "confidence_interval": {
        "lower": 133000.0,
        "upper": 163000.0
    }
}

4. 多模型预测

使用所有激活的模型进行预测并返回综合结果。

URL: /predict/all
方法: POST
请求体: 与单模型预测相同
响应示例:

{
    "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
请求体示例:

{
    "dataset_id": 1,
    "equipment_type": "巡飞弹"
}

响应示例:

{
    "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
请求体示例:

{
    "type": "巡飞弹",
    "train_dataset_id": 1,
    "validation_dataset_id": 2,
    "models": ["xgboost", "lightgbm", "rf"]
}

响应示例:

{
    "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
响应示例:

[
    {
        "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
响应示例:

{
    "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
请求体示例:

{
    "name": "测试数据集",
    "description": "用于测试的数据集",
    "equipment_type": "巡飞弹",
    "purpose": "训练",
    "equipment_ids": [1, 2, 3]
}

响应示例:

{
    "id": 2,
    "message": "数据集创建成功"
}

7.4 更新数据集

URL: /datasets/{id}
方法: PUT
请求体示例:

{
    "name": "更新后的数据集名称",
    "description": "更新后的描述",
    "equipment_type": "巡飞弹",
    "purpose": "验证",
    "equipment_ids": [1, 2, 3, 4]
}

响应示例:

{
    "success": true,
    "message": "数据集更新成功"
}

7.5 删除数据集

URL: /datasets/{id}
方法: DELETE
描述: 删除指定的数据集及其关联关系
响应示例:

{
    "success": true,
    "message": "数据集删除成功"
}

注意事项：

数据集删除后不会删除关联的装备数据
不能删除正在被模型使用的数据集
更新数据集时会重新计算统计信息
数据集的装备类型一旦创建后不能更改

8. 模型管理

8.1 获取模型列表

URL: /models
方法: GET
响应示例:

[
    {
        "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
响应示例:

{
    "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
描述: 激活指定模型，同时会将同类型的其他模型设置为非激活状态
响应示例:

{
    "success": true,
    "message": "模型已激活"
}

8.5 删除模型

URL: /models/{id}
方法: DELETE
描述: 删除指定模型，包括模型文件和数据库记录
响应示例:

{
    "success": true,
    "message": "模型已删除"
}

注意事项：

删除模型时会同时删除相关的文件和数据库记录
不能删除当前正在使用（已激活）的模型
激活模型时会自动取消同类型其他模型的激活状态
模型详情包含了更多的训练相关信息，如特征重要性等

9. 数据管理

9.1 获取装备数据列表

URL: /data
方法: GET
响应示例:

{
    "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
响应示例:

{
    "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
请求体示例:

{
    "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小时"
        }
    ]
}

响应示例:

{
    "success": true,
    "message": "装备数据更新成功"
}

9.4 删除装备数据

URL: /data/{id}
方法: DELETE
响应示例:

{
    "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
响应示例:

{
    "success": true,
    "message": "数据导入成功",
    "imported_count": {
        "rocket_artillery": 3,
        "loitering_munition": 5
    }
}

注意事项：

导入数据时必须使用系统提供的模板
更新装备数据时会同时更新关联的参数表
删除装备数据会同时删除相关的参数和成本数据
导入的Excel文件大小不应超过10MB
所有数值字段必须符合指定的单位和范围要求
特殊参数的值必须包含单位信息

错误响应

所有接口在发生错误时都会返回以下格式的响应：

{
    "error": "错误描述信息"
}

注意事项

所有数值参数必须大于0
所有单位必须按照参数名称中指定的单位提供
预测结果中的成本单位为元
置信区间表示预测结果的95%置信水平范围
所有请求和响应的编码均为 UTF-8

13 KiB Raw Blame History

装备成本估算系统 API 文档

基本信息

API 端点列表

1. 获取 API 信息

2. 单模型预测

3. PLS 模型预测

4. 多模型预测

5. 特征分析

6. 模型训练

7. 数据集管理

7.1 获取数据集列表

7.2 获取数据集详情

7.3 创建数据集

7.4 更新数据集

7.5 删除数据集

8. 模型管理

8.1 获取模型列表

8.2 获取最新模型

8.3 获取模型详情

8.4 激活模型

8.5 删除模型

9. 数据管理

9.1 获取装备数据列表

9.2 获取装备详情

9.3 更新装备数据

9.4 删除装备数据

9.5 下载数据模板

9.6 导入数据

错误响应

注意事项

13 KiB

Raw Blame History