YOLOv5与FastAPI构建高性能行人检测API实战

1. 项目背景与核心价值

行人检测作为机器视觉领域的经典应用场景，在智能安防、自动驾驶、客流统计等场景中具有广泛需求。YOLO系列算法凭借其出色的实时性能，成为工业界首选的检测框架之一。而FastAPI作为Python生态中高性能的Web框架，其异步特性和自动生成的API文档使其成为算法服务化的理想选择。

这个项目将YOLOv5s（最新11号版本）的行人检测模型通过FastAPI封装成RESTful API，解决了算法工程师常面临的三个痛点：

• 模型与业务系统的解耦
• 多语言客户端的统一调用
• 生产环境的高并发需求

2. 环境准备与依赖安装

2.1 基础环境配置

推荐使用Python 3.8+环境，过高版本可能导致PyTorch兼容性问题。创建隔离环境：

bash复制conda create -n yolo_api python=3.8
conda activate yolo_api

2.2 核心依赖安装

bash复制pip install fastapi[all] torch==1.12.1 torchvision==0.13.1 
pip install opencv-python pillow numpy

注意：torch与torchvision版本必须严格匹配，否则会出现CUDA相关错误

2.3 模型文件准备

从YOLOv5官方仓库下载v5s.pt预训练权重：

bash复制wget https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt

3. FastAPI服务核心实现

3.1 模型加载模块

创建model_loader.py实现模型初始化：

python复制import torch
from pathlib import Path

class YOLOModel:
    def __init__(self, model_path='yolov5s.pt'):
        self.model = torch.hub.load('ultralytics/yolov5', 
                                  'custom', 
                                  path=model_path,
                                  force_reload=True)
        self.model.eval()
        
    def predict(self, img_bytes):
        results = self.model(img_bytes)
        return results.pandas().xyxy[0].to_dict('records')

3.2 API路由设计

主服务文件main.py的核心逻辑：

python复制from fastapi import FastAPI, File, UploadFile
from model_loader import YOLOModel
import cv2
import numpy as np

app = FastAPI(title="YOLOv5行人检测API")
model = YOLOModel()

@app.post("/detect/")
async def detect_persons(file: UploadFile = File(...)):
    img_bytes = await file.read()
    img_array = np.frombuffer(img_bytes, np.uint8)
    img = cv2.imdecode(img_array, cv2.IMREAD_COLOR)
    
    results = model.predict(img)
    return {"detections": [r for r in results if r['name'] == 'person']}

3.3 性能优化技巧

1. 启用GPU加速：

python复制self.model = self.model.to('cuda' if torch.cuda.is_available() else 'cpu')

2. 批处理支持：

python复制@app.post("/batch_detect/")
async def batch_detect(files: List[UploadFile] = File(...)):
    batch_results = []
    for file in files:
        results = await detect_persons(file)
        batch_results.append(results)
    return {"batch_detections": batch_results}

4. 服务部署与测试

4.1 本地开发运行

使用uvicorn启动服务：

bash复制uvicorn main:app --reload --port 8000

4.2 生产环境部署

推荐使用gunicorn+uvicorn组合：

bash复制gunicorn -k uvicorn.workers.UvicornWorker -w 4 -b :8000 main:app

4.3 API测试示例

使用curl测试接口：

bash复制curl -X POST "http://127.0.0.1:8000/detect/" \
     -H "accept: application/json" \
     -F "file=@test.jpg"

5. 常见问题解决方案

5.1 CUDA内存不足

python复制# 在模型加载后添加
torch.cuda.empty_cache()

5.2 检测框漂移问题

调整置信度阈值：

python复制self.model.conf = 0.6  # 默认0.25

5.3 高并发优化

1. 启用FastAPI的异步特性
2. 增加gunicorn工作进程数
3. 使用Redis缓存高频检测结果

6. 进阶功能扩展

6.1 添加鉴权中间件

python复制from fastapi import Depends, HTTPException
from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key")

async def get_api_key(api_key: str = Depends(api_key_header)):
    if api_key != "your_secret_key":
        raise HTTPException(status_code=403)
    return api_key

@app.post("/secure_detect/")
async def secure_detect(file: UploadFile, _ = Depends(get_api_key)):
    return await detect_persons(file)

6.2 性能监控集成

使用Prometheus客户端：

python复制from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app)

7. 项目结构优化建议

推荐采用以下生产级目录结构：

code复制├── app/
│   ├── core/              # 核心逻辑
│   │   ├── config.py      # 配置管理
│   │   └── models.py      # 模型定义
│   ├── api/               # 路由定义
│   │   └── v1/            # 版本控制
│   │       └── endpoints/
│   ├── services/          # 业务服务
│   └── utils/             # 工具函数
├── tests/                 # 测试用例
├── requirements.txt       # 依赖文件
└── main.py                # 入口文件

在实际部署中发现，当并发请求超过50QPS时，建议：

1. 使用ONNX格式模型提升推理速度
2. 部署多个实例配合负载均衡
3. 对输入图像进行自动缩放（建议长边不超过640px）