计算机视觉 / 系统课时

构建 Web 检测服务

构建 Web 检测服务

本课把训练完成的 YOLOv5 权重封装成可调用的 HTTP 服务。完成后,你将得到一个 FastAPI 图片检测接口:客户端上传图片,服务完成解码、推理与结果整理,并返回边界框、类别和置信度等结构化 JSON。

学习目标

  • 使用 FastAPI 接收上传图片并调用 YOLOv5 模型
  • 将模型输出转换为稳定、可解析的 JSON 结构
  • 通过健康检查、启动命令和请求示例验证服务

定义接口输入与输出

检测接口采用 multipart/form-data 上传图片,避免客户端先把二进制转成体积更大的 Base64。响应中保留原图尺寸、检测数量和目标列表,目标列表统一返回左上角与右下角坐标、置信度、类别编号和类别名称。

请求处理链路包含上传文件、图片解码、模型推理、结果转换和 HTTP 响应。每一步都可能独立失败,因此接口需要分别返回可读的错误信息,而不是把所有异常都包装成模糊的 500 错误。

Web 图片检测接口处理流程

实现最小可用服务

下面示例假设当前目录存在 YOLOv5 源码目录 yolov5/,并且自定义权重位于 weights/best.pt。模型在模块加载时初始化一次,适合先完成接口联调;更完整的启动、关闭和并发管理将在下一课处理。

python
from io import BytesIO
from pathlib import Path

import torch
from fastapi import FastAPI, File, HTTPException, UploadFile
from PIL import Image, UnidentifiedImageError

BASE_DIR = Path(__file__).resolve().parent
YOLOV5_DIR = BASE_DIR / "yolov5"
WEIGHTS_PATH = BASE_DIR / "weights" / "best.pt"

app = FastAPI(title="YOLOv5 Detection Service", version="1.0.0")

# source="local" 强制从本地 YOLOv5 仓库加载,避免运行时访问网络。
model = torch.hub.load(
    str(YOLOV5_DIR),
    "custom",
    path=str(WEIGHTS_PATH),
    source="local",
)
model.conf = 0.25
model.iou = 0.45

@app.get("/health")
def health() -> dict:
    return {"status": "ok", "model": WEIGHTS_PATH.name}

@app.post("/detect")
async def detect(file: UploadFile = File(...)) -> dict:
    if file.content_type not in {"image/jpeg", "image/png"}:
        raise HTTPException(status_code=400, detail="仅支持 JPEG 或 PNG 图片")

    raw = await file.read()
    try:
        image = Image.open(BytesIO(raw)).convert("RGB")
    except UnidentifiedImageError as exc:
        raise HTTPException(status_code=400, detail="无法解析图片内容") from exc

    try:
        with torch.inference_mode():
            results = model(image, size=640)
    except Exception as exc:
        raise HTTPException(status_code=500, detail="模型推理失败") from exc

    detections = []
    for x1, y1, x2, y2, confidence, class_id in results.xyxy[0].cpu().tolist():
        class_index = int(class_id)
        detections.append(
            {
                "box": {
                    "x1": round(x1, 2),
                    "y1": round(y1, 2),
                    "x2": round(x2, 2),
                    "y2": round(y2, 2),
                },
                "confidence": round(confidence, 4),
                "class_id": class_index,
                "class_name": results.names[class_index],
            }
        )

    return {
        "filename": file.filename,
        "image_width": image.width,
        "image_height": image.height,
        "detection_count": len(detections),
        "detections": detections,
    }

预期结果

text
使用 Uvicorn 加载该文件后,服务提供 GET /health 和 POST /detect;模型在进程导入阶段加载一次。

这段代码是完整入口。安装依赖时还要包含 YOLOv5 仓库自身的 requirements.txt;python-multipart 用于解析上传文件,缺少时 FastAPI 会在启动阶段直接报错。

启动并验证接口

先安装 Web 服务依赖,再启动 Uvicorn。生产环境不要直接使用 --reload,因为它会创建监控进程并在文件变化时重启服务。

bash
python -m pip install fastapi uvicorn python-multipart pillow
python -m pip install -r yolov5/requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8000

预期输出

text
INFO:     Started server process [<ID>]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

进程编号可能不同。先调用健康检查,再上传一张测试图片。

bash
curl http://127.0.0.1:8000/health
curl -X POST "http://127.0.0.1:8000/detect" \
  -H "accept: application/json" \
  -F "file=@test.jpg;type=image/jpeg"

预期输出

text
{"status":"ok","model":"best.pt"}

{
  "filename": "test.jpg",
  "image_width": <WIDTH>,
  "image_height": <HEIGHT>,
  "detection_count": <COUNT>,
  "detections": [
    {
      "box": {"x1": <X1>, "y1": <Y1>, "x2": <X2>, "y2": <Y2>},
      "confidence": <CONFIDENCE>,
      "class_id": <CLASS_ID>,
      "class_name": "<CLASS_NAME>"
    }
  ]
}

坐标、置信度和目标数量由测试图片决定;无目标时 detections 是空数组。接口返回 200 只说明请求处理成功,不代表一定检测到目标。

处理边界与典型错误

上传文件必须限制类型和大小。示例已经校验 MIME 类型,但生产服务还应在读取前后限制请求体,防止超大图片占满内存。还应在网关层设置请求大小、超时和速率限制。

若启动时报 No such file or directory,先确认 yolov5/ 与 weights/best.pt 路径。若出现 Form data requires "python-multipart",安装对应依赖。若 GPU 推理报显存不足,可先缩小 size、降低并发或切换到 CPU 验证接口逻辑。

本课总结

  • 图片检测接口应明确区分文件校验、图片解码、模型推理和结果转换
  • 结构化响应需要稳定字段,并允许无目标时返回空数组
  • 健康检查与真实上传请求必须分别验证,避免只确认端口可访问

下一课预告

下一课将把模型加载移入应用生命周期,并加入设备选择、预热、资源释放和并发控制,避免每次请求重复加载模型或多个请求同时争用同一块显存。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建 Web 检测服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通