init proj

README.md

@@ -1,3 +1,178 @@
-# crop-disease
+# 病虫害识别 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
 
-基于Qwen3 VL 模型的病虫害识别 FastAPI 服务