# suanfa

**Repository Path**: mellen/suanfa

## Basic Information

- **Project Name**: suanfa
- **Description**: 机器学习算法训练，可以用页面来训练xgboost算法

- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Open-Start 模型训练平台

基于 Java + Spring Boot + XGBoost 的机器学习模型训练与部署平台。

## 功能特性

- **数据管理**: 支持 CSV、Excel、JSON、数据库、HTTP API 等多数据源导入
- **特征选择**: 百万级特征的可视化筛选和管理，支持分页查询
- **标签管理**: 独立的标签管理模块，支持特征批量打标签（多对多关系）
- **模型训练**: 基于 XGBoost 的二分类模型训练，支持超参数调优
- **AutoML**: 网格搜索、随机搜索、贝叶斯优化，自动寻找最优参数
- **模型管理**: 模型注册、版本管理、部署状态机
- **批量预测**: 对百万客户进行批量评分和筛选
- **效果评估**: AUC、KS、Lift 等核心指标计算和可视化
- **模型部署**: 部署状态机，支持 dev/test/staging/prod 多环境
- **结构化日志**: JSON 格式日志输出，便于日志收集和分析

## 技术栈

| 分类 | 技术 | 版本 |
|------|------|------|
| 后端框架 | Spring Boot | 3.2.11 (LTS) |
| 数据库 | MySQL | 8.x |
| ORM | Spring Data JPA | - |
| 机器学习 | XGBoost4J | 2.1.0 |
| Java 版本 | OpenJDK | 17 |
| 前端框架 | Vue 3 | - |
| UI 组件库 | Element Plus | - |
| 数据处理 | Apache Commons CSV | 1.10.0 |
| JSON 日志 | Logstash Logback Encoder | 7.4 |

## 快速开始

### 1. 环境要求

- JDK 17+
- Maven 3.9+
- MySQL 8.0+
- Node.js 18+ (前端开发)

### 2. 安装 XGBoost4J 依赖

```bash
# macOS
brew install libomp

# Linux (Ubuntu/Debian)
sudo apt-get install libgomp1

# Windows
# XGBoost4J 会自动下载本地库
```

### 3. 数据库初始化

```bash
# 登录 MySQL
mysql -u root -p

# 执行初始化脚本（按顺序）
source src/main/resources/scripts/sql/01-schema.sql
source src/main/resources/scripts/sql/02-seed-data.sql
source src/main/resources/scripts/sql/03-add-source-column.sql
source src/main/resources/scripts/sql/04-add-prediction-data-path.sql
```

### 4. 编译运行

```bash
# 克隆项目
cd credit-marketing-model

# 编译后端
mvn clean package -DskipTests

# 运行后端
java -jar target/credit-marketing-model-2.0.0.jar
```

### 5. 启动前端

```bash
cd frontend
npm install
npm run dev
```

### 6. 访问系统

打开浏览器访问: http://localhost:5173

## 项目结构

```
credit-marketing-model/
├── src/main/java/com/credit/marketing/
│   ├── controller/          # REST API 控制器
│   ├── service/             # 业务逻辑层
│   ├── model/               # 数据模型 (Entity, DTO)
│   ├── repository/           # 数据访问层
│   ├── data/                # 多数据源导入 (CSV/Excel/JSON/Database/HTTP)
│   ├── ml/                 # 机器学习核心 (XGBoost 封装)
│   └── config/             # 配置类
├── src/main/resources/
│   ├── application.yml       # 应用配置
│   ├── application-prod.yml  # 生产配置
│   └── db/                  # 数据库脚本
├── frontend/                # Vue 3 前端
│   └── src/
│       ├── views/           # 页面组件
│       ├── api/             # API 调用
│       ├── stores/          # 状态管理
│       └── types/           # TypeScript 类型
├── scripts/                 # 部署脚本
├── docs/                   # 项目文档
└── pom.xml
```

