# deep-vision

**Repository Path**: aizuda/deep-vision

## Basic Information

- **Project Name**: deep-vision
- **Description**: 🔥🔥🔥 从数据标注、模型训练到实时推理监控的全流程AI视觉系统
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 73
- **Forks**: 25
- **Created**: 2025-09-12
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: cv

**Tags**: None

## README

# deep-vision

[![语言](https://img.shields.io/badge/language-Python%2C%20Vue.js-blue.svg)](https://www.python.org/ "Python")
[![框架](https://img.shields.io/badge/framework-FastAPI%2C%20Vue.js-green.svg)](https://fastapi.tiangolo.com/ "FastAPI")
[![部署](https://img.shields.io/badge/deploy-Docker-orange.svg)](https://www.docker.com/ "Docker")

一份功能强大、开箱即用的全栈式deep-vision。它集成了现代化的Web界面与高性能的Python后端，通过Docker实现了一键部署，为您提供从数据准备、模型训练到实时推理的端到端解决方案。

![系统截图](images/首页.png)
![数据标注](images/数据标注.png)
![模型中心.jpg](images/模型中心.jpg)
![模型推理](images/模型推理.png)
![实时推理](images/实时推理.png)

---

## ✨ 核心功能

- **🎨 现代化Web界面**: 基于 Vue.js 3 和 Vite 构建，响应式设计，流畅交互体验。提供直观的数据集管理、模型训练监控、实时视频流分析等完整工作流，让AI视觉开发更简单高效。

- **⚡ 高性能后端API**: 基于 FastAPI 构建的异步高性能架构，RESTful API + WebSocket双协议支持，毫秒级响应速度。自动生成的API文档让接口调用一目了然。

- **📦 智能数据集管理**: 
  - 拖拽上传ZIP格式数据集，自动解析YOLO格式标注
  - 可视化数据集列表，一键查看、删除和管理
  - 支持多数据集并行管理，训练数据井然有序

- **🏷️ 强大的数据标注系统**:
  - **可视化标注工具**: 鼠标拖拽绘制标注框，支持移动、调整大小、删除等完整编辑功能
  - **AI辅助预标注**: 使用YOLO模型自动检测目标，一键生成标注框，支持80+通用类别识别
  - **视频拆帧标注**: 上传视频自动提取关键帧，支持按帧率或总帧数提取，批量标注更高效
  - **撤销/重做**: Ctrl+Z/Ctrl+Y快捷键操作，支持50步历史记录，标注更安心
  - **类别管理**: 自定义标注类别，浏览器缓存自动保存，下次使用更便捷
  - **导出下载**: 标注完成后一键导出YOLO格式数据集，即刻用于模型训练

- **🚀 异步模型训练**: 
  - 训练任务在独立进程中运行，不阻塞API服务，支持多任务并行
  - 实时获取训练状态、进度和日志，训练过程尽在掌握
  - 支持自定义训练参数（epochs、batch size、学习率等）
  - 训练结果自动保存，包括权重文件、混淆矩阵、训练曲线等

- **🤖 灵活的模型管理**: 
  - 自动识别所有可用的预训练模型和自定义训练模型
  - 支持YOLOv8、YOLOv11全系列模型（n/s/m/l/x）
  - 一键下载最新YOLO模型，动态加载无需重启服务
  - 模型导出支持多种格式（ONNX、TorchScript等）

- **🔍 多场景推理模式**:
  - **单图/批量推理**: 上传图片即时检测，支持批量处理，结果可视化展示
  - **实时视频流推理**: 支持Webcam、RTSP、HTTP等多种视频源，WebSocket推送实时结果，支持目标跟踪和唯一计数
  - **多路视频监控**: 九宫格布局同时监控9路视频流，适用于智能安防、工业质检等场景
  - **置信度调节**: 灵活调整检测阈值，平衡准确率和召回率

- **🐳 一键化容器部署**: 
  - 使用 Docker 和 Docker Compose 封装所有服务
  - 前后端分离架构，Nginx反向代理，生产级别配置
  - 数据持久化卷挂载，数据安全有保障
  - 一条命令启动全部服务，环境配置零烦恼

## 🏗️ 系统架构

本平台采用前后端分离的架构，并通过Docker容器化进行部署。

```text
.
├── User (Browser/Client)
│
└── Server (Docker Environment)
    │
    ├── Nginx (Reverse Proxy)
    │   ├── Routes to -> Frontend
    │   └── Routes to -> Backend API
    │
    ├── Frontend (Vue.js Container)
    │   └── User Interface, Real-time Views
    │
    ├── Backend API (FastAPI Container)
    │   ├── Handles REST API & WebSocket
    │   ├── Performs Inference
    │   └── Manages -> Background Training Process
    │
    ├── Background Training Process (Independent Python Process)
    │   └── Executes Model Training
    │
    └── Shared Data (Docker Volume: ./data)
        ├── Used by Backend & Training Process
        ├── Contains:
        │   ├── datasets/
        │   ├── runs/
        │   └── exports/
```

- **前端**: Vue.js 应用程序，通过 Nginx 部署在Docker容器中。
- **后端**: FastAPI 应用程序，运行在Docker容器中，负责处理业务逻辑、API请求和模型推理。
- **训练进程**: 一个独立的Python进程，由后端API启动，专门负责执行耗时的模型训练任务。
- **数据卷**: 使用Docker Volume将主机的`./data`目录映射到后端容器，用于持久化存储数据集、训练结果、导出模型等。

## 🛠️ 技术栈

- **后端**: Python 3, FastAPI, Ultralytics YOLOv8, Uvicorn, OpenCV
- **前端**: Vue.js 3, Vite, Element Plus, JavaScript/TypeScript
- **部署**: Docker, Docker Compose, Nginx

## 📁 目录结构

```
.
├── backend/         # 后端 FastAPI 服务
├── data/            # 持久化数据目录 (由Docker Volume映射)
│   ├── datasets/    # 存放数据集
│   ├── runs/        # 存放训练结果
│   └── ...
├── frontend/        # 前端 Vue.js 应用
├── scripts/         # 辅助脚本 (如本地开发启动)
├── docker-compose.yml # Docker编排文件
└── README.md        # 本说明文件
```

## 🚀 快速开始 (推荐)

本项目推荐使用 Docker 进行部署，可以免去繁琐的环境配置。

### 1. 先决条件

- [Docker](https://www.docker.com/get-started)
- [Docker Compose](https://docs.docker.com/compose/install/)

### 2. 启动步骤

1.  **克隆项目**
    ```bash
    git clone <your-repository-url>
    cd yolo_detection_system
    ```

2.  **构建并启动服务**
    使用 `docker-compose` 一键构建并启动所有服务（前端、后端）。
    ```bash
    docker-compose up -d --build
    ```
    `-d` 参数表示在后台运行。首次启动时，`--build` 会根据 `Dockerfile` 构建镜像，可能需要一些时间。

3.  **访问系统**
    - **前端Web界面**: [http://localhost:3000](http://localhost:3000)
    - **后端API文档**: [http://localhost:8000/docs](http://localhost:8000/docs) (由FastAPI自动生成的Swagger UI)

4.  **停止服务**
    ```bash
    docker-compose down
    ```

## 💻 本地开发 (可选)

如果您希望在本地直接运行前后端服务进行开发，可以使用 `scripts` 目录下的脚本。

### 1. 先决条件

- Python 3.8+
- Node.js 16+
- `pip` 和 `npm`

### 2. 启动步骤

1.  **启动后端**
    ```bash
    cd backend
    pip install -r requirements.txt
    python start_api.py
    ```
    后端服务将在 `http://localhost:8000` 运行。

2.  **启动前端**
    在另一个终端中：
    ```bash
    cd frontend
    npm install
    npm run dev
    ```
    前端开发服务器将在 `http://localhost:3000` 运行。

或者，您也可以使用项目根目录提供的一键启动脚本：
```bash
./scripts/start_all.sh
```

## 📖 API 端点概览

后端服务提供了丰富的API接口，以下是部分核心端点：

| 方法   | 路径                           | 描述                               |
| :----- | :----------------------------- | :--------------------------------- |
| `POST` | `/upload/dataset`              | 上传数据集压缩包 (ZIP)             |
| `GET`  | `/datasets`                    | 获取所有数据集列表                 |
| `POST` | `/train`                       | 启动一个新的模型训练任务           |
| `GET`  | `/status/{task_id}`            | 获取指定训练任务的状态             |
| `GET`  | `/logs/{task_id}`              | 获取训练任务的日志                 |
| `GET`  | `/models`                      | 获取所有可用模型列表               |
| `POST` | `/predict`                     | 对单张图片进行推理                 |
| `POST` | `/predict/batch`               | 对多张图片进行批量推理             |
| `WS`   | `/ws/realtime/{session_id}`    | 实时视频流推理的WebSocket连接      |
| `WS`   | `/ws/grid/{grid_id}`           | 多路视频监控的WebSocket连接        |

更详细的API说明和在线测试，请访问 [API文档 (http://localhost:8000/docs)](http://localhost:8000/docs)。

## 📄 其他文档

- **[部署说明 (DEPLOYMENT.md)](./DEPLOYMENT.md)**: 更详细的部署选项和注意事项。
- **[Docker说明 (DOCKER.md)](./DOCKER.md)**: 关于Docker镜像和容器的详细信息。
- **[训练日志 (TRAINING_LOGS.md)](./TRAINING_LOGS.md)**: 训练相关的一些记录和说明。

## 🎯 如何下载和使用高版本基础模型

系统内置了多个YOLO基础模型，您也可以自行下载更多版本的模型进行使用。

### 内置模型

系统默认包含以下预训练模型：
- `yolov8n.pt` - YOLOv8 Nano (最轻量)
- `yolov8s.pt` - YOLOv8 Small
- `yolo11n.pt` - YOLOv11 Nano
- `yolo11s.pt` - YOLOv11 Small

### 下载更多模型

您可以从 [Ultralytics官方仓库](https://github.com/ultralytics/ultralytics) 下载更多YOLO模型：

#### 1. YOLOv8系列模型
```bash
# 进入backend目录
cd backend

# 下载不同规格的YOLOv8模型
wget https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8n.pt  # Nano
wget https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8s.pt  # Small
wget https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8m.pt  # Medium
wget https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8l.pt  # Large
wget https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8x.pt  # XLarge
```

#### 2. YOLOv11系列模型
```bash
# YOLOv11是最新版本，性能更优
wget https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11n.pt  # Nano
wget https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11s.pt  # Small
wget https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11m.pt  # Medium
wget https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11l.pt  # Large
wget https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11x.pt  # XLarge
```

#### 3. 使用Python下载
```python
from ultralytics import YOLO

# 首次加载时会自动下载模型
model = YOLO('yolo11m.pt')  # 会自动下载到 ~/.ultralytics/weights/
```

### 模型规格对比

| 模型 | 大小 | 推理速度 | 精度 | 适用场景 |
|:-----|:-----|:---------|:-----|:---------|
| n (Nano) | ~6MB | 最快 | 基础 | 边缘设备、实时应用 |
| s (Small) | ~22MB | 快 | 良好 | 移动设备、快速推理 |
| m (Medium) | ~50MB | 中等 | 优秀 | 通用场景 |
| l (Large) | ~87MB | 慢 | 高 | 高精度需求 |
| x (XLarge) | ~136MB | 最慢 | 最高 | 精度优先场景 |

### 添加模型到系统

下载完成后，将`.pt`文件放置到以下位置之一：

1. **后端目录** (推荐):
   ```bash
   cp yolo11m.pt backend/
   ```

2. **models目录**:
   ```bash
   cp yolo11m.pt backend/models/
   ```

3. **Docker环境**:
   如果使用Docker部署，需要重新构建镜像或将模型挂载到容器中：
   ```bash
   # 方法1: 重新构建
   docker-compose up -d --build
   
   # 方法2: 使用volume挂载
   # 在docker-compose.yml中添加:
   # volumes:
   #   - ./backend:/app
   ```

### 在前端使用新模型

添加模型后，系统会自动识别并在前端的模型选择下拉框中显示。您可以在以下功能中使用新模型：

- **模型训练**: 选择作为基础模型进行训练
- **图片推理**: 用于单张或批量图片检测
- **实时推理**: 用于视频流实时检测
- **多路监控**: 用于九宫格视频监控

### 模型选择建议

- **开发测试**: 使用 `n` 或 `s` 模型，推理速度快
- **生产环境**: 根据硬件配置选择 `m` 或 `l` 模型
- **高精度需求**: 选择 `l` 或 `x` 模型
- **边缘设备**: 建议使用 `n` 模型
- **GPU服务器**: 可以使用 `x` 模型获得最佳效果

## 📝 更新日志

**v1.5.0 (2026-02-06)**
- **🎯 功能: 模型中心 (Model Hub)**
  - 新增完整的模型管理中心界面，统一管理所有模型
  - 支持预训练模型和自定义训练模型的分类展示
  - **模型保护机制**：基础预训练模型（yolov8n.pt、yolo11n.pt等）受保护，防止误删
  - **模型上传**：支持上传自定义训练的.pt模型文件
  - **模型下载**：一键下载任意模型文件
  - **批量管理**：支持多选模式下的批量删除操作
  - **一键清除**：快速清除所有训练生成的模型文件
  - **模型信息展示**：显示模型大小、训练时间、数据集信息等详细属性

- **🎨 功能: 多边形标注工具**
  - 新增多边形标注功能，支持更精确的目标轮廓标注
  - 点击画布添加顶点，点击起始点完成多边形绘制
  - 支持右键取消当前绘制或多边形编辑
  - 多边形和矩形框在同一界面无缝切换使用
  - 智能的绘制提示和操作引导

- **✨ 功能: 数据增强 (Data Augmentation)**
  - 新增图像数据增强功能，提升模型泛化能力
  - 支持多种增强方式：
    - 水平翻转、垂直翻转
    - 亮度调整（±30%）
    - 对比度调整（±30%）
    - 饱和度调整（±30%）
    - 随机旋转（±15度）
    - 随机缩放（90%-110%）
  - 实时预览增强效果，所见即所得
  - 可自定义增强数量和参数组合

- **📤 功能: 模型导出**
  - 支持将训练好的模型导出为多种格式：
    - ONNX格式：跨平台部署
    - TorchScript格式：生产环境优化
    - TFLite格式：移动端部署
    - CoreML格式：苹果设备部署
  - 通过 `/export` API接口实现格式转换
  - 导出文件自动归档管理

- **🗑️ 功能: 批量删除优化**
  - **数据集批量删除**：支持多选数据集进行批量删除
  - **模型批量删除**：模型中心支持多选删除操作
  - 删除前二次确认，防止误操作
  - 详细的删除结果反馈（成功/失败统计）

- **🔧 后端API增强**
  - 新增 `/models` 接口：获取所有可用模型列表（区分预训练和训练模型）
  - 新增 `/models/upload` 接口：上传自定义模型文件
  - 新增 `/models/{model_path}` DELETE接口：删除指定模型
  - 新增 `/export` 接口：模型格式导出功能
  - 新增 `/datasets/batch/delete` 接口：批量删除数据集
  - 模型路径解析优化，支持多种格式的模型引用

- **🎨 前端优化**
  - 新增模型中心页面，现代化的卡片式布局
  - 数据标注界面集成多边形工具和数据增强功能
  - 统一的批量操作UI设计（选择模式切换、全选、批量删除）
  - 增强的用户交互反馈和操作提示
  - 响应式设计适配不同屏幕尺寸

**v1.4.0 (2025-02-05)**
- **🎬 功能: 数据标注支持视频**
  - 新增视频上传功能，支持从视频文件中提取帧进行标注。
  - 支持两种帧提取模式：
    - 按帧率提取：可设置每秒提取的帧数（0.1-30帧/秒）
    - 按数量提取：可设置总共提取的帧数（1-500帧）
  - 提取的视频帧自动添加到图片列表，支持像标注图片一样进行标注。
  - 每帧都包含原视频名称、帧索引和时间戳信息。
- **🤖 功能: AI辅助预标注**
  - 新增AI辅助预标注功能，使用YOLO模型自动检测目标并生成标注框
  - 支持选择不同的YOLO模型（yolo11n.pt、yolo11s.pt、yolov8n.pt等）
  - 支持调整检测置信度阈值（0.1-0.9）
  - 提供两种标注模式：替换现有标注或追加到现有标注
  - 基于COCO数据集预训练模型，可检测80个通用类别
- **✏️ 功能: 标注框调整和移动**
  - 支持拖拽标注框的8个手柄（4个角+4条边）调整大小
  - 支持拖拽标注框内部区域移动位置
  - 智能鼠标指针提示（resize箭头、move手型）
  - 所有调整操作自动保存到历史记录
- **↩️ 功能: 撤销/重做**
  - 新增操作历史记录系统（最多保存50步）
  - 支持快捷键：Ctrl+Z撤销、Ctrl+Y重做
  - 工具栏添加撤销/重做按钮，按钮状态智能禁用
  - 所有标注操作（添加、删除、移动、调整）自动保存历史
- **🗑️ 功能: 图片列表管理优化**
  - 新增图片删除功能，鼠标悬停显示删除按钮
  - 删除前弹出确认对话框，防止误操作
  - 优化文件名显示，长文件名自动省略并显示tooltip提示
- **🔧 后端API增强**
  - 新增 `/annotation/video/upload` 接口：上传视频文件并提取视频信息
  - 新增 `/annotation/video/extract-frames` 接口：从视频中提取指定帧（支持小数帧率）
  - 新增 `/annotation/ai-assist` 接口：AI辅助预标注
  - 优化视频处理性能，支持大文件上传（2分钟超时）
- **🎨 前端优化**
  - 数据标注页面新增"上传视频"按钮
  - 新增视频帧提取配置对话框，支持实时预览提取参数
  - 新增AI辅助标注配置对话框，支持模型选择和置信度调整
  - 优化用户体验，提供详细的视频信息展示（时长、帧率、分辨率等）
  - 重构Canvas鼠标事件处理逻辑，支持更丰富的交互

**v1.3.0 (2025-09-28)**
- **🚀 功能: 前端体验优化**
  - 数据标注的类别现在会缓存在浏览器中，方便下次使用。
  - 模型训练时，可以直接从已保存的标注类别中选择，无需手动输入。
- **🔧 优化: 交互优化**
  - 移除了部分不必要的成功提示弹窗，使得操作流程更流畅。
- **🎨 风格: 品牌更新**
  - 前端项目名称和Logo更新为"deep-vision"，并同步更新了相关文档。

**v1.2.1 (2025-09-26)**
- **🔧 优化: 详细跟踪日志**
  - 在后台日志中为每个被跟踪的新对象添加了详细信息，现在会输出每个对象的 `track_id` 和 `class_name`，便于调试和监控。

**v1.2.0 (2025-09-26)**
- **🚀 功能: 实时视频流唯一对象计数**
  - 在实时视频流中增加了唯一对象计数功能，避免了对同一对象的重复计数。
- **🔧 技术实现**
  - 在 `yolo_trainer.py` 中添加了 `track` 方法，以支持YOLO的目标跟踪功能。
  - 更新了 `yolo_api.py` 中的实时处理流程，使用 `track` 方法代替 `predict` 方法。
  - 在WebSocket的输出中增加了 `unique_object_counts` 字段，用于实时展示各类物体的唯一数量。

**v1.1.0 (2025-09-26)**
- **🚀 功能: 新增 YOLOv11 模型支持**
  - 后端: `yolo11n.pt` 模型已添加至可用的预训练模型列表。
  - 前端: 所有模型选择下拉框（训练、推理、实时监控）现在都能动态展示 `YOLOv11` 及其他所有可用的后端模型。
- **🔧 优化: 动态模型加载**
  - 前端: 重构了模型选择功能，现在会通过API从后端动态获取模型列表，移除了硬编码。
  - 这使得系统更具扩展性，未来在后端新增任何模型，都将自动出现在用户界面中，无需修改前端代码。

## 📜 开源许可

本项目根据 [LICENSE](./LICENSE) 文件中的条款授权。