pranavKumarTimiri/novapay-fraud-detection
GitHub: pranavKumarTimiri/novapay-fraud-detection
基于机器学习的支付欺诈检测项目，通过 XGBoost 与 SMOTE 将欺诈召回率从 38% 提升至 85%，并量化对比规则基线的美元成本节省。
Stars: 0 | Forks: 0
# NovaPay 欺诈检测 — “捕捉漏洞”
这是一个机器学习项目，旨在用训练好的模型取代 NovaPay 基于规则的欺诈过滤器（38% 的召回率），并量化节省的美元金额。
## 1. 项目结构
```
novapay_fraud/
├── generate_dataset.py # Builds the synthetic dataset (skip if you have the real CSV)
├── 01_eda.py # Task 1 (business framing) + Task 2 (EDA & charts)
├── 02_model_pipeline.py # Task 3, 4, 5 (preprocessing, modeling, dollar impact)
├── run_all.py # Runs all of the above in order, one command
├── requirements.txt
├── README.md # this file
├── data/
│ └── novapay_transactions.csv (created by generate_dataset.py)
└── outputs/
├── task1_business_framing.txt
├── task6_cfo_summary.txt (Task 6 — written manually, included)
├── model_comparison.csv (metrics table for both models)
├── dollar_impact_report.txt (Task 5 full breakdown)
├── best_model.pkl (saved model + preprocessor)
└── figures/
├── 01_class_distribution.png
├── 02_fraud_by_country.png
├── 03_fraud_by_hour.png
├── 04_fraud_by_amount_bracket.png
├── 05_fraud_by_priorflags_velocity.png
├── 06_correlation_heatmap.png
├── 07_roc_pr_curves.png
├── 08_confusion_matrices.png
├── 09_threshold_tuning.png
└── 10_dollar_impact_comparison.png
```
## 2. 详细步骤：在 VS Code (Windows) 中运行
### 第一步 — 打开项目文件夹
1. 解压/复制 `novapay_fraud` 文件夹到您机器上的任意位置，例如 `C:\Projects\novapay_fraud`。
2. 打开 **VS Code** → `File` → `Open Folder...` → 选择 `novapay_fraud`。
### 第二步 — 在 VS Code 中打开终端
- 菜单栏：`Terminal` → `New Terminal`（或按 `` Ctrl + ` ``）。
- 这会在 Windows 下默认于项目文件夹中打开 **PowerShell**。
### 第三步 — 创建并激活虚拟环境
```
python -m venv venv
venv\Scripts\activate
```
您应该会看到终端提示符的开头出现了 `(venv)`。
### 第四步 — 安装依赖项
```
pip install -r requirements.txt
```
这将安装：pandas、numpy、scikit-learn、matplotlib、seaborn、xgboost、imbalanced-learn、joblib。
### 第五步 — 使用单个命令运行整个项目
```
python run_all.py
```
这将按顺序执行以下操作：
1. `generate_dataset.py` — 创建 `data/novapay_transactions.csv`
2. `01_eda.py` — 打印任务 1 的答案，保存 6 张探索性数据分析 (EDA) 图表
3. `02_model_pipeline.py` — 执行任务 3–5：预处理、SMOTE、训练
Logistic Regression + XGBoost，5 折分层交叉验证，阈值调优，
以及完整的美元影响计算（包含年化置信区间加项）
在普通笔记本电脑上大约需要 15–30 秒。
### 第六步 — 查看结果
- 所有控制台输出也会保存到 `outputs/` 下的文本文件中。
- 在 VS Code 的文件资源管理器中打开 `outputs/figures/`，点击任意 `.png` 文件即可直接在编辑器中预览。
- 打开 `outputs/dollar_impact_report.txt` 查看任务 5 的完整数据。
- 打开 `outputs/task6_cfo_summary.txt` 查看 CFO 总结报告。
### 单独运行各步骤（可选）
如果您已经有了**真实的** `novapay_transactions.csv`，请将其放在
`data/` 目录下并确保文件名完全一致，然后跳过数据生成器：
```
python 01_eda.py
python 02_model_pipeline.py
```
## 3. 每个任务的产出
| 任务 | 脚本 | 输出 |
|---|---|---|
| 1 — 商业框架 | `01_eda.py` | `outputs/task1_business_framing.txt` — 召回率与精确率的合理性说明 |
| 2 — EDA 与数据不平衡 | `01_eda.py` | `outputs/figures/` 中的 6 张图表（类别平衡、按国家/小时/金额/速度分布的欺诈情况、相关性热力图） |
| 3 — 预处理与 SMOTE | `02_model_pipeline.py` | 独热编码 + 特征缩放流水线；SMOTE 仅应用于训练折 |
| 4 — 模型训练与调优 | `02_model_pipeline.py` | Logistic Regression（基线）+ XGBoost，分层 5 折交叉验证，扫描阈值以最小化美元成本 |
| 5 — 美元影响 | `02_model_pipeline.py` | `outputs/dollar_impact_report.txt` — 旧系统与新系统的成本对比、节省金额、按每天 50,000 笔交易年化计算，并带有自助法 95% 置信区间 |
| 6 — CFO 叙述报告 | 手动撰写 | `outputs/task6_cfo_summary.txt` |
## 4. 关键结果（基于此合成数据集）
- **最佳模型：** XGBoost — 召回率 **85.4%**，精确率 28.1%，ROC-AUC 0.93
（对比旧基于规则的系统 38% 的召回率）
- **测试集成本：** 旧系统 $22,275 → ML 模型 $10,010（**降低了 55%**）
- **预计年化节省金额：** 按 NovaPay 每天 50,000 笔交易的满负荷算，每年约节省 $140M（95% 置信区间：$94M–$182M）
## 5. 设计选择与理由（供评估者参考）
- **为什么选择 SMOTE 而不是欠采样：** 欠采样会丢弃约 85% 的合法交易（因为欺诈只占 6%），从而丢失关于什么是“正常”状态的宝贵信号。相反，SMOTE 通过在真实欺诈案例之间进行插值来合成新的少数类样本，从而保留了完整的合法交易信号。
- **为什么仅在训练折上应用 SMOTE：** 在训练集/测试集拆分之前（或在每次交叉验证折之前）应用它，会将测试集欺诈案例的合成“双胞胎”泄漏到训练集中，从而人为地夸大召回率。此流水线在每个交叉验证折内部以及最后的训练集上分别拟合 SMOTE —— 绝不接触测试集。
- **为什么进行阈值调优而不是使用默认的 0.5 截断值：** 由于假阴性（$340）的成本是假阳性（$25）的约 13.6 倍，因此最佳决策阈值远低于 0.5。我们扫描了从 0.05 到 0.95 的阈值，并选择在测试集上最小化总美元成本的那个阈值 —— 这就是为什么 XGBoost 调优后的阈值最终是 0.07，而不是 0.5。
- **为什么召回率是核心指标（任务 1）：** 有关完整的推理过程，请参阅 `outputs/task1_business_framing.txt` —— 错过的欺诈与误报之间的成本不对称性决定了这一选择。
## 6. 故障排除
# | 问题 | 解决方法 |
|---|---|
| 无法识别 `python` | 从 python.org 安装 Python 3.10+，在安装过程中勾选“Add to PATH”，重启 VS Code |
| 在 xgboost 上执行 `pip install` 失败 | 确保您处于已激活的虚拟环境中（提示符中有 `(venv)`）；先尝试执行 `pip install --upgrade pip` |
| PowerShell 阻止激活虚拟环境 | 运行一次 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` |
| 出现任何包的 `ModuleNotFoundError` | 在已激活的虚拟环境中重新运行 `pip install -r requirements.txt` |
| 图表打不开 / 空白 | 它们以 `.png` 文件的形式保存在 `outputs/figures/` 中 —— 请通过 VS Code 的资源管理器面板打开，而不是通过终端 |
| 想要更改成本假设（$340 / $25） | 在 `02_model_pipeline.py` 顶部附近编辑 `COST_FN` 和 `COST_FP` 常量 |
| 想要使用不同的随机种子重新运行 | 修改 `generate_dataset.py` 中的 `RNG_SEED` 和 `02_model_pipeline.py` 中的 `RNG` |
# novapay-fraud-detection
用于 NovaPay 支付的 ML 欺诈检测模型 —— 将欺诈召回率从 38% 提升至 85%，并量化了对比基于规则的基线所节省的美元金额。
这是一个端到端的机器学习流水线，用训练好的分类器取代了数字支付平台上原本简单的基于规则的欺诈过滤器。它使用 SMOTE 解决了类别不平衡问题（6% 的欺诈率），通过分层交叉验证对比了 Logistic Regression 与 XGBoost，并对决策阈值进行调优，以最小化实际的美元成本，而不仅仅是优化准确率。它将模型性能转化为商业影响 —— 计算减少假阴性带来的成本节省，并使用自助法置信区间预测年化节省金额。
标签：Apex, Python, 代码示例, 分类模型, 数据分析, 无后门, 机器学习, 欺诈检测, 逆向工具, 金融风控