VLM2Vec-V2：面向视频、图像和文档的统一多模态嵌入

本仓库包含 VLM2Vec-V2 的官方代码与数据，这是一个用于学习跨多种视觉格式（包括图像、视频和视觉文档）的强大多模态嵌入的统一框架。

我们的工作提出了 MMEB-V2，一个包含 78 个任务的综合性基准，旨在系统性地评估这些模态下的嵌入模型。VLM2Vec-V2 创下了新的最先进水平，在所有类别中均超越了强大的基线模型。

这是一个开源项目，我们欢迎社区的贡献。我们尤其期待新增功能、支持新数据集、修复 bug 以及改进文档等工作。请随时提交 issue 讨论您的想法或发起 pull request！

📌 请查看我们的 CHANGELOG 以了解最新功能和 bug 修复！

🚨 V2 重大更新通知（2025 年 6 月） 🚨

本仓库已升级至 V2 版本，这是对代码库的一次彻底重构。之前的 VLM2Vec 代码已被归档，可在 v1 分支中找到。

警告： 请在继续操作前备份任何本地工作。如果您在此更新之前克隆了本地副本，必须重置主分支以同步新代码。

有关详细说明，请参阅下方的“如何升级到 V2”部分。

我们非常感谢您对此次过渡过程的反馈。如果您遇到任何问题，请通过提交 issue 告知我们。

---

🔥 最新消息

• [2026-01] 🎉 VLM2Vec-V2 被 TMLR 2026 接收。
• [2025-05] VLM2Vec-v2 发布！我们推出了一套适用于图像、视频和视觉文档的统一嵌入框架。同时发布的还有全新的 MMEB-V2 基准，包含 78 个多样化任务。VLM2Vec-V2 模型的表现优于先前版本及强大的专用基线。
• [2025-01] 🎉 VLM2Vec 被 ICLR 2025 接收。
• [2024-10] VLM2Vec 的技术报告、代码、数据和模型均已在线发布。

📜 查看旧版更新

