Mark007-R/Sentinel
GitHub: Mark007-R/Sentinel
一个基于 DVC 与 XGBoost 的端到端支付交易欺诈检测项目，解决数据可重现建模与实时预测问题。
Stars: 0 | Forks: 0
# SENTINEL 欺诈检测
端到端欺诈检测项目，用于支付交易，包含：
- 使用 DVC 的可重现机器学习流水线
- XGBoost 模型训练与评估
- 可选的亚马逊欺诈数据集基准（FDB）集成
- 多页面 Streamlit 仪表盘，用于预测与分析
## 本项目的作用
SENTINEL 将 PaySim 和 Sparkov 风格的交易数据整合到统一模式中，构建面向欺诈的特征，训练 XGBoost 分类器，评估性能，并与已发布的基准进行对比。
该仓库包含：
- 命令行流水线阶段（位于 src/）
- 用于交互式使用的 Streamlit 应用（app.py + pages/）
## 主要特性
- 带有依赖跟踪和可重现输出的 DVC 流水线
- PaySim 与 Sparkov 变体的统一模式映射
- 针对金额、时间与余额行为的特征工程
- 使用 params.yaml 中可配置超参数的 XGBoost 训练
- 指标与报告工件（评分 + SVG 混淆矩阵与 ROC 曲线）
- 单笔与批量欺诈预测（命令行 + 界面）
- 可选的 FDB 基准对比输出（JSON 格式）
## 仓库结构
```
Sentinel/
|-- app.py
|-- dvc.yaml
|-- params.yaml
|-- requirements.txt
|-- Readme.md
|-- src/
| |-- config.py
| |-- load_fdb.py
| |-- combine_datasets.py
| |-- preprocess.py
| |-- train.py
| |-- evaluate.py
| |-- predict.py
| `-- benchmark_fdb.py
|-- pages/
| |-- 1_Predict.py
| |-- 2_Performance.py
| `-- 3_Transactions.py
|-- data/
| |-- raw/
| `-- processed/
|-- models/
|-- metrics/
`-- notebooks/
```
## 数据流程
```
data/raw/paysim.csv + data/raw/sparkov.csv
|
v
src/combine_datasets.py
|
v
data/processed/combined_transactions.csv
|
v
src/preprocess.py
|
v
data/processed/features.csv
|
v
src/train.py -----------------------------> models/fraud_model.pkl
| data/processed/X_test.csv
| data/processed/y_test.csv
v
src/evaluate.py --------------------------> metrics/scores.json
reports/confusion_matrix.svg
reports/roc_curve.svg
(optional)
src/benchmark_fdb.py --------------------> metrics/fdb_benchmark.json
```
## 流水线阶段（DVC）
在 dvc.yaml 中定义：
1. load_fdb
- 脚本：src/load_fdb.py
- 用途：从 FDB 获取 Sparkov 训练集（支持本地回退）
- 输出：data/raw/sparkov.csv
2. combine
- 脚本：src/combine_datasets.py
- 用途：将 PaySim 与 Sparkov 列归一化至统一模式并洗牌
- 输出：data/processed/combined_transactions.csv
3. preprocess
- 脚本：src/preprocess.py
- 用途：构建模型特征并对类别变量进行独热编码
- 输出：data/processed/features.csv
4. train
- 脚本：src/train.py
- 用途：训练 XGBoost 模型并保留留出测试集
- 输出：models/fraud_model.pkl、data/processed/X_test.csv、data/processed/y_test.csv
5. evaluate
- 脚本：src/evaluate.py
- 用途：计算指标并生成报告可视化
- 指标：metrics/scores.json
- 图表：reports/confusion_matrix.svg、reports/roc_curve.svg
6. benchmark_fdb
- 脚本：src/benchmark_fdb.py
- 用途：将模型 AUC 与固定基准引用进行比较
- 指标：metrics/fdb_benchmark.json
## 安装
### 前置条件
- Python 3.9+
- Git
- DVC
### 设置
```
git clone
cd Sentinel
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
可选（用于 FDB 集成）：
```
pip install git+https://github.com/amazon-science/fraud-dataset-benchmark.git
```
## 运行项目
### 运行完整 DVC 流水线
```
dvc repro
```
### 运行单个阶段
```
dvc repro load_fdb
dvc repro combine
dvc repro preprocess
dvc repro train
dvc repro evaluate
dvc repro benchmark_fdb
```
### 直接运行脚本
```
python src/load_fdb.py
python src/combine_datasets.py
python src/preprocess.py
python src/train.py
python src/evaluate.py
python -m src.benchmark_fdb
```
## 推理
### 命令行预测
单笔交易 JSON：
```
python src/predict.py --input-json "{\"amount\":250000,\"transaction_type\":\"TRANSFER\",\"hour_of_day\":2,\"day_of_month\":14,\"balance_change_orig\":240000,\"balance_ratio\":0.05,\"has_balance_info\":1,\"source\":\"paysim\"}"
```
批量 CSV：
```
python src/predict.py --input-csv data/processed/X_test.csv --output-csv predictions.csv
```
## Streamlit 仪表盘
启动：
```
streamlit run app.py
```
页面：
- 首页（概览与关键指标）
- 欺诈预测（单笔输入 + 批量 CSV 上传）
- 性能（指标仪表盘与图表）
- 交易（特征探索与相关性）
## 配置
所有主要配置位于 params.yaml。
重要部分：
- data：数据/模型路径
- fdb：FDB 数据集键与缓存设置
- combine：PaySim/Sparkov 合并路径
- preprocess：特征输入/输出
- train：模型超参数与切分设置
- evaluate：指标/报告输出路径
- benchmark：基准输出路径
## 输出
流水线生成的主要工件：
- data/processed/combined_transactions.csv
- data/processed/features.csv
- data/processed/X_test.csv
- data/processed/y_test.csv
- models/fraud_model.pkl
- metrics/scores.json
- metrics/fdb_benchmark.json
- reports/confusion_matrix.svg
- reports/roc_curve.svg
## 当前指标快照
来自本工作区的 metrics/scores.json：
- 精确率：0.3370
- 召回率：0.9622
- F1 分数：0.4992
- 准确率：0.9960
- AUC-ROC：0.9990
- 平均精确率：0.8628
解读：
- 高召回率与 AUC 表明强大的排序/检测能力
- 较低精确率表示在默认阈值下存在较多假阳性
## 注意事项与限制
- 默认阈值 0.5 下精确率较低（0.34），表明存在大量假阳性；调整分类阈值可在召回率下降的情况下提升精确率。
- FDB 基准阶段需要可选的 `fraud-dataset-benchmark` 包，若不可用将回退到本地 Sparkov 数据。
## 常用命令
```
dvc metrics show
dvc params diff
dvc metrics diff
```
## 技术栈
- Python、pandas、numpy
- scikit-learn、XGBoost、imbalanced-learn
- DVC
- Streamlit、Plotly、Altair
-（可选）亚马逊欺诈数据集基准
## 许可证
本项目根据 MIT 许可证授权。
SPDX 标识符：MIT
版权 (c) 2026 Rodrigues Mark Oliver
特此授予任何人免费获取本软件及相关文档文件的权利，以在不受限制的情况下处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再授权和/或出售副本的权利。
请在 LICENSE 文件中查看完整许可证文本。
标签：Amazon Fraud Dataset, Apex, Dask, DVC, FDB, Kubernetes, params.yaml, PaySim, ROC曲线, Sparkov, Streamlit, XGBoost, 交易分析, 参数配置, 反欺诈系统, 可重现管道, 命令行管道, 实时预测, 实验跟踪, 批量预测, 指标报告, 支付风控, 数字支付, 数据版本控制, 数据预处理, 机器学习, 模型版本化, 模型评估, 欺诈检测, 混淆矩阵, 特征工程, 统一数据schema, 自动化特征工程, 访问控制, 逆向工具