2311020116_CreditCardFraudDetection/QUICKSTART.md

快速开始指南

本指南将帮助您在5分钟内运行信用卡欺诈检测系统。

前置要求

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

安装步骤

1. 克隆仓库

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

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

Windows:

python -m venv venv
venv\Scripts\activate

Linux/Mac:

python3 -m venv venv
source venv/bin/activate

3. 安装依赖

方式1: 使用 requirements.txt（推荐）

pip install -r requirements.txt

方式2: 使用 setup.py

pip install -e .

方式3: 使用 uv（需要先安装 uv）

pip install uv
uv sync

4. 准备数据

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

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

5. 训练模型

python src/train.py

训练完成后，模型文件将保存在 models/ 目录中：

• random_forest_model.joblib - 随机森林模型
• logistic_regression_model.joblib - 逻辑回归模型
• scaler.joblib - 特征缩放器

6. 运行应用

方式1: 使用 agent_app.py（推荐）

python src/agent_app.py

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

方式2: 直接运行 Streamlit

streamlit run src/streamlit_app.py

使用说明

Web 界面使用

1. 选择输入方式

   • 上传CSV文件：批量处理交易数据
   • 手动输入：输入30个特征值

2. 输入特征

   • Time: 交易时间（秒）
   • V1-V28: PCA转换后的特征
   • Amount: 交易金额

3. 点击"检测欺诈"按钮

   • 系统会显示预测结果
   • 查看特征解释
   • 获取行动建议

命令行使用

from src.agent_app import create_agent

agent = create_agent()

transaction = [
    0, -1.3598071336738, -0.0727811733098497, 2.53634673796914, 1.37815522427443,
    -0.338320769942518, 0.462387777762292, 0.239598554061257, 0.0986979012610507,
    0.363786969611213, 0.0907941719789316, -0.551599533260813, -0.617800855762348,
    -0.991389847235408, -0.311169353699879, 1.46817697209427, -0.470400525259478,
    0.207971241929242, 0.0257905801985591, 0.403992960255733, 0.251412098239705,
    -0.018306777944153, 0.277837575558899, -0.110473910188767, 0.0669280749146731,
    0.128539358273528, -0.189114843888824, 0.133558376740387, -0.0210530534538215,
    149.62
]

result = agent.process_transaction(transaction)
print(f"预测类别: {result.evaluation.class_name}")
print(f"欺诈概率: {result.evaluation.fraud_probability:.4f}")

运行测试

# 运行所有测试
pytest tests/

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

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

常见问题

Q1: 找不到数据文件

错误信息: FileNotFoundError: data/creditcard.csv

解决方案:

1. 确保数据文件存在于 data/ 目录
2. 从 Kaggle 下载数据集并放入正确位置

Q2: 模型文件不存在

错误信息: RuntimeError: 模型或缩放器加载失败

解决方案:

# 先训练模型
python src/train.py

Q3: 依赖安装失败

错误信息: pip install 失败

解决方案:

1. 确保使用 Python 3.10+
2. 升级 pip: pip install --upgrade pip
3. 使用国内镜像源: pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Q4: Streamlit 无法启动

错误信息: streamlit not found

解决方案:

pip install streamlit

Q5: 端口被占用

错误信息: Address already in use

解决方案:

# 使用不同端口启动
streamlit run src/streamlit_app.py --server.port 8502

项目结构

Credit-Card-Fraud-Detection/
├── data/                    # 数据目录
│   └── creditcard.csv      # 信用卡交易数据
├── models/                  # 模型目录
│   ├── random_forest_model.joblib
│   ├── logistic_regression_model.joblib
│   └── scaler.joblib
├── src/                     # 源代码
│   ├── agent_app.py        # Agent 入口（推荐使用）
│   ├── streamlit_app.py    # Streamlit Web 应用
│   ├── train.py            # 模型训练
│   ├── infer.py            # 推理接口
│   ├── data.py             # 数据处理
│   └── features.py         # 特征定义
├── tests/                   # 测试文件
├── requirements.txt        # Python 依赖
├── setup.py                # 安装脚本
├── QUICKSTART.md           # 快速开始指南（本文件）
└── README.md               # 详细文档

下一步

• 阅读 README.md 了解项目详情
• 查看 src/ 目录下的源代码
• 运行测试确保一切正常
• 开始使用系统进行欺诈检测

技术支持

如遇到问题，请：

1. 检查本指南的"常见问题"部分
2. 查看 README.md 获取更多信息
3. 提交 Issue 到项目仓库

许可证

MIT License