# BXC_VideoNet
**Repository Path**: Vanishi/BXC_VideoNet
## Basic Information
- **Project Name**: BXC_VideoNet
- **Description**: 视频动作识别深度学习框架
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 7
- **Forks**: 2
- **Created**: 2025-10-12
- **Last Updated**: 2025-11-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# BXC_VideoNet - 视频动作识别深度学习框架
[](version.py)
[](LICENSE)
[](https://www.python.org/)
[](https://pytorch.org/)
[](https://flask.palletsprojects.com/)
## 👨💻 作者信息
- **作者**：北小菜
- **官网**：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）
- ✅ **智能采样策略**：支持3种视频帧采样策略（uniform/random_segment/dense）
- ✅ 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
```
启动时会显示版本信息：
```
============================================================
BXC_VideoNet - 视频动作识别深度学习框架
版本: v1.01
作者: 北小菜
发布日期: 2025-10-31
============================================================
```
#### 4. 测试模型
```bash
python test.py
```
可以在test.py中配置采样策略：
```python
# 配置区
num_frames = 16 # 采样帧数（可修改为32、64等）
sampling_strategy = 'uniform' # 采样策略：'uniform', 'random_segment', 'dense'
```
#### 5. 导出模型
**导出为 ONNX 格式**：
```bash
python export2onnx.py
```
**转换为 OpenVINO 格式**：
```bash
mo --input_model best_model.onnx --output_dir best_model_openvino_model
```
## 📂 项目结构
```
BXC_VideoNet/
├── version.py # 版本管理模块（v1.01）
├── app.py # Flask Web 服务器主程序
├── train.py # 命令行训练脚本
├── test.py # 模型测试脚本（支持3种采样策略）
├── export2onnx.py # 模型导出ONNX脚本
├── split_ucf.py # UCF数据集分割工具
├── model.py # 模型架构定义
├── dataset.py # 数据集加载模块（支持视频和图像）
│ ├── VideoDatasetVideo # 从视频文件直接读取（支持3种采样策略）
│ └── VideoDatasetImage # 从图片序列读取
├── requirements.txt # 依赖库列表
├── README.md # 项目说明文档
├── VIDEO_SAMPLING_STRATEGIES.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++ 推理
```
## 💡 使用指南
### 视频采样策略说明 ⭐ 重要
项目提供了三种智能视频采样策略，可显著提升模型性能。所有策略都会采样固定数量的帧（默认16帧，可配置）。
#### 📊 采样策略对比
| 策略 | 适用场景 | 主要优势 | 数据增强 |
|------|---------|---------|----------|
| **uniform** | 验证集/测试集 | 稳定可复现 | 无 |
| **random_segment** ⭐ | 训练集（推荐） | 时间增强，提升泛化 | 强 |
| **dense** | 长视频/复杂动作 | 细粒度覆盖 | 中等 |
#### 🎯 策略详解
**1. uniform - 均匀采样**
- 在整个视频上均匀采样
- 每次采样结果完全一致
- 适合验证集和测试集
**2. random_segment - 随机片段采样**（推荐用于训练）
- 每个epoch随机选择视频的不同时间段
- 等效于2-3倍数据增强
- 预期准确率提升 **+3% ~ +8%**
- 训练集默认启用此策略
**3. dense - 密集分段采样**
- 将视频分段，每段采样一帧
- 适合超过300帧的长视频
- 训练时每段随机采样，验证时取中间帧
#### 💻 使用示例
```python
from dataset import VideoDatasetVideo
from torchvision import transforms
# 训练集 - 使用random_segment策略（数据增强）
train_dataset = VideoDatasetVideo(
phase='train',
root_dir='data/train',
transform=train_transforms,
num_frames=16, # 采样帧数（可配置）
sampling_strategy='random_segment' # 随机片段采样
)
# 验证集 - 使用uniform策略（稳定评估）
val_dataset = VideoDatasetVideo(
phase='val',
root_dir='data/val',
transform=val_transforms,
num_frames=16, # 采样帧数
sampling_strategy='uniform' # 均匀采样
)
# 长视频 - 使用dense策略 + 更多帧
long_video_dataset = VideoDatasetVideo(
phase='train',
root_dir='data/long_videos',
transform=train_transforms,
num_frames=32, # 增加采样帧数
sampling_strategy='dense' # 密集采样
)
```
> 📖 **详细说明**：查看 [VIDEO_SAMPLING_STRATEGIES.md](VIDEO_SAMPLING_STRATEGIES.md) 了解采样策略的原理、性能对比和最佳实践。
### 数据集加载模块说明
项目支持两种数据加载方式（位于 `dataset.py`）：
1. **VideoDatasetVideo**：直接从视频文件读取
- 支持三种智能采样策略
- 支持格式：.mp4、.avi、.mov
- 适合：原始视频文件数据集（如 UCF50/UCF101）
2. **VideoDatasetImage**：从图片序列读取
- 从视频帧图片文件夹读取
- 支持格式：.jpg、.jpeg、.png
- 适合：已提取帧的数据集
**使用示例**：
```python
# 导入数据集类
from dataset import VideoDatasetVideo, VideoDatasetImage
# 使用视频文件数据集（推荐）
dataset = VideoDatasetVideo('train', 'path/to/train',
transform=data_transforms['train'],
num_frames=16,
sampling_strategy='random_segment')
# 或使用图片序列数据集
dataset = VideoDatasetImage('train', 'path/to/frames',
transform=data_transforms['train'])
```
### 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帧
- 长视频（>300帧）：采样32-64帧，使用dense策略
4. **类别平衡**：
- 各类别视频数量尽量接近
- 避免数据倾斜
#### 解决过拟合
**现象**：训练准确率高，验证准确率低
**解决方案**：
- ✅ **启用random_segment采样策略**（数据增强，推荐）
- 减少训练轮数（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__()
# 修改网络层配置
# ...
```
### 调整数据增强
编辑 `train.py` 或 `app.py` 中的数据增强配置：
```python
# 在 train.py 或 app.py 中配置数据增强
data_transforms = {
'train': transforms.Compose([
transforms.RandomResizedCrop(224, scale=(0.8, 1.0)),
transforms.RandomHorizontalFlip(),
transforms.RandomVerticalFlip(p=0.2),
transforms.RandomRotation(15),
transforms.ColorJitter(brightness=0.2, contrast=0.2),
transforms.ToTensor(),
transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
])
}
```
### 配置视频采样策略
在创建数据集时指定采样策略：
```python
from dataset import VideoDatasetVideo
# 示例1：标准配置（16帧 + random_segment）
train_dataset = VideoDatasetVideo(
phase='train',
root_dir='data/train',
transform=train_transforms,
num_frames=16,
sampling_strategy='random_segment'
)
# 示例2：长视频配置（32帧 + dense）
train_dataset = VideoDatasetVideo(
phase='train',
root_dir='data/train',
transform=train_transforms,
num_frames=32,
sampling_strategy='dense'
)
# 示例3：验证集配置（uniform）
val_dataset = VideoDatasetVideo(
phase='val',
root_dir='data/val',
transform=val_transforms,
num_frames=16,
sampling_strategy='uniform'
)
```
### 修改训练策略
编辑 `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 | 最快 |
### 采样策略性能对比（UCF50数据集）
| 采样策略 | 验证准确率 | 训练时间/epoch | 数据增强效果 |
|---------|-----------|--------------|----------|
| uniform（基线） | 85.2% | 120s | - |
| **random_segment** | **89.7%** (+4.5%) | 125s | ⭐⭐⭐ |
| dense | 87.8% (+2.6%) | 130s | ⭐⭐ |
> 📈 **推荐配置**：训练集使用 `random_segment` 策略，验证集使用 `uniform` 策略，可获得最佳性能提升。
## 📝 更新日志
### v1.01 (2025-10-31) - 采样策略优化版
**新增功能**：
- ✅ **视频采样策略优化**：新增3种智能采样策略（uniform/random_segment/dense）
- ✅ **数据增强增强**：random_segment策略可将准确率提升3-8%
- ✅ **版本管理系统**：新增version.py，统一管理项目版本号
- ✅ **模型兼容性提升**：自动识别和加载新旧模型格式
- ✅ **Web界面优化**：所有页面显示版本号
**修复问题**：
- 🐛 修复test.py和export2onnx.py中的模型加载错误
- 🐛 修复app.py中Web测试和转换功能的兼容性问题
- 🐛 优化数据集加载模块，合并为dataset.py
**文档更新**：
- 📚 新增VIDEO_SAMPLING_STRATEGIES.md采样策略详细说明
- 📚 更新README.md，补充采样策略和版本管理说明
---
## 🤝 贡献指南
欢迎提交 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 ⭐ 支持一下吧！
---
**享受你的视频分类模型训练之旅！** 🎉
Made with ❤️ by 北小菜