基于 YOLOv 的 Web 目标检测系统：从模型导出到生产部署实战

3.2 模型准备与封装（关键！）

首先，将你的 YOLOv 模型（假设用 YOLOv5）导出为 ONNX 格式。在训练环境中运行：

import torch
model = torch.hub.load('ultralytics/yolov5', 'yolov5s', pretrained=True)
dummy_input = torch.randn(1, 3, 640, 640)
torch.onnx.export(model, dummy_input, "yolov5s.onnx", opset_version=12, input_names=['images'], output_names=['output'], dynamic_axes={'images': {0: 'batch_size'}, 'output': {0: 'batch_size'}})

将生成的 yolov5s.onnx 文件放到 backend/weights/ 目录下。

接着，在 backend/app/services/inference.py 中创建我们的推理服务类：

import onnxruntime as ort
import numpy as np
from PIL import Image
import cv2
from typing import List, Tuple, Dict
import time

class YOLOInferenceService:
    def __init__(self, model_path: str, providers=None):
        """初始化 ONNX Runtime 会话。"""
        if providers is None:
            providers = ['CUDAExecutionProvider', 'CPUExecutionProvider']
        self.session = ort.InferenceSession(model_path, providers=providers)
        self.input_name = self.session.get_inputs()[0].name
        self.input_shape = self.session.get_inputs()[0].shape
        self.img_size = self.input_shape[2:]
        print(f"模型加载成功，输入尺寸：{self.img_size}，使用设备：{self.session.get_providers()}")

    def preprocess(self, image: Image.Image) -> np.ndarray:
        """将 PIL 图像预处理为模型输入张量。"""
        img = np.array(image)
        h, w = img.shape[:2]
        r = min(self.img_size[0] / h, self.img_size[1] / w)
        new_h, new_w = int(h * r), int(w * r)
        img_resized = cv2.resize(img, (new_w, new_h))
        canvas = np.full((self.img_size[0], self.img_size[1], 3), 114, dtype=np.uint8)
        dh, dw = (self.img_size[0] - new_h) // 2, (self.img_size[1] - new_w) // 2
        canvas[dh:dh+new_h, dw:dw+new_w, :] = img_resized
        img_tensor = canvas.transpose(2, 0, 1)
        img_tensor = img_tensor[::-1, :, :]
        img_tensor = img_tensor.astype(np.float32) / 255.0
        img_tensor = np.expand_dims(img_tensor, axis=0)
        return img_tensor, (w, h), (new_w, new_h, dh, dw)

    def postprocess(self, outputs: np.ndarray, orig_size: Tuple, pad_info: Tuple, conf_threshold=0.25, iou_threshold=0.45) -> List[Dict]:
        """解析模型输出，应用 NMS，将框的坐标映射回原图尺寸。"""
        detections = []
        # 此处需实现过滤低置信度框、NMS、坐标反算等逻辑
        return detections

    async def predict(self, image: Image.Image) -> Dict:
        """异步推理管道。"""
        start_time = time.time()
        img_tensor, orig_size, pad_info = self.preprocess(image)
        preprocess_time = time.time()
        outputs = self.session.run(None, {self.input_name: img_tensor})[0]
        inference_time = time.time()
        results = self.postprocess(outputs, orig_size, pad_info)
        postprocess_time = time.time()
        return {
            'detections': results,
            'timing': {
                'preprocess_ms': (preprocess_time - start_time) * 1000,
                'inference_ms': (inference_time - preprocess_time) * 1000,
                'postprocess_ms': (postprocess_time - inference_time) * 1000,
                'total_ms': (postprocess_time - start_time) * 1000
            }
        }

_model_service = None

def get_inference_service():
    global _model_service
    if _model_service is None:
        model_path = "weights/yolov5s.onnx"
        _model_service = YOLOInferenceService(model_path)
    return _model_service

3.3 构建 FastAPI 后端

在 backend/app/main.py 中：

from fastapi import FastAPI, File, UploadFile, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from PIL import Image
import io
import logging
from app.services.inference import get_inference_service
from app.models.schemas import DetectionResponse

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

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.on_event("startup")
async def startup_event():
    logger.info("正在加载 YOLO 模型...")
    _ = get_inference_service()
    logger.info("模型加载完毕，服务准备就绪。")

