Initial commit: FishServer monorepo (FishAction, FishMeasure, fish_api)
Made-with: Cursor
This commit is contained in:
zaiun xu
379
FishAction/README.md
Executable file
379
FishAction/README.md
Executable file
@@ -0,0 +1,379 @@
|
||||
# FishAction
|
||||
|
||||
> **仓库瘦身说明**：为减小部署体积，已移除本目录下的 `slowfast/`（PySlowFast 完整训练工程）。当前默认推理与训练入口为 **PyTorchVideo X3D**（`train_pytorchvideo_x3d.py`、`predict_video_x3d_3class.py`）。若需恢复 SlowFast，请从备份或上游 `facebookresearch/SlowFast` 自行放回。
|
||||
|
||||
基于深度学习的鱼类行为识别与分类系统，通过分析输入视频片段自动识别和分类鱼类的各种行为动作。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [项目简介](#项目简介)
|
||||
- [推荐模型](#推荐模型)
|
||||
- [功能特性](#功能特性)
|
||||
- [环境要求](#环境要求)
|
||||
- [安装指南](#安装指南)
|
||||
- [数据集准备](#数据集准备)
|
||||
- [使用方法](#使用方法)
|
||||
- [模型训练](#模型训练)
|
||||
- [模型评估](#模型评估)
|
||||
- [推理预测](#推理预测)
|
||||
- [项目结构](#项目结构)
|
||||
- [贡献指南](#贡献指南)
|
||||
- [许可证](#许可证)
|
||||
|
||||
## 🐟 项目简介
|
||||
|
||||
FishAction 是一个专门用于鱼类行为识别和分类的深度学习项目。通过分析视频片段，系统能够自动识别和分类鱼类的各种行为，如游动、觅食、逃避、社交等。该项目可应用于：
|
||||
|
||||
- 海洋生态学研究
|
||||
- 水产养殖监控
|
||||
- 鱼类行为分析
|
||||
- 生物多样性保护
|
||||
|
||||
## 🎯 推荐模型
|
||||
|
||||
### 基于 PySlowFast 代码库
|
||||
|
||||
本项目基于 [PySlowFast](https://github.com/facebookresearch/SlowFast) 代码库构建，这是 Facebook AI Research (FAIR) 提供的开源视频理解代码库。PySlowFast 提供了多种先进的视频动作识别模型实现，包括：
|
||||
|
||||
- **X3D**: 轻量级高效的视频识别模型
|
||||
- **SlowFast**: 双路径架构，慢路径捕获空间语义，快路径捕获时间动态
|
||||
- **MViT**: 多尺度视觉 Transformer
|
||||
- **I3D**: Inflated 3D ConvNet
|
||||
- **C2D**: 2D CNN 基线
|
||||
- **Non-local Network**: 非局部神经网络
|
||||
- **VideoMAE**: 基于掩码自编码器的视频预训练
|
||||
- **Rev-ViT**: 可逆视觉 Transformer
|
||||
|
||||
### 主要推荐：X3D 系列模型
|
||||
|
||||
**X3D (Expandable 3D Networks)** 是 Facebook AI Research 开发的轻量级视频动作识别模型，专门为效率和性能的平衡而设计。推荐使用 **X3D-M** 或 **X3D-S** 变体：
|
||||
|
||||
#### 为什么选择 X3D？
|
||||
|
||||
✅ **速度快**：相比传统 3D CNN 模型（如 I3D、SlowFast），X3D 在保持高精度的同时显著提升了推理速度
|
||||
|
||||
✅ **模型小**：参数量适中，易于微调和部署
|
||||
|
||||
✅ **性能好**：在 Kinetics-400、Kinetics-600 等大型数据集上表现优异
|
||||
|
||||
✅ **易微调**：提供预训练权重，支持快速迁移学习
|
||||
|
||||
✅ **多尺度**：提供 XS、S、M、L、XL 等多个变体，可根据需求选择
|
||||
|
||||
#### 模型变体对比
|
||||
|
||||
| 模型 | 参数量 | FLOPs | 速度 | 推荐场景 |
|
||||
|------|--------|-------|------|----------|
|
||||
| X3D-XS | ~3.8M | 0.38G | 最快 | 实时推理、资源受限 |
|
||||
| X3D-S | ~13.2M | 1.3G | 快 | **推荐：平衡速度与精度** |
|
||||
| X3D-M | ~24.1M | 6.2G | 中等 | **推荐：更高精度需求** |
|
||||
| X3D-L | ~77.6M | 26.6G | 较慢 | 高精度要求 |
|
||||
|
||||
#### 其他可选模型
|
||||
|
||||
- **SlowFast**: 双路径架构，精度高，适合对精度要求高的场景
|
||||
- **MViT**: 基于 Transformer 的多尺度模型，适合复杂场景
|
||||
- **VideoMAE**: 基于 Masked Autoencoder 的视频模型，精度高但速度较慢
|
||||
- **I3D**: 经典的 3D CNN 模型，稳定可靠
|
||||
|
||||
## ✨ 功能特性
|
||||
|
||||
- 🎥 支持多种视频格式输入（MP4, AVI, MOV 等）
|
||||
- 🔄 支持模型微调（Fine-tuning）
|
||||
- 📊 提供详细的训练和评估指标
|
||||
- 🚀 快速推理，支持批量处理
|
||||
- 📈 可视化训练过程和结果
|
||||
- 🔧 易于扩展和自定义
|
||||
|
||||
## 💻 环境要求
|
||||
|
||||
- Python >= 3.8
|
||||
- PyTorch >= 1.10.0
|
||||
- CUDA >= 11.0 (GPU 推荐)
|
||||
- ffmpeg (用于视频处理)
|
||||
|
||||
## 📦 安装指南
|
||||
|
||||
### 0. Git 认证配置（重要）
|
||||
|
||||
**为了避免每次推送/拉取时输入用户名和密码，强烈建议配置 SSH 密钥。**
|
||||
|
||||
详细配置步骤请参考：[SETUP_GIT.md](SETUP_GIT.md)
|
||||
|
||||
配置完成后，使用 SSH URL 克隆仓库：
|
||||
```bash
|
||||
git clone --recursive git@github.com:yourusername/FishAction.git
|
||||
```
|
||||
|
||||
### 1. 克隆仓库（包含子模块）
|
||||
|
||||
```bash
|
||||
# 方式一：克隆时同时初始化子模块
|
||||
git clone --recursive https://github.com/yourusername/FishAction.git
|
||||
cd FishAction
|
||||
|
||||
# 方式二：如果已经克隆了仓库，需要初始化子模块
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
### 2. 安装 PySlowFast
|
||||
|
||||
进入 SlowFast 子模块目录并安装：
|
||||
|
||||
```bash
|
||||
cd slowfast
|
||||
python setup.py build develop
|
||||
cd ..
|
||||
```
|
||||
|
||||
### 3. 创建虚拟环境
|
||||
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Linux/Mac
|
||||
# 或
|
||||
venv\Scripts\activate # Windows
|
||||
```
|
||||
|
||||
### 4. 安装依赖
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 5. 安装 PyTorch (根据你的 CUDA 版本)
|
||||
|
||||
```bash
|
||||
# CUDA 11.3
|
||||
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu113
|
||||
|
||||
# CPU only
|
||||
pip install torch torchvision torchaudio
|
||||
```
|
||||
|
||||
### 6. 安装其他依赖
|
||||
|
||||
根据 PySlowFast 的要求，可能还需要安装：
|
||||
|
||||
```bash
|
||||
pip install fvcore iopath simplejson av psutil opencv-python tensorboard
|
||||
```
|
||||
|
||||
> **注意**：详细的安装说明请参考 `slowfast/INSTALL.md`
|
||||
|
||||
## 📁 数据集准备
|
||||
|
||||
### 数据集结构
|
||||
|
||||
建议按以下结构组织数据集：
|
||||
|
||||
```
|
||||
dataset/
|
||||
├── train/
|
||||
│ ├── swimming/
|
||||
│ │ ├── video1.mp4
|
||||
│ │ ├── video2.mp4
|
||||
│ │ └── ...
|
||||
│ ├── feeding/
|
||||
│ │ ├── video1.mp4
|
||||
│ │ └── ...
|
||||
│ └── escaping/
|
||||
│ └── ...
|
||||
├── val/
|
||||
│ └── (same structure as train)
|
||||
└── test/
|
||||
└── (same structure as train)
|
||||
```
|
||||
|
||||
### 数据集要求
|
||||
|
||||
- 视频格式：MP4, AVI, MOV 等常见格式
|
||||
- 视频长度：建议 2-10 秒
|
||||
- 分辨率：建议 224x224 或更高
|
||||
- 帧率：建议 30fps
|
||||
|
||||
## 🚀 使用方法
|
||||
|
||||
### 快速开始
|
||||
|
||||
```bash
|
||||
# 使用预训练模型进行推理
|
||||
python infer.py --video_path path/to/video.mp4 --model_path path/to/model.pth
|
||||
```
|
||||
|
||||
## 🎓 模型训练
|
||||
|
||||
### 1. 准备配置文件
|
||||
|
||||
PySlowFast 使用 YAML 配置文件。可以参考 `slowfast/configs/` 目录下的示例配置文件，或创建自定义配置：
|
||||
|
||||
```bash
|
||||
# 查看可用的配置文件
|
||||
ls slowfast/configs/
|
||||
|
||||
# 例如使用 X3D-M 配置
|
||||
cp slowfast/configs/Kinetics/X3D_M.yaml configs/x3d_m_fish.yaml
|
||||
```
|
||||
|
||||
修改配置文件中的关键参数：
|
||||
|
||||
```yaml
|
||||
MODEL:
|
||||
NUM_CLASSES: 10 # 你的鱼类行为类别数
|
||||
ARCH: x3d
|
||||
MODEL_NAME: X3D
|
||||
DEPTH: 16
|
||||
FRAME_HEIGHT: 224
|
||||
FRAME_WIDTH: 224
|
||||
|
||||
DATA:
|
||||
PATH_TO_DATA_DIR: "dataset"
|
||||
PATH_PREFIX: ""
|
||||
TRAIN_LISTS: ["train.csv"]
|
||||
TEST_LISTS: ["val.csv"]
|
||||
NUM_FRAMES: 16
|
||||
SAMPLING_RATE: 1
|
||||
|
||||
TRAIN:
|
||||
ENABLE: True
|
||||
BATCH_SIZE: 8
|
||||
NUM_WORKERS: 4
|
||||
EPOCHS: 50
|
||||
BASE_LR: 0.001
|
||||
```
|
||||
|
||||
### 2. 准备数据列表
|
||||
|
||||
PySlowFast 需要 CSV 格式的数据列表文件，格式如下：
|
||||
|
||||
```csv
|
||||
path/to/video1.mp4 0
|
||||
path/to/video2.mp4 1
|
||||
path/to/video3.mp4 0
|
||||
...
|
||||
```
|
||||
|
||||
### 3. 开始训练
|
||||
|
||||
使用 PySlowFast 的训练工具：
|
||||
|
||||
```bash
|
||||
python slowfast/tools/run_net.py \
|
||||
--cfg configs/x3d_m_fish.yaml \
|
||||
DATA.PATH_TO_DATA_DIR dataset \
|
||||
DATA.PATH_PREFIX "" \
|
||||
NUM_GPUS 1 \
|
||||
TRAIN.BATCH_SIZE 8
|
||||
```
|
||||
|
||||
### 4. 使用预训练权重
|
||||
|
||||
PySlowFast 支持从 Kinetics 预训练权重开始微调。预训练权重会自动下载，或手动下载后指定路径：
|
||||
|
||||
```bash
|
||||
# 在配置文件中设置
|
||||
MODEL:
|
||||
PRETRAINED_MODEL_FILE: "path/to/pretrained/x3d_m.pyth"
|
||||
```
|
||||
|
||||
## 📊 模型评估
|
||||
|
||||
使用 PySlowFast 的评估工具：
|
||||
|
||||
```bash
|
||||
python slowfast/tools/run_net.py \
|
||||
--cfg configs/x3d_m_fish.yaml \
|
||||
DATA.PATH_TO_DATA_DIR dataset \
|
||||
TEST.ENABLE True \
|
||||
TEST.CHECKPOINT_FILE_PATH checkpoints/best_model.pyth \
|
||||
NUM_GPUS 1
|
||||
```
|
||||
|
||||
## 🔮 推理预测
|
||||
|
||||
### 单视频推理
|
||||
|
||||
```bash
|
||||
python infer.py \
|
||||
--video_path path/to/video.mp4 \
|
||||
--model_path checkpoints/best_model.pth \
|
||||
--output_path result.json
|
||||
```
|
||||
|
||||
### 批量推理
|
||||
|
||||
```bash
|
||||
python infer.py \
|
||||
--video_dir path/to/videos \
|
||||
--model_path checkpoints/best_model.pth \
|
||||
--output_dir results/
|
||||
```
|
||||
|
||||
## 📂 项目结构
|
||||
|
||||
```
|
||||
FishAction/
|
||||
├── README.md
|
||||
├── requirements.txt
|
||||
├── slowfast/ # PySlowFast 子模块（包含 X3D、SlowFast 等模型实现）
|
||||
│ ├── slowfast/ # 核心代码
|
||||
│ ├── configs/ # 模型配置文件
|
||||
│ ├── tools/ # 训练和评估工具
|
||||
│ └── ...
|
||||
├── configs/ # 项目配置文件
|
||||
│ ├── x3d_s_config.yaml
|
||||
│ └── x3d_m_config.yaml
|
||||
├── src/
|
||||
│ ├── models/ # 自定义模型扩展
|
||||
│ ├── data/ # 数据处理
|
||||
│ │ ├── dataset.py
|
||||
│ │ └── transforms.py
|
||||
│ ├── train.py # 训练脚本（基于 PySlowFast）
|
||||
│ ├── evaluate.py # 评估脚本
|
||||
│ └── infer.py # 推理脚本
|
||||
├── utils/ # 工具函数
|
||||
│ ├── logger.py
|
||||
│ └── visualization.py
|
||||
├── checkpoints/ # 模型检查点
|
||||
└── results/ # 结果输出
|
||||
```
|
||||
|
||||
> **注意**：`slowfast/` 目录是 git 子模块，包含了完整的 PySlowFast 代码库。所有模型实现和训练工具都在此目录中。
|
||||
|
||||
## 📚 参考资料
|
||||
|
||||
### 代码库
|
||||
|
||||
- [PySlowFast 官方仓库](https://github.com/facebookresearch/SlowFast) - Facebook AI Research 的视频理解代码库
|
||||
- [PySlowFast 模型库](https://github.com/facebookresearch/SlowFast/blob/main/MODEL_ZOO.md) - 预训练模型和基准测试结果
|
||||
|
||||
### 论文
|
||||
|
||||
- [X3D: Expanding Architectures for Efficient Video Recognition](https://arxiv.org/abs/2004.04730)
|
||||
- [SlowFast Networks for Video Recognition](https://arxiv.org/abs/1812.03982)
|
||||
- [MViT: Multiscale Vision Transformers](https://arxiv.org/abs/2104.11227)
|
||||
- [VideoMAE: Masked Autoencoders are Data-Efficient Learners for Self-Supervised Video Pre-Training](https://arxiv.org/abs/2203.12602)
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
欢迎贡献代码！请遵循以下步骤：
|
||||
|
||||
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) 文件了解详情
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
- [Facebook AI Research (FAIR)](https://ai.facebook.com/research/) 提供的 [PySlowFast](https://github.com/facebookresearch/SlowFast) 代码库
|
||||
- PyTorch 社区的支持
|
||||
- 所有为视频理解领域做出贡献的研究者们
|
||||
|
||||
---
|
||||
|
||||
如有问题或建议，请提交 Issue 或联系项目维护者。
|
||||
Reference in New Issue
Block a user