erminga/cfan-didemo-inference

本仓库提供 CFAN 的代码、模型权重、DiDeMo 预提取特征与 GloVe 的完整压缩包。

下载与解压

下载 cfan_didemo_inference.tar.gz 及同名 .sha256 文件后：

sha256sum -c cfan_didemo_inference.tar.gz.sha256
tar -xzf cfan_didemo_inference.tar.gz
cd cfan_didemo_inference
python -m pip install -r requirements.txt

以下路径与命令均相对于解压后的目录。第三方资源使用说明见 THIRD_PARTY_NOTICES.md。

CFAN：代码与模型权重

本目录提供以下论文中 Coarse-to-Fine Alignment Network（CFAN）方法对应的代码、模型权重和推理所需数据：

Needle in a haystack: coarse-to-fine alignment network for moment retrieval from large-scale video collections

CFAN 根据自然语言查询，从视频集合中检索相关视频，并定位对应片段的起止时间。模型包含视频级对齐、跨模态交互、片段级与帧级对齐，以及基于细粒度信息的候选视频重排序。

目录结构

cfan_didemo_inference/
├── README.md
├── inference.py                     # Python 推理入口
├── run_inference.sh                 # Shell 推理入口
├── evaluate.sh                      # 批量评估入口
├── requirements.txt
├── pyproject.toml
├── verify_bundle.py                 # 文件完整性校验
├── SHA256SUMS
├── BUNDLE_MANIFEST.json              # 文件清单
├── cfan/                            # 模型、损失、训练及推理代码
├── configs/                         # 配置文件
├── scripts/                         # 数据处理等辅助脚本
├── weights/
│   ├── train_fit_epoch20.pt          # 默认模型权重
│   ├── validation_best_epoch4.pt     # 可选模型权重
│   └── METADATA.json                # 权重元数据
├── data/
│   ├── didemo/
│   │   ├── train.json
│   │   ├── val.json
│   │   ├── test.json
│   │   ├── provenance.json
│   │   ├── rgb_flow_features/       # 视频特征
│   │   ├── train_query_features/    # 查询词向量
│   │   ├── val_query_features/
│   │   └── test_query_features/
│   ├── annotations/                # DiDeMo 标注
│   └── glove/glove.6B.300d.txt       # GloVe 词向量
├── examples/                        # 推理输出示例
├── results/                         # 运行记录
└── THIRD_PARTY_NOTICES.md           # 第三方资源说明

环境安装

依赖 Python 3.10 或以上版本、PyTorch 2.3 或以上版本，以及 NumPy、PyYAML。

cd /path/to/cfan_didemo_inference
python -m pip install -r requirements.txt

支持 CPU 和 CUDA GPU。使用 GPU 时，请安装与本机驱动兼容的 PyTorch。推理所需的数据和词向量已包含在目录中，无需额外下载。

快速推理

使用数据清单中的一条查询进行全库检索：

bash run_inference.sh \
  --mode retrieve \
  --split test \
  --query-index 0 \
  --device cpu \
  --output outputs/retrieval.json

使用 GPU：

bash run_inference.sh \
  --mode retrieve \
  --split test \
  --query-index 0 \
  --device cuda:0 \
  --output outputs/retrieval_gpu.json

也可以直接调用 Python：

python inference.py --mode retrieve --split test --query-index 0 --device cpu

retrieve 模式在所选数据清单的全部视频中检索，默认选取 Top-5 候选视频进行片段定位和重排序。

自定义文本查询

bash run_inference.sh \
  --mode retrieve \
  --split test \
  --text "A person opens the door." \
  --top-n 5 \
  --device cuda:0 \
  --output outputs/text_query.json

文本采用英文分词和 GloVe 300 维词向量，最多保留 40 个词或标点。未登录词使用零向量；查询全部为未登录词时会提示错误。

如果已有查询特征，可以直接传入二维 .npy 数组，形状为 [词数, 300]：

python inference.py \
  --mode retrieve \
  --split test \
  --query-features /path/to/query.npy \
  --device cpu

指定视频内定位

localize 模式在一个已指定的视频内定位片段，不执行全库视频检索。

