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

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

目录

项目简介

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

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

  • 🎬 视频目标检测：支持视频上传、流式播放、逐帧检测、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. 访问服务

核心模块详解

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

# 人工智能 # electron # fastapi # 目标检测
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

flask+Python协同过滤算法的城市房屋租赁与购买推荐系统

avatar AtomGit开源社区
cover

多模态大模型学习笔记（二十）—— 基于 Qwen的 LoRA 意图分类微调实战

avatar AtomGit开源社区
cover

特征选择--过滤法

avatar AtomGit开源社区