2311020116_CreditCardFraudDetection/README.md

# 信用卡欺诈检测系统

> **机器学习 (Python) 课程设计**

## 项目结构

```
ml_course_design/
├── pyproject.toml            # 项目配置与依赖
├── uv.lock                   # 锁定的依赖版本
├── README.md                 # 项目说明与报告
├── .env.example              # 环境变量模板
├── .gitignore                # Git 忽略规则
│
├── data/                     # 数据目录
│   └── README.md             # 数据来源说明
│
├── models/                   # 训练产物
│   └── .gitkeep
│
├── src/                      # 核心代码
│   ├── __init__.py
│   ├── data.py               # 数据读取/清洗
│   ├── features.py           # Pydantic 特征模型
│   ├── train.py              # 训练与评估
│   ├── infer.py              # 推理接口
│   ├── agent_app.py          # Agent 入口
│   └── streamlit_app.py      # Demo 入口
│
└── tests/                    # 测试
    └── test_*.py
```

## 团队成员

| 姓名 | 学号 | 贡献 |
|------|------|------|
| 罗颢文 | 2311020115 | 模型训练、Agent开发|
| 骆华华 | 2311020116 | 数据处理、Web 应用 |
| 李俊昊 | 2311020111 | 测试、文档撰写 |

## 项目简介

本项目设计并实现了一个基于机器学习的信用卡欺诈检测系统，旨在实时识别和预防信用卡欺诈交易，有效降低金融风险。系统采用随机森林算法构建高性能分类模型，通过SMOTE技术解决数据不平衡问题，在ROC-AUC指标上达到0.98的优异表现。系统创新性地集成了多步决策Agent架构，将欺诈检测过程分解为评估、解释和行动建议三个阶段：评估阶段使用训练好的模型对交易进行预测并计算欺诈概率；解释阶段分析影响预测结果的关键特征，生成可解释性报告；行动阶段根据预测置信度和关键特征生成不同优先级的行动建议。项目基于Streamlit框架构建Web应用，提供直观的用户界面，支持数据可视化展示和实时欺诈检测功能，为金融机构提供了一套完整、可靠的欺诈检测解决方案。

## 数据切分策略

本项目采用**时间序列切分**策略，严格按照交易发生的时间顺序将数据集划分为训练集和测试集：

- **训练集**: 前80%的数据（按时间排序）
- **测试集**: 后20%的数据（按时间排序）

### 切分原则

1. **时间顺序**: 确保测试集的时间晚于训练集，符合实际应用场景
2. **防止数据泄露**: 避免未来信息泄露到训练集
3. **泛化能力**: 评估模型在时间序列上的泛化能力

### 防泄露措施

- **特征缩放**: 仅在训练集上计算StandardScaler参数，然后应用到测试集
- **采样处理**: 仅在训练集上进行SMOTE过采样，测试集保持原始分布
- **特征工程**: 确保所有特征都是交易发生时可获得的信息

## 核心功能

### 1. 数据处理 (src/data.py)

使用 Polars 进行高效数据处理：
- 数据加载与验证
- 时间序列切分
- 特征与标签分离

### 2. 特征定义 (src/features.py)

使用 Pydantic 定义特征和输出模型：
- TransactionFeatures: 交易特征模型
- EvaluationResult: 评估结果模型
- ExplanationResult: 解释结果模型
- ActionPlan: 行动计划模型

### 3. 模型训练 (src/train.py)

支持多种模型训练与评估：
- Logistic Regression
- Random Forest
- SMOTE 不平衡数据处理
- 完整的评估指标

### 4. 推理接口 (src/infer.py)

提供高效的推理服务：
- 单条交易预测
- 批量预测
- 概率输出

### 5. Agent 系统 (src/agent_app.py)

多步决策 Agent，包含 2 个工具：
- **predict_fraud** (ML 工具): 使用机器学习模型预测交易是否为欺诈
- **analyze_transaction**: 分析交易数据的统计特征和异常值

决策流程：
1. 评估阶段：使用训练好的模型对交易进行预测
2. 解释阶段：分析影响预测结果的关键特征
3. 行动阶段：根据预测置信度生成行动建议

### 6. Demo 应用 (src/streamlit_app.py)

基于 Streamlit 的交互式 Demo：
- 30个特征输入界面
- 实时欺诈检测
- 特征重要性分析
- 行动建议展示

## 模型性能

| 模型 | PR-AUC | F1-Score | Recall | Precision |
|------|--------|----------|---------|-----------|
| Logistic Regression | 0.93 | 0.75 | 0.70 | 0.80 |
| Random Forest | 0.98 | 0.85 | 0.95 | 0.78 |

## 技术栈

