VisRAG 2.0：视觉检索增强生成中的证据引导多图像推理

• 📖 Introduction • 🎉 News • ✨ VisRAG Pipeline • ⚙️ Setup • ⚡️ Training

• 📃 Evaluation • 🔧 Usage • 📄 Lisense • 📧 Contact • 📈 Star History

📖 Introduction

EVisRAG (VisRAG 2.0) 是一种证据引导的视觉检索增强生成框架，它通过首先对检索到的图像进行语言观察以收集每张图像的证据，然后基于这些线索进行推理来回答问题，从而赋予视觉语言模型（VLM）处理多图像问题的能力。EVisRAG 使用奖励范围内的GRPO进行训练，通过应用细粒度的token级别奖励来联合优化视觉感知和推理能力。

VisRAG 是一种基于视觉语言模型（VLM）的新型RAG流水线。在该流水线中，不再先解析文档获取文本，而是直接将文档作为图像使用VLM进行嵌入，然后进行检索以增强VLM的生成能力。与传统的基于文本的RAG相比，VisRAG 最大化了原始文档中数据信息的保留和利用，消除了解析过程中引入的信息损失。

🎉 News

• 20251207: 在HuggingFace上发布了所有基准测试。
• 20251118: EVisRAG和VisRAG都可以在UltraRAG v2中轻松复现。
• 20251022: 我们将所有评估基准上传到了HuggingFace收藏集。
• 20251014: 在HuggingFace上发布了EVisRAG-3B。
• 20251014: 发布了EVisRAG (VisRAG 2.0)，一个端到端的视觉语言模型。在arXiv上发布了我们的论文。在HuggingFace上发布了我们的模型。在GitHub上发布了我们的代码。
• 20241111: 在GitHub上发布了我们的VisRAG流水线，现在支持跨多个PDF文档的视觉理解。
• 20241104: 在Hugging Face Space上发布了我们的VisRAG流水线。
• 20241031: 在Colab上发布了我们的VisRAG流水线。发布了用于将文件转换为图像的代码，可在visrag_scripts/file2img中找到。
• 20241015: 在HuggingFace上发布了我们的训练数据和测试数据，可以在HuggingFace上的VisRAG收藏集中找到。本页开头已提及。
• 20241014: 在arXiv上发布了我们的论文。在HuggingFace上发布了我们的模型。在GitHub上发布了我们的代码。

✨ VisRAG Pipeline

EVisRAG

EVisRAG 是一个端到端的框架，在多图像场景下为VLM提供精确的视觉感知能力。我们基于Qwen2.5-VL-7B-Instruct和Qwen2.5-VL-3B-Instruct训练并发布了内置EVisRAG的VLRM。

VisRAG-Ret

VisRAG-Ret 是一个基于MiniCPM-V 2.0的文档嵌入模型，该模型整合了SigLIP作为视觉编码器，以及MiniCPM-2B作为语言模型。

VisRAG-Gen

在论文中，我们使用MiniCPM-V 2.0、MiniCPM-V 2.6和GPT-4o作为生成器。实际上，你可以使用任何你喜欢的VLM！

⚙️ Setup

EVisRAG

git clone https://github.com/OpenBMB/VisRAG.git
conda create --name EVisRAG python==3.10
conda activate EVisRAG
cd EVisRAG
pip install -r EVisRAG_requirements.txt

VisRAG

git clone https://github.com/OpenBMB/VisRAG.git
conda create --name VisRAG python==3.10.8
conda activate VisRAG
conda install nvidia/label/cuda-11.8.0::cuda-toolkit
cd VisRAG
pip install -r requirements.txt
pip install -e .
cd timm_modified
pip install -e .
cd ..

注意：

1. timm_modified 是timm库的一个增强版本，支持梯度检查点技术，我们在训练过程中使用它来减少内存占用。

⚡️ Training

EVisRAG

为了有效地训练EVisRAG，我们引入了奖励范围分组相对策略优化（RS-GRPO），该方法将细粒度的奖励与特定范围的标记绑定，从而联合优化视觉语言模型的视觉感知和推理能力。

阶段1：SFT（基于LLaMA-Factory）

git clone https://github.com/hiyouga/LLaMA-Factory.git 
bash evisrag_scripts/full_sft.sh

阶段2：RS-GRPO（基于Easy-R1）

bash evisrag_scripts/run_rsgrpo.sh

注：

1. 训练数据可在Hugging Face上找到，名称为EVisRAG-Train，本页开头已列出。
2. 我们采用两阶段训练策略。第一阶段，请克隆LLaMA-Factory并更新full_sft.sh脚本中的模型路径。第二阶段，我们在Easy-R1的基础上构建了专为EVisRAG设计的自定义算法RS-GRPO，其具体实现可在src/RS-GRPO中找到。