## 功能模块

### 1. 数据导入 (P0)

支持多种数据源导入：
- **CSV 文件**: 本地 CSV 文件上传
- **Excel 文件**: .xlsx/.xls 文件支持
- **JSON 数据**: JSON 数组或对象导入
- **数据库直连**: MySQL/PostgreSQL 查询
- **HTTP API**: 外部 API 数据拉取

### 2. 特征管理

- 特征展示：表格形式展示所有特征
- 特征选择：勾选要参与训练的特征
- 搜索过滤：按特征名称、描述、类别搜索
- 标签管理：批量打标签（多对多关系）
- 特征统计：按类别统计已选特征数量

### 3. 模型训练

- 参数配置：树数量、学习率、树深度等超参数
- 训练数据：指定训练集和测试集文件路径
- 预测数据：支持独立预测数据集路径（prediction_data_path）
- 任务管理：创建、执行、查看训练任务
- 实时状态：pending/running/completed/failed
- 结果展示：AUC、KS、Lift@10/20/30 等指标

### 4. AutoML 自动调参 (P2)

- **网格搜索 (Grid Search)**: 穷举搜索所有参数组合
- **随机搜索 (Random Search)**: 高效探索参数空间
- **贝叶斯优化 (Bayesian Optimization)**: 智能优化参数选择
- **进度追踪**: 实时查看搜索进度
- **参数导入**: 一键导入最佳参数

### 5. 模型管理 (P1)

- **模型注册**: 创建、编辑、删除模型
- **版本管理**: 版本历史、状态流转
- **版本对比**: 多版本指标对比
- **归档管理**: 历史版本归档

### 6. 模型部署 (P3)

- **部署状态机**: DRAFT → PENDING_REVIEW → APPROVED → DEPLOYING → DEPLOYED → MONITORING
- **环境管理**: dev/test/staging/prod
- **版本控制**: 支持多版本并行
- **一键回滚**: 快速回滚到历史版本

## 使用流程

### 1. 数据上传
- 进入"数据管理"页面
- 选择数据源类型（CSV/Excel/JSON/数据库/HTTP）
- 上传或配置数据连接
- 系统自动导入特征元数据

### 2. 特征选择
- 进入"特征选择"页面
- 支持按类型/类别/标签筛选特征
- 勾选要训练的特征
- 支持分页（20/50/100/200/500条/页）

### 3. 标签管理
- 进入"标签管理"页面
- 创建新标签（如"高价值"、"低风险"等）
- 在特征选择页面选择特征后，可批量绑定/解绑标签
- 标签与特征是多对多关系

### 4. 模型训练
- 进入"模型训练"页面
- 配置训练参数（树数量、学习率、树深度等）
- 指定训练数据和测试数据路径
- 启动训练任务

### 5. AutoML 调参 (可选)
- 进入"AutoML"页面
- 选择搜索策略（网格/随机/贝叶斯）
- 配置参数范围和搜索次数
- 查看搜索进度，导入最佳参数

### 6. 批量预测
- 进入"批量预测"页面
- 选择已训练的模型
- 配置预测数据和筛选阈值
- 启动预测任务
- 导出目标客户名单

### 7. 效果评估
- 进入"效果评估"页面
- 查看 AUC、KS、Lift 等核心指标
- 与原厂商算法结果进行对比

### 8. 模型管理与部署
- 进入"模型管理"页面
- 注册训练好的模型
- 创建版本
- 进入"模型部署"页面
- 提交部署申请
- 审核通过后部署

## API 接口

### 特征管理
- `GET /api/v1/features` - 获取所有特征
- `GET /api/v1/features/paged` - 分页查询特征（支持 search/type/category/tagId 筛选）
- `GET /api/v1/features/categories` - 获取所有类别
- `GET /api/v1/features/selected` - 获取已选特征
- `POST /api/v1/features/selection` - 更新特征选择
- `POST /api/v1/features/tags/batch` - 批量绑定标签
- `DELETE /api/v1/features/tags/batch` - 批量解绑标签