- **数据处理**: Polars
- **特征定义**: Pydantic
- **机器学习**: scikit-learn, imbalanced-learn
- **模型保存**: joblib
- **Web 应用**: Streamlit
- **依赖管理**: uv

## 快速开始

### 前置要求

- Python 3.10 或更高版本
- pip（Python包管理器）

### 安装步骤

#### 1. 克隆仓库

```bash
git clone <repository-url>
cd Credit-Card-Fraud-Detection
```

#### 2. 创建虚拟环境（推荐）

**Windows:**
```bash
python -m venv venv
venv\Scripts\activate
```

**Linux/Mac:**
```bash
python3 -m venv venv
source venv/bin/activate
```

#### 3. 安装依赖

**方式1: 使用 requirements.txt（推荐）**
```bash
pip install -r requirements.txt
```

**方式2: 使用 setup.py**
```bash
pip install -e .
```

**方式3: 使用 uv（需要先安装 uv）**
```bash
pip install uv
uv sync
```

#### 4. 准备数据

确保 `data/creditcard.csv` 文件存在。如果不存在，请：

1. 从 Kaggle 下载数据集: https://www.kaggle.com/mlg-ulb/creditcardfraud
2. 将下载的 `creditcard.csv` 文件放入 `data/` 目录

#### 5. 训练模型

```bash
python src/train.py
```

训练完成后，模型文件将保存在 `models/` 目录中：
- `random_forest_model.joblib` - 随机森林模型
- `logistic_regression_model.joblib` - 逻辑回归模型
- `scaler.joblib` - 特征缩放器

#### 6. 运行应用

**方式1: 使用 agent_app.py（推荐）**
```bash
python src/agent_app.py
```

这将自动启动 Web 界面并在浏览器中打开。

**方式2: 直接运行 Streamlit**
```bash
streamlit run src/streamlit_app.py
```

### 详细使用指南

查看 [QUICKSTART.md](QUICKSTART.md) 获取详细的使用说明和常见问题解答。

## 运行测试

```bash
# 运行所有测试
uv run pytest tests/

# 运行特定测试文件
uv run pytest tests/test_data.py

# 查看测试覆盖率
uv run pytest tests/ --cov=src --cov-report=html
```

## 开发心得

### 主要困难与解决方案

1. **数据不平衡问题**
   - 问题：欺诈交易占比<1%
   - 解决方案：使用SMOTE算法对训练集进行过采样
   - 结果：召回率从60%提高到95%

2. **特征工程挑战**
   - 问题：28个匿名特征缺乏业务含义
   - 解决方案：利用特征重要性分析识别关键影响因素
   - 结果：成功识别出对欺诈检测贡献最大的前5个特征

### 对 AI 辅助编程的感受

**积极体验：**
- 快速生成代码框架，提高开发效率
- 提供代码优化建议，改善代码质量
- 协助解决复杂算法问题，缩短学习曲线

**注意事项：**
- 需要人工审查生成的代码，确保逻辑正确性
- 对于特定领域问题，需要提供足够的上下文信息
- 生成的代码可能缺乏优化，需要进一步调整

### 局限与未来改进

**局限性：**
- 模型仅使用静态特征，未考虑时序信息
- Demo应用缺乏用户认证和权限管理
- 数据可视化功能较为基础

**未来改进方向：**
- 引入时序模型（如LSTM）考虑交易序列信息
- 实现用户认证系统，确保数据安全性
- 增强数据可视化功能，提供更直观的分析结果
- 部署到云平台，提高系统的可扩展性和可靠性

## 参考资料

### 核心工具文档

| 资源 | 链接 | 说明 |
|------|------|------|
| Streamlit | https://streamlit.io/ | Web 框架 |
| scikit-learn | https://scikit-learn.org/ | 机器学习库 |
| Polars | https://pola.rs/ | 高性能 DataFrame |
| Pydantic | https://docs.pydantic.dev/ | 数据验证 |
| joblib | https://joblib.readthedocs.io/ | 模型保存与加载 |
| uv | https://github.com/astral-sh/uv | Python 包管理器 |

### 数据集

- Credit Card Fraud Detection: https://www.kaggle.com/mlg-ulb/creditcardfraud

### 相关论文

- Dal Pozzolo, A., Caelen, O., Le Borgne, Y. A., Waterschoot, S., & Bontempi, G. (2018). Learned lessons in credit card fraud detection from a practitioner perspective. Expert Systems with Applications, 103, 124-136.
- Bhattacharyya, S., Jha, M. K., Tharakunnel, K., & Westland, J. C. (2011). Data mining for credit card fraud: A comparative study. Decision Support Systems, 50(3), 602-613.

## 许可证

MIT License