Torchreid

Torchreid 是一个基于 PyTorch <https://pytorch.org/>_ 编写的深度学习行人重识别库，专为我们在 ICCV'19 上发表的项目——“面向行人重识别的全尺度特征学习”（arXiv:1905.00953 <https://arxiv.org/abs/1905.00953>_）而开发。

其主要特性包括：

• 多 GPU 训练
• 同时支持图像和视频的行人重识别任务
• 端到端的训练与评估
• 极其简便的重识别数据集准备流程
• 多数据集联合训练
• 跨数据集评估
• 采用大多数研究论文通用的标准协议
• 高度可扩展性（易于添加模型、数据集、训练方法等）
• 实现了当前最先进的深度行人重识别模型
• 提供预训练的重识别模型
• 先进的训练技巧
• 可视化工具（TensorBoard、Rank 指标等）

代码：https://github.com/KaiyangZhou/deep-person-reid。

文档：https://kaiyangzhou.github.io/deep-person-reid/。

使用指南：https://kaiyangzhou.github.io/deep-person-reid/user_guide。

模型库：https://kaiyangzhou.github.io/deep-person-reid/MODEL_ZOO。

技术报告：https://arxiv.org/abs/1910.10093。

基于 Torchreid 构建的一些研究项目可以在这里找到：https://github.com/KaiyangZhou/deep-person-reid/tree/master/projects_。

模型权重也在 Hugging Face 上提供：https://huggingface.co/kaiyangzhou/osnet。

新增内容