• [2025-02] 🔥 新发布了两款基于 Qwen2VL 2B 和 7B 的 VLM2Vec 模型，在 MMEB 基准上分别取得了 60.1 和 65.8 的成绩（新的 SOTA！）。快来看看它们吧（2B, 7B)！
• [2025-02] 我们正着手开发 VLM2Vec 的更高级功能和扩展，并将所有更改记录在 CHANGELOG.md 中。如果任何更改与先前支持的功能冲突，请随时在此处提出 issue。提前感谢！
• [2025-01] 我们更新了训练数据集 (https://huggingface.co/datasets/TIGER-Lab/MMEB-train)。每个子集现在包含两个划分：original 和 diverse_instruction。original 划分用于支持论文结果的复现。而diverse_instruction 划分则包含了针对每个任务的改写指令，旨在增强指令多样性，提升模型对未见指令和任务的鲁棒性。今后，我们的后续发布将主要使用diverse_instruction 划分。
• [2024-12] 我们发布了 MMEB 排行榜。如果您希望将自己的模型纳入其中，请随时联系我们。
• [2024-12] 我们发布了一个基于 LLaVa-Next 主干的新版本 VLM2Vec，目前是我们表现最好的版本：https://huggingface.co/TIGER-Lab/VLM2Vec-LLaVa-Next。
• [2024-10] VLM2Vec 已集成到 vLLM 中。

核心更新

• 面向三种数据模态（图像、视频和视觉文档）的统一嵌入模型训练与评估框架。
• MMEB v2 基准：在 v1 基准基础上扩展了视频和视觉文档任务，共计 78 个任务。
• VLM2Vec-v2.0：基于 Qwen2-VL-2B 的全新嵌入模型。
• 使用 yaml 文件轻松配置训练与评估（示例见 experiments/release）。
• 通过创建并注册自定义数据加载器，可轻松扩展新数据集（示例见 src/dataset/）。

如何升级到 V2

1. 备份本地更改（至关重要！） 更新过程会丢弃您本地主分支上任何未提交的更改。如果您有需要保存的工作，请将其提交到新分支，或使用 git stash。
2. 将本地仓库重置为 V2 版本。 运行以下命令以获取新的 main 分支，并将您的本地副本重置为与之匹配。

# 首先确保您位于主分支上
git checkout main
# 获取远程的所有最新更新并移除过时的分支引用
git fetch --all --prune
# 强制您的本地主分支与新的远程主分支保持一致
git reset --hard origin/main

模型

VLM2Vec-V2 通过指令引导的对比学习微调了一种最先进的视觉-语言模型（VLM）。该模型能够为文本、图像、视频和文档输入的任意组合生成单一、强大的固定维度嵌入。

对于当前的 V2 版本，我们使用 Qwen2-VL 作为模型主干，它能够高效处理文本与视觉内容的交错序列、不同分辨率以及视频和视觉文档等长序列输入。

已发布的检查点

• VLM2Vec-v2.0 (Qwen2VL-2B)：我们的主要模型，在所有模态上均表现出强大且均衡的性能。

V1 检查点

• VLM2Vec-Qwen2VL (7B)
• VLM2Vec-Qwen2VL (2B)
• VLM2Vec-LLaVa-Next
• VLM2Vec-Phi3.5V

MMEB-v2 基准测试

我们推出了 MMEB-V2，这是一项扩展后的基准测试，包含 78 个数据集，覆盖图像、视频和视觉文档。

• 新增视频任务：视频检索、时刻检索、视频分类和视频问答。
• 新增视觉文档任务：视觉文档检索。
• 请在 Huggingface 上查看 MMEB-v2 数据集。

数据下载

请参考 experiments/public/data/download_data.sh。

训练

我们的训练过程使用来自三个主要来源的精选数据集：视频-语言数据（LLaVA-Hound）、视觉文档数据（Vidore、VisRAG）以及图像-文本数据（MMEB-train）。我们采用交错子批处理策略，以实现稳定高效的对比学习。

运行方法：请参阅 experiments/public/train 中的示例。

评估

支持在多 GPU 上进行 DDP 推理。整个评估流程非常流畅，可在数小时内完成。

运行方法：请参阅 experiments/public/eval 中的示例。

复现基线模型的注意事项

• GME：需要较旧版本的 transformers 库，版本号不超过 4.51.3。
• MomentSeeker：我们建议使用单 GPU，批量大小设为 10。这是由于基线处理器存在限制，无法处理图像和纯文本数据混合的批次。

引用

@article{jiang2024vlm2vec,
  title={VLM2Vec：面向大规模多模态嵌入任务的视觉-语言模型训练},
  author={Jiang, Ziyan and Meng, Rui and Yang, Xinyi and Yavuz, Semih and Zhou, Yingbo and Chen, Wenhu},
  journal={arXiv 预印本 arXiv:2410.05160},
  year={2024}
}

@article{meng2025vlm2vecv2,
  title={VLM2Vec-V2：推进视频、图像和视觉文档的多模态嵌入技术},
  author={Rui Meng and Ziyan Jiang and Ye Liu and Mingyi Su and Xinyi Yang and Yuepeng Fu and Can Qin and Zeyuan Chen and Ran Xu and Caiming Xiong and Yingbo Zhou and Wenhu Chen and Semih Yavuz},
  journal={arXiv 预印本 arXiv:2507.04590},
  year={2025}
}

点赞历史

VLM2Vec-V2 快速上手指南

VLM2Vec-V2 是一个统一的多模态嵌入框架，支持视频、图像和视觉文档的嵌入学习。本指南帮助开发者快速完成环境配置、安装及基础使用。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• Python: 3.9 或更高版本
• GPU: 支持 CUDA 的 NVIDIA GPU (推荐显存 ≥ 16GB，用于训练或大模型推理)
• 依赖管理: 建议使用 conda 或 venv 创建独立虚拟环境
• Git: 用于克隆代码库

注意：V2 版本是对代码库的彻底重构。如果您之前克隆过旧版 (V1)，请务必先备份本地修改，并按照官方说明重置分支至 main。

安装步骤

1. 克隆仓库

git clone https://github.com/TIGER-AI-Lab/VLM2Vec.git
cd VLM2Vec

2. 创建并激活虚拟环境

conda create -n vlm2vec python=3.10 -y
conda activate vlm2vec

3. 安装依赖

项目依赖通常包含在 requirements.txt 中。为确保兼容性，建议优先安装核心深度学习库，再安装项目依赖。

# 安装 PyTorch (根据您的 CUDA 版本调整，此处以 cu118 为例)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 安装项目其他依赖
pip install -r requirements.txt

(注：如果国内下载缓慢，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源)

4. 验证安装

确保能够导入核心库且无报错：

python -c "import vlm2vec; print('Installation successful')"

基本使用

VLM2Vec-V2 基于 Qwen2-VL 架构，通过指令引导的对比学习生成固定维度的多模态嵌入。以下是加载模型并生成嵌入的最简示例。

加载模型与生成嵌入

import torch
from transformers import AutoModel, AutoTokenizer
from PIL import Image

# 1. 加载预训练模型 (VLM2Vec-v2.0 based on Qwen2VL-2B)
model_name = "VLM2Vec/VLM2Vec-V2.0"
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
model = AutoModel.from_pretrained(
    model_name, 
    trust_remote_code=True, 
    device_map="auto", 
    torch_dtype=torch.bfloat16 # 推荐使用 bfloat16 以节省显存
).eval()

# 2. 准备输入数据 (文本 + 图像)
# 假设您有一张名为 'example.jpg' 的图片
image = Image.open("example.jpg").convert("RGB")
query_text = "这张图片里有什么？"

# 构建输入 (具体 prompt 格式需参考模型卡片，此处为通用示例)
inputs = tokenizer(
    text=[query_text], 
    images=[image], 
    return_tensors="pt", 
    padding=True
).to(model.device)

# 3. 生成嵌入向量
with torch.no_grad():
    embeddings = model.get_embedding(**inputs)

# embeddings 形状通常为 [batch_size, hidden_dim]
print(f"Embedding shape: {embeddings.shape}")

处理视频或长文档

VLM2Vec-V2 原生支持视频和长视觉文档。只需将 images 参数替换为视频帧列表或文档页面图像列表即可，模型会自动处理交错序列。

# 伪代码示例：处理视频帧
video_frames = [...] # 提取的视频帧列表 (PIL Image 对象)
inputs = tokenizer(
    text=["描述这个视频的内容"], 
    images=[video_frames], # 支持传入图像列表
    return_tensors="pt"
).to(model.device)

embeddings = model.get_embedding(**inputs)

运行评估 (可选)

项目提供了基于 YAML 配置的评估脚本。您可以参考 experiments/public/eval 目录下的示例运行基准测试：

# 示例：运行 MMEB-V2 基准测试 (需先下载数据集)
python experiments/public/eval/run_eval.py --config experiments/public/eval/configs/mmeb_v2.yaml