GluonCV 中 COOT 模型的训练全指南:视频-文本层次化表示学习的协作式 Transformer 实战
GluonCV 中 COOT 模型的训练全指南:视频-文本层次化表示学习的协作式 Transformer 实战
导读
COOT(Cooperative Hierarchical Transformer)是发表在 NeurIPS 2020 上的视频-文本表示学习模型,它针对真实视频-文本任务中"帧与词、片段与句子、视频与段落"等多层粒度语义问题,通过协作式层次 Transformer 建模不同粒度、不同模态之间的交互。GluonCV 仓库在 scripts/vision-language/video-language/coot/ 目录下提供了完整的 PyTorch 训练脚本与配置文件,并配套实现了数据加载、模型定义、损失函数与检索评估全链路。读完本文,你将掌握 COOT 的三大核心组件原理、预计算特征的下载与组织方式、youcook2.yaml 配置文件的全部字段含义,以及如何启动训练并解读 Paragraph->Video 与 Sentence->Clip 两类检索指标。
COOT 方法概述:层次化视频-文本表示学习
视频-文本任务天然存在多粒度对应关系:视频帧对应文本单词,视频片段(clip)对应句子,整段视频对应段落(paragraph)。COOT 论文(见仓库 README 引用的 arXiv 论文 2011.00597,作者为 Simon Ging、Mohammadreza Zolfaghari、Hamed Pirsiavash 与 Thomas Brox)提出用一个协作式层次 Transformer 同时建模粒度内(intra-level)与粒度间(inter-level)的语义关系,其方法由三大组件构成:
- 注意力感知特征聚合层(Attention-aware Feature Aggregation Layer):利用局部时间上下文(例如片段内部)聚合低层特征;
- 上下文 Transformer(Contextual Transformer):学习低层与高层语义之间的交互(例如片段-视频、句子-段落);
- 跨模态循环一致性损失(Cross-modal Cycle-Consistency Loss):将视频与文本两个模态在层次结构上对齐。
论文声称该方法在多个基准上以较少参数量取得有竞争力的效果——这是论文表述,仓库 README 中的复现结果表可作为量化参考(见下文"预期结果")。
仓库中的模型实现:四个 Transformer 的协作
在 GluonCV 中,COOT 模型定义在 coot_model.py 中。类 MultiModalTransformer 由四个独立的 Transformer 模块组成:
| 模块 | 作用 | 输入特征 |
|---|---|---|
video_pooler |
将帧级特征聚合为片段级特征、片段级特征聚合为视频级上下文 | 视频帧特征(FEATURE_DIM 维) |
video_sequencer |
对片段嵌入序列建模,输出视频嵌入 | VIDEO_POOLER.OUTPUT_DIM 维 |
text_pooler |
将词/句特征聚合为句子/段落级特征 | BERT 文本特征(TEXT_ENCODER.FEATURE_DIM 维) |
text_sequencer |
对句子嵌入序列建模,输出段落嵌入 | TEXT_POOLER.OUTPUT_DIM 维 |
模型注册在 model_zoo.py 中,键名为 multimodaltransformer_coot,训练脚本通过 get_model(cfg) 按配置中的 CONFIG.MODEL.NAME(默认 MultiModalTransformer_COOT,小写匹配)实例化。
MultiModalTransformer.encode_video 的调用链清晰体现了层次结构:先用 video_pooler 对整段视频的帧序列做池化得到视频全局上下文(vid_context);再对每个片段(clip)的帧序列分别池化得到片段嵌入;随后在 VIDEO_SEQUENCER.USE_CONTEXT=True 时,把视频上下文作为 attention 的 context 注入,由 video_sequencer 对片段序列建模得到最终视频嵌入。encode_paragraph 对文本侧执行完全对称的流程(段落上下文 -> 句子嵌入 -> 段落嵌入)。
Transformer 内部结构
Transformer 类(coot_model.py)的构造包含:
- 输入归一化:自定义
LayerNormalization; - 可选输入全连接层:
INPUT_FC=True时使用Linear + GELU将特征投影到INPUT_FC_OUTPUT_DIM; - 位置编码:
PositionalEncoding(正弦-余弦形式,max_len=1000); - Transformer 编码器:由
TransformerEncoderLayer(多头自注意力 + 前馈网络,均带残差与层归一化)堆叠而成,注意力实现为缩放点积注意力(MultiHeadAttention); - 上下文编码器:
USE_CONTEXT=True时额外堆叠一层tf_context,用于注入高层语义; - 池化器:通过
parse_pooler选择atn(注意力池化AtnPool)、avg(AvgPool)或max(MaxPool)。
注意力池化 AtnPool(coot_model.py)用两阶段线性投影为每个 token 学习软权重,再对特征加权求和得到固定维度表示;当 USE_CONTEXT=True 时,池化结果还会与上下文 attention 输出拼接。
损失函数:对齐 + 循环一致性
训练使用两类损失(定义在 loss.py):
- MaxMarginRankingLoss:即论文 Eq.1 的最大间隔排序损失,计算余弦相似度矩阵,拉近正样本对、惩罚负样本对,margin 默认 0.2;
- CycleConsistencyCootLoss:即论文 Eq.8 的跨模态循环一致性损失,通过 soft nearest neighbor 在"片段->句子->片段"与"句子->片段->句子"两个方向做循环对齐,输出 clip-to-clip 与 sentence-to-sentence 两项损失。
在 coot_utils.py 的 compute_constrastive_loss 中,总对齐损失由四部分相加:视频-段落、片段-句子(权重 LOSS_CONTRASTIVE_CLIP_W)、全局上下文(视频上下文-段落上下文)以及同模态内部的自对齐正则项;compute_cmc_loss 则按权重 LOSS_CYCLE_CONS_W 累加循环一致性损失。训练主循环位于 task_utils/coot.py 的 train_coot 中,先 forward 得到 vid_emb/clip_emb/par_emb/sent_emb,再组合两类损失反向传播。
仓库中的代码与配置结构
COOT 模块在仓库中由以下文件协同工作:
| 文件 | 职责 |
|---|---|
| train_pytorch.py | 训练入口脚本(解析 --config-file、构建模型/数据/优化器、执行训练验证循环) |
| configuration/youcook2.yaml | Youcook2 数据集完整训练配置 |
| coot_model.py | 模型定义(MultiModalTransformer 及 Transformer 组件) |
| dataloader.py | 数据加载(HDF5 特征、BERT 文本、层次化 collate) |
| coot_utils.py | 工具函数(路径构造、帧采样、检索指标、损失组合) |
| task_utils/coot.py | 训练/验证任务循环 |
| loss.py | 对齐与循环一致性损失 |
| engine/config/coot.py | COOT 默认配置(yacs CfgNode) |
其中默认配置通过 engine/config/init.py 中以 "coot" 为键注册,训练脚本调用 get_cfg_defaults(name='coot') 后与 YAML 文件 merge。
环境准备与依赖安装
仓库 README 要求本机安装 Python>=3.6,其余依赖遵循 GluonCV 的整体安装指引。从源码结构看,训练所需的核心依赖包括:torch、h5py(读取 HDF5 特征文件,见 dataloader.py)、yacs(配置解析)、tensorboardX(训练日志)以及 numpy/tqdm 等常用库。COOT 的代码位于仓库的 gluoncv.torch 包内,因此需要以仓库根目录为工作区(或安装 gluoncv 包)后,以模块方式运行训练脚本。
下载预计算特征:Youcook2 数据集
COOT 训练不需要原始视频帧,而是使用预计算好的特征文件。仓库 README 说明:用 wget 下载以下 Youcook2 数据,并全部放入同一文件夹(例如 /data/youcook2):
| 文件 | 内容 | 作用 |
|---|---|---|
meta_100m.json |
视频元数据(分段信息、帧数、标注 split、叙述文本) | 构造数据集,区分 train/val |
video_feat_100m.h5 |
视频特征(HowTo100M 特征,键为视频 ID) | 帧级视频特征输入 |
text_default.h5 |
文本特征(BERT 特征,键为视频 ID) | 段落/句子级文本特征 |
text_lens_default.json |
文本长度信息 | 将段落特征按句子长度切分 |
下载地址见原 README 中的 Link 字段;下载完成后,将文件夹路径写入配置文件中的 DATA_PATH 字段(例如 DATA_PATH: /data/youcook2)。
从源码看,这四个文件名的命名约定并非随意:create_dataloader_path(coot_utils.py)按 meta_{video_feature_name}.json、video_feat_{video_feature_name}.h5、text_{text_feature_name}.h5、text_lens_{text_feature_name}.json 的规则拼接路径,其中 video_feature_name 来自配置中的 COOT_DATA.FEATURE(Youcook2 示例为 '100m',即 HowTo100M 特征),text_feature_name 固定为 'default'(BERT 文本特征)。
数据加载与层次化组织
VideoDatasetFeatures 是核心数据集类:
- 读入
meta_100m.json,按split字段筛出训练/验证视频 ID; - 视频特征由
Youcook2VideoFeatureLoader从 HDF5 加载,文本特征由BertTextFeatureLoader加载;preload=True时通过make_shared_array(coot_utils.py)把特征转成共享内存数组以加速多进程 DataLoader; __getitem__返回层次化样本:整段视频帧(vid_frames)、每片段帧(clip_frames_list)、整段 BERT 特征(par_cap_vectors)、按句子长度切分后的句子特征(sent_cap_vectors_list)以及对应的长度与叙述文本分词结果;collate_fn(dataloader.py)把变长序列补齐成 batch 张量并生成 mask,供 Transformer 使用;- 帧采样由
compute_indices(coot_utils.py)完成:训练时在帧区间内随机偏移采样,验证时采用中心采样。
配置文件详解:youcook2.yaml
训练配置 youcook2.yaml 是复现 Youcook2 实验的完整入口,字段说明如下(默认值可对照 engine/config/coot.py)。
DDP_CONFIG:分布式训练配置
| 字段 | 示例值 | 说明 |
|---|---|---|
WORLD_SIZE |
1 | 节点数 |
WORLD_RANK |
0 | 节点 rank |
GPU_WORLD_SIZE |
8 | 总 GPU 数(本配置中实际只用单卡) |
GPU_WORLD_RANK |
0 | 当前 GPU rank |
DIST_URL |
tcp://172.31.72.195:23456 |
分布式 master 地址 |
DIST_BACKEND |
nccl |
分布式后端 |
GPU |
0 | 使用的 GPU id |
DISTRIBUTED |
False | 是否启用 DDP(False 时走单卡路径) |
在 deploy_model 中,DISTRIBUTED=False 且 GPU 非空时模型被部署到指定单卡;若开启分布式则包装为 DistributedDataParallel。
CONFIG.MODEL:模型选择
| 字段 | 示例值 | 说明 |
|---|---|---|
NAME |
MultiModalTransformer_COOT |
模型名(注册表键 multimodaltransformer_coot,匹配时不区分大小写) |
PRETRAINED |
False | 是否使用 model zoo 预训练权重 |
PRETRAINED_BASE |
False | 是否使用预训练骨干 |
CONFIG.TRAIN:训练超参
| 字段 | 示例值 | 说明 |
|---|---|---|
EPOCH_NUM |
100 | 最大训练轮数 |
BATCH_SIZE |
64 | 每 GPU 批大小 |
LR |
0.0009 | 基础学习率 |
MOMENTUM |
0.56 | RAdam 的 beta1 |
W_DECAY |
0. | L2 权重衰减 |
USE_WARMUP |
True | 是否使用 warmup |
WARMUP_EPOCHS |
0 | warmup 轮数 |
PATIENCE |
5 | 学习率降低的耐心轮数 |
COOLDOWN |
3 | 学习率降低后的冷却轮数 |
LR_POLICY |
LR_Warmup |
学习率策略(Step/Cosine/LR_Warmup) |
RESUME_EPOCH |
-1 | 断点续训轮数,-1 表示从头训练 |
LOSS_CYCLE_CONS_W |
0.001 | 循环一致性损失权重 |
LOSS_CONTRASTIVE_CLIP_W |
1 | 片段-句子对齐损失权重 |
在 train_pytorch.py 中,优化器使用 RAdam(定义于 optimizer.py,默认 betas=(0.9, 0.999),此处以 MOMENTUM 作为 beta1);学习率策略按 LR_POLICY 分支选择,LR_Warmup 对应 ReduceLROnPlateauWarmup,以验证指标最优模式调度。
CONFIG.VAL:验证配置
| 字段 | 示例值 | 说明 |
|---|---|---|
FREQ |
1 | 每隔多少轮验证一次 |
BATCH_SIZE |
32 | 验证批大小 |
CONFIG.COOT_DATA:数据配置
| 字段 | 示例值 | 说明 |
|---|---|---|
DATASET_NAME |
youcook2 |
数据集名(当前支持 youcook2,代码中另有 activitynet 分支) |
DATA_PATH |
/data/youcook2 |
预计算特征根目录(下载后务必修改为你自己的路径) |
FEATURE |
100m |
视频特征名(拼接为 video_feat_100m.h5、meta_100m.json) |
TRAIN_SPLIT |
train |
训练 split |
VALIDATION_SPLIT |
val |
验证 split |
MAX_FRAMES |
80 | 单视频/单片段最大帧数上限 |
FEATURE_DIM |
512 | 视频帧特征维度(HowTo100M 特征维度) |
WORD_EMB |
bert |
文本特征类型 |
VIDEO_PRELOAD |
True | 是否将视频特征预加载到共享内存 |
TEXT_PRELOAD |
True | 是否将文本特征预加载到共享内存 |
CONFIG.COOT_MODEL:模型结构配置
四个子模块(VIDEO_POOLER、VIDEO_SEQUENCER、TEXT_POOLER、TEXT_SEQUENCER)共享同一套 Transformer 配置字段:
| 字段 | 示例值 | 说明 |
|---|---|---|
NAME |
atn |
结构类型(当前代码路径主要使用 atn,rnn 分支在代码中保留但需相应实现) |
OUTPUT_DIM |
384 | 输出嵌入维度 |
INPUT_FC |
true/false | 是否在输入侧加全连接投影层 |
INPUT_FC_OUTPUT_DIM |
384 | 投影层输出维度 |
NUM_LAYERS |
1 | Transformer 编码器层数 |
NUM_HEADS |
8 | 多头注意力头数(需整除输入维度) |
DROPOUT |
0.05 | dropout 概率 |
USE_CONTEXT |
false/true | 是否注入高层上下文(Pooler 为 false,Sequencer 为 true) |
ATN_CTX_NUM_LAYERS |
1 | 上下文编码器层数 |
ATN_CTX_NUM_HEADS |
8 | 上下文编码器头数 |
POOLER |
atn/avg |
池化方式(atn 注意力池化或 avg 平均池化) |
ATN_POOL_DIM |
768 | 注意力池化中间维度 |
ATN_POOL_HEADS |
2 | 注意力池化头数 |
TEXT_ENCODER.FEATURE_DIM 为 1536,即 BERT 文本特征的输入维度。Youcook2 示例的关键组合是:Pooler 用 atn 池化 + 输入全连接,Sequencer 用 USE_CONTEXT=True 注入高层上下文并采用 avg 池化,最终所有嵌入统一到 384 维。
CONFIG.LOG:日志与保存
| 字段 | 示例值 | 说明 |
|---|---|---|
BASE_PATH |
./logs/coot |
输出根目录 |
LOG_DIR |
tb_log |
TensorBoard 日志目录 |
SAVE_DIR |
checkpoints |
模型保存目录 |
EVAL_DIR |
./logs/coot/eval |
评估输出目录 |
SAVE_FREQ |
2 | 每隔多少轮保存一次 checkpoint |
训练模型
环境就绪、特征下载完成、配置中的 DATA_PATH 修改好后,在仓库根目录执行(README 中的原始命令):
python3 -m scripts.vision-language.video-language.coot.train_pytorch --config-file scripts/vision-language/video-language/coot/configuration/youcook2.yaml
训练主循环解析
train_pytorch.py 的 main_worker 执行流程:
- 初始化:rank 0 创建 TensorBoard writer 与日志,随后
cfg.freeze()冻结配置; - 构建模型:
get_model(cfg)实例化MultiModalTransformer_COOT,deploy_model部署到 GPU; - 构建数据:
create_dataloader_path拼接特征路径,create_datasets/create_loaders构造训练/验证 DataLoader(带自定义collate_fn、pin_memory=True); - 构建优化器与损失:RAdam +
MaxMarginRankingLoss+CycleConsistencyCootLoss; - 训练/验证循环:每个 epoch 调用
train_coot训练,按VAL.FREQ调用validate_coot评估; - 模型选择与调度:以验证集的 Sentence->Clip R@1(
clip_best_at_1)作为最优模型判定指标,通过compare_metrics判断是否提升并记录best_epoch;随后scheduler.step_rop依据指标调度学习率; - 保存与早停:按
SAVE_FREQ保存 checkpoint(格式f{CLIP_LEN}_s{FRAME_RATE}_ckpt_epoch{N}.pth);若连续 15 个 epoch 无改进(源码中term_after = 15)则提前终止训练并打印停止信息。
评估指标与预期结果
检索指标的计算
验证阶段(task_utils/coot.py 的 validate_coot)收集全部验证样本的视频/片段嵌入与段落/句子嵌入,归一化后计算四类检索:
- **Paragraph->Video(段落检索视频)**与 Video->Paragraph:
compute_retr_par_to_vid/compute_retr_vid_to_par; - **Sentence->Clip(句子检索片段)**与 Clip->Sentence:同样按点积相似度计算。
compute_retrieval_metrics(coot_utils.py)基于相似度矩阵的排序位置统计 R@1、R@5、R@10、R@50、中位秩(MedR)、平均秩(MeanR)等指标;日志中按 EVALHEADER 格式输出 Par2Vid、Vid2Par、Sen2Shot、Shot2Sen 四组结果,并用 TensorBoard 记录各 R@K 随 epoch 的变化。
预期结果(Youcook2 + HowTo100M 特征)
仓库 README 给出了在 AWS 单张 Tesla T4 GPU 上运行本仓库代码复现的 Youcook2 结果:
| Model | Paragraph->Video R@1 | R@5 | R@10 | MR | Sentence->Clip R@1 | R@5 | R@10 | MR |
|---|---|---|---|---|---|---|---|---|
| COOT | 78.3 | 96.2 | 97.8 | 1 | 16.9 | 40.5 | 52.5 | 9 |
其中 MR 为 MedR(中位秩)。注意这是仓库作者在特定硬件(单张 Tesla T4)与特征版本下复现的结果,读者在自身环境下训练可能因随机种子、硬件与依赖版本不同而有所波动。
引用与扩展阅读
若你的研究或项目使用了该实现,请引用 COOT 论文(BibTeX 见仓库 README):
@inproceedings{ging2020coot,
title={COOT: Cooperative Hierarchical Transformer for Video-Text Representation Learning},
author={Simon Ging and Mohammadreza Zolfaghari and Hamed Pirsiavash and Thomas Brox},
booktitle={Conference on Neural Information Processing Systems},
year={2020}
}
进一步阅读建议:模型实现的细节可深入 coot_model.py 与 loss.py;数据管线可参考 dataloader.py;若需在 ActivityNet 等其他数据集上实验,可从 dataloader.py 中已有的 activitynet 分支(ActivityNetVideoFeatureLoader 读取 ICEP_V3_global_pool_skip_8_direct_resize 目录下的 .npz 特征)出发,参照 youcook2.yaml 编写新的数据集配置文件。