• [2022年8月] 我们为以下框架添加了模型导出功能：ONNX、OpenVINO 和 TFLite。导出脚本可在此处找到：here <https://github.com/KaiyangZhou/deep-person-reid/blob/master/tools/export.py>_
• [2021年8月] 我们发布了 osnet_ain_x0_75、osnet_ain_x0_5 和 osnet_ain_x0_25 的 ImageNet 预训练模型。预训练设置遵循 pycls <https://github.com/facebookresearch/pycls/blob/master/configs/archive/imagenet/resnet/R-50-1x64d_step_8gpu.yaml>_。
• [2021年4月] 我们更新了 OSNet 的 TPAMI 版本附录，以包含多源域泛化设置下的结果。训练好的模型可在 Model Zoo <https://kaiyangzhou.github.io/deep-person-reid/MODEL_ZOO.html>_ 中找到。
• [2021年4月] 我们添加了一个脚本，用于自动化计算多个划分的平均结果的过程。更多详情请参阅 tools/parse_test_res.py。
• [2021年4月] v1.4.0：我们增加了行人搜索数据集 CUHK-SYSU <http://www.ee.cuhk.edu.hk/~xgwang/PS/dataset.html>。请参阅 文档 <https://kaiyangzhou.github.io/deep-person-reid/> 了解如何下载该数据集（其中包含裁剪后的行人图像）。
• [2021年4月] 模型库中的所有模型已迁移到 Google Drive。如果任何模型的性能与模型库页面上显示的数字不一致，请提交 issue（可能是链接错误所致）。
• [2021年3月] OSNet <https://arxiv.org/abs/1910.06827>_ 将发表在 TPAMI 期刊上！与专注于使用全尺度构建模块进行判别特征学习的会议版本相比，该期刊扩展版进一步考虑了通过将 实例归一化层 <https://arxiv.org/abs/1607.08022>_ 整合到 OSNet 架构中来实现可泛化特征学习。我们希望这篇期刊论文能够激励更多的未来工作，以解决跨数据集重识别中的泛化问题。
• [2021年3月] 行人重识别中跨域（数据集）的泛化在实际应用中至关重要，这与 域泛化 主题密切相关。您是否想了解过去十年中域泛化领域的发展情况？请查看我们在该主题上的最新综述：https://arxiv.org/abs/2103.02503，其中涵盖了历史、数据集、相关问题、方法论、潜在方向等内容（*适用于可泛化重识别的方法也包含在内*！）。
• [2021年2月] v1.3.6 新增了 University-1652 <https://dl.acm.org/doi/abs/10.1145/3394171.3413896>，这是一个用于多视角多源地理定位的新数据集（感谢 Zhedong Zheng <https://github.com/layumi>）。
• [2021年2月] v1.3.5：现在 cython 代码 <https://github.com/KaiyangZhou/deep-person-reid/pull/412>_ 可以在 Windows 上运行（感谢 lablabla <https://github.com/lablabla>_）。
• [2021年1月] 我们的最新工作 MixStyle <https://openreview.net/forum?id=6xHJ37MVxxp>_（混合不同域样本的实例级特征统计以提高域泛化能力）已被 ICLR'21 接受。代码已在 https://github.com/KaiyangZhou/mixstyle-release 上发布，其中行人重识别部分基于 Torchreid。
• [2021年1月] 在 深度学习在行人重识别中的应用：综述与展望（TPAMI 2021） <https://arxiv.org/abs/2001.04193>_ 中，引入了一种新的行人重识别评估指标，称为 平均逆向负惩罚 (mINP)。其代码可在 <https://github.com/mangye16/ReID-Survey>_ 获取。
• [2020年8月] v1.3.3：修复了 visrank 中的 bug（由于未解包 dsetid 所致）。
• [2020年8月] v1.3.2：在 grid 和 prid 中添加了 _junk_pids。这样可以在设置 combineall=True 时避免使用标记错误的图库图像进行训练。
• [2020年8月] v1.3.0：(1) 在现有的三元组数据源中添加了 dsetid，从而得到 (impath, pid, camid, dsetid)。该变量表示数据集 ID，在合并多个数据集进行训练时非常有用（作为数据集标识）。例如，当合并 market1501 和 cuhk03 时，前者将被分配 dsetid=0，而后者则被分配 dsetid=1。 (2) 添加了 RandomDatasetSampler。类似于 RandomDomainSampler，RandomDatasetSampler 会从每个指定的数据集中抽取一定数量的图像（batch_size // num_datasets），抽取的数量由 num_datasets 决定。
• [2020年8月] v1.2.6：添加了 RandomDomainSampler（它会从 num_cams 个摄像头中各抽取 batch_size // num_cams 张图像，组成一个小批次）。
• [2020年6月] v1.2.5：(1) 数据加载器从 __getitem__ 返回的结果由原来的 list 改为 dict。以前，可以通过 imgs=data[0] 来获取某个元素，比如图像张量。现在则应通过 imgs=data['img'] 来获取。有关详细更改，请参阅此 提交 <https://github.com/KaiyangZhou/deep-person-reid/commit/aefe335d68f39a20160860e6d14c2d34f539b8a5>_。 (2) 添加了 k_tfm 作为图像数据加载器的一个选项，允许对一张图像独立地应用 k_tfm 次数据增强。如果 k_tfm > 1，imgs=data['img'] 将返回一个包含 k_tfm 张图像张量的列表。
• [2020年5月] 添加了用于 面向行人重识别的全尺度特征学习（ICCV'19） <https://arxiv.org/abs/1905.00953>_ 中的行人属性识别代码。请参阅 projects/attribute_recognition/。
• [2020年5月] v1.2.1：添加了一个简单的特征提取 API（torchreid/utils/feature_extractor.py）。有关说明，请参阅 文档 <https://kaiyangzhou.github.io/deep-person-reid/user_guide.html>_。
• [2020年4月] 用于复现 深度互学习 <https://zpascal.net/cvpr2018/Zhang_Deep_Mutual_Learning_CVPR_2018_paper.pdf>_ 实验的代码，已在 OSNet 论文 <https://arxiv.org/pdf/1905.00953v6.pdf>_（补充 B）的 projects/DML 中发布。
• [2020年4月] 升级至 v1.2.0。引擎类变得更加模型无关，以提高可扩展性。有关详细信息，请参阅 Engine <torchreid/engine/engine.py>_ 和 ImageSoftmaxEngine <torchreid/engine/image/softmax.py>。感谢 Dassl.pytorch <https://github.com/KaiyangZhou/Dassl.pytorch>。
• [2019年12月] 我们的 OSNet 论文 <https://arxiv.org/pdf/1905.00953v6.pdf>_ 已更新，补充部分 B 中增加了额外的实验，展示了一些在实践中提升 OSNet 性能的实用技术。
• [2019年11月] `ImageDataManager可以通过设置load_train_targets=True从目标数据集加载训练数据，并可通过train_loader_t = datamanager.train_loader_t`` 访问训练加载器。此功能对域适应研究非常有用。

安装

确保已安装 conda <https://www.anaconda.com/distribution/>_。

.. code-block:: bash

切换到您 preferred 的目录并克隆此仓库

git clone https://github.com/KaiyangZhou/deep-person-reid.git

# 创建环境
cd deep-person-reid/
conda create --name torchreid python=3.7
conda activate torchreid

# 安装依赖
# 确保 `which python` 和 `which pip` 指向正确的路径
pip install -r requirements.txt

# 安装 PyTorch 和 torchvision（根据您的机器选择合适的 CUDA 版本）
conda install pytorch torchvision cudatoolkit=9.0 -c pytorch

# 安装 torchreid（如果您修改了源代码，则无需重新构建）
python setup.py develop

另一种安装方式是在 Docker 容器中运行所有步骤：

• 构建：make build-image
• 运行：make run

快速入门：30 秒掌握 Torchreid

1. 导入 torchreid

.. code-block:: python

import torchreid

2. 加载数据管理器

.. code-block:: python

datamanager = torchreid.data.ImageDataManager(
    root="reid-data",
    sources="market1501",
    targets="market1501",
    height=256,
    width=128,
    batch_size_train=32,
    batch_size_test=100,
    transforms=["random_flip", "random_crop"]
)

3 构建模型、优化器和学习率调度器

.. code-block:: python

model = torchreid.models.build_model(
    name="resnet50",
    num_classes=datamanager.num_train_pids,
    loss="softmax",
    pretrained=True
)

model = model.cuda。

optimizer = torchreid.optim.build_optimizer(
    model,
    optim="adam",
    lr=0.0003
)

scheduler = torchreid.optim.build_lr_scheduler(
    optimizer,
    lr_scheduler="single_step",
    stepsize=20
)

4. 构建训练引擎

.. code-block:: python

engine = torchreid.engine.ImageSoftmaxEngine(
    datamanager,
    model,
    optimizer=optimizer,
    scheduler=scheduler,
    label_smooth=True
)

5. 开始训练和测试

.. code-block:: python

engine.run(
    save_dir="log/resnet50",
    max_epoch=60,
    eval_freq=10,
    print_freq=10,
    test_only=False
)

统一接口

在“deep-person-reid/scripts/”中，我们提供了一个统一的接口来训练和测试模型。更多细节请参阅“scripts/main.py”和“scripts/default_config.py”。文件夹“configs/”包含一些预定义的配置文件，您可以将其作为起点。

下面提供一个训练和测试 OSNet (Zhou et al. ICCV'19) <https://arxiv.org/abs/1905.00953>_ 的示例。假设 :code:PATH_TO_DATA 是包含 reid 数据集的目录。环境变量 :code:CUDA_VISIBLE_DEVICES 被省略，如果您有一组 GPU 并希望使用其中特定的一组，则需要指定该变量。

常规设置 ^^^^^^^^^^^^^^^^^

要在 Market1501 上训练 OSNet，请执行以下命令：

.. code-block:: bash

python scripts/main.py \
--config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \
--transforms random_flip random_erase \
--root $PATH_TO_DATA

配置文件将 Market1501 设置为默认数据集。如果您想使用 DukeMTMC-reID，则可以执行以下命令：

.. code-block:: bash

python scripts/main.py \
--config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \
-s dukemtmcreid \
-t dukemtmcreid \
--transforms random_flip random_erase \
--root $PATH_TO_DATA \
data.save_dir log/osnet_x1_0_dukemtmcreid_softmax_cosinelr

代码会自动（下载并）加载 ImageNet 预训练权重。训练完成后，模型将保存为 “log/osnet_x1_0_market1501_softmax_cosinelr/model.pth.tar-250”。在同一文件夹下，您还可以找到 tensorboard <https://pytorch.org/docs/stable/tensorboard.html>_ 文件。要使用 tensorboard 可视化学习曲线，可以在终端中运行 :code:tensorboard --logdir=log/osnet_x1_0_market1501_softmax_cosinelr，然后在浏览器中访问 :code:http://localhost:6006/。

训练结束时会自动进行评估。要使用已训练好的模型再次进行测试，可以执行以下命令：

.. code-block:: bash

python scripts/main.py \
--config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \
--root $PATH_TO_DATA \
model.load_weights log/osnet_x1_0_market1501_softmax_cosinelr/model.pth.tar-250 \
test.evaluate True

跨域设置 ^^^^^^^^^^^^^^^^^

假设您想在 DukeMTMC-reID 上训练 OSNet，并在 Market1501 上测试其性能，可以执行以下命令：

.. code-block:: bash

python scripts/main.py \
--config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad.yaml \
-s dukemtmcreid \
-t market1501 \
--transforms random_flip color_jitter \
--root $PATH_TO_DATA

在这里，我们仅测试跨域性能。然而，如果您还想测试源数据集（即 DukeMTMC-reID）上的性能，可以设置 :code:-t dukemtmcreid market1501，这将分别在两个数据集上评估模型。

与同域设置不同，这里我们将 :code:random_erase 替换为 :code:color_jitter。这可以提高模型在未见过的目标数据集上的泛化能力。

预训练模型可在 Model Zoo <https://kaiyangzhou.github.io/deep-person-reid/MODEL_ZOO.html>_ 中找到。

数据集

图像 reid 数据集 ^^^^^^^^^^^^^^^^^^^^^

• Market1501 <https://www.cv-foundation.org/openaccess/content_iccv_2015/papers/Zheng_Scalable_Person_Re-Identification_ICCV_2015_paper.pdf>_
• CUHK03 <https://www.cv-foundation.org/openaccess/content_cvpr_2014/papers/Li_DeepReID_Deep_Filter_2014_CVPR_paper.pdf>_
• DukeMTMC-reID <https://arxiv.org/abs/1701.07717>_
• MSMT17 <https://arxiv.org/abs/1711.08565>_
• VIPeR <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.331.7285&rep=rep1&type=pdf>_
• GRID <http://www.eecs.qmul.ac.uk/~txiang/publications/LoyXiangGong_cvpr_2009.pdf>_
• CUHK01 <http://www.ee.cuhk.edu.hk/~xgwang/papers/liZWaccv12.pdf>_
• SenseReID <http://openaccess.thecvf.com/content_cvpr_2017/papers/Zhao_Spindle_Net_Person_CVPR_2017_paper.pdf>_
• QMUL-iLIDS <http://www.eecs.qmul.ac.uk/~sgg/papers/ZhengGongXiang_BMVC09.pdf>_
• PRID <https://pdfs.semanticscholar.org/4c1b/f0592be3e535faf256c95e27982db9b3d3d3.pdf>_

地理定位数据集 ^^^^^^^^^^^^^^^^^^^^^^^

• University-1652 <https://dl.acm.org/doi/abs/10.1145/3394171.3413896>_

视频 reid 数据集 ^^^^^^^^^^^^^^^^^^^^^^^

• MARS <http://www.liangzheng.org/1320.pdf>_
• iLIDS-VID <https://www.eecs.qmul.ac.uk/~sgg/papers/WangEtAl_ECCV14.pdf>_
• PRID2011 <https://pdfs.semanticscholar.org/4c1b/f0592be3e535faf256c95e27982db9b3d3d3.pdf>_
• DukeMTMC-VideoReID <http://openaccess.thecvf.com/content_cvpr_2018/papers/Wu_Exploit_the_Unknown_CVPR_2018_paper.pdf>_

模型

ImageNet分类模型 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

• ResNet <https://arxiv.org/abs/1512.03385>_
• ResNeXt <https://arxiv.org/abs/1611.05431>_
• SENet <https://arxiv.org/abs/1709.01507>_
• DenseNet <https://arxiv.org/abs/1608.06993>_
• Inception-ResNet-V2 <https://arxiv.org/abs/1602.07261>_
• Inception-V4 <https://arxiv.org/abs/1602.07261>_
• Xception <https://arxiv.org/abs/1610.02357>_
• IBN-Net <https://arxiv.org/abs/1807.09441>_

轻量级模型 ^^^^^^^^^^^^^^^^^^^

• NASNet <https://arxiv.org/abs/1707.07012>_
• MobileNetV2 <https://arxiv.org/abs/1801.04381>_
• ShuffleNet <https://arxiv.org/abs/1707.01083>_
• ShuffleNetV2 <https://arxiv.org/abs/1807.11164>_
• SqueezeNet <https://arxiv.org/abs/1602.07360>_

ReID专用模型 ^^^^^^^^^^^^^^^^^^^^^^

• MuDeep <https://arxiv.org/abs/1709.05165>_
• ResNet-mid <https://arxiv.org/abs/1711.08106>_
• HACNN <https://arxiv.org/abs/1802.08122>_
• PCB <https://arxiv.org/abs/1711.09349>_
• MLFN <https://arxiv.org/abs/1803.09132>_
• OSNet <https://arxiv.org/abs/1905.00953>_
• OSNet-AIN <https://arxiv.org/abs/1910.06827>_

实用链接

• OSNet-IBN1-Lite（仅用于测试的代码及精简版Docker容器） <https://github.com/RodMech/OSNet-IBN1-Lite>_
• 基于深度学习的人体重识别：综述与展望 <https://github.com/mangye16/ReID-Survey>_

引用

如果您在研究中使用了本代码或相关模型，请引用以下论文：

.. code-block:: bash

@article{torchreid,
  title={Torchreid: 一个基于PyTorch的深度学习人体重识别库},
  author={周凯阳和向涛},
  journal={arXiv预印本 arXiv:1910.10093},
  year={2019}
}

@inproceedings{zhou2019osnet,
  title={面向人体重识别的全尺度特征学习},
  author={周凯阳、杨永新、卡瓦拉罗和向涛},
  booktitle={ICCV},
  year={2019}
}

@article{zhou2021osnet,
  title={学习可泛化的全尺度人体重识别表示},
  author={周凯阳、杨永新、卡瓦拉罗和向涛},
  journal={TPAMI},
  year={2021}
}

deep-person-reid 快速上手指南

deep-person-reid (Torchreid) 是一个基于 PyTorch 的深度学习行人重识别（Person Re-ID）库，支持图像和视频 ReID、多 GPU 训练、跨数据集评估等高级功能，并集成了多种 SOTA 模型（如 OSNet）。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux 或 Windows (Windows 需特定配置以支持 Cython)。
• Python: 推荐版本 3.7。
• 包管理器: 必须安装 Conda。
• GPU: 推荐使用 NVIDIA GPU 并安装对应的 CUDA 驱动（用于加速训练）。

安装步骤

以下是标准的本地安装流程。国内用户若遇到 pip 下载慢的问题，可临时使用清华源或阿里源。

1. 克隆仓库

   git clone https://github.com/KaiyangZhou/deep-person-reid.git
   cd deep-person-reid/
   

2. 创建 Conda 环境

   conda create --name torchreid python=3.7
   conda activate torchreid
   

3. 安装依赖

   # 建议先配置 pip 国内镜像加速 (可选)
   # pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
   
   pip install -r requirements.txt
   

4. 安装 PyTorch 和 torchvision 请根据您的机器 CUDA 版本选择合适的命令。以下为示例（CUDA 9.0）：

   # 国内用户推荐使用清华源安装 PyTorch
   conda install pytorch torchvision cudatoolkit=9.0 -c pytorch
   

   注：如需其他 CUDA 版本，请访问 PyTorch 官网获取对应命令。

5. 安装 Torchreid 使用 develop 模式安装，以便修改源码后无需重新编译即可生效。

   python setup.py develop
   

Docker 替代方案：如果您偏好容器化部署，也可在项目根目录运行 make build-image 构建镜像，然后运行 make run。

基本使用

以下是一个最简单的"30 秒上手”示例，演示如何加载数据、构建模型并启动训练。

1. Python 代码示例

创建一个 .py 文件（例如 quick_start.py），填入以下代码：

import torchreid

# 1. 加载数据管理器
datamanager = torchreid.data.ImageDataManager(
    root="reid-data",
    sources="market1501",
    targets="market1501",
    height=256,
    width=128,
    batch_size_train=32,
    batch_size_test=100,
    transforms=["random_flip", "random_crop"]
)

# 2. 构建模型、优化器和学习率调度器
model = torchreid.models.build_model(
    name="resnet50",
    num_classes=datamanager.num_train_pids,
    loss="softmax",
    pretrained=True
)

model = model.cuda()

optimizer = torchreid.optim.build_optimizer(
    model,
    optim="adam",
    lr=0.0003
)

scheduler = torchreid.optim.build_lr_scheduler(
    optimizer,
    lr_scheduler="single_step",
    stepsize=20
)

# 3. 构建引擎
engine = torchreid.engine.ImageSoftmaxEngine(
    datamanager,
    model,
    optimizer=optimizer,
    scheduler=scheduler,
    label_smooth=True
)

# 4. 运行训练和测试
engine.run(
    save_dir="log/resnet50",
    max_epoch=60,
    eval_freq=10,
    print_freq=10,
    test_only=False
)

2. 命令行统一接口（推荐）

对于更复杂的实验配置，建议使用项目提供的统一脚本接口。假设您的数据集位于 $PATH_TO_DATA 目录下。

训练 OSNet 模型 (Market1501 数据集):

python scripts/main.py \
--config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \
--transforms random_flip random_erase \
--root $PATH_TO_DATA

训练 OSNet 模型 (DukeMTMC-reID 数据集):

python scripts/main.py \
--config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \
-s dukemtmcreid \
-t dukemtmcreid \
--transforms random_flip random_erase \
--root $PATH_TO_DATA \
data.save_dir log/osnet_x1_0_dukemtmcreid_softmax_cosinelr

说明：代码会自动下载并加载 ImageNet 预训练权重。训练完成后，模型将保存在指定的 save_dir 中。