github-actions-creator/docs/python-ai.md

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 测试，发送示例图片并验证响应。

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