@app.post("/detect/", response_model=DetectionResponse)
async def detect_objects(file: UploadFile = File(...)):
    if not file.content_type.startswith("image/"):
        raise HTTPException(status_code=400, detail="请上传图片文件。")
    try:
        contents = await file.read()
        image = Image.open(io.BytesIO(contents)).convert("RGB")
        logger.info(f"收到图片：{file.filename}, 尺寸：{image.size}")
        service = get_inference_service()
        result = await service.predict(image)
        return {
            "filename": file.filename,
            "detections": result["detections"],
            "timing": result["timing"],
            "status": "success"
        }
    except Exception as e:
        logger.error(f"处理图片时发生错误：{e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"服务器内部错误：{str(e)}")

@app.get("/health")
async def health_check():
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

3.4 实现一个简单的前端（Vue 示例）

在 frontend/src/views/Home.vue 中：

<template>
  <div>
    <h1>YOLOv5 目标检测演示</h1>
    <div>
      <input type="file" @change="onFileChange" accept="image/*" />
      <button @click="uploadImage" :disabled="!file || uploading">
        {{ uploading ? '检测中...' : '开始检测' }}
      </button>
    </div>
    <div v-if="error">{{ error }}</div>
    <div v-if="result">
      <h3>检测结果 (耗时：{{ result.timing.total_ms.toFixed(2) }} ms)</h3>
      <div>
        <img :src="imagePreview" alt="预览" v-if="imagePreview" />
        <canvas ref="canvas" v-if="imagePreview"></canvas>
      </div>
      <ul>
        <li v-for="(det, idx) in result.detections" :key="idx">
          {{ det.class }} (置信度：{{ (det.confidence * 100).toFixed(1) }}%) - 位置：{{ det.bbox }}
        </li>
      </ul>
    </div>
  </div>
</template>

<script>
import axios from 'axios';
export default {
  name: 'Home',
  data() {
    return {
      file: null,
      imagePreview: null,
      uploading: false,
      result: null,
      error: null,
      apiBase: 'http://localhost:8000'
    };
  },
  methods: {
    onFileChange(e) {
      this.file = e.target.files[0];
      this.result = null;
      this.error = null;
      if (this.file) {
        const reader = new FileReader();
        reader.onload = (e) => {
          this.imagePreview = e.target.result;
        };
        reader.readAsDataURL(this.file);
      }
    },
    async uploadImage() {
      if (!this.file) return;
      this.uploading = true;
      this.error = null;
      const formData = new FormData();
      formData.append('file', this.file);
      try {
        const response = await axios.post(`${this.apiBase}/detect/`, formData, {
          headers: { 'Content-Type': 'multipart/form-data' }
        });
        this.result = response.data;
      } catch (err) {
        console.error(err);
        this.error = err.response?.data?.detail || '上传或检测失败';
      } finally {
        this.uploading = false;
      }
    }
  }
};
</script>

4. 性能与安全考量

性能测试：在本地开发机上简单测试，使用 ONNX Runtime CUDA provider，单张图片推理总耗时约 50-100ms。使用 async 接口，在并发请求下 QPS 有显著提升。

安全性考量：

1. 输入校验：FastAPI + Pydantic 已帮我们做了基础类型校验。对于生产环境，还应限制文件大小，防止大文件攻击。
2. 防滥用：可以添加简单的速率限制，防止同一 IP 短时间内疯狂调用接口。
3. 模型安全：模型文件是核心资产，不要暴露在可公开访问的目录。

5. 生产环境避坑指南

这才是精华，很多坑只有部署时才会遇到：

1. 模型版本管理：当模型需要更新时，不要直接覆盖原文件。可以采用'模型版本目录'或数据库记录模型版本，API 通过参数指定使用哪个版本的模型。
2. 静态资源缓存：配置合理的缓存策略。对于检测返回的图片结果，也可以考虑生成唯一文件名并设置缓存头。
3. 日志与监控：一定要记录详细的日志。可以接入像 Sentry 这样的错误监控平台。
4. 健康检查与优雅退出：K8s 或 Docker Compose 等编排工具会使用 /health 端点。在应用关闭时，确保安全地释放模型资源。

CUDA 环境隔离：服务器上 CUDA 版本、驱动版本必须与 ONNX Runtime CUDA provider 要求的版本匹配。强烈建议使用 Docker。创建一个包含特定 CUDA 版本和 ONNX Runtime 的 Docker 镜像，确保环境一致性。

# backend/Dockerfile 示例
FROM nvidia/cuda:11.8.0-runtime-ubuntu22.04
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

写在最后

按照这个流程走下来，你应该能得到一个结构清晰、性能不错、易于维护的毕业设计项目。它不再是一个'勉强能跑'的脚本，而是一个有模有样的 Web 服务。

这个架构的扩展性也很好。比如，如何支持多模型服务？你可以在 services 目录下为不同模型创建不同的推理类，然后在 main.py 中通过路由参数来动态选择使用哪个服务。

最实际的下一步，我建议你尝试Docker 容器化部署。写一个 Dockerfile 和一个 docker-compose.yml 文件，把后端、前端都容器化。这不仅能彻底解决环境问题，还能让你提前接触工业界标准的部署方式，这绝对是简历上的一个亮点。

希望这篇笔记能帮你绕过那些踩过的坑，顺利搞定毕业设计，甚至为以后更复杂的 AI 应用开发打下个好基础。动手试试吧，遇到问题，社区和搜索引擎永远是你的好朋友。