Agentic Fruad Detection System

基于强化学习（RL）和多智能体协同规划（MCP）的代理欺诈检测系统

一个先进的欺诈检测系统，利用强化学习（RL）和模型上下文协议（MCP）实现智能、自适应的欺诈预防。

概述

这个项目实现了一个复杂的欺诈检测系统，采用的方法包括：

• 人工智能代理使用GitHub Copilot CLI和上下文工程进行自动化模型构建
• 机器学习XGBoost、LightGBM和随机森林用于欺诈分类
• 强化学习针对欺诈预防的自适应决策制定
• MLflow全面的实验追踪与模型管理
• 模型上下文协议（MCP）标准化AI模型集成

特性/特点

✅ 已完成的功能

数据管道（手动实现）

• ✅ 从IEEE-CIS欺诈检测数据集中加载数据
• ✅ 预处理流程（缺失值填补，异常值处理）
• ✅ 特征工程（时间特征、分类编码、聚合操作）
• ✅ 预处理后的数据集：590,540笔交易 × 434个特征

✅ 特性1：代理驱动的模型构建

状态✅ 90% 完成 - 全面模型对比研究已完成

已完成：

• ✅ MLflow 实验跟踪设置
• ✅ MLflow 服务器正在 http://localhost:5000 上运行
• ✅ 创建了包含15+次运行的“欺诈检测”实验
• ✅ 完整的项目背景文档
• ✅ 代理基础设施和辅助脚本
• ✅ XGBoost模型 - 测试了5种不平衡技术（任务7）
• ✅ LightGBM模型 - 测试了5种不平衡技术（任务8）
• ✅ 随机森林模型 - 测试了5种不平衡技术（任务9）
• ✅ 完成3×5比较矩阵 - 对所有15种组合进行了评估
• ✅ 不平衡处理研究 - SMOTE，ADASYN，SMOTETomek，欠采样，类别权重
• ✅ 翻译为中文是：✓（对号，表示正确或确认） 生产建议 - 随机森林+ADASYN被认定为最佳方法

结果总结:

🏆（这个符号通常表示奖杯或胜利，没有直接对应的中文翻译，但可以理解为“奖杯”或“胜利的象征”） 总冠军：随机森林 + ADASYN

• F1分数测试0.5411（在所有15个组合中最高）
• 精确度74.12%（平衡度高 - 假阳性低）
• 召回42.61%（拦截了43%的欺诈行为）
• ROC-AUC88.67%
• 外部袋外（Out-Of-Bag）得分97.95%（卓越稳定性）

模型排名 （按最佳F1分数）：

1. 🥇 随机森林 + ADASYN： 0.5411
2. 🥈 随机森林 + SMOTE：0.5367
3. 🥉 随机森林 + SMOTETomek：0.5332
4. XGBoost + SMOTE：0.5264
5. XGBoost + SMOTETomek：0.5262
6. LightGBM + ADASYN：0.5255

关键见解：

• ✅ 重采样技术在仅使用类别权重的基础上，使F1分数提高了200-300%
• ✅ 所有三个模型（XGBoost、LightGBM、随机森林）均适用于生产环境
• ✅ 随机森林在精确度和召回率平衡的情况下取得了最佳F1分数
• ✅ ADASYN在随机森林和LightGBM上的表现优于SMOTE
• ✅ OOB分数（97.9%）表明出色的泛化能力

剩余任务：

• ⏳ 任务10：最终模型选择及生产部署文档编制

关键组件:

• MLflow 实验: fraud-detection （记录了15个跑动）
• 跟踪URI（统一资源标识符）http://localhost:5000 翻译为中文是：“本地主机：5000 端口”。不过，通常我们不会直接这样翻译网址，而是会说“访问本地主机的5000端口”或者“打开http://localhost:5000这个网址”。在这里，“localhost”指的是当前计算机，“5000”是端口号
• 报告： reports/all_models_techniques_comparison.csv （完成3×5矩阵）
• 模型16个训练模型已保存（约330 MB）
• 文档: 功能1/任务/ - 完成任务文档

📋 计划中的功能

特性2：强化学习智能体

