# Python (AI/ML) 项目：图像分类 API

## 概述

使用 Python, FastAPI 和一个预训练模型 (如 MobileNetV2) 构建一个 REST API。服务接收上传的图像，并返回分类预测结果。

## 功能需求

### 1. API 端点
- **健康检查**: `GET /` - 响应 `{ "status": "ok" }`。
- **图像分类**: `POST /predict`
  - **请求**: `multipart/form-data`，含名为 `file` 的图像 (JPEG, PNG)。
  - **响应**: `{ "filename": "...", "predictions": [ {"label": "...", "probability": ...} ] }`，包含 Top 5 预测结果。
  - **失败**: 返回 400 等错误码及信息。

### 2. 核心功能
- **模型加载**: 应用启动时加载一次预训练模型 (从 TensorFlow Hub, PyTorch Hub 等)。
- **图像预处理**: 预测前，将图像调整为模型所需尺寸 (如 224x224)，并进行归一化。
- **预测**: 将预处理后的图像输入模型获取结果。
- **结果后处理**: 将模型输出转换为带标签和概率的 Top 5 结果列表。

## 技术栈

- **语言**: Python 3.9+
- **框架**: FastAPI
- **AI框架**: TensorFlow/Keras 或 PyTorch
- **模型**: MobileNetV2 或 EfficientNet
- **图像处理**: Pillow, OpenCV-Python
- **计算**: NumPy
- **部署**: Docker

## 项目结构

```
/image-classifier-api
├── app/
│   ├── main.py             # FastAPI 入口和路由
│   ├── ml/
│   │   ├── model.py        # 模型加载和预测逻辑
│   │   └── utils.py        # 图像处理工具
│   └── schemas.py          # Pydantic 响应模型
├── models/                 # (可选) 存放下载的模型文件
├── static/                 # 存放 ImageNet 标签文件
├── Dockerfile
└── requirements.txt
```

## 任务步骤

1.  **环境设置**: 创建虚拟环境并安装 FastAPI, Uvicorn, TF/PyTorch, Pillow, NumPy。
2.  **模型准备**: 实现应用启动时从 Hub 下载并加载预训练模型的逻辑。下载 ImageNet 标签文件。
3.  **Schemas**: 定义 API 响应的 Pydantic 模型。
4.  **图像处理**: 在 `app/ml/utils.py` 中创建图像预处理和结果后处理的函数。
5.  **模型服务**: 在 `app/ml/model.py` 中封装模型加载和调用逻辑，使用 FastAPI 的 `startup` 事件确保只加载一次。
6.  **API路由**: 在 `main.py` 中创建 `/predict` 端点，接收上传文件，调用处理函数并返回结果。
7.  **容器化**: 编写 `Dockerfile` 构建应用镜像。
8.  **测试**: 使用 `pytest` 和 `httpx` 编写 API 测试，发送示例图片并验证响应。

**先行任务**: 确定预训练模型的来源、输入尺寸和像素值范围，并整理成文档。