仓库瘦身说明：为减小部署体积，已移除本目录下的 slowfast/（PySlowFast 完整训练工程）。当前默认推理与训练入口为 PyTorchVideo X3D（train_pytorchvideo_x3d.py、predict_video_x3d_3class.py）。若需恢复 SlowFast，请从备份或上游 facebookresearch/SlowFast 自行放回。

基于深度学习的鱼类行为识别与分类系统，通过分析输入视频片段自动识别和分类鱼类的各种行为动作。

📋 目录

项目简介
推荐模型
功能特性
环境要求
安装指南
数据集准备
使用方法
模型训练
模型评估
推理预测
项目结构
贡献指南
许可证

🐟 项目简介

FishAction 是一个专门用于鱼类行为识别和分类的深度学习项目。通过分析视频片段，系统能够自动识别和分类鱼类的各种行为，如游动、觅食、逃避、社交等。该项目可应用于：

海洋生态学研究
水产养殖监控
鱼类行为分析
生物多样性保护

🎯 推荐模型

基于 PySlowFast 代码库

本项目基于 PySlowFast 代码库构建，这是 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

配置完成后，使用 SSH URL 克隆仓库：

git clone --recursive git@github.com:yourusername/FishAction.git

1. 克隆仓库（包含子模块）

# 方式一：克隆时同时初始化子模块
git clone --recursive https://github.com/yourusername/FishAction.git
cd FishAction

# 方式二：如果已经克隆了仓库，需要初始化子模块
git submodule update --init --recursive

2. 安装 PySlowFast

进入 SlowFast 子模块目录并安装：

cd slowfast
python setup.py build develop
cd ..

3. 创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

4. 安装依赖

pip install -r requirements.txt

5. 安装 PyTorch (根据你的 CUDA 版本)

# 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 的要求，可能还需要安装：

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

🚀 使用方法

快速开始

# 使用预训练模型进行推理
python infer.py --video_path path/to/video.mp4 --model_path path/to/model.pth

🎓 模型训练

1. 准备配置文件

PySlowFast 使用 YAML 配置文件。可以参考 slowfast/configs/ 目录下的示例配置文件，或创建自定义配置：

# 查看可用的配置文件
ls slowfast/configs/

# 例如使用 X3D-M 配置
cp slowfast/configs/Kinetics/X3D_M.yaml configs/x3d_m_fish.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 格式的数据列表文件，格式如下：

path/to/video1.mp4 0
path/to/video2.mp4 1
path/to/video3.mp4 0
...

3. 开始训练

使用 PySlowFast 的训练工具：

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 预训练权重开始微调。预训练权重会自动下载，或手动下载后指定路径：

# 在配置文件中设置
MODEL:
  PRETRAINED_MODEL_FILE: "path/to/pretrained/x3d_m.pyth"

📊 模型评估

使用 PySlowFast 的评估工具：

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

🔮 推理预测

单视频推理

python infer.py \
    --video_path path/to/video.mp4 \
    --model_path checkpoints/best_model.pth \
    --output_path result.json

批量推理

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 官方仓库 - Facebook AI Research 的视频理解代码库
PySlowFast 模型库 - 预训练模型和基准测试结果

论文

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

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

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

🙏 致谢

Facebook AI Research (FAIR) 提供的 PySlowFast 代码库
PyTorch 社区的支持
所有为视频理解领域做出贡献的研究者们

如有问题或建议，请提交 Issue 或联系项目维护者。

README.md Unescape Escape

FishAction