YeAljohani/AI-Multi-Agent-Financial-Fraud-Detection-System

# Fraud Intel — AI 多智能体金融欺诈检测系统  ## 项目功能 大多数欺诈系统仅停留在给出评分。**Fraud Intel** 是专为调查人员打造的： 1. **采集** 通过 Kafka 以可配置的 TPS 接收合成支付事件 2. **处理** 在 PySpark 中处理数据（Bronze → Silver → Gold Delta lakehouse），并结合客户/设备信息进行丰富 3. **评分** 使用可解释的**规则引擎**（映射到策略）+ **XGBoost** 模型对每笔交易进行评分 4. **标记** 将高风险案例标记至 PostgreSQL，并展示在 React 工作区中 5. **调查** 由基于 ChromaDB RAG（涵盖 AML 策略、银行卡组织规则和历史案例）的 **7 智能体 LangGraph 团队**提供支持 6. **对话** 与能引用检索来源的调查助手进行交流 UI 是一个温暖、极简的调查工作区（灵感来自现代 SOC 仪表盘）——而不是炫彩的“黑客终端”。 ## 架构 ``` flowchart LR P[Transaction Producer] --> K1[(Kafka: transactions.raw)] K1 --> S[PySpark Streaming] S --> D[(Delta Lakehouse)] S --> K2[(Kafka: transactions.enriched)] K2 --> B[FastAPI Backend] B --> R[Rule Engine] B --> M[XGBoost ML] R --> PG[(PostgreSQL)] M --> PG PG --> FE[React Dashboard] FE --> INV[Multi-Agent Investigation] INV --> RAG[(ChromaDB RAG)] INV --> LLM[OpenAI GPT] ``` ### 流水线阶段 | 阶段 | 组件 | 输出 | |-------|-----------|--------| | 1. 数据采集 | Python 生产者 | 原始 JSON 事件 → `transactions.raw` | | 2. 流处理 | Spark 结构化流 | 丰富的特征 → Delta + `transactions.enriched` | | 3. 规则 | 确定性规则引擎 | 分数 0–100 + 每次命中的策略引用 | | 4. 机器学习 (ML) | XGBoost 分类器 | 欺诈概率融合进综合评分中 | | 5. 存储 | PostgreSQL | 可搜索的交易、状态和调查记录 | | 6. RAG | ChromaDB + BGE 嵌入 | 为智能体和聊天提供策略/案例检索 | | 7. 多智能体 AI | LangGraph（7 个节点） | 带有证据支持的调查报告 | | 8. 仪表盘 | React + FastAPI | 概览、队列、案例审查、聊天 | ### 多智能体拓扑 五名专家分析师**并行**运行，然后汇总： ``` START → Transaction Analyst ──┐ → Behavior Analyst ──┤ → ML Analyst ──┼→ Evidence Collector → Senior Investigator → END → Policy Expert ──┤ → Historical Invest. ──┘ ``` 每个智能体都会生成结构化的调查结果。**高级调查员** 会综合撰写一份叙述性报告、建议以及带有引用证据的行动清单。 ## 截图 — 高风险案例审查 ### 关键交易队列 支持按风险等级和状态筛选交易。关键案例（分数 ≥ 80）显示在优先队列的顶部。  ### 案例审查 — 分数 82 / 关键 真实案例示例：**TXN-7B0C52A0D5** — 来自尼日利亚的 MegaStore 消费 35,941 SAR，达到客户 30 天平均消费的 258 倍，且与归属国 SA 存在地理位置不匹配。  ### 可解释的规则命中 每条触发的规则都映射到内部 **欺诈风险策略** 的特定章节——调查人员随时都能回答*“依据哪条策略？”* | 规则 | 信号 | 分值 | |------|--------|--------| | R-AMT-01 | 金额 > 15,000 SAR | +25 | | R-AMT-02 | 达到平均消费额的 258 倍 | +20 | | R-GEO-01 | 国家 NG ≠ 归属地 SA | +15 | 综合评分：`0.45 × rule_score + 0.55 × ml_probability × 100` → **82 (关键)**  ## 评估 ### 机器学习模型（基于合成数据的 XGBoost） 在容器构建时（`python -m app.ml.train`）使用 4 万个标注样本（80/20 划分）进行训练： | 指标 | 值 | |--------|-------| | Accuracy | 1.000 | | Precision | 1.000 | | Recall | 1.000 | | F1 | 1.000 | | ROC-AUC | 1.000 | | 训练 / 测试 | 32,000 / 8,000 | ### 规则引擎（单元测试） Pytest 验证了已知的欺诈模式会触发预期的规则并带有策略引用： - 高额异地交易 + 新设备 + 高频交易 → 分数 ≥ 60，触发规则 R-AMT-01/02、R-GEO-01、R-DEV-01、R-VEL-01 - 正常的境内消费 → 分数 < 40，无关键命中 ### 端到端评分流水线 集成测试确认高风险特征向量会产生以下结果： - `fraud_score ≥ 60`，`risk_level ∈ {high, critical}` - `status = flagged` - ≥ 3 个带有 `policy_ref` 的规则原因 - `ml_probability ≥ 0.4` ### 运行测试（在 Docker 内部） ``` docker compose exec backend pytest tests/ -q ``` ## 快速开始 ### 前置条件 - Docker Desktop（建议分配 8 GB 以上内存） - OpenAI API 密钥（可选 — 提供 mock 模式） ### 1. 配置环境 ``` cp .env.example .env ``` 编辑 `.env`： ``` OPENAI_API_KEY=sk-... # optional; leave empty + LLM_MOCK=true for offline demo LLM_MODEL=gpt-4o-mini JWT_SECRET=your-long-random-secret TPS=2 # transactions per second FRAUD_RATE=0.08 # ~8% injected fraud patterns ``` ### 2. 启动技术栈 ``` docker compose up --build -d ``` 等待约 2 分钟，以便 Kafka、Spark、后端完成健康检查并进行初始评分。 ### 3. 打开工作区 | 服务 | URL | |---------|-----| | 仪表盘 | http://localhost:3000 | | API (OpenAPI) | http://localhost:8000/docs | | ChromaDB | http://localhost:8001 | **演示登录：** `investigator` / `investigate123` ### 4. 典型调查流程 1. 打开 **概览** — 查看警报数量和风险分布 2. 前往 **交易** — 筛选 `critical` 或按 ID 搜索 3. 打开一个案例 → **运行 AI 调查**（需要 OpenAI 密钥或使用 mock 模式） 4. 审查智能体调查结果、证据及类似历史案例 5. 使用侧边的 **调查员聊天** 询问策略问题 6. 选择 **确认欺诈** 或 **清除** 以更新案例状态 ## 技术栈 | 层级 | 技术 | |-------|------------| | 流处理 | Apache Kafka 3.9 | | 数据处理 | PySpark 3.5, Delta Lake | | 后端 | FastAPI, SQLAlchemy, PostgreSQL 16 | | 机器学习 | XGBoost, scikit-learn | | RAG | ChromaDB, sentence-transformers (BGE-small) | | 智能体 | LangGraph, OpenAI GPT-4o-mini | | 前端 | React 18, Vite, Tailwind CSS, Chart.js, lucide-react | | 基础设施 | Docker Compose | ## 项目结构 ``` ├── producer/ # Synthetic transaction generator → Kafka ├── spark/ # Bronze/Silver/Gold streaming job ├── backend/ │ ├── app/rules/ # Explainable rule engine │ ├── app/ml/ # XGBoost train + inference │ ├── app/rag/ # Chroma ingestion & retrieval │ ├── app/agents/ # LangGraph multi-agent graph │ ├── knowledge_base/ # Policies, AML docs, historical cases │ └── tests/ # Rule, ML, RAG, agent, pipeline tests ├── frontend/ # Investigation dashboard (Fraud Intel UI) ├── docs/screenshots/ # README visuals from live high-risk cases └── docker-compose.yml ``` ## 配置参考 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `OPENAI_API_KEY` | — | 用于智能体和聊天的 OpenAI 密钥 | | `LLM_MODEL` | `gpt-4o-mini` | 用于所有智能体节点的模型 | | `LLM_MOCK` | `false` | 在没有 API 的情况下提供确定性响应 | | `TPS` | `2` | 生产者吞吐量 | | `FRAUD_RATE` | `0.08` | 欺诈模式交易的比例 | | `EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` | RAG 嵌入模型 | ## 许可证 MIT — 可自由用于学习、演示和功能扩展。

标签：Apex, 云计算, 多智能体, 大数据流处理, 机器学习, 检索增强生成, 测试用例, 版权保护, 规则引擎, 软件成分分析, 金融反欺诈