# 病虫害识别 API

基于 OpenRouter 的 Qwen3 VL 8B Instruct 模型构建的病虫害识别 FastAPI 服务。

## 功能特性

- 🖼️ 支持图片上传识别病虫害
- 🔍 智能识别植物病虫害类型和症状
- 💡 提供详细的防治建议
- 📡 支持 base64 编码图片识别
- 🚀 基于 FastAPI 的高性能异步接口

## 安装

1. 克隆项目并进入目录

```bash
cd hm-qwen3-vl
```

2. 安装依赖

```bash
pip install -e .
```

或者使用 uv（推荐）：

```bash
uv pip install -e .
```

3. 配置环境变量

复制 `env.example` 为 `.env` 并填入你的 OpenRouter API 密钥：

```bash
cp env.example .env
```

编辑 `.env` 文件，填入你的 API 密钥：

```
OPENROUTER_API_KEY=your_openrouter_api_key_here
```

获取 API 密钥：访问 [OpenRouter](https://openrouter.ai/keys) 注册并获取 API 密钥。

## 运行服务

```bash
python main.py
```

或者使用 uvicorn 直接运行：

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

服务启动后，访问以下地址：

- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/health

## API 接口

### 1. 图片上传识别

**POST** `/api/v1/identify`

上传图片文件进行病虫害识别。

**请求参数：**
- `file` (file, required): 植物图片文件（支持 jpg, jpeg, png）
- `question` (string, optional): 自定义问题，不提供则使用默认提示

**示例（使用 curl）：**

```bash
curl -X POST "http://localhost:8000/api/v1/identify" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/plant_image.jpg" \
  -F "question=请识别这张图片中的病虫害问题"
```

**示例（使用 Python requests）：**

```python
import requests

url = "http://localhost:8000/api/v1/identify"
files = {"file": open("plant_image.jpg", "rb")}
data = {"question": "请识别这张图片中的病虫害问题"}

response = requests.post(url, files=files, data=data)
print(response.json())
```

**响应示例：**

```json
{
  "success": true,
  "result": "根据图片分析，该植物叶片上出现了...",
  "image_info": {
    "format": "JPEG",
    "size": [1920, 1080],
    "mode": "RGB"
  }
}
```

### 2. Base64 图片识别

**POST** `/api/v1/identify/base64`

使用 base64 编码的图片进行识别。

**请求体（JSON）：**

```json
{
  "image_base64": "iVBORw0KGgoAAAANS...",
  "question": "请识别这张图片中的病虫害问题"
}
```

**示例：**

```bash
curl -X POST "http://localhost:8000/api/v1/identify/base64" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "base64_encoded_image_string",
    "question": "请识别病虫害"
  }'
```

### 3. 健康检查

**GET** `/health`

检查服务状态。

**响应：**

```json
{
  "status": "healthy",
  "model": "qwen/qwen-3-vl-8b-instruct"
}
```

## 使用 Swagger UI

启动服务后，访问 http://localhost:8000/docs 可以使用交互式 API 文档进行测试。

## 注意事项

1. **API 密钥安全**：请妥善保管你的 OpenRouter API 密钥，不要将其提交到版本控制系统
2. **图片大小**：图片会自动缩放到最大 4096x4096 像素
3. **请求超时**：API 请求超时时间设置为 60 秒
4. **费用**：使用 OpenRouter API 可能会产生费用，请查看 [OpenRouter 定价](https://openrouter.ai/models)

## 技术栈

- FastAPI：现代、快速的 Web 框架
- OpenRouter：统一的 AI 模型 API 接口
- Qwen3 VL 8B Instruct：多模态视觉语言模型
- Pillow：图片处理库
- httpx：异步 HTTP 客户端

## 许可证

MIT