README.md

---
title: Pet Classifier
emoji: 🐾
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: "4.31.0"
python_version: "3.10"
app_file: app_hf.py
pinned: false
license: mit
---

# 🐾 Oxford-IIIT Pet 37类分类项目

基于 Vibe Coding 开发理念，使用预训练模型微调实现宠物图片分类任务。

## 在线演示

[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/YOUR_USERNAME/pet-classifier)

## 项目特性

- ✅ 使用 ResNet50 预训练模型，仅微调分类头
- ✅ 支持 Mac MPS / CUDA / CPU 训练
- ✅ 自动下载 Oxford-IIIT Pet 数据集
- ✅ 生成错误分析报告（最容易混淆的5对类别）
- ✅ 生成 HTML 格式测试准确率报告
- ✅ Web 应用支持图片上传分类
- ✅ SQLite 数据库存储预测历史

## 项目结构

```
exam_4/
├── config.py              # 项目配置
├── download_dataset.py    # 数据集下载脚本
├── dataset.py             # 数据加载器
├── model.py               # 模型定义
├── train.py               # 训练脚本
├── error_analysis.py      # 错误分析脚本
├── generate_report.py     # 准确率报告生成
├── app.py                 # Flask Web 应用
├── database.py            # 数据库模块
├── requirements.txt       # 依赖包
├── templates/
│   └── index.html         # Web 前端页面
├── data/                  # 数据集目录
├── models/                # 模型保存目录
├── output/                # 输出目录
│   ├── reports/           # 准确率报告
│   └── error_analysis/    # 错误分析报告
├── uploads/               # 上传图片目录
└── database/              # 数据库目录
    └── predictions.db     # SQLite 预测历史数据库
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 下载数据集

```bash
python download_dataset.py
```

### 3. 训练模型

```bash
python train.py
```

训练完成后，模型将保存在 `models/best_model.pth`。

### 4. 生成测试报告

```bash
# 生成测试准确率报告
python generate_report.py

# 生成错误分析报告
python error_analysis.py
```

报告将保存在 `output/` 目录下。

### 5. 启动 Web 服务

```bash
python app.py
```

访问 http://localhost:5000 即可使用 Web 界面进行图片分类。

## 配置说明

在 `config.py` 中可以修改以下配置：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `MODEL_NAME` | resnet50 | 使用的预训练模型 |
| `NUM_CLASSES` | 37 | 分类数量 |
| `BATCH_SIZE` | 32 | 批次大小 |
| `NUM_EPOCHS` | 10 | 训练轮数 |
| `LEARNING_RATE` | 0.001 | 学习率 |
| `DEVICE` | mps | 运行设备 (mps/cuda/cpu) |
| `FREEZE_BACKBONE` | True | 是否冻结 backbone |

## API 接口

### POST /api/predict

上传图片并获取分类结果。

**请求**:
- Content-Type: multipart/form-data
- Body: file (图片文件)

**响应**:
```json
{
  "predicted_class": "Persian",
  "confidence": 95.32,
  "top5": [
    {"class": "Persian", "probability": 95.32},
    {"class": "Ragdoll", "probability": 2.15},
    ...
  ],
  "filename": "xxx.jpg",
  "original_filename": "pet.jpg",
  "prediction_id": 1
}
```

### GET /api/history

获取历史预测记录。

### GET /api/statistics

获取分类统计信息。

### GET /api/classes

获取所有类别列表。

## 37个宠物类别

**猫类 (12种)**: Abyssinian, Bengal, Birman, Bombay, British_Shorthair, Egyptian_Mau, Maine_Coon, Persian, Ragdoll, Russian_Blue, Siamese, Sphynx

**狗类 (25种)**: american_bulldog, american_pit_bull_terrier, basset_hound, beagle, boxer, chihuahua, english_cocker_spaniel, english_setter, german_shorthaired, great_pyrenees, havanese, japanese_chin, keeshond, leonberger, miniature_pinscher, newfoundland, pomeranian, pug, saint_bernard, samoyed, scottish_terrier, shiba_inu, staffordshire_bull_terrier, wheaten_terrier, yorkshire_terrier

## 输出文件

1. **训练历史**: `output/training_history.json`
2. **测试报告**: `output/reports/test_accuracy_report.html`
3. **错误分析**: `output/error_analysis/error_analysis_report.html`
4. **混淆对数据**: `output/error_analysis/confusion_pairs.json`
5. **预测数据库**: `database/predictions.db`

## 技术栈

- **深度学习**: PyTorch, timm
- **数据处理**: NumPy, Pandas, Pillow
- **Web 框架**: Flask
- **数据库**: SQLite, SQLAlchemy
- **可视化**: Matplotlib, Seaborn

## 开发理念

本项目采用 **Vibe Coding** 开发理念：
- 快速迭代，持续改进
- AI 辅助开发，提高效率
- 关注核心功能，简化流程
- 现代化 UI/UX 设计

## License

MIT License