易于扩展的基础深度度量学习流水线

Karsten Roth (karsten.rh1@gmail.com), Biagio Brattoli (biagio.brattoli@gmail.com)

在学术工作中使用此仓库时，请引用

@misc{roth2020revisiting,
    title={Revisiting Training Strategies and Generalization Performance in Deep Metric Learning},
    author={Karsten Roth and Timo Milbich and Samarth Sinha and Prateek Gupta and Björn Ommer and Joseph Paul Cohen},
    year={2020},
    eprint={2002.08473},
    archivePrefix={arXiv},
    primaryClass={cs.CV}
}

---

基于该仓库的扩展版本，我们进行了深度度量学习的全面比较与评估：

https://arxiv.org/abs/2002.08473

新发布的代码可在此处找到：https://github.com/Confusezius/Revisiting_Deep_Metric_Learning_PyTorch

其中包含更多的损失函数、采样器、评估指标和日志记录选项！

---

使用方法请参见第3节，实验结果请参见第4节

1. 概述

本仓库包含一个完整且易于扩展的流水线，用于测试和实现当前及新的深度度量学习方法。作为参考和测试，本仓库实现了以下组件：

损失函数

• Triplet Loss（三元组损失）(https://arxiv.org/abs/1412.6622)
• Margin Loss（间隔损失）(https://arxiv.org/abs/1706.07567)
• ProxyNCA（代理NCA损失）(https://arxiv.org/abs/1703.07464)
• N-Pair Loss（N对损失）(https://papers.nips.cc/paper/6200-improved-deep-metric-learning-with-multi-class-n-pair-loss-objective.pdf)

采样方法

• Random Sampling（随机采样）
• Softhard Sampling（软难采样，困难元组采样的软版本）
• Semihard Sampling（半难采样）(https://arxiv.org/abs/1503.03832)
• Distance Sampling（距离采样）(https://arxiv.org/abs/1706.07567)
• N-Pair Sampling（N对采样）(https://papers.nips.cc/paper/6200-improved-deep-metric-learning-with-multi-class-n-pair-loss-objective.pdf)

数据集

• CUB200-2011 (http://www.vision.caltech.edu/visipedia/CUB-200.html)
• CARS196 (https://ai.stanford.edu/~jkrause/cars/car_dataset.html)
• Stanford Online Products (http://cvgl.stanford.edu/projects/lifted_struct/)
• In-Shop Clothes (http://mmlab.ie.cuhk.edu.hk/projects/DeepFashion/InShopRetrieval.html, 从 https://drive.google.com/drive/folders/0B7EVK8r0v71pVDZFQXRsMDZCX1E 下载。感谢 KunHe 提供链接！)
• （可选）PKU Vehicle-ID (https://www.pkuml.org/resources/pku-vds.html)

网络架构

• ResNet50 (https://arxiv.org/abs/1512.03385)
• GoogLeNet (https://arxiv.org/abs/1409.4842)
  [注：此版本遵循官方torchvision实现，与原始版本有所不同。]

注意: PKU Vehicle-ID 是_（可选的）_，因为没有直接下载该数据集的方式，它需要特殊许可。但是，如果该数据集可用（结构如2.2节所示），则可以直接使用。

---

1.1 相关仓库：

• Metric Learning with Mined Interclass Characteristics
• Metric Learning by dividing the embedding space
• Deep Metric Learning to Rank

---

2. 仓库与数据集结构

2.1 仓库结构

Repository
│   ### 通用文件
│   README.md
│   requirements.txt    
│   installer.sh
|
|   ### 主脚本
|   Standard_Training.py     (主训练脚本)
|   losses.py   (损失函数和采样实现集合)
│   datasets.py (所有数据集的数据加载器)
│   
│   ### 工具脚本
|   auxiliaries.py  (实用工具集合)
|   evaluate.py     (评估函数集合)
│   
│   ### 网络脚本
|   netlib.py       (ResNet50实现)
|   googlenet.py    (GoogLeNet实现)
│   
│   
└───Training Results (训练过程中生成)
|    │   e.g. cub200/Training_Run_Name
|    │   e.g. cars196/Training_Run_Name
|
│   
└───Datasets (应添加到此，如果不想设置路径)
|    │   cub200
|    │   cars196
|    │   online_products
|    │   in-shop
|    │   vehicle_id

2.2 数据集结构

CUB200-2011/CARS196

cub200/cars196
└───images
|    └───001.Black_footed_Albatross
|           │   Black_Footed_Albatross_0001_796111
|           │   ...
|    ...

Online Products

online_products
└───images
|    └───bicycle_final
|           │   111085122871_0.jpg
|    ...
|
└───Info_Files
|    │   bicycle.txt
|    │   ...

In-Shop Clothes

in-shop
└─img
|    └─MEN
|         └─Denim
|               └─id_00000080
|                  │   01_1_front.jpg
|                  │   ...
|               ...
|         ...
|    ...
|
└─Eval
|  │   list_eval_partition.txt

PKU Vehicle ID

vehicle_id
└───image
|     │   <img>.jpg
|     |   ...
|     
└───train_test_split
|     |   test_list_800.txt
|     |   ...

---

3. 使用流水线

[1.] 环境要求

该流水线基于 Python3（即通过安装 Miniconda https://conda.io/miniconda.html）和 Pytorch 1.0.0/1 构建。已在 cuda 8 和 cuda 9 环境下测试。

要安装所需的库，可以直接查看 requirements.txt 或创建 conda 环境：

conda create -n <Env_Name> python=3.6

激活环境

conda activate <Env_Name>

然后运行

bash installer.sh

注意，对于 k均值聚类（kMeans）和最近邻（Nearest Neighbour）计算，我们使用了 faiss 库，如果需要速度，可以将这些计算移动到GPU上。然而，在大多数情况下，faiss 已经足够快，使得评估指标的计算不会成为瓶颈。
注意： 如果不想使用 faiss 而想使用标准的 sklearn，只需在导入库时使用 auxiliaries_nofaiss.py 替换 auxiliaries.py。

[2.] 示例运行

主脚本是 Standard_Training.py。如果不带输入参数运行，将执行在 CUB200-2011 数据集上使用 Marginloss（边际损失）和 Distance-sampling（距离采样）对 ResNet50 进行训练。

否则，可以使用以下标志来使用不同的损失函数（loss）、采样方法（sampling）、架构（arch）和数据集（dataset）进行训练：

python Standard_Training.py --dataset <dataset> --loss <loss> --sampling <sampling> --arch <arch> --k_vals <k_vals> --embed_dim <embed_dim>

以下标志可用：

• <dataset> <- cub200, cars196, online_products, in-shop, vehicle_id
• <loss> <- marginloss, triplet, npair, proxynca
• <sampling> <- distance, semihard, random, npair
• <arch> <- resnet50, googlenet
• <k_vals> <- 要评估的 Recall @ k 值列表，例如 1 2 4 8
• <embed_dim> <- 网络嵌入维度。默认值：ResNet50 为 128，GoogLeNet 为 512。

对于所有其他训练相关的参数（例如 batch-size（批大小）、num. training epochs（训练轮数）等），只需参考 Standard_Training.py 中的输入参数。

注意：如果希望为最终的线性嵌入层（linear embedding layer）使用不同的学习率（learning rate），需要将标志 --fc_lr_mul 设置为非零值（即 10，如各种实现中所做的那样）。

最后，要决定使用哪个 GPU（图形处理器）以及存储网络权重、样本恢复（sample recoveries）和指标（metrics）的训练文件夹名称，请设置：

python Standard_Training.py --gpu <gpu_id> --savename <name_of_training_run>

如果未设置 --savename，将基于开始日期选择一个默认名称。

如果希望简单地使用标准参数并获得接近文献结果的效果（或多或少取决于随机种子和整体训练调度），请参考 sample_training_runs.sh，其中包含一系列可执行的单行命令。

[3.] 关于可扩展性的实现说明：

要扩展或测试其他采样或损失方法，只需执行：

对于基于批次的采样（Batch-based Sampling）：
在 losses.py 中，添加采样方法，该方法应作用于一个批次（batch）以及相应的标签集，例如：

def new_sampling(self, batch, label, **additional_parameters): ...

如果需要与现有损失函数一起运行，此函数应返回一个包含相对于批次的索引的元组列表，例如对于返回三元组的采样方法：

return [(anchor_idx, positive_idx, negative_idx) for anchor_idx, positive_idx, negative_idx in zip(anchor_idxs, positive_idxs, negative_idxs)]

同时，别忘了在 Sampler.__init__() 中添加一个句柄。

对于特定数据的采样（Data-specific Sampling）：
要影响用于生成批次的数据样本，请在 datasets.py 中编辑 BaseTripletDataset。

对于新的损失函数（Loss Functions）：
只需添加一个继承自 torch.nn.Module（PyTorch 模块基类）的新类。参考其他损失变体以了解如何实现。通常，需要包含一个 Sampler 类的实例，该实例将在 forward()（前向传播）期间通过调用 self.sampler_instance.give(batch, labels, **additional_parameters) 提供采样的数据元组。最后，将损失函数包含在 loss_select() 函数中。参数可以通过字典表示法传递（参见其他示例），如果添加了可学习的参数，请将它们包含在 to_optim 列表中。

[4.] 存储的数据：

默认情况下，会保存以下文件：

Name_of_Training_Run
|  checkpoint.pth.tar   -> 包含网络 state-dict（状态字典）
|  hypa.pkl             -> 包含所有网络参数的 pickle（Python 序列化格式）文件
|                          可直接用于重新创建网络
| log_train_Base.csv    -> 记录的训练数据（CSV 格式）                     
| log_val_Base.csv      -> 记录的测试指标（CSV 格式）                    
| Parameter_Info.txt    -> 所有参数以可读文本文件形式存储
| InfoPlot_Base.svg     -> 训练/测试指标进展的图形化总结
| sample_recoveries.png -> 最佳验证权重下的样本恢复结果
|                          作为合理性测试

注意： 红色表示查询图像，绿色显示相应的最近邻。

注意： 摘要图中的标题显示整个运行过程中的最佳测试指标。

[5.] 附加说明：

最后，在检查相应运行时，以下几个标志可能值得关注：

--dist_measure: 如果设置，将计算每轮迭代后的平均类内距离（intraclass-distances）与平均类间距离（interclass distances）之比
                （通过质心距离（center-of-mass distances）度量），并存储/绘制该值
--grad_measure: 如果设置，将从嵌入层到最后一层卷积层（conv. layer）的平均（绝对）梯度存储在 Pickle-File（Pickle 文件）中。这可用于检查每次迭代期间特征的变化

更多详情，请参考 auxiliaries.py 中的相应类。

---

4. 结果

这些结果是通过运行 sample_training_runs.sh 中的相应命令获得的性能估计。请注意，学习率调度（learning rate scheduling）可能未完全优化，因此这些值仅应作为参考/预期，而非通过更多调整所能最终达到的性能。

另请注意，结果对所使用的随机种子（seed）有不可忽视的依赖性。

CUB200

架构	损失/采样	NMI	F1	Recall @ 1 -- 2 -- 4 -- 8
ResNet50	Margin/Distance	68.2	38.7	63.4 -- 74.9 -- 86.0 -- 90.4
ResNet50	Triplet/Softhard	66.2	35.5	61.2 -- 73.2 -- 82.4 -- 89.5
ResNet50	NPair/None	65.4	33.8	59.0 -- 71.3 -- 81.1 -- 88.8
ResNet50	ProxyNCA/None	68.1	38.1	64.0 -- 75.4 -- 84.2 -- 90.5

Cars196

架构	损失/采样	NMI	F1	Recall @ 1 -- 2 -- 4 -- 8
ResNet50	Margin/Distance	67.2	37.6	79.3 -- 87.1 -- 92.1 -- 95.4
ResNet50	Triplet/Softhard	64.4	32.4	75.4 -- 84.2 -- 90.1 -- 94.1
ResNet50	NPair/None	62.3	30.1	69.5 -- 80.2 -- 87.3 -- 92.1
ResNet50	ProxyNCA/None	66.3	35.8	80.0 -- 87.2 -- 91.8 -- 95.1

Online Products

架构	损失/采样	NMI	F1	Recall @ 1 -- 10 -- 100 -- 1000
ResNet50	Margin/Distance	89.6	34.9	76.1 -- 88.7 -- 95.1 -- 98.3
ResNet50	Triplet/Softhard	89.1	33.7	74.3 -- 87.6 -- 94.9 -- 98.5
ResNet50	NPair/None	88.8	31.1	70.9 -- 85.2 -- 93.8 -- 98.2

In-Shop Clothes

架构	损失/采样	NMI	F1	Recall @ 1 -- 10 -- 20 -- 30 -- 50
ResNet50	Margin/Distance	88.2	27.7	84.5 -- 96.1 -- 97.4 -- 97.9 -- 98.5
ResNet50	Triplet/Semihard	89.0	30.8	83.9 -- 96.3 -- 97.6 -- 98.4 -- 98.8
ResNet50	NPair/None	88.0	27.6	80.9 -- 95.0 -- 96.6 -- 97.5 -- 98.2

注意：

1. 关于 Vehicle-ID：由于测试集数量、训练集规模以及公开可访问性较低，暂不提供结果。
2. 关于 Online Products 和 In-Shop Clothes 的 ProxyNCA：由于类别数量过多，所需的代理数量对于有效训练而言过高（>10000 个代理）。

---

待办事项：

• 修复 requirements.txt 中的版本
• 添加实现的结果
• 完善注释
• 添加 Inception-BN
• 添加 Lifted Structure Loss

Deep-Metric-Learning-Baselines 快速上手指南

环境准备

• Python: 3.6+ (推荐使用 Miniconda)
• PyTorch: 1.0.0/1.0.1
• CUDA: 8.0 或 9.0
• GPU: 建议使用 NVIDIA GPU

安装步骤

1. 创建 Conda 环境并安装依赖

conda create -n dml python=3.6
conda activate dml
bash installer.sh

2. 准备数据集 将数据集下载并解压到 Datasets 目录，保持原始结构：

Datasets/
├── cub200/
├── cars196/
├── online_products/
├── in-shop/
└── vehicle_id/  # 可选

基本使用

启动训练

默认配置 (ResNet50 + Margin Loss + Distance Sampling on CUB200-2011):

python Standard_Training.py

自定义配置:

python Standard_Training.py \
  --dataset <dataset> \
  --loss <loss> \
  --sampling <sampling> \
  --arch <arch> \
  --gpu <gpu_id> \
  --savename <run_name>

核心参数说明

参数	可选值	说明
--dataset	cub200, cars196, online_products, in-shop, vehicle_id	数据集
--loss	marginloss, triplet, npair, proxynca	损失函数
--sampling	distance, semihard, random, npair	采样方法
--arch	resnet50, googlenet	网络架构
--embed_dim	整数	嵌入维度 (默认: ResNet50=128, GoogLeNet=512)
--fc_lr_mul	浮点数	嵌入层学习率倍数 (建议设为 10)
--k_vals	如 1 2 4 8	评估 Recall@k 的 k 值

常用示例

CARS196 + Triplet Loss:

python Standard_Training.py --dataset cars196 --loss triplet --sampling semihard --gpu 0 --savename triplet_cars

Online Products + N-Pair Loss:

python Standard_Training.py --dataset online_products --loss npair --sampling npair --embed_dim 512 --gpu 0

批量执行示例:

bash sample_training_runs.sh

训练输出

结果保存在 Training Results/<dataset>/<run_name>/:

• checkpoint.pth.tar: 模型权重
• log_train_Base.csv / log_val_Base.csv: 训练/验证日志
• InfoPlot_Base.svg: 指标可视化
• sample_recoveries.png: 样本检索效果图

性能参考 (CUB200-2011)

配置	Recall@1	Recall@2	Recall@4	Recall@8
Margin/Distance	63.4	74.9	86.0	90.4
Triplet/Softhard	61.2	73.2	82.4	89.5
NPair	59.0	71.3	81.1	88.8

注：结果可能因随机种子和调度策略略有差异。