Khlybtssh/fraud-detection-system

# 欺诈检测系统 一个适用于金融交易的生产级异常检测与欺诈分类系统。 本项目安全地从 Jupyter Notebook pipeline 重构为健壮的 Python 架构，将数据处理、模型训练、artifact 管理以及实时推理系统分离开来。 ## 架构概述 系统采用两个主要模型并行运行来评估交易风险： 1. **异常检测层**：一个 `IsolationForest` 模型，用于识别统计上的异常行为或缺乏历史先例的离群点交易。 2. **欺诈神经网络**：一个通过 `SMOTE` 进行平衡的 PyTorch 深度学习分类器，基于编码特征生成交易欺诈的统计概率。 3. **风险引擎**：一个硬编码的确定性规则引擎，用于根据特定领域的触发条件（例如，夜间活动风险、地理风险）检查交易。允许系统在特殊情况下的模糊 ML 边界上作出判断并覆盖。 这些输出会汇入统一的 **决策层**，以决定交易是 `APPROVE`、`REVIEW` 还是 `DECLINE`。 ### 目录结构 ``` fraud_detection_system/ │ ├── config.py # Centralized hyperparameters & paths ├── main.py # Direct Python entry point for single-transaction inference ├── app.py # FastAPI REST API server for HTTP-based inference │ ├── artifacts/ # Saved output directory for trained ML weights │ ├── anomaly_model.pkl # Fitted IsolationForest instance │ ├── encoders.pkl # Fitted OneHot/Ordinal encoders dict │ ├── model.pt # PyTorch model weights dict │ └── scaler.pkl # Fitted StandardScaler instance │ ├── training_pipeline/ # Executable scripts for dataset ingestion & training │ ├── train.py # Entry script combining pipeline components │ ├── anomaly_training.py # Wrapper for Isolation Forest fits │ ├── dataset.py # PyTorch custom Dataset class │ ├── data_loader.py # pandas loading and explicit column drops │ └── trainer.py # PyTorch optimization loops and validation logic │ ├── inference_pipeline/ # Executable components for evaluating a parsed transaction │ ├── anomaly_scoring.py # Applies fitted Isolation Forest │ ├── fraud_inference.py # Evaluates PyTorch classifier probabilties │ └── model_loader.py # Loads .pkl and .pt weights safely from artifacts │ ├── preprocessing/ # Shared stateless logic ensuring exact parity │ ├── encoding.py # Categorical mapping definitions │ ├── feature_engineering.py # Time, Distance, Haversine, and coordinate parsing │ └── scaling.py # StandardScaler interfaces │ ├── models/ # Network architectures │ └── fraud_nn.py # PyTorch `FraudNN` sequential module │ ├── risk_engine/ # Deterministic evaluators │ ├── rule_engine.py # Static condition flags (e.g. `HIGH_AMOUNT`) │ └── decision_layer.py # Evaluates all thresholds to output APPROVE/REVIEW │ └── utils/ └── metrics.py # Standard ML calculation functions (F1, AUC, Recall) ``` ## 设置与执行 ### 1. 训练系统 在运行预测之前，您必须执行训练 pipeline 以生成必要的 artifact。确保 `config.py` 中的 CSV 数据路径准确反映了您的本地数据集位置。 ``` cd fraud_detection_system python training_pipeline/train.py ``` **训练流程 (`train.py`)：** 1. 加载定义的数据集。 2. 通过 `feature_engineering.py` 解析复杂特征，如地理 `haversine` 距离和日期时间偏移量。 3. 处理分类标识符的 `OneHotEncoding` 和 `OrdinalEncoding`。 4. 使用 `StandardScaler` 对剩余特征进行缩放。 5. 拟合无监督的 `IsolationForest` 异常模型。 6. 使用 `SMOTE` 处理类别不平衡问题。 7. 在 CUDA（如果可用）上实例化并优化目标 `FraudNN` PyTorch 分类器。 8. 将所有成功拟合的组件转储到 `artifacts/` 中。 ### 2. 实时推理 编译好 artifact 后，您有两个选项可以运行实时推理： #### 选项 A：REST API (`app.py`) — 推荐 系统公开了一个 **FastAPI** REST API，用于基于 HTTP 的交易评估。使用以下命令启动服务器： ``` cd fraud_detection_system uvicorn app:app --reload ``` API 将在 `http://127.0.0.1:8000` 可用。交互式文档自动生成于 `/docs` (Swagger UI) 和 `/redoc`。 #### API 端点 | 方法 | 端点 | 描述 | |----------|-----------------------------------|----------------------------------------------| | `GET` | `/` | 健康检查 — 返回欢迎信息 | | `GET` | `/transactions` | 列出所有记录的交易 | | `GET` | `/transactions/{transaction_id}` | 通过 ID 获取特定交易 | | `POST` | `/transactions` | 提交新交易进行评估 | | `DELETE` | `/transactions/{transaction_id}` | 通过 ID 删除交易 | #### 请求示例 **列出所有交易：** ``` curl http://127.0.0.1:8000/transactions ``` **获取特定交易：** ``` curl http://127.0.0.1:8000/transactions/1 ``` **提交新交易：** ``` curl -X POST "http://127.0.0.1:8000/transactions?amount=500.00&merchant=Amazon" ``` 金额 `amount < 1000` 的交易会自动 `approved`；金额 `>= 1000` 的交易会被 `flagged` 以供审查。 **删除交易：** ``` curl -X DELETE http://127.0.0.1:8000/transactions/2 ``` #### 选项 B：直接通过 Python (`main.py`) `main.py` 作为独立的入口点，无需启动服务器即可直接通过 Python 评估交易。 ``` cd fraud_detection_system python main.py ``` **推理流程 (`main.py`)：** 1. 系统初始化并通过 `model_loader.py` 缓存权重。 2. 获取原始字典交易 (`process_transaction`)。 3. 对齐特征列，使其与训练循环中观察到的完全匹配。 4. 删除不必要的引用列 (`cc_num`、`first`、`last` 等)。 5. 填充缺失的编码，提取特征，并按照 `preprocessing` 内部的逻辑对数组进行缩放。 6. PyTorch 前向传播生成欺诈概率，而 `IsolationForest` 返回交易异常的严重程度。 7. 两个元数据源都进入规则引擎逻辑。 8. 最终的决策字符串通过决策层算法返回。 ## 配置 您可以轻松地通过 `config.py` 调整超参数或模型架构，而无需修改运行代码： ``` "model": { "input_dim": 77, "hidden_dims": [128, 64], "dropout": 0.2 }, "optimizer": { "type": "adam", "lr": 0.001 } ``` ## 依赖项 API 层需要 **FastAPI** 和 **Uvicorn**。请将它们与现有需求一起安装： ``` pip install fastapi uvicorn pip install -r requirements.txt ``` ## 添加新功能/规则 - 要添加新的 ML 特征转换，请更新 `preprocessing/feature_engineering.py`。 - 要确立新的公司政策或业务逻辑约束，请在 `risk_engine/rule_engine.py` 中实现该标志。 - 要添加新的 API 端点，请在 `app.py` 中定义路由。

标签：Apex, AV绕过, FastAPI, PyTorch, Vectored Exception Handling, 凭据扫描, 异常检测, 机器学习, 欺诈检测, 逆向工具, 风险控制