### 标签管理
- `GET /api/v1/tags` - 获取所有标签
- `POST /api/v1/tags` - 创建标签
- `PUT /api/v1/tags/{id}` - 更新标签
- `DELETE /api/v1/tags/{id}` - 删除标签

### 数据导入
- `POST /api/v1/data/upload` - 上传数据文件
- `POST /api/v1/data/import` - 多数据源导入
- `GET /api/v1/data/preview` - 预览数据

### 模型训练
- `POST /api/v1/models` - 创建模型配置
- `GET /api/v1/models` - 获取模型配置列表
- `POST /api/v1/training` - 创建训练任务
- `GET /api/v1/training` - 获取训练任务列表
- `DELETE /api/v1/models/training/{taskId}` - 删除训练任务
- `POST /api/v1/training/{id}/execute` - 执行训练

### 批量预测
- `POST /api/v1/prediction` - 创建预测任务
- `GET /api/v1/prediction` - 获取预测任务列表
- `POST /api/v1/prediction/{id}/execute` - 执行预测
- `GET /api/v1/prediction/{id}/results` - 获取预测结果

### AutoML 自动调参
- `POST /api/v1/automl/run` - 同步执行 AutoML
- `POST /api/v1/automl/run-async` - 异步执行 AutoML
- `POST /api/v1/automl/run-random` - 随机搜索
- `POST /api/v1/automl/run-bayesian` - 贝叶斯优化
- `GET /api/v1/automl/progress/{taskId}` - 进度查询
- `POST /api/v1/automl/cancel/{taskId}` - 取消任务

### 模型管理
- `POST /api/v1/model-management/registries` - 创建模型注册
- `GET /api/v1/model-management/registries` - 获取模型列表
- `GET /api/v1/model-management/registries/{id}` - 获取模型详情
- `PUT /api/v1/model-management/registries/{id}` - 更新模型
- `DELETE /api/v1/model-management/registries/{id}` - 删除模型
- `POST /api/v1/model-management/versions` - 创建版本
- `GET /api/v1/model-management/versions?modelId={id}` - 获取版本列表
- `GET /api/v1/model-management/versions/latest?modelId={id}` - 获取最新版本
- `POST /api/v1/model-management/versions/{id}/archive` - 归档版本
- `POST /api/v1/model-management/versions/{id}/activate` - 激活版本

### 模型部署
- `POST /api/v1/deployments` - 创建部署
- `GET /api/v1/deployments` - 获取部署列表
- `GET /api/v1/deployments/{id}` - 获取部署详情
- `PUT /api/v1/deployments/{id}` - 更新部署配置
- `POST /api/v1/deployments/{id}/submit` - 提交审核
- `POST /api/v1/deployments/{id}/approve` - 批准部署
- `POST /api/v1/deployments/{id}/reject` - 拒绝部署
- `POST /api/v1/deployments/{id}/deploy` - 开始部署
- `POST /api/v1/deployments/{id}/undeploy` - 下架
- `POST /api/v1/deployments/{id}/archive` - 归档
- `GET /api/v1/deployments/stats` - 部署统计

## 数据格式

### 训练数据 CSV 格式
```csv
customer_id,feature1,feature2,...,featureN,label
C001,0.5,0.3,...,0.8,1
C002,0.2,0.7,...,0.1,0
...
```

### 预测数据 CSV 格式
```csv
customer_id,feature1,feature2,...,featureN
C001,0.5,0.3,...,0.8
C002,0.2,0.7,...,0.1
...
```

## 配置说明

修改 `src/main/resources/application.yml`:

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/suanfa?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: your_password

app:
  data:
    raw-path: data/raw          # 训练数据
    processed-path: data/processed  # 测试数据
    model-path: data/models     # 模型文件路径
