AbhinavKhareTech/BGI-Fraud-Detection
GitHub: AbhinavKhareTech/BGI-Fraud-Detection
基于混合架构的实时欺诈检测系统，利用图模型与梯度提升结合识别协调欺诈模式。
Stars: 0 | Forks: 0
# BGI — 行为图智能
**一种用于实时欺诈检测的混合生产架构。**
BGI 不是一个单体模型。它是一种生产架构，结合了
图原生推理与梯度提升表格特征以及堆叠集成。XGBoost 处理冷启动和稀疏情况。基于 DGL 的图注意力模型检测协调的欺诈模式——骡子环、设备合谋、商户端洗钱。堆叠层通过上下文感知权重融合两者，并生成可审计的解释。
这确实来自 `scripts/smoke_test.py` 的输出，而不是虚构的插图。这就是演示的核心。
## 为何采用混合方案（而非纯图模型）
纯 GNN 在论文中看起来很好。在生产中它们存在四种失效模式：
1. **冷启动。** 新用户和新商户没有邻居。图模型预测会变成噪声。仅凭表格特征，XGBoost 能很好地处理这种情况。
2. **稀疏情况下的延迟。** 子图为空的交易不应等待图数据库。XGBoost 约 5ms 即可响应。
3. **可解释性。** 监管要求 SHAP 值和特征重要性，而不只是子图注意力图。我们两者都提供。
4. **降级容错。** 如果图基础设施出现故障，XGBoost 能保持欺诈引擎继续运行。
混合系统正是生产欺诈检测的实际形态——Feedzai、Sardine、Stripe Radar 都采用集成方案。BGI 让这种架构成为一等公民。
## 架构
```
┌────────────────────┐
Transaction ──────┤ Feature Pipeline │
└──────────┬─────────┘
│
┌───────────┴────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ XGBoost │ │ DGL GraphSAGE │
│ tabular, 5 ms │ │ subgraph, 30ms │
└────────┬────────┘ └────────┬────────┘
│ │
└───────────┬────────────┘
│
┌──────────▼─────────┐
│ Stacking Ensemble │
│ (logistic meta) │
└──────────┬─────────┘
│
▼
Score + per-arm contributions + subgraph explanation
```
**所有内容均采用 Apache 2.0 许可，可部署在客户 VPC 中。**
PyTorch + DGL + XGBoost + scikit-learn。这是标准的可雇佣技术栈，无供应商锁定。
## 优雅降级：每个依赖项均为可选
为了保持 CI 快速并降低安装摩擦，BGI 使用依赖注入的后端：
| 组件 | 主要（生产） | 降级（CI / 无 GPU） |
|----------|----------------------------------|---------------------------------------------|
| 表格臂 | XGBoost | sklearn `HistGradientBoosting` |
| 图臂 | DGL GraphSAGE（异构图） | NetworkX 结构特征 + sklearn |
| 集成 | sklearn `LogisticRegression` |（同上） |
相同的 `HybridScorer` 接口适用于两者。烟雾测试运行在降级路径上，因此仅需 numpy/pandas/sklearn。若要在 YC 演示中使用，安装主依赖栈：`pip install -e ".[dev"`，代码会自动识别。
### 路线图：可插拔图后端（v2）
BGI 在生产规模图推理中使用 DGL（AWS SageMaker 集成、成熟的分布式训练、无 Kumo 依赖）。计划引入 **PyTorch Geometric (PyG) 作为可替换后端**，以实现最大框架中立性与研究敏捷性。
理由如下：
- **DGL 在生产中胜出**——获得 AWS 支持、与 SageMaker 原生集成、多 GPU 扩展能力强，已在 Amazon、DoorDash、BlackRock 等企业规模验证。
- **PyG 在研究中胜出**——最大的 GNN 研究社区，最快采用新架构（时序 GAT、异构图注意力变体），更易原型设计。
- **使其可插拔**让我们能在 PyG 中迭代架构，再部署到生产环境的 DGL，同时保持相同的 `GraphArm` 接口。
当前的 `GraphArm` 已通过 `fit()` / `predict_proba()` / `compute_features_for()` 抽象后端；替换 DGL 为 PyG 仅需修改 `src/bgi/models/graph_model.py`，无需更改代码库其他部分。
## 数据集
本演示基于
[Synthetic Merchant Fraud Dataset (Graph Structure)](https://www.kaggle.com/datasets/akashraj121/synthetic-merchant-fraud-dataset-graph-structure)
（来自 Kaggle）。数据加载器（`src/bgi/data/loader.py`）自动识别图导向的商户欺诈数据集中的通用列名，包括类似 PaySim 的 `nameOrig`/`nameDest`/`isFraud` 以及标准化的 `customer_id`/`merchant_id`/`is_fraud`。
**如果你无法访问 Kaggle**，仓库自带一个合成数据生成器，它生成相同模式并注入欺诈环与骡子网络——因此演示可开箱即用运行：
```
python scripts/generate_synthetic_data.py --out data/raw/transactions.csv
```
该生成器故意构建五种不同的欺诈原型：
| 欺诈原型 | XGBoost 能捕获？ | 图臂能捕获？ |
|----------------------|------------------------|---------------------|
| 个人欺诈 | 是（金额异常） | 是 |
| 速度爆发 | **是** | 有时 |
| 骡子环 | 否（单行看正常） | **是** |
| 设备合谋环 | 部分 | **是** |
| 商户端洗钱 | 否 | **是** |
这正是演示可信的原因：你可以指向图臂捕获的具体交易，而这些是纯表格模型无法发现的。
详见 [docs/DATA.md](docs/DATA.md) 了解完整的列处理说明。
## 快速开始
```
# 安装（仅回退模式，尚未支持 XGBoost/DGL）
pip install -e .
# 验证一切是否正常工作（尚未有数据或模型 — 仅内存中合成并训练）
python scripts/smoke_test.py
# 持久化流水线并生成演示用例
python scripts/generate_synthetic_data.py # synthetic, no Kaggle needed
# 或将 Kaggle CSV 放入 data/raw/transactions.csv
python scripts/train.py # trains + saves bundle
python scripts/evaluate.py # prints disagreement cases + saves JSON
# 对于完整的 YC 技术栈，添加主要的后端
pip install xgboost dgl torch fastapi uvicorn jinja2
# 运行实时演示服务器
python scripts/run_demo.py
# 打开 http://localhost:8000
```
演示页面展示实时交易流，采用终端/交易台风格。对于每笔交易，你可以并排查看三个分数——当两侧臂不一致时，会显示触发该结果的子图证据。
## 烟雾测试结果（使用 sklearn 降级后端）
运行 `python scripts/smoke_test.py` 端到端生成的数据，结果大致如下（运行间方差约 0.01）：
```
[4/7] Model arms
tabular AUC-ROC=0.986 AUC-PR=0.958
graph AUC-ROC=0.747 AUC-PR=0.649
ensemble AUC-ROC=0.986 AUC-PR=0.960
```
整体 AUC 提升较小，因为表格臂已能干净地捕获速度爆发和金额异常。关键在于 **独特捕获情况**：
```
[BONUS] Unique-catch breakdown at threshold 0.5
total fraud in test: 169
caught by both arms: 70
caught ONLY by graph arm: 10 <- YC demo gold
caught ONLY by tabular arm: ~76
caught by NEITHER arm: ~13
```
**大约十个被纯表格 XGBoost 批准的欺诈案例被图臂捕获——包括设备共享环和洗钱商户。** 这些正是演示 UI 高亮展示的案例。表格单独捕获约 76 个速度爆发，而图臂漏检。这正是混合架构存在的原因：两者的盲区是互补的。
安装 XGBoost + DGL 后，数值还会进一步提升。详见 `scripts/smoke_test.py` 获取精确复现——大约运行 30 秒。
## 一个示例解释（自动生成）
以下段落直接来自某个随机环案例的解释器：
这正是调查人员打开被 BGI 拦截的交易时所看到的内容——不是特征向量，而是一段文字。
## 仓库结构
```
src/bgi/
data/ loader + schema auto-detection, graph builder, synthetic generator
features/ streaming-safe tabular features (velocity, entropy, ratios)
models/ tabular_model.py, graph_model.py, ensemble.py
inference/ hybrid_scorer.py (parallel-shaped inference + timing)
explain/ plain-English explainer
scripts/ train, evaluate, run_demo, generate_synthetic_data, smoke_test
demo/ FastAPI + SSE live scoring UI (the YC demo itself)
configs/ YAML configs
tests/ pytest suite
```
## 运行测试
有两种方式验证流水线：
```
# 选项 A：纯 Python（无需 pytest）
python scripts/smoke_test.py # 22 checks, ~30 seconds
# 选项 B：pytest（标准开发流程）
pip install pytest
pytest tests/ -v
```
## YC 推介，一句话总结
BGI 是一种混合生产架构。梯度提升的表格模型处理冷启动和稀疏情况。我们基于 DGL 的图模型检测设备共享环、骡子网络、商户端洗钱等按行特征无法识别的协调欺诈模式。逻辑堆叠器以可审计的方式融合两侧臂的贡献。构建于 PyTorch，可部署在客户 VPC，支持在 AWS 或本地环境自托管。我们在构建自托管栈的同时，已对 7 个试点客户验证了该架构。本仓库即该栈，烟雾测试证明它能捕获纯表格模型会放过的环欺诈。
## 许可证
Apache 2.0。参见 [LICENSE](LICENSE)。
标签：DGL, Feedzai, Sardine, SEO, SHAP, Stripe Radar, XGBoost, 上下文加权, 冷启动, 凭据扫描, 协同欺诈, 反欺诈系统, 可解释性, 商户洗钱, 图注意力网络, 图神经网络, 堆叠集成, 实时检测, 审计解释, 案例研究, 欺诈检测, 深度图学习, 混合架构, 特征工程, 生产系统, 设备共谋, 账户接管, 骡子网络