937544e7b6
- 添加 requirements.txt 用于 pip 依赖管理 - 添加 setup.py 用于包安装 - 添加 QUICKSTART.md 快速开始指南 - 添加 check_environment.py 环境检查脚本 - 更新 README.md 添加详细的安装步骤 - 更新 .gitignore 忽略模型和数据文件
226 lines
5.1 KiB
Markdown
226 lines
5.1 KiB
Markdown
# 快速开始指南
|
||
|
||
本指南将帮助您在5分钟内运行信用卡欺诈检测系统。
|
||
|
||
## 前置要求
|
||
|
||
- 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
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
### Web 界面使用
|
||
|
||
1. **选择输入方式**
|
||
- 上传CSV文件：批量处理交易数据
|
||
- 手动输入：输入30个特征值
|
||
|
||
2. **输入特征**
|
||
- Time: 交易时间（秒）
|
||
- V1-V28: PCA转换后的特征
|
||
- Amount: 交易金额
|
||
|
||
3. **点击"检测欺诈"按钮**
|
||
- 系统会显示预测结果
|
||
- 查看特征解释
|
||
- 获取行动建议
|
||
|
||
### 命令行使用
|
||
|
||
```python
|
||
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}")
|
||
```
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
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: 模型或缩放器加载失败`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 先训练模型
|
||
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`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
pip install streamlit
|
||
```
|
||
|
||
### Q5: 端口被占用
|
||
|
||
**错误信息**: `Address already in use`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 使用不同端口启动
|
||
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](README.md) 了解项目详情
|
||
- 查看 [src/](src/) 目录下的源代码
|
||
- 运行测试确保一切正常
|
||
- 开始使用系统进行欺诈检测
|
||
|
||
## 技术支持
|
||
|
||
如遇到问题，请：
|
||
1. 检查本指南的"常见问题"部分
|
||
2. 查看 [README.md](README.md) 获取更多信息
|
||
3. 提交 Issue 到项目仓库
|
||
|
||
## 许可证
|
||
|
||
MIT License
|