• 动态欺诈检测阈值
• 基于奖励的学习欺诈模式
• 自适应决策

特性3：模型上下文协议集成

• 标准化模型接口
• 多模型协同调度
• 实时欺诈预测API

特性4：生产部署

• FastAPI REST API
• 模型服务基础设施
• 监控和报警

快速入门

先决条件

1. Python 3.11

   python --version  # Should be 3.11.x

1. 虚拟环境

   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # Unix/MacOS
   source .venv/bin/activate

1. 依赖项

   pip install -r requirements.txt

1. 带有 Copilot 的 GitHub CLI （针对AI代理）

   gh --version
   gh copilot --version

设置 MLflow

# Start MLflow server
mlflow ui --host 0.0.0.0 --port 5000

# Access MLflow UI
# Open browser: http://localhost:5000

数据集准备

预处理后的数据集已可获取于 data/datasets/train_processed.csv。

数据集规范:

• 来源IEEE-CIS欺诈检测（Kaggle）
• 形状590,540 行 × 434 列
• 目标isFraud（二进制：0=合法，1=欺诈）
• 类别分布3.5%的欺诈率（严重失衡）
• 特点/特性433项特征，包括交易、卡片、地址、设备和时间属性

🎯 准生产就绪模型（15种组合中的最佳选择）

获胜者随机森林 + ADASYN（一种用于处理类别不平衡数据的过采样技术）

from models.random_forest_model import RandomForestFraudDetector
from data.imbalance_handler import ImbalanceHandler
import pandas as pd

# Load and prepare data
df = pd.read_csv('data/datasets/train_processed.csv')
X, y = df.drop('isFraud', axis=1), df['isFraud']

# Apply ADASYN resampling
handler = ImbalanceHandler()
X_resampled, y_resampled = handler.handle_imbalance(
    X, y, strategy='adasyn', random_state=42
)

# Train production model
model = RandomForestFraudDetector(params={
    'n_estimators': 100, 'max_depth': 15, 'n_jobs': -1,
    'oob_score': True, 'random_state': 42
})
model.train(X_resampled, y_resampled)

# Results: F1=0.5411, Precision=74.12%, Recall=42.61%, OOB=97.95%

性能对比：

备选方案：

• 为了达到最高速度：使用LightGBM + ADASYN
• 为了达到最高精度：LightGBM + ADASYN（81.76%）
• 为了达到最高的召回率：随机森林 + 类别权重（69.42%）

运行模型比较

# Compare all techniques across all models
python scripts/compare_imbalance_methods.py          # XGBoost
python scripts/compare_imbalance_lightgbm.py         # LightGBM
python scripts/compare_imbalance_random_forest.py    # Random Forest

# View complete 3×5 matrix
cat reports/all_models_techniques_comparison.csv

使用AI代理生成模型

# Navigate to agents directory
cd agents

# Generate XGBoost model
./model_builder_agent.sh xgboost

# Generate LightGBM model
./model_builder_agent.sh lightgbm

# Generate Random Forest model
./model_builder_agent.sh randomforest

训练模型

# Train XGBoost
python scripts/train_xgboost.py

# Train LightGBM
python scripts/train_lightgbm.py

# Train Random Forest
python scripts/train_random_forest.py

在MLflow中查看结果

1. 打开 http://localhost:5000
2. 导航至“欺诈检测”实验
3. 通过F1分数、精确率、召回率、ROC-AUC来比较运行结果
4. 下载模型工件和可视化结果

项目结构

