cvpods 快速上手指南

cvpods 是一个高效、通用的计算机视觉代码库，支持分类、分割、检测、自监督学习、关键点及 3D 任务等。旨在实现高效的实验管理和顺畅的任务切换。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux
• Python: 版本 ≥ 3.6
• 深度学习框架: PyTorch ≥ 1.3 且需安装与之匹配的 torchvision（建议在 pytorch.org 确认对应版本）。
• 其他依赖: OpenCV（可选，用于演示和可视化）。
• 硬件要求: 本地机器需具备可用的 GPU。

国内加速建议：若下载 PyTorch 或 GitHub 资源较慢，推荐使用清华源或阿里源进行加速。

• PyTorch 清华源示例：pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple
• Git 克隆加速：可使用 git clone https://github.com.cnpmjs.org/Megvii-BaseDetection/cvpods.git 替代官方地址。

安装步骤

您可以选择直接通过 pip 安装，或克隆源码后安装。

方式一：直接通过 Git 安装（推荐）

pip install 'git+https://github.com/Megvii-BaseDetection/cvpods.git' --user

方式二：源码安装（可编辑模式）

如果您需要修改源码或进行开发，建议克隆仓库后安装：

# 克隆仓库
git clone https://github.com/Megvii-BaseDetection/cvpods.git

# 进入目录并安装
cd cvpods
pip install -e . --user

注意：构建过程默认需要 CUDA 支持。若在无 GPU 环境下强制构建（不推荐用于训练），可设置环境变量： FORCE_CUDA=1 pip install -e . --user

基本使用

以下以 COCO 数据集上的物体检测任务（RetinaNet）为例，展示最基础的训练与测试流程。

1. 准备数据

将 COCO 数据集链接到项目指定的 datasets 目录下：

ln -s /path/to/your/coco/dataset datasets/coco

2. 进入实验目录

切换到具体的实验配置文件夹（例如 RetinaNet Res50 FPN 配置）：

cd playground/retinanet/retinanet.res50.fpn.coco.multiscale.1x

3. 开始训练

使用 pods_train 命令启动训练，指定 GPU 数量：

pods_train --num-gpus 8

4. 模型测试

训练完成后，使用 pods_test 进行评估。您可以指定模型权重路径和输出目录：

pods_test --num-gpus 8 \
    MODEL.WEIGHTS /path/to/your/save_dir/ckpt.pth \
    OUTPUT_DIR /path/to/your/save_dir

5. 多机分布式训练（可选）

若需在多台机器上并行训练，请使用以下命令格式（需提前安装 net-tools）：

# 安装网络工具
sudo apt install net-tools ifconfig

# 启动多机训练
# 参数说明：--num-machines 为机器总数，--machine-rank 为当前机器编号 (0 到 N-1)
pods_train --num-gpus 8 --num-machines N --machine-rank 0 --dist-url "tcp://MASTER_IP:port"

更多详细功能、API 文档及进阶教程，请参考官方 文档 或查看仓库中的 tutorial notebook。