# BXC_VideoNet

**Repository Path**: wanzij177/BXC_VideoNet

## Basic Information

- **Project Name**: BXC_VideoNet
- **Description**: 适用于视频片段分类的算法训练框架
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2025-10-24
- **Last Updated**: 2025-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BXC_VideoNet - 视频分类深度学习训练框架

<div align="center">

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![PyTorch](https://img.shields.io/badge/pytorch-2.1.0-red.svg)](https://pytorch.org/)
[![Flask](https://img.shields.io/badge/flask-3.0.0-green.svg)](https://flask.palletsprojects.com/)

</div>

## 👨‍💻 作者信息

- **作者**：北小菜
- **官网**：http://www.beixiaocai.com
- **邮箱**：bilibili_bxc@126.com
- **QQ**：1402990689
- **微信**：bilibili_bxc
- **哔哩哔哩**：https://space.bilibili.com/487906612
- **Gitee**：https://gitee.com/Vanishi/BXC_VideoNet
- **GitHub**：https://github.com/beixiaocai/BXC_VideoNet

## 📖 项目简介

BXC_VideoNet 是一个面向视频片段分类的深度学习训练框架，提供完整的模型训练、测试、部署解决方案。项目包含：

- 🎯 **命令行训练工具**：传统的 Python 脚本训练方式
- 🌐 **Web 管理后台**：基于 Flask 的可视化训练管理平台
- 🚀 **多平台部署**：支持 ONNX、OpenVINO、TensorRT 模型导出
- 💡 **轻量级模型**：高效的 3D 卷积神经网络架构

## ✨ 主要特性

### 核心功能
- ✅ 视频分类模型训练（基于 PyTorch）
- ✅ UCF50/UCF101 数据集支持
- ✅ 数据集自动分割（train/val）
- ✅ 模型导出（PyTorch → ONNX → OpenVINO）
- ✅ 实时训练进度监控
- ✅ 断点续训支持

### Web 管理后台特色
- 🎨 **现代化 UI**：渐变色设计，响应式布局
- 📁 **数据集管理**：拖拽上传、类别管理、自动分割
- 🚀 **训练监控**：实时显示损失、准确率、进度条
- 🧪 **模型测试**：上传视频预测，Top-5 结果展示
- 🔄 **模型转换**：一键转换 ONNX/OpenVINO 格式
- 💾 **零第三方库**：纯原生 HTML/CSS/JavaScript 实现

## 🛠️ 技术栈

- **深度学习**：PyTorch 2.1.0 + torchvision 0.16.0
- **Web 框架**：Flask 3.0.0
- **模型导出**：ONNX 1.16.1 + OpenVINO 2024.3.0
- **视频处理**：OpenCV 4.8.0.74
- **推理加速**：ONNX Runtime 1.19.0

## 📦 安装指南

### 环境要求

- **Python 版本**：
  - Windows：Python 3.10（推荐）
  - Linux：Python 3.8（推荐）
- **操作系统**：Windows 10/11、Ubuntu 18.04+
- **GPU（可选）**：NVIDIA GPU + CUDA 12.1

### 1️⃣ 创建虚拟环境

> ⚠️ **重要**：强烈建议使用虚拟环境，避免依赖冲突

#### Windows 系统

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
venv\Scripts\activate

# 更新 pip
python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
```

#### Linux 系统

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 更新 pip
python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2️⃣ 安装依赖库

#### 安装基础依赖

```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

#### 安装 PyTorch

**CPU 版本**（适合学习测试）：

```bash
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**GPU 版本**（CUDA 12.1，推荐训练使用）：

```bash
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu121
```

> 📌 **注意**：请根据你的 CUDA 版本选择对应的 PyTorch 版本，访问 [PyTorch 官网](https://pytorch.org/) 查看更多版本。

### 3️⃣ 验证安装

```bash
python -c "import torch; print('PyTorch版本:', torch.__version__); print('CUDA可用:', torch.cuda.is_available())"
```

## 🚀 快速开始

### 方式一：Web 管理后台（推荐）

#### 1. 启动 Web 服务器

```bash
python app.py
```

#### 2. 访问管理后台

在浏览器中打开：`http://127.0.0.1:5000`

#### 3. 使用流程

1. **📁 数据集管理**：
   - 创建类别文件夹（如 Basketball、Dancing）
   - 拖拽上传视频到对应类别
   - 设置比例分割训练集/验证集（默认 8:2）

2. **🚀 模型训练**：
   - 配置训练参数（轮数、批次大小、学习率）
   - 可选预训练模型（断点续训）
   - 实时查看训练进度和日志

3. **🧪 模型测试**：
   - 选择训练好的模型
   - 上传测试视频
   - 查看预测结果和 Top-5 概率

4. **🔄 模型转换**：
   - 选择训练模型
   - 转换为 ONNX 格式（支持动态输入）
   - 转换为 OpenVINO 格式（Intel 平台优化）

### 方式二：命令行训练

#### 1. 准备数据集

数据集目录结构：

```
UCF50/
├── train/
│   ├── BaseballPitch/
│   │   ├── v_BaseballPitch_g01_c01.avi
│   │   ├── v_BaseballPitch_g01_c02.avi
│   │   └── ...
│   ├── Basketball/
│   │   ├── v_Basketball_g01_c01.avi
│   │   └── ...
│   └── ...
└── val/
    ├── BaseballPitch/
    │   ├── v_BaseballPitch_g01_c03.avi
    │   └── ...
    └── ...
```

#### 2. 转换 UCF 数据集格式

如果你下载的是原始 UCF50/UCF101 数据集：

```bash
python split_ucf.py
```

#### 3. 训练模型

```bash
python train.py
```

#### 4. 测试模型

```bash
python test.py
```

#### 5. 导出模型

**导出为 ONNX 格式**：

```bash
python export2onnx.py
```

**转换为 OpenVINO 格式**：

```bash
mo --input_model best_model.onnx --output_dir best_model_openvino_model
```

## 📂 项目结构

```
BXC_VideoNet/
├── app.py                      # Web 服务器主程序
├── train.py                    # 命令行训练脚本
├── test.py                     # 模型测试脚本
├── export2onnx.py              # ONNX 导出脚本
├── split_ucf.py                # UCF 数据集分割脚本
├── model.py                    # 模型架构定义
├── dataset_video.py            # 视频数据集加载
├── dataset_image.py            # 图像数据集加载
├── requirements.txt            # 依赖库列表
├── README.md                   # 项目说明文档
├── templates/                  # Web 页面模板
│   ├── base.html              # 基础模板
│   ├── index.html             # 数据集管理页面
│   ├── train.html             # 训练页面
│   ├── test.html              # 测试页面
│   └── convert.html           # 模型转换页面
├── web_data/                   # Web 数据目录（自动生成）
│   ├── uploads/               # 上传的视频
│   ├── dataset/               # 分割后的数据集
│   ├── models/                # 保存的模型
│   └── config.json            # 配置文件
├── models_20251012001_ucf50/  # 预训练模型（可选）
└── test/                      # C++ 推理示例
    ├── onnx_inference.py      # ONNX Runtime 推理
    ├── openvino_inference/    # OpenVINO C++ 推理
    └── tensorrt_inference/    # TensorRT C++ 推理
```

## 💡 使用指南

### Web 管理后台详细说明

#### 📁 数据集管理

1. **创建类别文件夹**：
   - 输入类别名称（如 Basketball、Dancing、Running）
   - 点击"创建类别"按钮
   - 类别卡片会显示在页面上

2. **上传视频**：
   - 点击类别卡片选中（会高亮显示）
   - 拖拽或点击上传视频文件
   - 支持多文件并行上传
   - 支持格式：.mp4、.avi、.mov
   - 单文件最大 500MB

3. **分割数据集**：
   - 调整训练集比例滑块（默认 80%）
   - 设置随机种子（保证可重复性）
   - 点击"开始分割"按钮
   - 系统自动将视频复制到 train/val 目录

4. **查看统计信息**：
   - 页面顶部显示训练集/验证集数量
   - 类别总数和每类视频数量
   - 实时更新统计数据

#### 🚀 模型训练

**训练参数说明**：

- **训练轮数 (Epochs)**：
  - 小数据集：50-100
  - 中等数据集：100-200
  - 大数据集：200-300

- **批次大小 (Batch Size)**：
  - GPU 显存 4GB：4-8
  - GPU 显存 8GB：8-16
  - GPU 显存 12GB+：16-32
  - CPU 训练：2-4

- **学习率 (Learning Rate)**：
  - 从头训练：0.0005-0.001
  - 迁移学习：0.0001-0.0005

- **预训练模型**：
  - 从头训练：不选择
  - 断点续训：选择 latest_model.pth
  - 迁移学习：选择其他训练好的模型

**训练监控**：

- 实时显示当前轮次进度条
- 训练集损失和准确率
- 验证集损失和准确率
- 历史最佳验证准确率
- 详细训练日志滚动显示

**模型保存**：

- 最佳模型：`best_model_epoch{轮次}_acc{准确率}.pth`
- 最新模型：`latest_model.pth`（每轮更新）
- 保存位置：`web_data/models/`

#### 🧪 模型测试

1. **选择模型**：从下拉列表选择已训练模型
2. **上传测试视频**：拖拽或点击上传
3. **查看预测结果**：
   - 预测类别
   - 置信度（百分比）
   - Top-5 预测概率分布
4. **测试历史**：保留最近 10 次测试记录

#### 🔄 模型转换

**ONNX 格式转换**：

- ✅ 跨平台部署（Windows、Linux、ARM）
- ✅ 可选动态输入维度
- ✅ 自动模型验证
- 📦 生成 `.onnx` 文件

**OpenVINO 格式转换**：

- ✅ Intel CPU/GPU 优化
- ✅ 推理性能提升 2-5 倍
- ✅ 支持边缘设备部署
- 📦 生成 `.xml` 和 `.bin` 文件

### 训练优化建议

#### 数据集准备

1. **数量要求**：
   - 每个类别至少 20-50 个视频
   - 总样本数建议 500+ 以上

2. **质量要求**：
   - 视频清晰、稳定、光线充足
   - 避免过度晃动和模糊
   - 背景尽量简洁

3. **时长建议**：
   - 3-10 秒最佳（系统自动采样 16 帧）
   - 过长视频会自动均匀采样

4. **类别平衡**：
   - 各类别视频数量尽量接近
   - 避免数据倾斜

#### 解决过拟合

**现象**：训练准确率高，验证准确率低

**解决方案**：
- 减少训练轮数（Early Stopping）
- 收集更多训练数据
- 使用数据增强
- 降低模型复杂度

#### 解决欠拟合

**现象**：训练和验证准确率都低

**解决方案**：
- 增加训练轮数
- 提高学习率
- 检查数据质量
- 增加模型复杂度

## 📊 数据集下载

### 官方数据集

- **UCF101**（101 类动作识别）：
  - 官网：https://www.crcv.ucf.edu/data/UCF101.php
  - 样本数：13,320 个视频
  - 大小：~6.5GB

- **UCF50**（50 类动作识别）：
  - 官网：https://www.crcv.ucf.edu/data/UCF50.php
  - 样本数：6,676 个视频
  - 大小：~3.2GB

### 数据集类别示例

```
BaseballPitch、Basketball、BenchPress、Biking、Billiards、
BreastStroke、CleanAndJerk、Diving、Drumming、Fencing、
GolfSwing、HighJump、HorseRace、HorseRiding、HulaHoop、
JavelinThrow、JugglingBalls、JumpingJack、JumpRope、Kayaking...
```

## ❓ 常见问题

### Q1: 上传视频失败？

**可能原因**：
- ❌ 文件格式不支持（仅支持 .mp4、.avi、.mov）
- ❌ 文件大小超过 500MB
- ❌ 磁盘空间不足
- ❌ 未选择目标类别

**解决方案**：
- ✅ 检查文件格式和大小
- ✅ 清理磁盘空间
- ✅ 先点击选中类别卡片

### Q2: 训练时显存不足（CUDA Out of Memory）？

**解决方案**：
- 降低 Batch Size（如从 16 降到 8 或 4）
- 关闭其他占用 GPU 的程序
- 使用 CPU 训练（速度较慢）

### Q3: 训练速度很慢？

**检查项**：
- 是否使用了 GPU（查看训练日志中的设备信息）
- 数据加载是否成为瓶颈（调整 num_workers）
- 批次大小是否过小

**优化方案**：
- 使用 GPU 训练（提速 10-50 倍）
- 增加批次大小
- 使用 SSD 硬盘存储数据

### Q4: 如何断点续训？

1. 在训练页面选择预训练模型
2. 选择 `latest_model.pth`（最新保存的模型）
3. 配置训练参数（可以调整学习率等）
4. 点击开始训练，系统会从上次状态继续

### Q5: 模型转换失败？

**ONNX 转换失败**：
- 检查模型文件是否完整
- 确认已安装 `onnx` 库
- 查看日志中的详细错误信息

**OpenVINO 转换失败**：
- 确认已安装 `openvino-dev`
- 检查虚拟环境是否激活
- 查看是否有权限问题

### Q6: Web 页面无法访问？

**检查项**：
- Flask 服务是否正常启动
- 是否有其他程序占用 5000 端口
- 防火墙是否阻止访问

**解决方案**：
```bash
# 检查端口占用
netstat -ano | findstr :5000  # Windows
lsof -i :5000                  # Linux

# 更换端口启动
# 修改 app.py 最后一行的 port 参数
app.run(debug=True, host='0.0.0.0', port=8080)
```

## 🔧 高级配置

### 修改模型架构

编辑 `model.py` 文件中的 `VideoNetModel` 类：

```python
class VideoNetModel(nn.Module):
    def __init__(self, num_classes=50):
        super(VideoNetModel, self).__init__()
        # 修改网络层配置
        # ...
```

### 调整数据增强

编辑 `dataset_video.py` 文件中的数据变换：

```python
transforms.Compose([
    transforms.Resize((224, 224)),
    # 添加更多数据增强
    transforms.RandomHorizontalFlip(),
    transforms.RandomRotation(10),
    # ...
])
```

### 修改训练策略

编辑 `train.py` 或 `app.py` 中的训练循环：

```python
# 学习率调度器
scheduler = optim.lr_scheduler.ReduceLROnPlateau(
    optimizer, mode='max', factor=0.5, patience=5
)

# 早停策略
if epochs_no_improve >= patience:
    print("Early stopping")
    break
```

## 📈 性能指标

### 训练性能

| 配置 | Batch Size | 训练速度 | 显存占用 |
|------|-----------|---------|----------|
| RTX 3090 | 32 | ~2s/epoch | ~8GB |
| RTX 3060 Ti | 16 | ~4s/epoch | ~6GB |
| GTX 1660 | 8 | ~8s/epoch | ~4GB |
| CPU (i7-10700) | 4 | ~120s/epoch | ~2GB RAM |

### 推理性能

| 格式 | 平台 | 单帧耗时 | 备注 |
|------|------|---------|------|
| PyTorch | NVIDIA GPU | ~15ms | 原始模型 |
| ONNX | CPU | ~80ms | 跨平台 |
| OpenVINO | Intel CPU | ~45ms | 优化推理 |
| TensorRT | NVIDIA GPU | ~8ms | 最快 |

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 开源协议

本项目采用 MIT 协议开源 - 详见 [LICENSE](LICENSE) 文件

## 📞 联系方式

- 📧 邮箱：bilibili_bxc@126.com
- 💬 QQ：1402990689
- 📱 微信：bilibili_bxc
- 🎥 B站：https://space.bilibili.com/487906612
- 🌐 官网：http://www.beixiaocai.com

## 🙏 致谢

感谢以下开源项目：

- [PyTorch](https://pytorch.org/) - 深度学习框架
- [Flask](https://flask.palletsprojects.com/) - Web 框架
- [OpenVINO](https://github.com/openvinotoolkit/openvino) - 推理优化工具
- [ONNX](https://onnx.ai/) - 模型交换格式
- [UCF](https://www.crcv.ucf.edu/) - 数据集提供

## ⭐ Star History

如果这个项目对你有帮助，请给个 Star ⭐ 支持一下吧！

---

<div align="center">

**享受你的视频分类模型训练之旅！** 🎉

Made with ❤️ by 北小菜

</div>