2311020116_CreditCardFraudDetection/README.md

# 信用卡欺诈检测系统

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

## 项目结构

```
ml_course_design/
├── pyproject.toml            # 项目配置与依赖
├── uv.lock                   # 锁定的依赖版本
├── requirements.txt          # Python依赖列表
├── setup.py                # 包安装脚本
├── README.md               # 项目说明与报告
├── QUICKSTART.md           # 快速开始指南
├── .env.example            # 环境变量模板
├── .gitignore             # Git 忽略规则
├── install.bat            # Windows一键安装脚本
├── install.sh             # Linux/Mac一键安装脚本
├── auto_install.py        # 跨平台自动化安装脚本
├── check_environment.py   # 环境检查脚本
│
├── 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

## 快速开始

### 🚀 一键安装（推荐）

**最简单的方式 - 只需运行一个脚本！**

#### Windows 用户

双击运行 `install.bat` 文件，或在命令行中执行：

```bash
install.bat
```

#### Linux/Mac 用户

```bash
chmod +x install.sh
./install.sh
```

#### 跨平台方式（使用Python）

```bash
python auto_install.py
```

**一键安装脚本会自动完成以下步骤：**
1. ✓ 检查Python版本
2. ✓ 安装所有依赖包
3. ✓ 提示下载数据文件
4. ✓ 自动训练模型（如果需要）
5. ✓ 运行环境检查
6. ✓ 启动Web界面

**注意：** 首次运行时，脚本会提示您下载数据文件，请按照提示操作。

---

### 手动安装

如果您希望手动控制每个步骤，请按照以下说明操作：

### 前置要求

- 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) 获取详细的使用说明和常见问题解答。

---

## 一键安装脚本说明

### 脚本功能

我们提供了三个自动化安装脚本，让您无需手动执行多个步骤：

| 脚本文件 | 适用平台 | 使用方法 |
|-----------|---------|---------|
| `install.bat` | Windows | 双击运行或在命令行执行 `install.bat` |
| `install.sh` | Linux/Mac | `chmod +x install.sh && ./install.sh` |
| `auto_install.py` | 跨平台 | `python auto_install.py` |

### 自动化流程

脚本会自动完成以下步骤：

1. **环境检查**
   - 验证Python版本（需要3.10+）
   - 检查必要的依赖包

2. **依赖安装**
   - 自动安装所有Python依赖
   - 支持国内镜像源加速

3. **数据准备**
   - 检查数据文件是否存在
   - 提供数据下载链接和说明

4. **模型训练**
   - 自动训练模型（如果不存在）
   - 保存模型到 `models/` 目录

5. **环境验证**
   - 运行环境检查脚本
   - 验证所有组件正常

6. **启动应用**
   - 自动启动Web界面
   - 在浏览器中打开应用

### 首次使用

首次运行脚本时，您需要：

1. **下载数据文件**
   - 访问: https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud
   - 下载 `creditcard.csv`
   - 放入项目的 `data/` 目录

2. **运行安装脚本**
   - Windows: 双击 `install.bat`
   - Linux/Mac: 执行 `./install.sh`

3. **等待安装完成**
   - 依赖安装：2-5分钟
   - 模型训练：5-10分钟（取决于硬件）

4. **开始使用**
   - Web界面会自动在浏览器中打开
   - 访问地址: http://localhost:8501

### 常见问题

**Q: 脚本运行失败怎么办？**

A: 可以尝试以下步骤：
1. 确保Python版本 >= 3.10
2. 检查网络连接
3. 手动运行: `pip install -r requirements.txt`
4. 查看 [QUICKSTART.md](QUICKSTART.md) 的常见问题部分

**Q: 如何使用国内镜像源加速安装？**

A: 修改安装命令：
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**Q: 模型训练时间太长怎么办？**

A: 模型训练需要一定时间，这是正常的。您可以：
- 等待训练完成（推荐）
- 使用预训练模型（如果提供）
- 减少训练数据量（修改代码）

**Q: 如何停止Web服务？**

A: 在运行脚本的终端窗口中按 `Ctrl+C`

---

## 运行测试

```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