agentic-fraud-detection/
│
├── agents/                          # AI agent scripts and context
│   ├── context/
│   │   └── project_context.md      # Comprehensive specifications for agents
│   ├── model_builder_agent.sh      # Agent for model generation
│   ├── _agent_helpers.sh           # Shared utilities
│   └── README.md                   # Agent usage guide
│
├── data/                            # Data pipeline and datasets
│   ├── datasets/
│   │   └── train_processed.csv     # Preprocessed data (590K rows × 434 cols)
│   ├── loader.py                   # Data loading utilities
│   ├── preprocessing.py            # Preprocessing pipeline
│   └── feature_engineering.py      # Feature engineering
│
├── models/                          # Model implementations (agent-generated)
│   ├── xgboost_model.py            # XGBoost fraud detector
│   ├── lightgbm_model.py           # LightGBM fraud detector
│   └── random_forest_model.py      # Random Forest fraud detector
│
├── scripts/                         # Training and evaluation scripts
│   ├── train_xgboost.py
│   ├── train_lightgbm.py
│   └── train_random_forest.py
│
├── mlruns/                          # MLflow experiment tracking data
│   └── fraud-detection/            # Experiment runs and artifacts
│
├── rl/                              # Reinforcement learning components
│   └── (planned)
│
├── api/                             # REST API for predictions
│   └── (planned)
│
├── tests/                           # Unit and integration tests
│   └── test_mlflow_setup.py
│
├── requirements.txt                 # Python dependencies
├── .env                            # Environment variables
└── README.md                       # This file

技术栈

核心技术

• Python 3.11主要编程语言
• 熊猫数据操作
• Scikit-learn机器学习工具和随机森林
• XGBoost梯度提升框架
• LightGBM快速梯度提升
• MLflow实验追踪和模型注册
• GitHub Copilot 命令行界面 (CLI)基于人工智能的代码生成

可视化

• Matplotlib（中文常译为“马特洛普特”或直接使用英文原名，因其是一个绘图库名称，具体翻译可能因习惯而异，但通常不译为中文）绘图与可视化
• Seaborn（注：Seaborn是一个用于Python的数据可视化库，常用于绘制统计图形，但在此处作为专有名词直接翻译，不添加额外解释）统计图形

处理类别不平衡问题

• imbalanced-learn（中文可译为“不平衡学习库”或根据上下文简化为“不平衡学习”）SMOTE和重采样技术
• 类别权重内置模型参数

未来的增补

• Ray RLlib强化学习框架
• FastAPIREST API框架
• Docker集装箱化
• Prometheus/Grafana（普罗米修斯/格拉法纳）监测

模型性能指标

所有模型均在以下方面进行了评估：

1. F1分数 （主要指标）- 精确率和召回率之间的平衡
2. 精确度 - 最小化误报（将合法交易标记为欺诈）
3. 召回 - 最小化假阴性（漏检欺诈）
4. ROC-AUC（受试者工作特征曲线下面积） - 整体辨别能力

目标绩效:

• F1分数 > 0.5（最低基准）
• ROC-AUC > 0.85（具有良好的判别能力）
• 召回率 > 0.6（至少捕捉到60%的欺诈行为）

MLflow 实验追踪

追踪的内容是什么

• 参数所有超参数、随机种子、划分比例
• 指标F1分数，精确度，召回率，ROC曲线下面积（训练集和测试集）
• 人工制品；文物；遗迹训练好的模型、混淆矩阵、ROC曲线、特征重要性

访问MLflow

Web 用户界面http://localhost:5000 翻译为中文是：“本地主机上的5000端口”。不过，通常我们不会直接这样翻译网址，而是根据上下文可能解释为“访问本地开发服务器（运行在5000端口）”或“打开本地5000端口的服务”。但简短地翻译网址本身，就是“本地主机上的5000端口”

程序化访问：

import mlflow

# Search for best run
best_run = mlflow.search_runs(
    experiment_names=["fraud-detection"],
    order_by=["metrics.f1_score DESC"],
    max_results=1
)

开发工作流程

利用AI代理进行开发

这个项目使用了 上下文工程 - 一种技术，即向人工智能代理（如GitHub Copilot CLI）提供全面的规范，以生成可直接用于生产的代码。

工作流程：

1. 定义（或“明确”）需求于 agents/context/project_context.md
2. 运行代理脚本： ./agents/model_builder_agent.sh
3. 代理生成完整的模型类和训练脚本
4. 审查并验证生成的代码
5. 在MLflow中训练模型并进行追踪
6. 比较结果并选择最佳模型

好处：

• ✅ 更快的开发速度（几分钟对比几小时）
• ✅ 代码质量一致（符合标准）
• ✅ 完整的文档（自动生成）
• ✅ 减少了人为错误

