从AI模型到桌面应用：用Electron + FastAPI + YOLO打造开箱即用的智能检测系统（后端文档）

基于 FastAPI 框架开发的目标检测系统后端服务，集成 YOLO 模型进行图像和视频的目标检测，支持大语言模型和多模态模型对话功能。

---

目录

• 项目简介

• 技术栈

• 项目结构

• 快速开始

• 核心模块详解

  • 主入口文件

  • 通用响应模型

  • 图片管理模块

  • 视频管理模块

  • 日志管理模块

  • 系统监控模块

  • 模型管理模块

  • 大语言模型模块

  • 多模态模型模块

  • 仪表板模块

• API 接口文档

• 数据模型

• 配置说明

• 部署指南

• 常见问题

---

项目简介

本项目是一个功能完善的目标检测系统后端服务，提供以下核心功能：

• 🖼️ 图片目标检测：支持图片上传、预览、检测、下载、批量操作

• 🎬 视频目标检测：支持视频上传、流式播放、逐帧检测、H.264 编码输出

• 📊 系统监控：实时监控 CPU、内存、磁盘、网络等系统资源

• 🤖 模型管理：支持 YOLO 模型上传、加载、切换

• 💬 LLM 对话：集成大语言模型，支持流式输出

• 👁️ VLLM 多模态：支持图像+文本的多模态对话

• 📝 日志管理：系统日志记录、预览、下载

---

技术栈

技术	版本	说明
Python	3.8+	编程语言
FastAPI	0.104+	高性能 Web 框架
Uvicorn	0.24+	ASGI 服务器
Ultralytics	8.0+	YOLO 目标检测库
OpenCV	4.8+	视频处理库
Pillow	10.0+	图像处理库
psutil	5.9+	系统监控库
httpx	0.25+	异步 HTTP 客户端
Pydantic	2.0+	数据验证库

依赖安装

pip install -r requirements.txt

requirements.txt 内容：

fastapi>=0.104.0
uvicorn[standard]>=0.24.0
python-multipart>=0.0.6
pillow>=10.0.0
psutil>=5.9.0
httpx>=0.25.0
pydantic>=2.0.0
ultralytics>=8.0.0
opencv-python>=4.8.0

---

项目结构

backend/
├── main.py                 # 🚀 FastAPI 主入口文件
├── schemas.py              # 📦 通用响应模型与工具函数
├── requirements.txt        # 📋 Python 依赖列表
├── yolo11n.pt             # 🎯 默认 YOLO 模型文件 (5.3MB)
├── routers/               # 🔌 API 路由模块目录
│   ├── __init__.py        # 路由模块初始化
│   ├── images.py          # 📷 图片管理 (9个接口)
│   ├── videos.py          # 🎬 视频管理 (12个接口)
│   ├── logs.py            # 📝 日志管理 (5个接口)
│   ├── systems.py         # 💻 系统监控 (1个接口)
│   ├── models.py          # 🤖 模型管理 (8个接口)
│   ├── dashboard.py       # 📊 仪表板 (6个接口)
│   ├── llm.py             # 💬 大语言模型 (2个接口)
│   └── vllm.py            # 👁️ 多模态模型 (2个接口)
├── images/                # 🖼️ 图片存储目录
│   ├── upload/            # 上传的原始图片
│   └── detected/          # 检测结果图片
├── videos/                # 🎥 视频存储目录
│   ├── upload/            # 上传的原始视频
│   └── detected/          # 检测结果视频
├── models/                # 📦 模型文件存储目录
│   └── models_info.json   # 模型元信息
└── logs/                  # 📋 日志文件存储目录
    └── YYYY.MM.DD.log     # 按日期命名的日志文件

---

快速开始

1. 打开后端

cd backend

2. 创建虚拟环境（推荐）

python -m venv venv
​
# Windows
.\venv\Scripts\activate
​
# Linux/Mac
source venv/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 启动服务

python main.py

或使用 uvicorn 启动（支持热重载）：

uvicorn main:app --host 0.0.0.0 --port 10077 --reload

5. 访问服务

• API 根路由：http://localhost:10077

• Swagger 文档：http://localhost:10077/docs

• ReDoc 文档：http://localhost:10077/redoc

---

核心模块详解

1. 主入口文件 (main.py)

主入口文件是整个后端服务的核心，负责：

• 应用初始化：创建 FastAPI 实例

• 生命周期管理：服务启动/关闭时的初始化和清理