```

## 日志配置

系统使用 JSON 格式结构化日志，便于日志收集和分析。

### 日志格式示例

```json
{
  "@timestamp": "2026-03-20T15:30:00.000+08:00",
  "level": "INFO",
  "message": "AutoML任务完成, 试验数=50, 最佳AUC=0.8234",
  "app": "credit-marketing-model",
  "thread": "async-1",
  "logger": "com.credit.marketing.service.AutoMLService"
}
```

### 日志文件

- `${LOG_HOME}/credit-marketing-model.log` - 应用日志
- `${LOG_HOME}/credit-marketing-model-error.log` - 错误日志

### 日志等级说明

| 等级 | 说明 |
|------|------|
| DEBUG | 详细调试信息 |
| INFO | 任务开始/完成/失败记录 |
| WARN | 性能警告 |
| ERROR | 错误信息 |

## 核心算法参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| n_estimators | 树的数量 | 100 |
| learning_rate | 学习率 | 0.1 |
| max_depth | 树的最大深度 | 6 |
| subsample | 样本采样比例 | 0.8 |
| colsample_bytree | 特征采样比例 | 0.8 |

## 评估指标说明

- **AUC**: ROC 曲线下面积，衡量模型区分能力
- **KS**: 最大区分度，KS > 0.3 表示模型有效
- **Lift**: 提升度，衡量营销转化率提升效果
- **Accuracy**: 准确率
- **Precision**: 精确率
- **Recall**: 召回率

## 版本历史

### v2.3.0 (2026-03-23)
- **训练任务重构**: 重构为3个清晰Tab（AutoML自动调参、手动配置、任务训练）
- **参数对齐修复**: 修复数据导入、AutoML、手动配置的参数对齐问题
- **预测数据路径**: 新增 prediction_data_path 字段，支持独立预测数据集
- **历史任务管理**: 新增历史任务分页和删除功能
- **批量对比/删除冲突修复**: 修复选择框自动添加到对比的问题
- **任务详情页修复**: 修复轮询和数据显示问题
- **删除无用预测模块**: 移除 PredictionView.vue 和相关路由

### v2.2.0 (2026-03-22)
- **AutoML 模型文件优化**: 试验过程不保存模型文件，仅最终模型保存
- **数据导入界面重构**: 不同数据源（CSV/Excel/JSON/DATABASE/HTTP_API）显示不同配置表单
- **CSV类型检测修复**: 改用采样100行数据进行类型判断，提高准确性
- **安全修复**: 数据导入功能添加路径验证，防止路径遍历攻击
- **特征导入日志增强**: 导入时记录跳过的重复特征
- **批量标签绑定修复**: 修复批量标签操作后关系未正确持久化的问题
- **前端小修复**: 修复 checkQuality API 调用问题

### v2.1.0 (2026-03-20)
- **P0 数据导入增强**: 支持 CSV、Excel、JSON、数据库直连、HTTP API
- **P1 模型版本管理**: 模型注册、版本管理、归档
- **P2 AutoML**: 网格搜索、随机搜索、贝叶斯优化、进度追踪
- **P3 模型部署**: 部署状态机、环境管理、一键回滚
- **日志增强**: JSON 结构化日志输出
- **单元测试**: ModelManagementServiceTest (16 tests), ModelDeploymentServiceTest (22 tests)
- **冒烟测试**: smoke-test.sh 脚本
- **代码修复**: 修复4个编译错误，完善引用完整性检查

### v2.0.0 (2026-03-19)
- 升级 Spring Boot 2.7 → 3.2.11
- 升级 Java 1.8 → 17
- 升级 XGBoost4J 2.0.3 → 2.1.0
- 新增标签管理功能（多对多关系）
- 重构特征选择为分页查询，支持百万级特征
- 移除 Lombok 依赖

### v1.0.0
- 初始版本

## 许可证

MIT License