计算机视觉 / 系统课时

设计检测接口

设计检测接口

本课把“上传一张图片并返回检测框”整理成稳定的 HTTP 契约。完成后,你将得到一个可运行的 FastAPI 最小接口,明确图片、阈值、成功结果和错误响应的格式,为后续接入真实 YOLOv5 推理模块留出清晰边界。

学习目标

  • 设计图片上传、置信度阈值和 IoU 阈值的请求格式
  • 定义可扩展的检测结果与统一错误响应
  • 运行并验证一个不依赖真实模型的最小接口

从调用方反推接口边界

检测服务的调用方通常只关心四件事:图片如何提交、阈值如何调整、结果字段如何读取、失败时如何处理。接口层负责协议转换和参数校验,不应把模型加载、图像预处理或张量细节暴露给客户端。

检测接口数据流

本课采用 POST /v1/detections,图片放在 multipart/form-data 的 image 字段中,conf 与 iou 作为同一表单的可选字段。这样既适合浏览器、移动端和脚本上传,也避免把二进制图片编码进 JSON。

定义请求与响应契约

请求字段保持精简:

字段 类型 必填 约束
image 文件 是 JPEG、PNG 或 WebP,最大 10 MB
conf 小数 否 0~1,默认 0.25
iou 小数 否 0~1,默认 0.45

成功响应包含请求标识、原文件名、实际参数、检测数量、检测项和耗时。单个检测项使用 label、classId、confidence 与 box,其中边界框统一采用像素坐标 x1、y1、x2、y2。客户端无需理解模型输出张量,就能直接绘制矩形框。

错误响应统一为 code、message 和 requestId。HTTP 状态码负责表示错误类别,响应体负责提供可读原因,便于前端提示和日志追踪。

实现最小可运行接口

下面的示例先完成接口契约和校验,检测结果暂时返回空数组。下一课只需把占位逻辑替换为独立推理模块的调用,不必修改客户端协议。

python
from time import perf_counter
from uuid import uuid4

from fastapi import FastAPI, File, Form, HTTPException, UploadFile
from fastapi.responses import JSONResponse
from pydantic import BaseModel

ALLOWED_CONTENT_TYPES = {"image/jpeg", "image/png", "image/webp"}
MAX_IMAGE_BYTES = 10 * 1024 * 1024

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

class Box(BaseModel):
    x1: float
    y1: float
    x2: float
    y2: float

class DetectionItem(BaseModel):
    label: str
    classId: int
    confidence: float
    box: Box

class InferenceParameters(BaseModel):
    conf: float
    iou: float

class DetectionResponse(BaseModel):
    requestId: str
    filename: str
    objectCount: int
    parameters: InferenceParameters
    detections: list[DetectionItem]
    elapsedMs: float

@app.exception_handler(HTTPException)
async def handle_http_exception(_, exc: HTTPException) -> JSONResponse:
    message = exc.detail if isinstance(exc.detail, str) else "request failed"
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "code": f"HTTP_{exc.status_code}",
            "message": message,
            "requestId": str(uuid4()),
        },
    )

@app.post("/v1/detections", response_model=DetectionResponse)
async def detect(
    image: UploadFile = File(...),
    conf: float = Form(0.25),
    iou: float = Form(0.45),
) -> DetectionResponse:
    request_id = str(uuid4())
    started = perf_counter()

    if image.content_type not in ALLOWED_CONTENT_TYPES:
        raise HTTPException(415, "only JPEG, PNG and WebP are supported")
    if not 0 <= conf <= 1 or not 0 <= iou <= 1:
        raise HTTPException(422, "conf and iou must be between 0 and 1")

    payload = await image.read()
    if not payload:
        raise HTTPException(400, "image file is empty")
    if len(payload) > MAX_IMAGE_BYTES:
        raise HTTPException(413, "image file exceeds 10 MB")

    # 此处只保留接口占位,下一课再调用真实推理模块。
    detections: list[DetectionItem] = []
    return DetectionResponse(
        requestId=request_id,
        filename=image.filename or "unnamed",
        objectCount=len(detections),
        parameters=InferenceParameters(conf=conf, iou=iou),
        detections=detections,
        elapsedMs=round((perf_counter() - started) * 1000, 2),
    )

安装依赖并启动服务:

bash
python -m pip install fastapi uvicorn python-multipart
uvicorn app:app --host 0.0.0.0 --port 8000

预期输出:

text
Uvicorn running on http://0.0.0.0:<PORT>

<PORT> 在本例中为 8000;不同启动参数会产生不同端口。

调用接口并检查结果

准备一张不超过 10 MB 的 test.jpg,执行请求:

bash
curl -X POST "http://127.0.0.1:8000/v1/detections" -F "image=@test.jpg" -F "conf=0.3" -F "iou=0.45"

预期响应状态码为 200,响应体结构如下,requestId 和 elapsedMs 的实际值会变化:

json
{
  "requestId": "<ID>",
  "filename": "test.jpg",
  "objectCount": 0,
  "parameters": {
    "conf": 0.3,
    "iou": 0.45
  },
  "detections": [],
  "elapsedMs": 0.12
}

上传文本文件时,服务应返回 415。将 conf 设为 1.2 时,服务应返回 422。这两项验证可以确认文件类型和阈值边界已经在模型调用前被拦截。

本课总结

  • 检测接口应隔离 HTTP 协议与模型实现,只暴露稳定的数据契约
  • 图片适合使用 multipart/form-data 上传,阈值作为同一表单字段传递
  • 成功与失败响应都应携带请求标识,便于客户端处理和服务端追踪

下一课预告

下一课将把模型加载、图像解码、YOLOv5 推理和检测结果转换封装为独立 Python 模块,再接入本课定义的接口。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计检测接口

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

登录哪都通