计算机视觉 / 系统课时

模型导出与部署

模型导出与部署

本课把训练得到的 YOLO 权重转换为 ONNX 模型,并封装一个可调用的 HTTP 推理接口。完成后,你将明确模型文件、预处理、推理引擎、后处理和接口契约之间的边界,并能在本机完成一次部署验收。

学习目标

  • 理解模型导出与在线推理服务的完整链路
  • 将 .pt 权重导出为支持动态输入维度的 ONNX 文件
  • 封装并验证包含明确输入输出约定的检测接口

从训练权重到部署服务

训练阶段常直接使用 .pt 权重,部署阶段则要根据硬件和运行环境选择推理格式。无论最终选择 ONNX、TensorRT 还是 OpenVINO,服务端都应把模型细节封装在接口内部,对调用方只暴露稳定的请求与响应结构。

YOLO 模型导出与部署链路

部署链路中最容易出错的不是“能否加载模型”,而是输入尺寸、颜色顺序、归一化方式、置信度阈值和输出坐标是否保持一致。使用 Ultralytics 封装 ONNX 推理,可以先复用其预处理和后处理逻辑,再根据性能需求逐步替换为底层运行时。

导出 ONNX 模型

创建 export_model.py,指定训练权重、输入尺寸和 ONNX opset。dynamic=True 允许批次维度变化,适合服务接口按请求逐张处理图片。

python
import argparse
from pathlib import Path

from ultralytics import YOLO

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--weights", default="best.pt")
    parser.add_argument("--imgsz", type=int, default=640)
    parser.add_argument("--opset", type=int, default=12)
    args = parser.parse_args()

    weights = Path(args.weights)
    if not weights.is_file():
        raise FileNotFoundError(f"权重不存在:{weights}")

    # 先加载训练权重,再交由 Ultralytics 生成 ONNX 图。
    model = YOLO(str(weights))
    exported_path = model.export(
        format="onnx",
        imgsz=args.imgsz,
        opset=args.opset,
        dynamic=True,
        # 初次导出先关闭图优化,减少额外依赖和兼容性变量。
        simplify=False,
    )
    print(f"导出完成:{exported_path}")

if __name__ == "__main__":
    main()

预期结果

text
脚本读取指定权重并生成 ONNX 文件;实际文件路径会在执行命令后打印。

执行导出命令:

bash
python -m pip install ultralytics onnx onnxruntime
python export_model.py --weights best.pt --imgsz 640 --opset 12

预期结果

text
导出完成:best.onnx

实际导出日志会包含模型摘要、算子信息和耗时,文件名也可能带原权重目录。验证时至少确认 ONNX 文件存在且大小大于 0;若导出报算子不支持,应把 opset 调整到目标运行时支持的范围,并检查运行时是否支持模型中的算子。

约定接口输入与输出

本示例约定调用方通过 multipart/form-data 上传字段名为 file 的图片,并用查询参数 conf 控制置信度阈值。服务返回图片宽高和检测数组,每个检测项包含类别编号、类别名称、置信度以及 x1、y1、x2、y2 坐标。

项目 约定
请求方法 POST /v1/detect
图片字段 file
支持格式 OpenCV 可解码的 JPEG、PNG 等图片
置信度 conf,范围 0~1,默认 0.25
坐标 原图像素坐标,左上角与右下角形式
成功响应 HTTP 200,返回图片尺寸和检测数组
非法图片 HTTP 400,返回可读错误信息

接口契约应独立于具体模型格式。后续即使把 ONNX 换成 TensorRT,只要输入输出语义不变,客户端就不需要修改。

封装 FastAPI 推理接口

先安装服务端依赖并验证导入。服务器环境通常使用无界面的 opencv-python-headless,避免额外图形库依赖。

bash
python -m pip install fastapi uvicorn python-multipart ultralytics onnxruntime opencv-python-headless
python -c "import fastapi, cv2, onnxruntime; print('服务依赖可用')"

预期输出

text
服务依赖可用

创建 app.py。模型在进程启动时加载一次,避免每次请求重复读取文件;接口只负责解码图片、调用模型和整理响应。

python
import os

import cv2
import numpy as np
from fastapi import FastAPI, File, HTTPException, Query, UploadFile
from ultralytics import YOLO

MODEL_PATH = os.getenv("MODEL_PATH", "best.onnx")
# 模型在进程启动时加载一次,避免每次请求重复初始化。
MODEL = YOLO(MODEL_PATH)
app = FastAPI(title="YOLO Inference API")

@app.get("/health")
def health():
    return {"status": "UP", "model": MODEL_PATH}

@app.post("/v1/detect")
async def detect(
    file: UploadFile = File(...),
    conf: float = Query(default=0.25, ge=0.0, le=1.0),
):
    content = await file.read()
    # 上传内容必须能被 OpenCV 解码为三通道图像。
    image = cv2.imdecode(np.frombuffer(content, dtype=np.uint8), cv2.IMREAD_COLOR)
    if image is None:
        raise HTTPException(status_code=400, detail="无法解码上传图片")

    result = MODEL.predict(image, imgsz=640, conf=conf, verbose=False)[0]
    detections = []
    for box in result.boxes:
        class_id = int(box.cls[0].item())
        x1, y1, x2, y2 = [round(value, 2) for value in box.xyxy[0].tolist()]
        detections.append(
            {
                "classId": class_id,
                "className": result.names[class_id],
                "confidence": round(float(box.conf[0].item()), 4),
                "box": {"x1": x1, "y1": y1, "x2": x2, "y2": y2},
            }
        )

    # 返回原图坐标,调用方不需要反算模型内部缩放比例。
    height, width = image.shape[:2]
    return {
        "image": {"width": width, "height": height},
        "detections": detections,
    }

预期结果

text
应用定义完成;启动后将提供 GET /health 和 POST /v1/detect 两个接口。

启动服务:

bash
MODEL_PATH=best.onnx uvicorn app:app --host 0.0.0.0 --port 8000

预期输出

text
Uvicorn running on http://0.0.0.0:8000

端口可按部署环境调整为 <PORT>。生产环境还应由进程管理器或容器负责重启、日志和资源限制,而不是直接在终端长期运行单个进程。

调用接口并完成验收

使用一张测试图片调用接口:

bash
curl -i -F "file=@demo.jpg" "http://127.0.0.1:8000/v1/detect?conf=0.25"

预期结果

text
HTTP/1.1 200 OK
content-type: application/json

{"image":{"width":1280,"height":720},"detections":[{"classId":0,"className":"person","confidence":0.9132,"box":{"x1":110.42,"y1":84.16,"x2":502.71,"y2":690.33}}]}

上面的类别、尺寸、坐标和置信度只展示响应结构,实际值由模型和图片决定。验收时还应检查 /health 返回 UP、非法文件返回 HTTP 400、连续请求没有重复加载模型,并记录单次延迟和内存占用。

部署环境选择应服从硬件与性能目标:通用 CPU 可优先使用 ONNX Runtime;NVIDIA GPU 且追求低延迟时可评估 TensorRT;Intel CPU 或边缘设备可评估 OpenVINO。先用统一测试集比较精度、延迟和资源占用,再决定是否更换推理后端。

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

目录与阅读设置

记录一个想法

模型导出与部署

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

登录哪都通