VisRAG-Ret

我们用于VisRAG-Ret的362,110对查询-文档（Q-D）训练数据集由公开可用的学术数据集的训练集（34%）以及一个合成数据集组成，该合成数据集由网络爬取的PDF文档页面构成，并辅以VLM生成的伪查询（GPT-4o）（66%）。

bash visrag_scripts/train_retriever/train.sh 2048 16 8 0.02 1 true false config/deepspeed.json 1e-5 false wmean causal 1 true 2 false <model_dir> <repo_name_or_path>

注：

1. 我们的训练数据可在Hugging Face上的VisRAG集合中找到，本页开头已列出。请注意，我们已将“领域内数据”和“合成数据”分开，因为它们存在显著差异。若希望使用完整数据集进行训练，需手动合并并打乱数据。
2. 上述参数为我们论文中使用的参数，可用于复现实验结果。
3. <repo_name_or_path>可以是以下任一选项：openbmb/VisRAG-Ret-Train-In-domain-data、openbmb/VisRAG-Ret-Train-Synthetic-data、从Hugging Face下载的仓库目录路径，或包含您自有训练数据的目录。
4. 若希望使用您自己的数据集进行训练，请移除train.sh脚本中的--from_hf_repo一行。此外，确保您的数据集目录中包含一个metadata.json文件，其中必须包含一个length字段，用于指定数据集中样本的总数。
5. 我们的训练框架是在OpenMatch的基础上修改而成。

VisRAG-Gen

生成部分未进行任何微调，我们直接使用现成的LLM/VLM进行生成。

📃 评估

EVisRAG

bash evisrag_scripts/predict.sh
bash evisrag_scripts/eval.sh 

注：

1. 测试数据可在Hugging Face上找到，名称为EVisRAG-Test-xxx，本页开头已列出。
2. 运行评估时，首先执行predict.sh脚本，模型输出将保存在preds目录中。然后使用eval.sh脚本对预测结果进行评估，将直接报告EM、Accuracy和F1等指标。

VisRAG-Ret

bash visrag_scripts/eval_retriever/eval.sh 512 2048 16 8 wmean causal ArxivQA,ChartQA,MP-DocVQA,InfoVQA,PlotQA,SlideVQA <ckpt_path>

注：

1. 我们的测试数据可在Hugging Face上的VisRAG集合中找到，本页开头已列出。
2. 上述参数为我们论文中使用的参数，可用于复现实验结果。
3. 评估脚本默认配置为使用Hugging Face上的数据集。若您希望使用本地下载的数据集仓库进行评估，可修改评估脚本中的CORPUS_PATH、QUERY_PATH、QRELS_PATH变量，使其指向本地仓库目录。

VisRAG-Gen

我们的生成方式分为三种：基于文本的生成、基于单张图像的VLM生成以及基于多张图像的VLM生成。在基于单张图像的VLM生成中，又有两种额外设置：页面拼接和加权选择。有关这些设置的详细信息，请参阅我们的论文。

python visrag_scripts/generate/generate.py \
--model_name <model_name> \
--model_name_or_path <model_path> \
--dataset_name <dataset_name> \
--dataset_name_or_path <dataset_path> \
--rank <process_rank> \ 
--world_size <world_size> \
--topk <用于生成的检索文档数量> \
--results_root_dir <检索结果目录> \
--task_type <任务类型> \
--concatenate_type <图像拼接类型> \
--output_dir <输出目录>

注：

