252 lines
4.6 KiB
Markdown
252 lines
4.6 KiB
Markdown
# 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模型包装类
|
||
|
||
## 许可证
|
||
|
||
[根据项目实际许可证填写] |