请见 agents/README.md（文件名保持不变，可理解为“agents 目录下的 README.md 文件”） 以获取详细的代理使用指南。

手动开发

如果不使用代理，请按照以下步骤操作：

1. 创建模型类 在 models/{model_name}_model.py

- 实现所需方法：训练、评估、预测、保存、加载 - 处理类别不平衡问题 - 包含类型提示和文档字符串

1. 创建培训脚本 在 scripts/train_{model_name}.py

- 加载预处理后的数据 - 训练集-测试集划分（80-20，分层划分） - MLflow 跟踪 - 生成可视化图表

1. 训练与评估

   python scripts/train_{model_name}.py

1. 在MLflow中的审查（或“复审”）

- 检查指标 - 下载工件（或制品） - 与其他模型进行比较

测试

运行所有测试

pytest tests/

测试MLflow设置

python tests/test_mlflow_setup.py

验证上下文文档

# Test agent understanding of context
cd agents
gh copilot suggest -t shell "Context: $(cat context/project_context.md)
Task: List the 3 main model types and their key hyperparameters."

故障排除

MLflow 服务器未运行

# Check if running
curl http://localhost:5000/health

# Restart if needed
pkill -f "mlflow"
mlflow ui --host 0.0.0.0 --port 5000 &

导入错误

# Verify virtual environment is activated
which python  # Unix/MacOS
where python  # Windows

# Reinstall dependencies
pip install -r requirements.txt

代理生成问题

# Check GitHub CLI
gh --version
gh copilot --version

# Test simple prompt
gh copilot suggest -t shell "echo hello"

数据集加载错误

# Verify dataset exists
python -c "import pandas as pd; df = pd.read_csv('data/datasets/train_processed.csv'); print(f'Shape: {df.shape}')"

做出贡献

代码标准

• Python 3.11 兼容性
• 类型提示 对于所有函数
• 谷歌风格的文档字符串
• 错误处理 使用 try-except 块
• 记录日志 （不是打印语句）
• PEP 8（Python增强提案8） 格式化

拉取请求流程

1. 创建特性分支
2. 遵循代码规范
3. 为新功能添加测试
4. 更新文档
5. 提交带有描述的拉取请求（Pull Request）

路线图

第一阶段：基础 ✅ 已完成

• ✅ 数据管道实现
• ✅ MLflow 实验追踪
• ✅ 人工智能代理基础设施
• ✅ 基线模型生成

第二阶段：模型开发 ✅ 90% 完成

• ✅ XGBoost、LightGBM、随机森林模型
• ✅ 不平衡处理方法对比（5种技术）
• ✅ 完成3×5模型+技术矩阵（15种组合）
• ✅ 已确定生产模型（随机森林+ADASYN）
• ⏳ 最终部署文档（任务10）

第三阶段：强化学习

• ⏳ 用于自适应阈值的强化学习（RL）智能体
• ⏳ 奖励函数设计
• ⏳ 训练流程
• ⏳ 性能评估

第四阶段：生产

• ⏳ REST API开发
• ⏳ 模型部署
• ⏳ 监控仪表盘
• ⏳ A/B测试框架

许可证

\[在此指定许可证\]

致谢

• 数据集IEEE-CIS欺诈检测（Kaggle）
• MLflowDatabricks/MLflow 团队
• GitHub CopilotGitHub/OpenAI（直接翻译为中文即为“GitHub/开放人工智能研究所”，但通常我们保留原名以指代特定平台或组织，因此也可直接使用“GitHub/OpenAI”这一表述）
• 开源社区XGBoost、LightGBM、Scikit-learn 的贡献者

联系

如有疑问或需支持：

• 审查文档中的内容 agents/README.md
• 在 http://localhost:5000 上查看 MLflow 用户界面
• 检查上下文文档于 agents/context/project_context.md

______________________________________________________________________

最后更新时间2025年10月9日\ 状态积极开发中 - 功能1 完成度90%\ 当前阶段模型开发 - 确定生产模型\ 最佳模型随机森林 + ADASYN（F1分数：0.5411）