将检测任务迁移python

python-inference-service/README.md

@@ -0,0 +1,252 @@
+# Python推理服务
+
+基于FastAPI的YOLOv8目标检测推理服务。
+
+## 功能特性
+
+- 支持YOLOv8模型推理
+- RESTful API接口
+- 支持Base64图像和文件上传
+- 支持GPU加速（可选）
+- Docker部署支持
+
+## 模型要求
+
+本服务使用**YOLOv8**（Ultralytics）进行目标检测。
+
+### 模型文件准备
+
+1. **模型文件**: 将YOLOv8训练好的模型文件命名为`best.pt`，放在`models/`目录下
+2. **类别文件**: （可选）创建`classes.txt`文件，每行一个类别名称
+3. **配置文件**: `models.json`配置模型参数
+
+### 目录结构
+
+```
+python-inference-service/
+├── app/
+│   ├── __init__.py
+│   ├── main.py          # FastAPI应用
+│   ├── detector.py      # 检测器封装
+│   └── models.py        # 数据模型
+├── models/
+│   ├── best.pt          # YOLOv8模型文件（必需）
+│   ├── classes.txt      # 类别名称（可选）
+│   ├── yolov8_model.py  # YOLOv8模型包装类
+│   └── models.json      # 模型配置
+├── requirements.txt
+└── Dockerfile
+```
+
+## 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+主要依赖：
+- `ultralytics>=8.0.0` - YOLOv8框架
+- `fastapi` - Web框架
+- `uvicorn` - ASGI服务器
+- `opencv-python` - 图像处理
+- `torch` - PyTorch
+
+## 配置模型
+
+编辑`models/models.json`：
+
+```json
+[
+  {
+    "name": "yolov8_detector",
+    "path": "models/yolov8_model.py",
+    "size": [640, 640],
+    "comment": "YOLOv8检测模型"
+  }
+]
+```
+
+参数说明：
+- `name`: 模型名称（API调用时使用）
+- `path`: 模型包装类的路径
+- `size`: 输入图像尺寸 [宽度, 高度]
+
+## 启动服务
+
+### 本地启动
+
+```bash
+# 启动服务（默认端口8000）
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+
+# 或使用启动脚本
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+### Docker启动
+
+```bash
+# 构建镜像
+docker build -t python-inference-service .
+
+# 运行容器
+docker run -p 8000:8000 \
+  -v $(pwd)/models:/app/models \
+  python-inference-service
+```
+
+### 使用GPU
+
+```bash
+# 确保安装了NVIDIA Docker Runtime
+docker run --gpus all -p 8000:8000 \
+  -v $(pwd)/models:/app/models \
+  python-inference-service
+```
+
+## API接口
+
+服务启动后访问：http://localhost:8000/docs 查看API文档
+
+### 1. 健康检查
+
+```bash
+GET /health
+```
+
+### 2. 获取可用模型列表
+
+```bash
+GET /api/models
+```
+
+### 3. Base64图像检测
+
+```bash
+POST /api/detect
+Content-Type: application/json
+
+{
+  "model_name": "yolov8_detector",
+  "image_data": "base64_encoded_image_string"
+}
+```
+
+### 4. 文件上传检测
+
+```bash
+POST /api/detect/file
+Content-Type: multipart/form-data
+
+model_name: yolov8_detector
+file: <image_file>
+```
+
+## 响应格式
+
+```json
+{
+  "model_name": "yolov8_detector",
+  "detections": [
+    {
+      "label": "[yolov8_detector] 类别名",
+      "confidence": 0.95,
+      "x": 100,
+      "y": 150,
+      "width": 200,
+      "height": 180,
+      "color": 65280
+    }
+  ],
+  "inference_time": 45.6
+}
+```
+
+## 自定义模型
+
+要使用自己训练的YOLOv8模型：
+
+1. **训练模型**：使用Ultralytics YOLOv8训练您的模型
+   ```python
+   from ultralytics import YOLO
+   
+   model = YOLO('yolov8n.yaml')
+   model.train(data='your_data.yaml', epochs=100)
+   ```
+
+2. **导出模型**：训练完成后会生成`best.pt`文件
+
+3. **准备类别文件**：创建`classes.txt`
+   ```
+   class1
+   class2
+   class3
+   ```
+
+4. **放置文件**：将`best.pt`和`classes.txt`放到`models/`目录
+
+5. **更新配置**：确保`models.json`配置正确
+
+6. **重启服务**
+
+## 环境变量
+
+- `MODEL_DIR`: 模型目录路径（默认：`/app/models`）
+- `MODELS_JSON`: 模型配置文件路径（默认：`models/models.json`）
+
+## 性能优化
+
+### GPU加速
+
+服务会自动检测GPU并使用。如果有多张GPU，可以指定：
+
+```bash
+CUDA_VISIBLE_DEVICES=0 uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+### 置信度阈值
+
+在`yolov8_model.py`中调整：
+
+```python
+self.conf_threshold = 0.25  # 降低阈值检测更多目标
+```
+
+## 故障排查
+
+### 模型加载失败
+
+```
+错误：找不到 best.pt
+解决：确保模型文件在 models/ 目录下
+```
+
+### GPU不可用
+
+```
+错误：CUDA not available
+解决：
+1. 检查NVIDIA驱动
+2. 检查PyTorch GPU版本
+3. 检查CUDA版本兼容性
+```
+
+### 推理速度慢
+
+```
+解决：
+1. 使用GPU加速
+2. 使用更小的模型（如yolov8n.pt）
+3. 减小输入图像尺寸
+```
+
+## 开发者
+
+如需修改或扩展功能，请参考：
+- `app/main.py` - API路由定义
+- `app/detector.py` - 检测器基类
+- `models/yolov8_model.py` - YOLOv8模型包装类
+
+## 许可证
+
+[根据项目实际许可证填写]