179 lines
3.5 KiB
Markdown
179 lines
3.5 KiB
Markdown
# 病虫害识别 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
|
||
|