XGBoost · 登录防欺诈示例

使用 XGBoost 二分类模型识别可疑登录。本项目包含合成 CSV 数据、Flask 后端 JSON API，以及浏览器前端：可浏览数据、调参训练、保存/加载参数预设与模型，并在测试集上评估。

代码下载: Download .

---

内容概览

项目	说明
数据	data/train.csv（200 条）、data/test.csv（20 条）；约 30% 为正样本（is_fraud = 1）
后端	Flask，默认 http://127.0.0.1:5050/ （可用环境变量 PORT 修改端口）
前端	单页 HTML，三个标签页：数据 、训练与调参 、预测
产出	超参数预设保存在 params/，训练好的模型保存在 models/

---

环境要求

• 推荐 Python 3.10+（一般 3.9+ 也可用）
• 已安装 pip

---

安装步骤

在项目根目录（xgboost/）执行：

cd xgboost

# 建议：创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

依赖包括：Flask、XGBoost、NumPy、scikit-learn（用于指标与训练/验证划分）。

---

启动服务

python backend/app.py

浏览器访问：http://127.0.0.1:5050/

更换端口示例：

PORT=8080 python backend/app.py

首次启动时，若缺少 data/train.csv 或 data/test.csv，程序会自动运行数据生成逻辑创建这两个文件。

---

使用流程（网页界面）

在浏览器打开 http://127.0.0.1:5050/ 后，建议按下面顺序操作。

一、「数据」标签页

1. 下拉框选择 训练集（200 条） 或 测试集（20 条）。
2. 若在磁盘上重新生成了 CSV，点击 Reload 刷新表格。
3. 表格中带红色背景的为欺诈样本，绿色偏色的为正常登录。

二、「训练与调参」标签页

1. 修改超参数（页面加载时会填入默认值）：

• 树相关： n_estimators、max_depth、learning_rate
• 采样： subsample、colsample_bytree
• 正则： min_child_weight、gamma、reg_alpha、reg_lambda
• 训练过程： early_stopping_rounds（早停轮数）、val_size（验证集比例）、random_state（随机种子）

1. 点击 Train model 开始训练，等待状态与指标出现。
2. 查看 Training results：

• 准确率、精确率、召回率、F1、ROC-AUC（在可计算时显示）
• 验证集混淆矩阵 （当 val_size > 0 时从训练数据中划出验证集）
• 特征重要度（按增益排序的主要特征）

1. 保存参数预设： 在输入框填写名称（仅允许字母、数字、_、-），点击 Save preset 。下方列表可对预设 Load 或 Delete。
2. 保存模型： 填写模型名称，点击 Save model 。文件写入 models/ 目录（<名称>.json 与 <名称>.meta.json）。
3. 页面底部的 Saved models 可快速跳转预测或删除模型。

三、「预测」标签页

1. Source（来源）： 选择 本会话最后一次训练的模型 ，或下拉选择已保存的 model: xxx。
2. Decision threshold（决策阈值）： 默认 0.5；当预测概率 ≥ 阈值时判为欺诈。
3. 点击 Run prediction 。后端会对 **data/test.csv 中全部行** 打分。
4. 查看 Test-set metrics 与 Confusion matrix。
5. 在 Predictions 表格中查看每条样本：原始字段、真实标签 is_fraud、_probability、_predicted、_correct。预测错误的行会以橙色高亮。

---

可选：重新生成数据

使用内置脚本（脚本内固定随机种子）重新生成训练/测试 CSV：

python backend/data_generator.py

生成后重启服务或在「数据」页点击 Reload。

---

目录结构

xgboost/
├── backend/
│   ├── app.py              Flask 接口
│   └── data_generator.py   合成数据生成
├── frontend/
│   └── index.html          前端页面
├── data/
│   ├── train.csv
│   └── test.csv
├── models/                 已保存的 XGBoost 模型及元数据
├── params/                 已保存的超参数 JSON
├── requirements.txt
├── README.md
└── README_cn.md

---

特征字段说明

字段	含义
username_length、password_length、password_strength	用户名/密码长度与强度
login_hour、login_day_of_week、is_weekend	登录时间模式
ip_country_match、ip_change_count_24h	IP 与地域一致性
failed_login_attempts_24h、captcha_failures	暴力破解 / 验证码失败
typing_speed_cpm、mouse_movement_score	打字与鼠标行为（人机区分）
device_known、user_agent_known、num_devices_used_30d	设备与 UA 指纹
vpn_detected、tor_detected、proxy_detected	VPN / Tor / 代理
account_age_days、num_password_changes_30d	账号历史
geo_distance_km、time_since_last_login_h、avg_session_duration_min	地理位置与会话习惯
is_fraud	标签： 0 正常，1 欺诈

---

HTTP 接口速查

方法	路径	作用
GET	/	网页前端
GET	/api/features	特征列名与标签列
GET	/api/data/train、/api/data/test	返回对应 CSV 的 JSON
GET	/api/params/defaults	默认超参数
POST	/api/train	请求体：{ "params": { ... } }
POST	/api/predict	请求体：{ "use_last": true } 或 { "model": "名称", "threshold": 0.5 }
GET	/api/params/list	列出所有参数预设
POST	/api/params/save	请求体：{ "name": "...", "params": { ... } }
GET	/api/params/load/<name>	加载某一预设
DELETE	/api/params/<name>	删除预设
GET	/api/models/list	列出已保存模型
POST	/api/models/save	请求体：{ "name": "...", "metrics": { ... } }（保存内存中最近一次训练的模型）
DELETE	/api/models/<name>	删除模型文件

命令行示例 --- 使用默认参数训练：

curl -s -X POST http://127.0.0.1:5050/api/train \
  -H 'Content-Type: application/json' \
  -d '{"params":{}}'

命令行示例 --- 用本会话最后一次训练的模型预测测试集：

curl -s -X POST http://127.0.0.1:5050/api/predict \
  -H 'Content-Type: application/json' \
  -d '{"use_last":true,"threshold":0.5}'

---

常见问题

现象	处理建议
端口被占用（Address already in use）	换端口：PORT=8080 python backend/app.py，或结束占用该端口的旧进程。
ModuleNotFoundError	在已激活的虚拟环境中执行 pip install -r requirements.txt。
数据页为空或不是最新	执行 python backend/data_generator.py 后，在「数据」页点 Reload。
预测报错提示没有模型	先在「训练与调参」中训练一次，或在「预测」中选择已保存的模型名称。

---

生产环境说明

当前使用的是 Flask 开发服务器，适合学习与演示。若要在生产环境部署，请使用 Gunicorn 等 WSGI 服务器并结合反向代理，并做好接口鉴权与安全加固。