1. use_positive_sample决定是否仅使用查询的正例文档。启用此选项可排除检索到的文档，并省略topk和results_root_dir。若禁用，则必须指定topk（检索文档的数量）并按results_root_dir/dataset_name/*.trec的格式组织results_root_dir。
2. concatenate_type仅在task_type设置为page_concatenation时需要。若无需此设置，则可忽略。
3. 始终需指定model_name_or_path、dataset_name_or_path和output_dir。
4. 仅在需要基于GPT的评估时才使用--openai_api_key。

🔧 使用

EVisRAG

Hugging Face 上的模型：https://huggingface.co/openbmb/EVisRAG-7B

from transformers import AutoProcessor
from vllm import LLM, SamplingParams
from qwen_vl_utils import process_vision_info

def evidence_promot_grpo(query):
    return f"""你是一位AI视觉问答助手。我会提供一个问题和几张图片，请按照以下四个步骤操作：

第一步：观察图片
首先分析问题，思考哪些类型的图片可能包含相关信息。然后逐一检查每张图片，特别关注与问题相关的内容。判断每张图片是否包含潜在的相关信息。
将你的观察结果用 <observe></observe> 标签包裹起来。

第二步：记录图片中的证据
在查看完所有图片后，将你在每张图片中找到的证据用 <evidence></evidence> 标签记录下来。
如果你确定某张图片不包含任何相关信息，则记录为：[i]: 无相关信息（其中 i 表示图片的索引）。
如果一张图片包含相关证据，则记录为：[j]: [你为该问题找到的证据]（其中 j 是图片的索引）。

第三步：根据问题和证据进行推理
基于已记录的证据，推导出问题的答案。
将你的逐步推理过程用 <think></think> 标签包裹起来。

第四步：回答问题
仅根据你在图片中找到的证据给出最终答案。
将你的答案用 <answer></answer> 标签包裹起来。
避免在最终答案中添加不必要的内容，例如，如果问题是“是/否”问题，只需回答“是”或“否”。
如果所有图片都不足以回答问题，则回复 <answer>无法回答</answer>。

格式要求：
请严格按照 <observe>、<evidence>、<think> 和 <answer> 标签进行结构化输出。
可能没有任何图片、仅有一张图片或有多张图片包含相关证据。
如果你没有找到任何证据，或者证据不足无法帮助你回答问题，请按照上述关于信息不足的指示操作。

问题和图片如下所示。请按照指示步骤操作。
问题：{query}
"""

model_path = "xxx"
processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True, padding_side='left')

imgs, query = ["imgpath1", "imgpath2", ..., "imgpathX"], "What xxx?"
input_prompt = evidence_promot_grpo(query)

content = [{"type": "text", "text": input_prompt}]
for imgP in imgs:
    content.append({
        "type": "image",
        "image": imgP
    })
msg = [{
          "role": "user",
          "content": content,
      }]

llm = LLM(
    model=model_path,
    tensor_parallel_size=1,
    dtype="bfloat16",
    limit_mm_per_prompt={"image":5, "video":0},
)

sampling_params = SamplingParams(
    temperature=0.1,
    repetition_penalty=1.05,
    max_tokens=2048,
)

prompt = processor.apply_chat_template(
    msg,
    tokenize=False,
    add_generation_prompt=True,
)

image_inputs, _ = process_vision_info(msg)

msg_input = [{
    "prompt": prompt,
    "multi_modal_data": {"image": image_inputs},
}]

output_texts = llm.generate(msg_input,
    sampling_params=sampling_params,
)

print(output_texts[0].outputs[0].text)

VisRAG-Ret

Hugging Face 上的模型：https://huggingface.co/openbmb/VisRAG-Ret

from transformers import AutoModel, AutoTokenizer
import torch
import torch.nn.functional as F
from PIL import Image
import os

def weighted_mean_pooling(hidden, attention_mask):
    attention_mask_ = attention_mask * attention_mask.cumsum(dim=1)
    s = torch.sum(hidden * attention_mask_.unsqueeze(-1).float(), dim=1)
    d = attention_mask_.sum(dim=1, keepdim=True).float()
    reps = s / d
    return reps

@torch.no_grad()
def encode(text_or_image_list):
    
    if (isinstance(text_or_image_list[0], str)):
        inputs = {
            "text": text_or_image_list,
            'image': [None] * len(text_or_image_list),
            'tokenizer': tokenizer
        }
    else:
        inputs = {
            "text": [''] * len(text_or_image_list),
            'image': text_or_image_list,
            'tokenizer': tokenizer
        }
    outputs = model(**inputs)
    attention_mask = outputs.attention_mask
    hidden = outputs.last_hidden_state

    reps = weighted_mean_pooling(hidden, attention_mask)   
    embeddings = F.normalize(reps, p=2, dim=1).detach().cpu().numpy()
    return embeddings

model_name_or_path = "openbmb/VisRAG-Ret"
tokenizer = AutoTokenizer.from_pretrained(model_name_or_path, trust_remote_code=True)
model = AutoModel.from_pretrained(model_name_or_path, torch_dtype=torch.bfloat16, trust_remote_code=True)
model.eval()

script_dir = os.path.dirname(os.path.realpath(__file__))
queries = ["狗长什么样？"]
passages = [
    Image.open(os.path.join(script_dir, 'test_image/cat.jpeg')).convert('RGB'),
    Image.open(os.path.join(script_dir, 'test_image/dog.jpg')).convert('RGB'),
]

INSTRUCTION = "将此查询表示为用于检索相关文档的形式："
queries = [INSTRUCTION + query for query in queries]

embeddings_query = encode(queries)
embeddings_doc = encode(passages)

scores = (embeddings_query @ embeddings_doc.T)
print(scores.tolist())

VisRAG-Gen

对于 VisRAG-Gen，你可以在 Google Colab 上探索包含 VisRAG-Ret 和 VisRAG-Gen 的 VisRAG 流程，以体验这个简单的演示。

📄 许可证

• 本仓库中的代码遵循 Apache-2.0 许可协议。
• VisRAG-Ret 模型权重的使用必须严格遵守 MiniCPM 模型许可证.md。
• VisRAG-Ret 的模型和权重完全免费供学术研究使用。填写一份 "问卷" 进行注册后，VisRAG-Ret 权重也可免费用于商业用途。

📧 联系方式

EVisRAG

• Yubo Sun: syb2000417@stu.pku.edu.cn
• Chunyi Peng: hm.cypeng@gmail.com

VisRAG

• Shi Yu: yus21@mails.tsinghua.edu.cn
• Chaoyue Tang: tcy006@gmail.com

📈 星标历史

VisRAG 快速上手指南

VisRAG 是一个基于视觉语言模型（VLM）的检索增强生成（RAG）框架。与传统文本 RAG 不同，它直接将文档作为图像嵌入和检索，最大程度保留原始文档中的视觉信息。EVisRAG (VisRAG 2.0) 进一步引入了证据引导的多图像推理能力，通过奖励范围化的 GRPO 算法联合优化视觉感知与推理。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu)
• Python: 3.10 (EVisRAG) 或 3.10.8 (VisRAG)
• GPU: NVIDIA GPU (需安装 CUDA Toolkit)
  • VisRAG 训练/推理推荐 CUDA 11.8
• 依赖管理: Conda (推荐)

安装步骤

根据您想使用的模块（EVisRAG 或原版 VisRAG），选择对应的安装流程。

方案 A：安装 EVisRAG (VisRAG 2.0)

适用于多图像推理和端到端视觉问答任务。

# 1. 克隆代码库
git clone https://github.com/OpenBMB/VisRAG.git
cd VisRAG

# 2. 创建并激活 Conda 环境
conda create --name EVisRAG python==3.10
conda activate EVisRAG

# 3. 安装依赖
pip install -r EVisRAG_requirements.txt

方案 B：安装 VisRAG (含检索器训练)

适用于构建完整的文档图像检索与生成流水线。

# 1. 克隆代码库
git clone https://github.com/OpenBMB/VisRAG.git
cd VisRAG

# 2. 创建并激活 Conda 环境 (注意版本为 3.10.8)
conda create --name VisRAG python==3.10.8
conda activate VisRAG

# 3. 安装 CUDA Toolkit (以 11.8 为例)
conda install nvidia/label/cuda-11.8.0::cuda-toolkit

# 4. 安装核心依赖
pip install -r requirements.txt
pip install -e .

# 5. 安装修改版的 timm 库 (支持梯度检查点以节省显存)
cd timm_modified
pip install -e .
cd ..

提示：国内用户若遇到 pip 下载缓慢，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 参数加速安装。

基本使用

以下展示如何使用 EVisRAG 进行最简单的推理演示。该模型基于 Qwen2.5-VL，能够直接处理多图像输入并进行证据引导的回答。

Python 推理示例

确保已安装 transformers, vllm, qwen_vl_utils 等依赖，并从 Hugging Face 下载模型 (openbmb/EVisRAG-7B)。

from transformers import AutoProcessor
from vllm import LLM, SamplingParams
from qwen_vl_utils import process_vision_info

def evidence_prompt_grpo(query):
    return f"""You are an AI Visual QA assistant. I will provide you with a question and several images. 
    First, observe each image carefully to extract relevant evidence. 
    Then, reason based on the collected evidence to answer the question.
    
    Question: {query}
    """

# 初始化模型和处理器
model_path = "openbmb/EVisRAG-7B" # 或本地路径
processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)
llm = LLM(model=model_path, trust_remote_code=True, gpu_memory_utilization=0.9)

# 准备输入数据 (示例：一个问题 + 多张图片)
messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": evidence_prompt_grpo("图中有多少个红色的圆圈？")},
            {"type": "image", "image": "path/to/image1.jpg"},
            {"type": "image", "image": "path/to/image2.jpg"},
        ]
    }
]

# 处理视觉信息
prompt = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
image_inputs, _ = process_vision_info(messages)

# 生成回答
sampling_params = SamplingParams(temperature=0.7, max_tokens=512)
outputs = llm.generate(
    prompts=[prompt],
    sampling_params=sampling_params,
    multi_modal_data={"image": image_inputs}
)

# 输出结果
print(outputs[0].outputs[0].text)

运行评估脚本 (可选)

如果您需要复现论文中的评估结果，可以使用官方提供的脚本：

# 1. 生成预测结果
bash evisrag_scripts/predict.sh

# 2. 执行评估 (输出 EM, Accuracy, F1 等指标)
bash evisrag_scripts/eval.sh

注意：运行评估前，请确保测试数据已下载至指定目录（参考项目首页的 HuggingFace Collection 链接）。