使用数据清单中的查询时，默认从该查询的标注记录中取得对应视频：

bash run_inference.sh \
  --mode localize \
  --split test \
  --query-index 0 \
  --device cpu \
  --output outputs/localization.json

自定义文本需要同时指定 --video-id：

python inference.py \
  --mode localize \
  --split test \
  --text "A person opens the door." \
  --video-id YOUR_VIDEO_ID \
  --device cuda:0

将 YOUR_VIDEO_ID 替换为所选数据清单中的实际视频 ID。输出字段 ground_truth_video_used 表示是否通过查询标注取得了视频。

权重加载

默认加载：

weights/train_fit_epoch20.pt

通过 --checkpoint 切换另一份权重：

python inference.py \
  --mode retrieve \
  --split test \
  --query-index 0 \
  --checkpoint weights/validation_best_epoch4.pt \
  --device cpu

两份权重均包含完整 CFAN 的模型参数和配置，包括粗检索编码器、跨模态定位、门控和细粒度重排序模块。权重文件用于推理，不包含优化器和随机状态；文件元数据见 weights/METADATA.json。

数据格式

DiDeMo 数据清单位于 data/didemo/，每份清单包含 videos 和 queries：

数据清单	视频数	查询数
train.json	8,511	33,005
val.json	1,094	4,180
test.json	1,037	4,021

视频输入为预提取的 RGB 与光流特征：RGB 4096 维、光流 1024 维，拼接后共 5120 维。每个视频包含 5 或 6 个有效时间段。查询特征为 GloVe 300 维词向量。

数据目录包含特征和标注，不包含原始 MP4/AVI 文件；推理入口不直接读取原始视频。时间戳采用 DiDeMo 的五秒片段网格，原视频最后一段实际时长可能不足五秒。数据来源见 data/didemo/provenance.json 和 THIRD_PARTY_NOTICES.md。

主要参数

参数	作用
--mode retrieve	全视频库检索与片段定位
--mode localize	指定视频内定位
--split	选择 train、val 或 test 数据清单
--manifest	使用指定路径的数据清单
--query-index / --query-id	选择清单中的查询
--text	输入英文查询
--query-features	输入查询词向量数组
--video-id	指定定位视频，仅用于 localize
--checkpoint	指定模型权重
--candidate-k	粗检索候选视频数，默认 5
--top-n	输出片段数，默认 5
--device	cpu 或 cuda:0 等设备
--output	保存输出 JSON
--no-cache	不使用已有索引缓存

--query-index、--query-id、--text 和 --query-features 四者互斥。

首次全库推理会构建视频索引并写入 cache/，之后自动复用相同权重和数据清单的缓存。如果原位修改了视频特征文件，应使用 --no-cache 或清除对应缓存后重新构建。

输出说明

推理结果采用 JSON 格式，主要字段包括：

• mode：推理模式。
• query_id、text：查询信息。
• moments：返回的片段列表，每项包含 video_id、timestamp 和片段置信度。
• video_ids、coarse_video_ids：重排后和粗检索的视频顺序，仅在检索模式中提供。
• ground_truth_video_used：是否使用查询标注指定视频。
• reference：清单查询对应的参考标注，在推理后附加，便于查看。

retrieve 模式不会使用参考标注过滤候选视频。

批量评估

bash evaluate.sh test weights/validation_best_epoch4.pt cuda:0

结果写入 outputs/。评估采用 R@n, IoU=m 和视频召回指标；DiDeMo 的片段需要与至少两名标注者的区间达到指定 IoU。

代码入口与文件校验

文件	功能
cfan/model.py	CFAN 网络结构
cfan/losses.py	视频、片段和帧级对齐损失
cfan/temporal.py	候选生成与时间 IoU
cfan/data.py	数据清单与特征读取
cfan/train.py	模型训练
cfan/evaluate.py	全库评估
inference.py	单条查询推理

检查交付文件完整性：

python verify_bundle.py

整个目录可复制到其他路径或机器。数据清单使用相对特征路径，命令中的相对文件路径从包根目录解析。cache/ 和 outputs/ 为运行时生成内容。