计算机视觉 / 系统课时
设计检测接口
设计检测接口
本课把“上传一张图片并返回检测框”整理成稳定的 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 状态码负责表示错误类别,响应体负责提供可读原因,便于前端提示和日志追踪。
实现最小可运行接口
下面的示例先完成接口契约和校验,检测结果暂时返回空数组。下一课只需把占位逻辑替换为独立推理模块的调用,不必修改客户端协议。
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),
)安装依赖并启动服务:
python -m pip install fastapi uvicorn python-multipart
uvicorn app:app --host 0.0.0.0 --port 8000预期输出:
Uvicorn running on http://0.0.0.0:<PORT><PORT> 在本例中为 8000;不同启动参数会产生不同端口。
调用接口并检查结果
准备一张不超过 10 MB 的 test.jpg,执行请求:
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 的实际值会变化:
{
"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 模块,再接入本课定义的接口。