PyTorch中的场景图基准测试

我们的论文《从有偏训练中无偏生成场景图》（Unbiased Scene Graph Generation from Biased Training）已被CVPR 2020接受并作口头报告。

最新更新

• 2020.06.23 增加无图约束平均召回率@K (ng-mR@K) 和无图约束零样本召回率@K (ng-zR@K) [链接]
• 2020.06.23 允许在自定义图像上进行场景图检测 (SGDet) [链接]
• 2020.07.21 将自定义图像上的场景图检测输出更改为json文件 [链接]
• 2020.07.21 可视化自定义图像的检测到的场景图 [链接]
• 待办：使用【背景排除推理】(Background-Exempted Inference) 来提升TDE场景图的质量

目录

1. 概述
2. 安装依赖
3. 准备数据集
4. 我们工具包的指标与结果
   • R@K、mR@K、zR@K、ng-R@K、ng-mR@K、ng-zR@K、A@K、S2G的解释
   • 输出格式
   • 报告的结果
5. Faster R-CNN预训练模型
6. 作为RoI_Head的场景图生成
7. 场景图生成的训练
8. 场景图生成的评估
9. 在您的自定义图像上检测场景图 :star2:
10. 可视化自定义图像的检测到的场景图 :star2:
11. 可能提升SGG性能的其他选项
12. 针对任何无偏任务的技巧与窍门
13. 常见问题
14. 引用

概述

该项目旨在构建一个新的场景图生成（SGG）代码库，同时也是论文《从有偏训练中无偏生成场景图》（Unbiased Scene Graph Generation from Biased Training）的PyTorch实现。此前广泛采用的SGG代码库neural-motifs已经脱离了Faster/Mask R-CNN的最新发展。因此，我决定基于著名的maskrcnn-benchmark项目构建一个场景图基准测试，并将关系预测定义为额外的roi_head。顺便说一下，得益于他们优雅的框架，这个代码库比之前的neural-motifs框架更加友好，也更容易阅读和修改以适应您自己的项目（至少我希望如此）。遗憾的是，在我开发这个项目时，detectron2尚未发布，但我认为我们可以把maskrcnn-benchmark视为一个更稳定、bug更少的版本，哈哈哈哈哈。此外，我还介绍了SGG中使用的所有新旧指标，并在METRICS.md中澄清了SGG指标中的两个常见误解，这些误解导致了一些论文中出现异常结果。

凭借maskrcnn-benchmark中最新的Faster R-CNN，该代码库通过使用两块1080ti显卡和批量大小8重新实现的VCTree模型，在SGCls和SGGen任务上达到了新的最先进水平的Recall@k（截至2020年2月16日）：

模型	SGGen R@20	SGGen R@50	SGGen R@100	SGCls R@20	SGCls R@50	SGCls R@100	PredCls R@20	PredCls R@50	PredCls R@100
VCTree	24.53	31.93	36.21	42.77	46.67	47.64	59.02	65.42	67.18

请注意，VCTree的所有结果都应该优于我们在《从有偏训练中无偏生成场景图》中报告的结果，因为在论文发表后我们对树结构网络进行了优化。

来自《从有偏训练中无偏生成场景图》的无偏SGG示意图

安装

请参阅INSTALL.md获取安装说明。

数据集

请参阅DATASET.md获取数据集预处理说明。

指标与结果 (重要)

我们工具包中的指标解释以及报告的结果均在METRICS.md中给出。

预训练模型

