使用说明
基于强化学习（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分数）：
- 🥇 随机森林 + ADASYN： 0.5411
- 🥈 随机森林 + SMOTE：0.5367
- 🥉 随机森林 + SMOTETomek：0.5332
- XGBoost + SMOTE：0.5264
- XGBoost + SMOTETomek：0.5262
- 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
- 模型服务基础设施
- 监控和报警
快速入门
先决条件
-
Python 3.11
python --version # Should be 3.11.x -
虚拟环境
python -m venv .venv # Windows .venv\Scripts\activate # Unix/MacOS source .venv/bin/activate -
依赖项
pip install -r requirements.txt -
带有 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%
性能对比：
| 模型 | 技术 | F1分数 | 精确度 | 召回率 | 速度 |
|---|---|---|---|---|---|
| 随机森林 | ADASYN（一种处理类别不平衡数据的方法） | 0.5411 🏆 | 74.12% | 42.61% | 约20分钟 |
| XGBoost | SMOTE | 0.5264 | 80.34% | 39.15% | 约12分钟 |
| LightGBM | ADASYN | 0.5255 | 81.76% | 38.71% | 约10分钟 |
备选方案：
- 为了达到最高速度：使用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中查看结果
- 打开 http://localhost:5000
- 导航至“欺诈检测”实验
- 通过F1分数、精确率、召回率、ROC-AUC来比较运行结果
- 下载模型工件和可视化结果
项目结构
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（普罗米修斯/格拉法纳）**监测
模型性能指标
所有模型均在以下方面进行了评估：
- F1分数 （主要指标）- 精确率和召回率之间的平衡
- 精确度 - 最小化误报（将合法交易标记为欺诈）
- 召回 - 最小化假阴性（漏检欺诈）
- 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）提供全面的规范，以生成可直接用于生产的代码。
工作流程：
- 定义（或“明确”）需求于
agents/context/project_context.md - 运行代理脚本：
./agents/model_builder_agent.sh <model_name> - 代理生成完整的模型类和训练脚本
- 审查并验证生成的代码
- 在MLflow中训练模型并进行追踪
- 比较结果并选择最佳模型
好处：
- ✅ 更快的开发速度（几分钟对比几小时）
- ✅ 代码质量一致（符合标准）
- ✅ 完整的文档（自动生成）
- ✅ 减少了人为错误
请见 agents/README.md（文件名保持不变，可理解为“agents 目录下的 README.md 文件”） 以获取详细的代理使用指南。
手动开发
如果不使用代理，请按照以下步骤操作：
-
创建模型类 在
models/{model_name}_model.py- 实现所需方法：训练、评估、预测、保存、加载
- 处理类别不平衡问题
- 包含类型提示和文档字符串
-
创建培训脚本 在
scripts/train_{model_name}.py- 加载预处理后的数据
- 训练集-测试集划分（80-20，分层划分）
- MLflow 跟踪
- 生成可视化图表
-
训练与评估
python scripts/train_{model_name}.py -
在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） 格式化
拉取请求流程
- 创建特性分支
- 遵循代码规范
- 为新功能添加测试
- 更新文档
- 提交带有描述的拉取请求（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）