• 中间件配置：CORS 跨域配置

• 静态文件挂载：图片、视频静态资源服务

• 路由注册：注册所有 API 路由模块

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles

# 创建 FastAPI 应用
app = FastAPI(
    title="目标检测系统 API",
    description="支持图片、视频的上传、检测、管理，集成 YOLO 模型和大语言模型",
    version="1.0.0",
    lifespan=lifespan
)

# CORS 配置 - 允许所有来源跨域访问
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 静态文件挂载
app.mount("/static/images/upload", StaticFiles(directory=IMAGES_UPLOAD_DIR))
app.mount("/static/images/detected", StaticFiles(directory=IMAGES_DETECTED_DIR))
app.mount("/static/videos/upload", StaticFiles(directory=VIDEOS_UPLOAD_DIR))
app.mount("/static/videos/detected", StaticFiles(directory=VIDEOS_DETECTED_DIR))

# 路由注册
app.include_router(images.router, prefix="/api/images", tags=["图片管理"])
app.include_router(videos.router, prefix="/api/videos", tags=["视频管理"])
app.include_router(logs.router, prefix="/api/logs", tags=["日志管理"])
app.include_router(systems.router, prefix="/api/systems", tags=["系统监控"])
app.include_router(models.router, prefix="/api/models", tags=["模型管理"])
app.include_router(llm.router, prefix="/api/llm", tags=["大语言模型"])
app.include_router(vllm.router, prefix="/api/vllm", tags=["多模态模型"])

日志配置：

系统使用 Python 标准 logging 模块，日志按日期存储：

log_filename = datetime.now().strftime("%Y.%m.%d.log")
log_filepath = os.path.join(LOGS_DIR, log_filename)

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    handlers=[
        logging.FileHandler(log_filepath, encoding="utf-8"),
        logging.StreamHandler()  # 同时输出到控制台
    ]
)

---

2. 通用响应模型 (schemas.py)

定义统一的 API 响应格式，确保所有接口返回一致的 JSON 结构。

from typing import Any, Optional
from pydantic import BaseModel

class APIResponse(BaseModel):
    """统一 API 响应格式"""
    code: int = 200
    message: str = "成功"
    data: Optional[Any] = None

def success_response(data: Any = None, message: str = "成功") -> dict:
    """成功响应"""
    return {"code": 200, "message": message, "data": data}

def error_response(message: str = "操作失败", code: int = 400) -> dict:
    """错误响应"""
    return {"code": code, "message": message, "data": None}

统一响应格式示例：

// 成功响应
{
  "code": 200,
  "message": "操作成功",
  "data": { ... }
}

// 错误响应
{
  "detail": "错误信息描述"
}

---

3. 图片管理模块 (routers/images.py)

功能概述： 提供完整的图片生命周期管理，包括上传、预览、检测、下载、删除等功能。

核心特性：

• 支持 PNG、JPG、JPEG、GIF、BMP 格式

• 单文件最大 10MB 限制

• 延迟加载 YOLO 模型（节省内存）

• 检测结果自动保存并带边界框标注

图片接口列表（9个）：

方法	路径	功能	说明
POST	/upload/{filename}	上传图片	支持重命名，自动添加时间戳
GET	/list	获取图片列表	返回所有上传图片信息
GET	/view/{filename}	查看图片	支持 width/height 参数缩放
GET	/download/{filename}	下载图片	返回原始文件
POST	/download/batch	批量下载	打包成 ZIP 文件
DELETE	/delete/{filename}	删除图片	同时删除检测结果
DELETE	/delete/batch	批量删除	批量删除多个图片
GET	/detectedlist	检测结果列表	获取所有检测结果图片
POST	/detect/{filename}	图片检测	执行 YOLO 目标检测

---

4. 视频管理模块 (routers/videos.py)

功能概述： 提供视频的完整管理功能，支持视频上传、流式播放、逐帧目标检测。

核心特性：

• 支持 MP4、AVI、MOV、WMV、FLV、MKV 格式

• 单文件最大 500MB 限制

• 逐帧 YOLO 检测

• 自动转码为 H.264 格式（需要 FFmpeg）

• 输出分辨率限制为 720p（内存优化）

视频接口列表（12个）：