由于我们在论文《从有偏训练中无偏生成场景图》中测试了许多SGG模型，因此我不会在此处上传所有预训练的SGG模型。不过，您可以下载我们在论文中使用的【预训练Faster R-CNN】(https://1drv.ms/u/s!AmRLLNf6bzcir8xemVHbqPBrvjjtQg?e=hAhYCw)，这是整个训练过程中最耗时的步骤（当时使用了4块2080ti显卡）。至于SGG模型，您可以按照后续说明自行训练，每个SGG模型仅需2块GPU即可完成训练。训练结果应与[METRICS.md](METRICS.md)中报告的结果非常接近。

下载【Faster R-CNN模型】(https://1drv.ms/u/s!AmRLLNf6bzcir8xemVHbqPBrvjjtQg?e=hAhYCw)后，请将所有文件解压到目录`/home/username/checkpoints/pretrained_faster_rcnn`。要训练您自己的Faster R-CNN模型，请参阅下一节。

上述预训练的Faster R-CNN模型在VG训练集、验证集和测试集上的mAp分别为38.52、26.35和28.14。

替代链接

感谢Catchip的赞助。由于OneDrive链接在中国大陆可能会失效，我们还提供了以下替代链接，用于访问所有预训练模型和数据集标注：

链接1(Baidu)：https://pan.baidu.com/s/1oyPQBDHXMQ5Tsl0jy5OzgA 提取码：1234

链接2(Weiyun): https://share.weiyun.com/ViTWrFxG

Faster R-CNN 预训练

可以使用以下命令来训练您自己的 Faster R-CNN 模型：

CUDA_VISIBLE_DEVICES=0,1,2,3 python -m torch.distributed.launch --master_port 10001 --nproc_per_node=4 tools/detector_pretrain_net.py --config-file "configs/e2e_relation_detector_X_101_32_8_FPN_1x.yaml" SOLVER.IMS_PER_BATCH 8 TEST.IMS_PER_BATCH 4 DTYPE "float16" SOLVER.MAX_ITER 50000 SOLVER.STEPS "(30000, 45000)" SOLVER.VAL_PERIOD 2000 SOLVER.CHECKPOINT_PERIOD 2000 MODEL.RELATION_ON False OUTPUT_DIR /home/kaihua/checkpoints/pretrained_faster_rcnn SOLVER.PRE_VAL False

其中 CUDA_VISIBLE_DEVICES 和 --nproc_per_node 分别表示您使用的 GPU 编号和 GPU 数量，--config-file 表示我们所使用的配置文件，您可以在该文件中调整其他参数。SOLVER.IMS_PER_BATCH 和 TEST.IMS_PER_BATCH 分别是训练和测试的批次大小，DTYPE "float16" 启用由 APEX 支持的自动混合精度，SOLVER.MAX_ITER 是最大迭代次数，SOLVER.STEPS 是学习率衰减的步长，SOLVER.VAL_PERIOD 和 SOLVER.CHECKPOINT_PERIOD 分别是验证和保存检查点的周期，MODEL.RELATION_ON 表示是否开启关系头（由于这是仅针对 Faster R-CNN 的预训练阶段，因此关闭关系头），OUTPUT_DIR 是用于保存检查点和日志的输出目录（例如 /home/username/checkpoints/pretrained_faster_rcnn），SOLVER.PRE_VAL 表示是否在训练前进行验证。

场景图生成作为 RoI_Head

为了标准化场景图生成任务，我将其定义为一个 RoI_Head。参考其他 RoI_Head（如 box_head）的设计，我将大部分 SGG 相关代码放在 maskrcnn_benchmark/modeling/roi_heads/relation_head 目录下，其调用顺序如下所示：

进行场景图生成的训练

共有 三种标准协议：(1) 谓词分类 (PredCls)：以真实边界框和标签作为输入；(2) 场景图分类 (SGCls)：使用没有标签的真实边界框；(3) 场景图检测 (SGDet)：从零开始检测场景图。我们通过两个开关 MODEL.ROI_RELATION_HEAD.USE_GT_BOX 和 MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL 来选择不同的协议。

对于 谓词分类 (PredCls)，需要设置：

MODEL.ROI_RELATION_HEAD.USE_GT_BOX True MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL True

对于 场景图分类 (SGCls)：

MODEL.ROI_RELATION_HEAD.USE_GT_BOX True MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False

对于 场景图检测 (SGDet)：

MODEL.ROI_RELATION_HEAD.USE_GT_BOX False MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False

预定义模型

我们将各种 SGG 模型抽象为 roi_heads/relation_head/roi_relation_predictors.py 文件中的不同 relation-head predictors，这些预测器与 Faster R-CNN 的主干网络和关系头特征提取器无关。要选择预定义的模型，可以使用 MODEL.ROI_RELATION_HEAD.PREDICTOR。

对于 Neural-MOTIFS 模型：

MODEL.ROI_RELATION_HEAD.PREDICTOR MotifPredictor

对于 迭代消息传递 (IMP) 模型（注意，在 SGCls 中应将 SOLVER.BASE_LR 改为 0.001，否则模型无法收敛）：

MODEL.ROI_RELATION_HEAD.PREDICTOR IMPPredictor

对于 VCTree 模型：

MODEL.ROI_RELATION_HEAD.PREDICTOR VCTreePredictor

对于我们预定义的 Transformer 模型（注意，Transformer 模型需要将 SOLVER.BASE_LR 改为 0.001，SOLVER.SCHEDULE.TYPE 改为 WarmupMultiStepLR，SOLVER.MAX_ITER 改为 16000，SOLVER.IMS_PER_BATCH 改为 16，SOLVER.STEPS 改为 (10000, 16000)。该模型由 Jiaxin Shi 提供）：

MODEL.ROI_RELATION_HEAD.PREDICTOR TransformerPredictor

对于 Unbiased-Causal-TDE 模型：

MODEL.ROI_RELATION_HEAD.PREDICTOR CausalAnalysisPredictor

默认设置位于 configs/e2e_relation_X_101_32_8_FPN_1x.yaml 和 maskrcnn_benchmark/config/defaults.py 中。优先级顺序为：命令 > yaml > defaults.py。

自定义您的模型

如果您想自定义模型，可以参考 maskrcnn-benchmark/modeling/roi_heads/relation_head/model_XXXXX.py 和 maskrcnn-benchmark/modeling/roi_heads/relation_head/utils_XXXXX.py。同时，您还需要在 maskrcnn-benchmark/modeling/roi_heads/relation_head/roi_relation_predictors.py 中添加相应的 nn.Module。有时，您可能还需要通过 maskrcnn-benchmark/modeling/roi_heads/relation_head/relation_head.py 修改模块的输入和输出。

关于 偏置训练下的无偏场景图生成 中提出的因果 TDE

对于无偏因果 TDE，还有一些额外的参数需要了解。MODEL.ROI_RELATION_HEAD.CAUSAL.EFFECT_TYPE 用于在推理（测试）阶段选择因果效应分析类型，其中“none”表示原始似然，“TDE”表示总直接效应，“NIE”表示自然间接效应，“TE”表示总效应。MODEL.ROI_RELATION_HEAD.CAUSAL.FUSION_TYPE 有两个选项：“sum”或“gate”。由于无偏因果 TDE 分析与具体模型无关，我们支持 Neural-MOTIFS、VCTree 和 VTransE。MODEL.ROI_RELATION_HEAD.CAUSAL.CONTEXT_LAYER 用于选择参与无偏因果分析的模型，有三个选项：motifs、vctree、vtranse。

需要注意的是，在训练过程中，我们始终将 MODEL.ROI_RELATION_HEAD.CAUSAL.EFFECT_TYPE 设置为“none”，因为因果效应分析仅适用于推理/测试阶段。

训练命令示例

训练示例 1：（PreCls，Motif 模型）

CUDA_VISIBLE_DEVICES=0,1 python -m torch.distributed.launch --master_port 10025 --nproc_per_node=2 tools/relation_train_net.py --config-file "configs/e2e_relation_X_101_32_8_FPN_1x.yaml" MODEL.ROI_RELATION_HEAD.USE_GT_BOX True MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL True MODEL.ROI_RELATION_HEAD.PREDICTOR MotifPredictor SOLVER.IMS_PER_BATCH 12 TEST.IMS_PER_BATCH 2 DTYPE "float16" SOLVER.MAX_ITER 50000 SOLVER.VAL_PERIOD 2000 SOLVER.CHECKPOINT_PERIOD 2000 GLOVE_DIR /home/kaihua/glove MODEL.PRETRAINED_DETECTOR_CKPT /home/kaihua/checkpoints/pretrained_faster_rcnn/model_final.pth OUTPUT_DIR /home/kaihua/checkpoints/motif-precls-exmp

其中 GLOVE_DIR 是用于保存 Glove 初始化的目录，MODEL.PRETRAINED_DETECTOR_CKPT 是您想要加载的预训练 Faster R-CNN 模型，OUTPUT_DIR 是用于保存检查点和日志的输出目录。由于我们为 SGG 使用了 WarmupReduceLROnPlateau 学习率调度器，因此不再需要设置 SOLVER.STEPS。

训练示例 2：（SGCls，Causal，TDE，SUM 融合，MOTIFS 模型）

CUDA_VISIBLE_DEVICES=0,1 python -m torch.distributed.launch --master_port 10026 --nproc_per_node=2 tools/relation_train_net.py --config-file "configs/e2e_relation_X_101_32_8_FPN_1x.yaml" MODEL.ROI_RELATION_HEAD.USE_GT_BOX True MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False MODEL.ROI_RELATION_HEAD.PREDICTOR CausalAnalysisPredictor MODEL.ROI_RELATION_HEAD.CAUSAL.EFFECT_TYPE none MODEL.ROI_RELATION_HEAD.CAUSAL.FUSION_TYPE sum MODEL.ROI_RELATION_HEAD.CAUSAL.CONTEXT_LAYER motifs  SOLVER.IMS_PER_BATCH 12 TEST.IMS_PER_BATCH 2 DTYPE "float16" SOLVER.MAX_ITER 50000 SOLVER.VAL_PERIOD 2000 SOLVER.CHECKPOINT_PERIOD 2000 GLOVE_DIR /home/kaihua/glove MODEL.PRETRAINED_DETECTOR_CKPT /home/kaihua/checkpoints/pretrained_faster_rcnn/model_final.pth OUTPUT_DIR /home/kaihua/checkpoints/causal-motifs-sgcls-exmp

评估

测试命令示例

测试示例 1：（PreCls，Motif 模型）

CUDA_VISIBLE_DEVICES=0 python -m torch.distributed.launch --master_port 10027 --nproc_per_node=1 tools/relation_test_net.py --config-file "configs/e2e_relation_X_101_32_8_FPN_1x.yaml" MODEL.ROI_RELATION_HEAD.USE_GT_BOX True MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL True MODEL.ROI_RELATION_HEAD.PREDICTOR MotifPredictor TEST.IMS_PER_BATCH 1 DTYPE "float16" GLOVE_DIR /home/kaihua/glove MODEL.PRETRAINED_DETECTOR_CKPT /home/kaihua/checkpoints/motif-precls-exmp OUTPUT_DIR /home/kaihua/checkpoints/motif-precls-exmp

测试示例 2：（SGCls，Causal，TDE，SUM 融合，MOTIFS 模型）

CUDA_VISIBLE_DEVICES=0 python -m torch.distributed.launch --master_port 10028 --nproc_per_node=1 tools/relation_test_net.py --config-file "configs/e2e_relation_X_101_32_8_FPN_1x.yaml" MODEL.ROI_RELATION_HEAD.USE_GT_BOX True MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False MODEL.ROI_RELATION_HEAD.PREDICTOR CausalAnalysisPredictor MODEL.ROI_RELATION_HEAD.CAUSAL.EFFECT_TYPE TDE MODEL.ROI_RELATION_HEAD.CAUSAL.FUSION_TYPE sum MODEL.ROI_RELATION_HEAD.CAUSAL.CONTEXT_LAYER motifs  TEST.IMS_PER_BATCH 1 DTYPE "float16" GLOVE_DIR /home/kaihua/glove MODEL.PRETRAINED_DETECTOR_CKPT /home/kaihua/checkpoints/causal-motifs-sgcls-exmp OUTPUT_DIR /home/kaihua/checkpoints/causal-motifs-sgcls-exmp

预训练的 Causal MOTIFS-SUM 模型示例

SGDet/SGCls/PredCls 上的预训练 Causal MOTIFS-SUM 模型示例（批量大小 12）：(SGDet 下载), (SGCls 下载), (PredCls 下载)

对应结果（论文中使用的原始模型已丢失，这些是新生成的模型，因此结果存在一些波动。更多结果请参见 报告结果）：

模型	R@20	R@50	R@100	mR@20	mR@50	mR@100	zR@20	zR@50	zR@100
MOTIFS-SGDet-none	25.42	32.45	37.26	4.36	5.83	7.08	0.02	0.08	0.24
MOTIFS-SGDet-TDE	11.92	16.56	20.15	6.58	8.94	10.99	1.54	2.33	3.03
MOTIFS-SGCls-none	36.02	39.25	40.07	6.50	8.02	8.51	1.06	2.18	3.07
MOTIFS-SGCls-TDE	20.47	26.31	28.79	9.80	13.21	15.06	1.91	2.95	4.10
MOTIFS-PredCls-none	59.64	66.11	67.96	11.46	14.60	15.84	5.79	11.02	14.74
MOTIFS-PredCls-TDE	33.38	45.88	51.25	17.85	24.75	28.70	8.28	14.31	18.04

SGDet 在自定义图像上的应用

请注意，自定义图像上的评估仅适用于 SGDet 模型，因为 PredCls 和 SGCls 模型需要额外的标注边界框信息。要在您自己的图像上检测场景图并将其保存为 JSON 文件，您需要打开 TEST.CUSTUM_EVAL 开关，并在 TEST.CUSTUM_PATH 中指定包含自定义图像的文件夹路径（或包含图像路径列表的 JSON 文件）。仅允许使用 JPG 格式的文件。输出将被保存为 custom_prediction.json，位于指定的 DETECTED_SGG_DIR 目录中。

测试示例 1：(SGDet，因果 TDE，MOTIFS 模型，SUM 融合) (检查点)

CUDA_VISIBLE_DEVICES=0 python -m torch.distributed.launch --master_port 10027 --nproc_per_node=1 tools/relation_test_net.py --config-file "configs/e2e_relation_X_101_32_8_FPN_1x.yaml" MODEL.ROI_RELATION_HEAD.USE_GT_BOX False MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False MODEL.ROI_RELATION_HEAD.PREDICTOR CausalAnalysisPredictor MODEL.ROI_RELATION_HEAD.CAUSAL.EFFECT_TYPE TDE MODEL.ROI_RELATION_HEAD.CAUSAL.FUSION_TYPE sum MODEL.ROI_RELATION_HEAD.CAUSAL.CONTEXT_LAYER motifs TEST.IMS_PER_BATCH 1 DTYPE "float16" GLOVE_DIR /home/kaihua/glove MODEL.PRETRAINED_DETECTOR_CKPT /home/kaihua/checkpoints/causal-motifs-sgdet OUTPUT_DIR /home/kaihua/checkpoints/causal-motifs-sgdet TEST.CUSTUM_EVAL True TEST.CUSTUM_PATH /home/kaihua/checkpoints/custom_images DETECTED_SGG_DIR /home/kaihua/checkpoints/your_output_path

测试示例 2：(SGDet，原始，MOTIFS 模型，SUM 融合) (相同检查点)

CUDA_VISIBLE_DEVICES=0 python -m torch.distributed.launch --master_port 10027 --nproc_per_node=1 tools/relation_test_net.py --config-file "configs/e2e_relation_X_101_32_8_FPN_1x.yaml" MODEL.ROI_RELATION_HEAD.USE_GT_BOX False MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False MODEL.ROI_RELATION_HEAD.PREDICTOR CausalAnalysisPredictor MODEL.ROI_RELATION_HEAD.CAUSAL.EFFECT_TYPE none MODEL.ROI_RELATION_HEAD.CAUSAL.FUSION_TYPE sum MODEL.ROI_RELATION_HEAD.CAUSAL.CONTEXT_LAYER motifs TEST.IMS_PER_BATCH 1 DTYPE "float16" GLOVE_DIR /home/kaihua/glove MODEL.PRETRAINED_DETECTOR_CKPT /home/kaihua/checkpoints/causal-motifs-sgdet OUTPUT_DIR /home/kaihua/checkpoints/causal-motifs-sgdet TEST.CUSTUM_EVAL True TEST.CUSTUM_PATH /home/kaihua/checkpoints/custom_images DETECTED_SGG_DIR /home/kaihua/checkpoints/your_output_path

输出是一个 JSON 文件。对于每张图像，场景图信息以字典形式保存，包含 bbox（已排序）、bbox_labels（已排序）、bbox_scores（已排序）、rel_pairs（已排序）、rel_labels（已排序）、rel_scores（已排序）以及 rel_all_scores（已排序），其中 rel_all_scores 提供了每对物体的所有 51 种谓词的概率。数据集信息则保存为 custom_data_info.json，位于相同的 DETECTED_SGG_DIR 目录中。

可视化自定义图像的检测到的场景图

要可视化自定义图像的检测到的场景图，您可以按照以下 Jupyter 笔记进行操作：visualization/3.visualize_custom_SGDet.jpynb。我们的可视化代码的输入是 DETECTED_SGG_DIR 中的 custom_prediction.json 和 custom_data_info.json。如果您成功运行了上述自定义 SGDet 指令，这些文件将会自动生成。请注意，可能会出现过多的无关紧要的边界框和关系，因此您可以通过调整参数 box_topk 和 rel_topk 来选择前 k 个边界框和谓词，从而获得更清晰的场景图。

其他可能提升 SGG 效果的选项

• 对于某些模型（并非全部），开启或关闭 MODEL.ROI_RELATION_HEAD.POOLING_ALL_LEVELS 会显著影响谓词预测的性能。例如，关闭该选项可以提升 VCTree 的 PredCls 性能，但不会改善相应的 SGCls 和 SGGen。对于 VCTree 的报告结果，我们像其他模型一样，在所有三种协议中都将其保持开启状态。

• 对于某些模型（并非全部），Learning to Count Object 提出的一种奇特融合方法能够显著提升效果，其形式为 f(x1, x2) = ReLU(x1 + x2) - (x1 - x2)**2。这种方法可用于在 roi_heads/relation_head/roi_relation_predictors.py 中结合主体和客体特征。目前，大多数模型只是简单地将它们拼接在一起，即 torch.cat((head_rep, tail_rep), dim=-1)。

• 更不用说模型中的隐藏维度，例如 MODEL.ROI_RELATION_HEAD.CONTEXT_HIDDEN_DIM。由于时间有限，我们并未在此项目中充分探索所有设置。因此，如果您仅仅通过调整其中一个超参数就提升了我们的结果，我也不会感到意外。

针对从有偏训练中得到的无偏任务 X 的技巧与窍门

反事实推理不仅适用于 SGG。事实上，我的同事 Yulei 发现，反事实因果推理在 无偏 VQA 中也具有巨大潜力。我们相信，这种反事实推理同样可以应用于许多存在显著偏差的推理任务。其基本原理是让模型运行两次（一次生成原始输出，另一次生成干预后的输出），然后用后者减去应被剔除的有偏先验，从而得到最终的无偏预测。不过，您需要注意以下三点：

• 最重要的是因果图。您需要找到正确的因果图，并识别出导致有偏预测的可辨识分支。如果因果图不正确，后续的一切都将毫无意义。需要注意的是，因果图并不是对现有网络的总结（而是指导网络构建的原则），您应当根据因果图来修改网络结构，而不是反过来。
• 对于那些在因果图中有多个输入分支的节点，选择合适的融合函数至关重要。我们尝试过多种融合函数，最终发现 SUM 融合和 GATE 融合始终表现稳定。而诸如逐元素相乘之类的融合方式在大多数情况下并不适用于 TDE 分析，因为来自不同分支的因果影响已经无法线性分离，也就不再具备可辨识的“影响力”。
• 对于那些在因果图中有多个输入分支的最终预测，可能还需要为每个分支添加辅助损失，以稳定各独立分支的因果影响力。因为当这些分支的收敛速度不同时，较慢的分支很容易被视为依赖于最快或最稳定的分支的微不足道的小浮动值。辅助损失能够让各个分支拥有独立且平等的影响力。

常见问题解答：

1. 问： 无法加载给定的检查点。 答： 要加载的模型是基于 OUTPUT_DIR 路径下的 last_checkpoint 文件。如果无法加载给定的预训练检查点，很可能是由于 last_checkpoint 文件中仍然保存的是您本地工作站的路径，而不是您当前环境的路径。

2. 问： 在 assert len(fns) == 108073 处出现断言错误。 答： 如果您正在使用 VG 数据集，这很可能是由于 maskrcnn_benchmark/config/paths_catalog.py 文件中 DATASETS（数据路径）配置错误导致的。如果您使用的是自定义数据集，可以直接注释掉这些断言语句。

3. 问： 在 model_motifs.py 中出现 l_batch == 1 的断言错误。 答： 原始的 MOTIFS 代码仅支持在单 GPU 上进行评估。由于我重新实现的 MOTIFS 是基于他们的代码，因此保留了这一断言，以确保不会引发任何意外错误。

引用

如果您认为本项目对您的研究有所帮助，请在您的论文或出版物中引用我们的项目或相关论文。

@misc{tang2020sggcode,
title = {基于 PyTorch 的场景图生成代码库},
author = {唐凯华},
year = {2020},
note = {\url{https://github.com/KaihuaTang/Scene-Graph-Benchmark.pytorch}},
}

@inproceedings{tang2018learning,
  title={学习为视觉上下文构建动态树结构},
  author={唐凯华、张汉旺、吴宝元、罗文翰、刘伟},
  booktitle= "计算机视觉与模式识别会议",
  year={2019}
}

@inproceedings{tang2020unbiased,
  title={从有偏训练中无偏地生成场景图},
  author={唐凯华、牛宇雷、黄建强、史佳欣、张汉旺},
  booktitle= "计算机视觉与模式识别会议",
  year={2020}
}

Scene-Graph-Benchmark.pytorch 快速上手指南

本指南基于 PyTorch 实现，旨在帮助开发者快速搭建场景图生成（SGG）基准环境，复现 CVPR 2020 Oral 论文《Unbiased Scene Graph Generation from Biased Training》中的成果。

1. 环境准备

在开始之前，请确保满足以下系统和依赖要求：

• 操作系统: Linux (推荐 Ubuntu)
• Python: 3.7
• PyTorch: 1.2.0 (需匹配对应的 CUDA 版本)
• GPU: 支持 CUDA 的 NVIDIA 显卡 (训练 Faster R-CNN 预训练模型建议多卡，如 4x 2080Ti；训练 SGG 模型仅需 2x 1080Ti)
• 核心依赖:
  • maskrcnn-benchmark: 本项目基于此框架构建。
  • APEX: 用于启用混合精度训练 (float16)，加速训练过程。
  • 其他标准库：numpy, scipy, opencv-python, yacs 等。

注意：详细的环境安装步骤（包括 CUDA/cuDNN 配置及依赖包安装命令）请参考项目根目录下的 INSTALL.md 文件。

2. 安装步骤

2.1 克隆代码库

git clone https://github.com/KaihuaTang/Scene-Graph-Benchmark.pytorch.git
cd Scene-Graph-Benchmark.pytorch

2.2 安装依赖

请严格按照 INSTALL.md 中的指示安装 maskrcnn-benchmark 及其依赖。通常涉及以下步骤（具体版本请以官方文档为准）：

# 示例：安装 apex (需根据实际 CUDA 版本调整)
git clone https://github.com/NVIDIA/apex
cd apex
pip install -v --no-cache-dir ./ --global-option="--cpp_ext" --global-option="--cuda_ext"
cd ..

2.3 下载预训练模型与数据集

由于原链接可能在大陆访问受限，优先推荐使用国内镜像源下载必要的资源。

预训练 Faster R-CNN 模型（训练 SGG 的基础，最耗时步骤）：

• 百度网盘: 下载链接 (提取码：1234)
• 微云: 下载链接

下载后，将解压后的文件放置于指定目录（请根据实际用户名修改路径）：

# 假设下载的文件解压后包含模型权重
mv <downloaded_files> /home/username/checkpoints/pretrained_faster_rcnn

数据集准备： 本项目主要使用 Visual Genome (VG) 数据集。请参考 DATASET.md 进行数据预处理和标注文件的整理。

3. 基本使用

本项目将场景图生成定义为 Faster R-CNN 的一个 RoI_Head。使用前需明确三种标准协议：

1. PredCls (谓词分类): 输入为真值框和真值标签。
2. SGCls (场景图分类): 输入为真值框，无标签。
3. SGDet (场景图检测): 从零开始检测（最常用，完全端到端）。

3.1 训练 Faster R-CNN (可选)

如果未使用提供的预训练模型，可自行训练：

CUDA_VISIBLE_DEVICES=0,1,2,3 python -m torch.distributed.launch --master_port 10001 --nproc_per_node=4 tools/detector_pretrain_net.py --config-file "configs/e2e_relation_detector_X_101_32_8_FPN_1x.yaml" SOLVER.IMS_PER_BATCH 8 TEST.IMS_PER_BATCH 4 DTYPE "float16" SOLVER.MAX_ITER 50000 SOLVER.STEPS "(30000, 45000)" SOLVER.VAL_PERIOD 2000 SOLVER.CHECKPOINT_PERIOD 2000 MODEL.RELATION_ON False OUTPUT_DIR /home/kaihua/checkpoints/pretrained_faster_rcnn SOLVER.PRE_VAL False

3.2 训练场景图生成模型 (SGG)

通过修改命令行参数选择模型架构和任务协议。

示例：使用 VCTree 模型进行场景图检测 (SGDet) 训练

CUDA_VISIBLE_DEVICES=0,1 python -m torch.distributed.launch --master_port 10002 --nproc_per_node=2 tools/relation_train_net.py --config-file "configs/e2e_relation_X_101_32_8_FPN_1x.yaml" MODEL.ROI_RELATION_HEAD.USE_GT_BOX False MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False MODEL.ROI_RELATION_HEAD.PREDICTOR VCTreePredictor SOLVER.IMS_PER_BATCH 8 DTYPE "float16" OUTPUT_DIR /home/username/checkpoints/vctree_sgdet

常用模型选择参数 (MODEL.ROI_RELATION_HEAD.PREDICTOR):

• MotifPredictor: Neural-MOTIFS 模型
• IMPPredictor: IMP 模型 (SGCls 任务需调整学习率为 0.001)
• VCTreePredictor: VCTree 模型 (默认推荐)
• TransformerPredictor: Transformer 模型 (需调整学习率、迭代次数等超参)
• CausalAnalysisPredictor: 无偏因果 TDE 模型 (论文核心贡献)

协议切换开关:

• PredCls: MODEL.ROI_RELATION_HEAD.USE_GT_BOX True + MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL True
• SGCls: MODEL.ROI_RELATION_HEAD.USE_GT_BOX True + MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False
• SGDet: MODEL.ROI_RELATION_HEAD.USE_GT_BOX False + MODEL.ROI_RELATION_HEAD.USE_GT_OBJECT_LABEL False

3.3 在自定义图片上检测场景图 (SGDet)

项目支持对用户上传的自定义图片进行场景图检测，并输出 JSON 结果或可视化图像。

执行检测: 确保已训练好 SGDet 模型，运行推理脚本（具体脚本名参考项目最新更新，通常为 tools/relation_test_net.py 或特定 demo 脚本），并将输出格式设置为 JSON。

可视化结果: 利用内置工具将检测到的场景图绘制在图片上，直观展示物体间的关系三元组。

提示: 更多高级用法、指标解释（R@K, mR@K, ng-R@K 等）及自定义模型开发指南，请参阅项目根目录下的 METRICS.md 及相关源码注释。