ANHSIRKKK/fraud-detection-pipeline

# 监督学习 — 欺诈检测 Pipeline [](https://www.python.org/) [](LICENSE) [](tests/) ## 🎯 目标 机器学习模型天生具有“惰性”：当合法交易占总交易量的 99.83% 以上时，简单的全局误差最小化会驱使模型在每次预测时都简单地输出“合法”——在抓获 **零** 欺诈的情况下获得 99.83% 的准确率。本项目致力于构建并调优一个分类模型，以捕获罕见的 0.17% 欺诈行为，使用方法包括： - ✅ **SMOTE**（合成少数类过采样技术，Synthetic Minority Over-sampling）处理极端的类别不平衡问题 - ✅ **Logistic Regression** 和 **Random Forest**，通过 Scikit-Learn 进行训练 - ✅ 严格的 **Precision、Recall 和 ROC-AUC** 评估 —— 绝不报告 accuracy - ✅ **零泄漏（zero-leakage）** 的 pipeline 架构（`imblearn.pipeline.Pipeline`，分层划分，且重采样仅作用于训练折） ## 🧱 陷阱 1：准确率的错觉 | | 预测为合法 | 预测为欺诈 | |---|---|---| | **实际为合法** | True Negative | False Positive | | **实际为欺诈** | **False Negative** ⚠️ | True Positive | 一个将所有交易都分类为合法的模型，在造成灾难性财务损失（100% False Negatives）的同时，却能获得近乎完美的准确率。本项目完全摒弃了 accuracy，转而采用以下指标： | 指标 | 公式 | 它回答的问题 | |---|---|---| | **Precision** | `TP / (TP + FP)` | 当我们标记为欺诈时，我们判断对了吗？（最小化误判拒付） | | **Recall** | `TP / (TP + FN)` | 我们是否抓住了所有的欺诈行为？（漏掉欺诈 = 直接财务损失） | | **ROC-AUC** | ROC 曲线下面积 | 模型能否总体上将合法分布与欺诈分布区分开来？ | ## 🧱 陷阱 2：数据泄漏灾难 在划分训练集/测试集之前，对 *整个* 数据集应用 SMOTE（或缩放器），意味着测试集是在已经“知道”训练答案的合成数据上进行评估的——这会让所有指标虚高，产生虚假的自信心。 **本项目绝不这样做。** 相反，我们的做法是： ``` Raw Imbalanced Data → Stratified Split → [ Scaler(if LR) → SMOTE → Model ] → GridSearchCV → Final Evaluation └────────── imblearn Pipeline ──────────┘ (re-fit fresh on every CV training fold only) ``` - `sklearn.pipeline.Pipeline` 在这里会 **静默失败** —— 它期望 `transform()` 方法仅修改 `X`，因此同时修改 `y` 的重采样器会被忽略或导致崩溃。 - `imblearn.pipeline.Pipeline` 是生产标准：它原生支持 `fit_resample`，严格地仅在训练折上正确修改 `X` 和 `y`。 ## 🏗️ 架构 ``` ├── src/ │ ├── generate_raw_data.py # Synthetic fraud dataset (mirrors 0.17% real-world rate) │ ├── preprocessing.py # Stratified split (Zero-Leakage Protocol entrypoint) │ ├── model_pipeline.py # imblearn Pipelines: Scaler+SMOTE+LR, and SMOTE+RandomForest │ ├── evaluation.py # Precision/Recall/F1/ROC-AUC — accuracy is never reported │ └── pipeline.py # Orchestrator: GridSearchCV -> evaluate -> save best model ├── notebooks/ │ └── 01_fraud_detection_pipeline.ipynb # Full walkthrough with plots & threshold tuning ├── tests/ │ └── test_pipeline.py # Unit tests for every stage, incl. a leakage regression test ├── models/ # Saved best model (best_fraud_model.joblib) ├── data/ │ ├── raw/ # Synthetic raw transactions │ └── processed/ # Model comparison table + metrics.json └── reports/figures/ # Class distribution, ROC/PR curves, confusion matrices ``` ### 选择预测引擎 | 模型 | 速度与可解释性 | 对缩放的敏感性 | 决策边界 | |---|---|---|---| | Logistic Regression | 高（系数具有透明度） | **无缩放器时是致命的** —— 正则化惩罚会被巨大的交易金额方差扭曲 | 线性 | | Random Forest | 较慢（集成逻辑），中等可解释性 | **免疫** —— 分裂是有序的特征划分，不受尺度影响 | 高度复杂的非线性 | ### 验证的黄金法则 绝不能让验证折暴露于缩放或重采样操作中。`GridSearchCV` 会在每次折计算中、针对每一个超参数组合（包括 SMOTE 自身的 `k_neighbors`）安全地应用 SMOTE —— 确保在超参数调优期间实现零泄漏。 ## 🚀 快速开始 ``` # 克隆并设置环境 git clone https://github.com//fraud-detection-pipeline.git cd fraud-detection-pipeline python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt # 生成 synthetic raw 数据集 python src/generate_raw_data.py # 运行完整的 leak-free training + evaluation pipeline python src/pipeline.py # 运行 test suite pytest -v # （可选）探索 notebook jupyter notebook notebooks/01_fraud_detection_pipeline.ipynb ``` ### Pipeline 输出示例 ``` [INPUT] Loading data from data/raw/credit_card_transactions.csv shape: (15000, 23) fraud rate: 0.167% [SPLIT] train=12,000 (fraud=0.167%) test=3,000 (fraud=0.167%) -> Stratified split preserves the real-world imbalance in both partitions. -> SMOTE has NOT been applied yet. It will only ever touch X_train, inside CV folds. [MODEL] logistic_regression best CV ROC-AUC: 0.8262 best params: {'classifier__C': 0.01, 'smote__k_neighbors': 5} TEST precision=0.0214 recall=0.8000 f1=0.0417 roc_auc=0.9310 [MODEL] random_forest best CV ROC-AUC: 0.9198 best params: {'classifier__max_depth': 10, 'classifier__n_estimators': 150, 'smote__k_neighbors': 5} TEST precision=0.0000 recall=0.0000 f1=0.0000 roc_auc=0.9594 [COMPARISON] precision recall f1 roc_auc average_precision model random_forest 0.0000 0.0 0.0000 0.9594 0.0261 logistic_regression 0.0214 0.8 0.0417 0.9310 0.4674 [BEST MODEL] random_forest (highest test ROC-AUC) ``` ### 💡 本仓库中最重要的一课 请注意，**Random Forest 在 ROC-AUC（0.96）上胜出，但在默认的 0.5 概率阈值下却抓获了零欺诈。** ROC-AUC 衡量的是跨 *所有* 阈值的排序能力 —— 它并不能保证默认的截断点是解决 0.17% 发生率问题的良好操作点。 Notebook 中的阈值调优部分（`notebooks/01_fraud_detection_pipeline.ipynb`, §8）扫描 Precision-Recall 曲线，并选择一个深思熟虑的操作阈值，而不是盲目相信 `.predict()` 默认的 0.5 截断点 —— 这正是现实中的反欺诈团队必须明确做出的那种业务判断。 ## 🧪 测试 ``` pytest -v ``` 覆盖范围：分层划分比例的保留、两个 pipeline 的正确拟合/预测、确认 SMOTE 绝不会膨胀测试集大小的回归测试（即它绝不触碰推理时的数据）、评估指标的形状/边界检查，以及对 **绝不报告 accuracy** 的显式断言。 ## 🔑 展示的核心技能 分类算法 · Scikit-Learn pipeline · `imbalanced-learn` (SMOTE) · 不平衡数据处理 · `GridSearchCV` 超参数调优 · 无泄漏交叉验证设计 · Precision/Recall/ROC-AUC 评估 · 阈值调优 · 单元测试 ## 📌 备注 - 原始数据集 (`data/raw/credit_card_transactions.csv`) 由 `src/generate_raw_data.py` 使用固定随机种子合成生成，映射了训练简报中引用的经典真实基准的结构（`Time`, `V1..V20`, `Amount`, `Class`）以及精确的约 0.17% 欺诈率，无需下载或重新分发该数据集。 - 数据集大小和 Random Forest 超参数网格有意设置得相对适中，以便整个 pipeline 在单核 CPU 上几分钟内即可运行完毕；如果你有更多可用的核心，可以在 `src/model_pipeline.py` 中拓宽 `RANDOM_FOREST_PARAM_GRID`。 - 欺诈/合法类别的分离被有意设定为仅具有中等程度的可分性，因此各项指标是符合现实的（而不是轻易达到 100% 的分离），并且 ROC-AUC 与阈值的课程教训依然成立。 ## 📄 许可证 本项目基于 [MIT 许可证](LICENSE) 授权。 *作为数据科学工业实训套件 (Data Science Industrial Training Kit) 的一部分构建，2026 届。*

标签：Apex, NoSQL, Scikit-Learn, 分类模型, 安全规则引擎, 数据科学, 数据预处理, 机器学习, 欺诈检测, 资源验证, 逆向工具