计算机视觉 / 系统课时
构建 Web 检测服务
构建 Web 检测服务
本课把训练完成的 YOLOv5 权重封装成可调用的 HTTP 服务。完成后,你将得到一个 FastAPI 图片检测接口:客户端上传图片,服务完成解码、推理与结果整理,并返回边界框、类别和置信度等结构化 JSON。
学习目标
- 使用 FastAPI 接收上传图片并调用 YOLOv5 模型
- 将模型输出转换为稳定、可解析的 JSON 结构
- 通过健康检查、启动命令和请求示例验证服务
定义接口输入与输出
检测接口采用 multipart/form-data 上传图片,避免客户端先把二进制转成体积更大的 Base64。响应中保留原图尺寸、检测数量和目标列表,目标列表统一返回左上角与右下角坐标、置信度、类别编号和类别名称。
请求处理链路包含上传文件、图片解码、模型推理、结果转换和 HTTP 响应。每一步都可能独立失败,因此接口需要分别返回可读的错误信息,而不是把所有异常都包装成模糊的 500 错误。

实现最小可用服务
下面示例假设当前目录存在 YOLOv5 源码目录 yolov5/,并且自定义权重位于 weights/best.pt。模型在模块加载时初始化一次,适合先完成接口联调;更完整的启动、关闭和并发管理将在下一课处理。
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,
}预期结果
使用 Uvicorn 加载该文件后,服务提供 GET /health 和 POST /detect;模型在进程导入阶段加载一次。这段代码是完整入口。安装依赖时还要包含 YOLOv5 仓库自身的 requirements.txt;python-multipart 用于解析上传文件,缺少时 FastAPI 会在启动阶段直接报错。
启动并验证接口
先安装 Web 服务依赖,再启动 Uvicorn。生产环境不要直接使用 --reload,因为它会创建监控进程并在文件变化时重启服务。
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预期输出
INFO: Started server process [<ID>]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000进程编号可能不同。先调用健康检查,再上传一张测试图片。
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"预期输出
{"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 验证接口逻辑。
本课总结
- 图片检测接口应明确区分文件校验、图片解码、模型推理和结果转换
- 结构化响应需要稳定字段,并允许无目标时返回空数组
- 健康检查与真实上传请求必须分别验证,避免只确认端口可访问
下一课预告
下一课将把模型加载移入应用生命周期,并加入设备选择、预热、资源释放和并发控制,避免每次请求重复加载模型或多个请求同时争用同一块显存。