方法	路径	功能
POST	/upload/{filename}	上传视频
GET	/list	获取视频列表
GET	/view/{filename}	流式播放视频
GET	/download/{filename}	下载视频
POST	/download/batch	批量下载视频
DELETE	/delete/{filename}	删除视频
POST	/delete/batch	批量删除视频
GET	/detected/list	检测结果列表
GET	/detected/view/{filename}	播放检测结果
GET	/detected/download/{filename}	下载检测结果
POST	/detected/download/batch	批量下载检测结果
DELETE	/detected/delete/{filename}	删除检测结果
POST	/detected/delete/batch	批量删除检测结果
POST	/detect	视频目标检测

---

5. 日志管理模块 (routers/logs.py)

功能概述： 管理系统运行日志，支持查看、预览、下载。

日志接口列表（5个）：

方法	路径	功能
GET	/list	获取日志文件列表
GET	/preview/{filename}	预览日志内容
GET	/download/{filename}	下载日志文件
POST	/download/batch	批量下载日志
DELETE	/{filename}	删除日志文件

---

6. 系统监控模块 (routers/systems.py)

功能概述： 实时获取系统资源使用情况。

响应数据结构：

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "cpu": { "percent": 45.5, "count": 8 },
    "memory": { "total": 17179869184, "used": 10300000000, "percent": 60.0 },
    "disk": { "total": 512000000000, "used": 204000000000, "percent": 40.0 },
    "network": { "bytes_sent": 1234567890, "bytes_recv": 9876543210 },
    "uptime": { "boot_time": "2026-01-30 08:00:00", "days": 1, "hours": 3, "minutes": 47, "seconds": 44 },
    "system": { "system": "Windows", "release": "11" }
  }
}

---

7. 模型管理模块 (routers/models.py)

功能概述： YOLO 模型的完整生命周期管理，支持上传、加载、切换。

模型接口列表（8个）：

方法	路径	功能
GET	/list	获取模型列表
POST	/upload	上传模型（带元数据）
GET	/info/{filename}	获取模型详情
PUT	/put/{filename}	更新模型信息
GET	/download/{filename}	下载模型
POST	/download/batch	批量下载模型
DELETE	/delete/{filename}	删除模型
POST	/load/{filename}	加载模型

---

8. 大语言模型模块 (routers/llm.py)

功能概述： 集成第三方大语言模型 API，支持流式和非流式响应。

支持的模型列表：

模型ID	名称	说明
Qwen/Qwen2.5-Coder-32B-Instruct	Qwen 2.5 Coder (32B)	通义千问编程模型
Qwen/Qwen2.5-72B-Instruct	Qwen 2.5 (72B)	通义千问大模型
Qwen/Qwen2.5-32B-Instruct	Qwen 2.5 (32B)	通义千问大模型
deepseek-ai/DeepSeek-V3	DeepSeek V3	DeepSeek 大模型
deepseek-ai/DeepSeek-R1	DeepSeek R1	DeepSeek 推理模型

请求参数模型：

class ChatRequest(BaseModel):
    model: str = "Qwen/Qwen2.5-Coder-32B-Instruct"
    messages: List[Message]
    temperature: float = 0.7
    max_tokens: int = 4096
    stream: bool = False
    top_p: float = 0.95
    frequency_penalty: float = 0.0
    presence_penalty: float = 0.0

流式响应实现：

@router.post("/chat/completions")
async def chat_completions(request: ChatRequest):
    if request.stream:
        async def generate():
            async with httpx.AsyncClient(timeout=60.0) as client:
                async with client.stream("POST", url, headers=headers, json=payload) as response:
                    async for chunk in response.aiter_text():
                        yield chunk
        
        return StreamingResponse(generate(), media_type="text/event-stream")

---

9. 多模态模型模块 (routers/vllm.py)

功能概述： 支持图像+文本的多模态对话。

支持的多模态模型：

模型ID	名称	说明
Qwen/Qwen2-VL-72B-Instruct	Qwen2-VL 72B	通义千问视觉语言模型
Qwen/Qwen2-VL-7B-Instruct	Qwen2-VL 7B	通义千问视觉语言模型
internlm/internlm-xcomposer2d5-7b	InternLM-XComposer2.5	书生浦语多模态模型
OpenGVLab/InternVL2-26B	InternVL2 26B	书生万象多模态模型

多模态消息格式：

class ContentItem(BaseModel):
    type: str  # "text" 或 "image_url"
    text: Optional[str] = None
    image_url: Optional[ImageUrl] = None

class MultimodalMessage(BaseModel):
    role: str
    content: Union[str, List[ContentItem]]  # 支持纯文本或混合内容

