Nexus：重复 caption 的多正样本对比学习
这是 Nexus 多模态检索的代码补丁包，不是独立可安装项目，不包含模型权重或训练数据。需要已有、兼容版本的 Nexus 代码和依赖。本包保持 text-to-candidate 训练方向，并未实现完整的双向 EgoVLP 预训练流程。
必须一起接入的四个源文件
| 文件 | 职责 |
|---|---|
Nexus/training/embedder/multimodal_retrieval/caption_positive.py |
精确 caption ID、多正样本 loss、配置校验 |
Nexus/training/embedder/multimodal_retrieval/arguments.py |
新配置开关 |
Nexus/training/embedder/multimodal_retrieval/runner.py |
校验配置、向模型传递参数 |
Nexus/training/embedder/multimodal_retrieval/modeling.py |
loss 路由和跨卡 caption ID 同步 |
仅复制新增 helper、测试和文档，无法让训练调用该功能。
接入现有 Nexus
优先审阅并在兼容的未修改代码目录中检查补丁：
cd /path/to/Nexus
patch --dry-run -p1 < /path/to/this-package/patches/caption-multi-positive.patch
patch -p1 < /path/to/this-package/patches/caption-multi-positive.patch
如果目标代码已有其他修改，请人工合并补丁。Nexus/ 中的完整文件是实现快照，不应盲目覆盖其他版本。已经接入的代码不要再次应用补丁。
开关
将 examples/training_config.fragment.json 的字段合并到 training_config.json：
{
"caption_multi_positive_loss": "egonce",
"caption_group_normalize": false,
"negatives_cross_device": true
}
将 examples/data_config.fragment.json 的字段合并到 data_config.json：
{
"same_dataset_within_batch": true,
"no_in_batch_neg": false,
"knowledge_distillation": false,
"query_normalized_multi_positive": false
}
off（默认）：原来的单正样本训练。egonce：对同 caption 的正视频概率求和，再取负对数。mean_ce：逐正样本计算 CE 后平均。caption_group_normalize=true：主 loss 按唯一 caption 分组平均，调整 query 端重复计权，不消除候选端频率差异。
精确匹配的是 instruction 应用后的完整 query 文本及 title，不做语义聚类。只扩展每条数据实际采样出的 pos 位置，显式 neg 不会因其所属行 caption 相同而被自动升级为正样本。使用完整 SHA-256 ID 跨卡同步，保留现有采样和候选数量，不增加视频编码次数。
本模式仅支持纯文本 query；显式/随机补 neg 仍必须正确。原有随机补负例逻辑不排除同 caption 行，此补丁没有改动该采样逻辑。
测试
在已接入的 Nexus 根目录：
PYTHONPATH=. python -m unittest discover -s tests/multimodal_retrieval -p test_caption_multi_positive.py -v
PYTHONPATH=. python -m torch.distributed.run --standalone --nproc_per_node=2 tests/multimodal_retrieval/check_caption_cross_device.py
可选 CUDA/NCCL 与真实模型冒烟测试（先将本包对应测试脚本复制到目标 Nexus）：
CUDA_VISIBLE_DEVICES=0,1 PYTHONPATH=. python -m torch.distributed.run --standalone --nproc_per_node=2 tests/multimodal_retrieval/check_caption_cuda.py
CUDA_VISIBLE_DEVICES=0 HF_HUB_OFFLINE=1 PYTHONPATH=. python tests/multimodal_retrieval/check_caption_video_model.py --model-path /path/to/Qwen3-VL-Embedding-2B --output-dir work/caption-video-smoke
16 项单测已通过；两进程 CPU/gloo 和 CUDA/NCCL 的跨卡重复 caption loss、本地 embedding 梯度与全局参考一致；CUDA BF16 检查通过。Qwen3-VL-Embedding-2B + BF16 + rank 4 LoRA 用两个同 caption query、四段不同的合成视频（每段 16 帧）验证前向、反向、参数更新。结构化结果见 reports/。
以上验证了处理逻辑和训练链路，没有证明真实 COC 检索指标提升。真实视频模型测试为单卡，完整视频模型的多卡 DDP Trainer 训练尚未验证。测试需要 passage_max_len=4096 容纳 processor 生成的完整视频 token；1024 曾因截断报错。正式所需长度和显存取决于实际配置。
更多说明见 docs/multimodal_retrieval/caption_multi_positive.md。
许可与来源
修改基于现有 Nexus 代码，保留原项目 LICENSE（Apache 2.0 加原项目 Additional Terms）。请一并阅读其中的附加条款。本包未从 EgoVLP 复制源码，借鉴其多正样本概率集合目标。