请求示例：

{
  "model": "Qwen/Qwen2-VL-72B-Instruct",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "请描述这张图片"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
      ]
    }
  ],
  "stream": true
}

---

API 接口文档

接口总览

模块	前缀	接口数	说明
图片管理	/api/images	9	图片上传、检测、管理
视频管理	/api/videos	14	视频上传、检测、管理
日志管理	/api/logs	5	系统日志管理
系统监控	/api/systems	1	系统资源监控
模型管理	/api/models	8	YOLO 模型管理
仪表板	/api/dashboard	6	数据可视化（已废弃）
LLM	/api/llm	2	大语言模型对话
VLLM	/api/vllm	2	多模态模型对话

文件限制

类型	最大大小	支持格式
图片	10 MB	.png, .jpg, .jpeg, .gif, .bmp
视频	500 MB	.mp4, .avi, .mov, .wmv, .flv, .mkv
模型	500 MB	.pt (PyTorch)

---

数据模型

图片信息

interface ImageInfo {
  filename: string;      // 文件名
  url: string;          // 访问 URL
  size: number;         // 文件大小（字节）
  create_time: string;  // 创建时间
  modify_time: string;  // 修改时间
}

检测结果

interface Detection {
  class_id: number;     // 类别 ID
  class_name: string;   // 类别名称
  confidence: number;   // 置信度 (0-1)
  box: {
    x1: number;        // 左上角 X
    y1: number;        // 左上角 Y
    x2: number;        // 右下角 X
    y2: number;        // 右下角 Y
  };
}

模型信息

interface ModelInfo {
  filename: string;     // 模型文件名
  name: string;         // 模型名称
  dataset: string;      // 训练数据集
  base_model: string;   // 基础模型类型
  upload_time: string;  // 上传时间
  description: string;  // 描述
  version: string;      // 版本号
  accuracy: number;     // 精度 (0-100)
}

系统状态

interface SystemStatus {
  cpu: {
    percent: number;    // CPU 使用率
    count: number;      // CPU 核心数
  };
  memory: {
    total: number;      // 总内存（字节）
    used: number;       // 已用内存
    percent: number;    // 使用百分比
  };
  disk: {
    total: number;      // 总磁盘（字节）
    used: number;       // 已用磁盘
    percent: number;    // 使用百分比
  };
  network: {
    bytes_sent: number; // 发送字节
    bytes_recv: number; // 接收字节
  };
  uptime: {
    boot_time: string;  // 启动时间
    days: number;       // 运行天数
    hours: number;      // 小时
    minutes: number;    // 分钟
    seconds: number;    // 秒
  };
  system: {
    system: string;     // 操作系统
    release: string;    // 版本
  };
}

---

配置说明

环境变量

变量名	默认值	说明
LLM_API_KEY	-	LLM/VLLM API 密钥
LLM_BASE_URL	https://api.siliconflow.cn/v1	LLM API 基础 URL

CORS 配置

生产环境建议限制允许的来源：

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "https://your-domain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)

---

部署指南

开发环境

uvicorn main:app --host 0.0.0.0 --port 10077 --reload

生产环境

使用 Gunicorn + Uvicorn Workers：

pip install gunicorn

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:10077

使用 Docker：

FROM python:3.10-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 10077
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "10077"]

---

常见问题

1. 模型加载失败

问题：启动时提示 YOLO 模型加载失败

解决方案：

• 确保 yolo11n.pt 文件存在于 backend 目录

• 检查是否安装了 ultralytics 库

• 尝试手动下载模型：from ultralytics import YOLO; YOLO('yolo11n.pt')

2. 视频检测后无法播放

问题：浏览器无法播放检测后的视频

解决方案：

• 安装 FFmpeg，系统会自动转码为 H.264 格式

• 如未安装 FFmpeg，下载视频后使用本地播放器观看

3. LLM 接口请求超时

问题：调用 /api/llm/chat/completions 超时

解决方案：

• 检查 LLM_API_KEY 环境变量是否正确设置

• 检查网络连接是否正常

• 尝试增加 timeout 时间（默认 60 秒）

4. 内存占用过高

问题：处理大视频时内存占用过高

解决方案：

• 系统已自动限制输出分辨率为 720p

• 系统每 50 帧自动释放内存

• 可进一步降低处理分辨率

联系方式

• 微信公众号：DetectionHub