ViDoRAG：基于动态迭代推理智能体的视觉文档检索增强生成

🔥 新闻

• 🎉 我们已发布评估代码，允许您自定义专属的评估流程。
• 🎉 我们的框架集成了多种嵌入模型，使您可以构建自己的检索器。
• 🎉 我们发布了 ViDoSeek 数据集，该数据集适用于大型富含视觉信息的文档集合中的检索增强生成任务。

🚀概述

• 我们推出了 ViDoSeek，这是一个专为富含视觉信息的文档检索—推理—回答设计的基准，完全适用于大规模文档语料库中 RAG 模型的评估。
• 我们提出了 ViDoRAG，一种新颖的 RAG 框架，采用多智能体、演员—评论家范式进行迭代推理，从而提升生成模型的抗噪能力。
• 我们引入了一种基于 GMM 的多模态混合检索策略，以有效整合视觉与文本两条检索路径。
• 大量实验表明我们的方法非常有效。ViDoRAG 显著优于强大的基线模型，性能提升了超过 10%，从而在 ViDoSeek 基准上树立了新的最先进水平。

🔍ViDoSeek 数据集

我们发布了 ViDoSeek 数据集，该数据集专为富含视觉信息的文档检索—推理—回答任务而设计。在 ViDoSeek 中，每个查询都有唯一的答案和特定的参考页码。

提供的 JSON 结构包括一个唯一标识符（uid），用于区分查询；查询内容（query）；参考答案（reference_answer）；以及元数据（meta_info），其中包含原始文件名（file_name）、参考页码（reference_page）、数据来源类型（source_type）和查询类型（query_type）：

{
    "uid": "04d8bb0db929110f204723c56e5386c1d8d21587_2",
    "query": "制备柳枝稷和甘蔗渣预处理过程中蒸汽爆炸的温度是多少？", 
    "reference_answer": "195-205 摄氏度", 
    "meta_info": {
        "file_name": "Pretreatment_of_Switchgrass.pdf", 
        "reference_page": [10, 11], 
        "source_type": "文本", 
        "query_type": "多跳" 
    }
}

您可以通过 Git LFS 从 Hugging Face 或 ModelScope 下载标注文件和原始文档。文件格式可参考 ./data/ExampleDataset。

下载数据集

bash scripts/ViDoSeek_down.sh

然后，您可以使用以下脚本将原始文件转换为图像：

python ./scripts/pdf2images.py

可选地，您还可以使用 OCR 模型或视觉—语言模型（VLMs）来识别图像中的文字：

## 传统 OCR 模型
python ./scripts/ocr_triditional.py 
## VLMs 作为 OCR 模型（可选）
python ./scripts/ocr_vlms.py 

💻 运行 ViDoRAG

ViDoRAG 是一种新颖的多智能体 RAG 框架，专为跨视觉文档的复杂推理任务而设计。ViDoRAG 采用基于高斯混合模型（GMM）的混合策略，以有效处理多模态检索任务。

依赖项

# 创建环境
conda create -n vidorag python=3.10
# 克隆项目
git clone https://github.com/alibaba-nlp/ViDoRAG.git
cd ViDoRAG
# 安装依赖
pip install -r requirements.txt

或者您也可以使用 uv 来安装依赖：

pip install uv
uv venv -p 3.10
uv sync

我们建议遵循 Colpali-engine 和 Transformer 库的指导，以安装最适合的版本。

以下是帮助您在自己的数据集上运行整个框架的分步指南。您也可以单独使用各个模块：

第一步：构建索引数据库

我们的框架建立在 Llama-Index 的基础上。我们会预先对语料库进行处理，然后建立索引数据库。

在对整个数据集进行嵌入之前，您可以先运行 ./llms/vl_embedding.py 来检查嵌入模型是否正确加载：

python ./llms/vl_embedding.py

之后，您可以运行 ingestion.py 对整个数据集进行嵌入：

# 文档摄取与多模态嵌入
python ./ingestion.py

第二步：运行多模态检索器

尝试使用基础的单模态搜索引擎：

from search_engine import SearchEngine
# 初始化引擎
search_engine = SearchEngine(dataset='ViDoSeek', node_dir_prefix='colqwen_ingestion',embed_model_name='vidore/colqwen2-v1.0')
# 检索一些结果
recall_results = search_engine.search('某个查询')

尝试使用带有 GMM 的动态单模态搜索引擎：

from search_engine import SearchEngine
# 初始化引擎
search_engine = SearchEngine(dataset='ViDoSeek', node_dir_prefix='colqwen_ingestion',embed_model_name='vidore/colqwen2-v1.0')
# 设置动态检索参数
search_engine.gmm = True
search_engine.input_gmm = 20 # 默认设置为 K
# 使用动态召回检索一些结果
recall_results = search_engine.search('某个查询')

尝试使用动态混合多模态搜索引擎：

from search_engine import HybridSearchEngine
# 初始化引擎
hybrid_search_engine = HybridSearchEngine(dataset='ViDoSeek', embed_model_name_vl='vidore/colqwen2-v0.1', embed_model_name_text='BAAI/bge-m3', gmm=True)
# 使用动态召回检索一些结果
hybrid_recall_results = hybrid_search_engine.search('某个查询')

可选地，您可以在 search_engine.py 中测试这些功能。

步骤3. 运行多智能体生成

您可以直接使用 vidorag_agents.py 中的脚本进行生成，也可以将其集成到您自己的框架中：

from llms.llm import LLM
vlm = LLM('qwen-vl-max')
agent = ViDoRAG_Agents(vlm)
answer=agent.run_agent(query='谁是蒂姆？', images_path=['./data/ExampleDataset/img/00a76e3a9a36255616e2dc14a6eb5dde598b321f_1.jpg','./data/ExampleDataset/img/00a76e3a9a36255616e2dc14a6eb5dde598b321f_2.jpg'])
print(answer)

步骤4. 运行评估

对于我们的端到端评估，我们采用基于大语言模型的评估方法：

python eval.py \
  --experiment_type retrieval_infer ## 可选值为 retrieval_infer/dynamic_hybird_retrieval_infer/vidorag
  --dataset ViDoSeek ## 数据集文件夹名称 
  --embed_model_name_vl ## 视觉-语言嵌入模型名称
  --embed_model_name_text ## 文本嵌入模型名称
  --embed_model_name ## 仅用于单一嵌入模型评估，当不需要使用视觉-语言或文本嵌入时
  --generate_vlm ## 视觉-语言模型名称，例如 gpt-4o/qwen-max-vl

📝 引用

@article{wang2025vidorag,
  title={ViDoRAG：基于动态迭代推理智能体的视觉文档检索增强生成},
  author={王秋晨、丁瑞雪、陈泽辉、吴伟琪、王世航、谢鹏俊、赵峰},
  journal={arXiv 预印本 arXiv:2502.18017},
  year={2025}
}

ViDoRAG 快速上手指南

ViDoRAG 是一个基于动态迭代推理智能体的视觉文档检索增强生成（RAG）框架，专为处理视觉丰富文档（如 PDF、图表混合文档）的复杂推理任务而设计。

环境准备

• 操作系统: Linux / macOS (推荐 Ubuntu 20.04+)
• Python 版本: 3.10
• 硬件要求: 建议配备 NVIDIA GPU 以加速嵌入模型和 VLM 推理
• 前置依赖:
  • Conda 或 uv (包管理工具)
  • Git LFS (用于下载大型数据集文件)

注意：由于 Transformer、Llama Index、Colpali Engine 和 Qwen 2.5 的最新版本可能存在兼容性问题，建议为检索任务和生成任务分别创建独立的虚拟环境。

安装步骤

1. 克隆项目

git clone https://github.com/alibaba-nlp/ViDoRAG.git
cd ViDoRAG

2. 创建环境并安装依赖

方式一：使用 Conda (推荐)

conda create -n vidorag python=3.10
conda activate vidorag
pip install -r requirements.txt

方式二：使用 uv (更快速)

pip install uv
uv venv -p 3.10
source .venv/bin/activate  # Linux/macOS
# source .venv\Scripts\activate  # Windows
uv sync

提示：安装完成后，建议参考 Colpali-engine 和 Transformer 官方文档确认版本兼容性。国内用户可使用清华或阿里镜像源加速 pip 安装：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 下载数据集 (可选)

如果需要运行官方基准测试，可下载 ViDoSeek 数据集：

bash scripts/ViDoSeek_down.sh

将 PDF 转换为图像：

python ./scripts/pdf2images.py

(可选) 使用 OCR 提取文本：

# 传统 OCR
python ./scripts/ocr_triditional.py 
# 或使用 VLM 作为 OCR
python ./scripts/ocr_vlms.py 

基本使用

以下是运行 ViDoRAG 核心流程的最简示例，包含索引构建、检索和生成三个关键步骤。

第一步：构建索引数据库

在嵌入整个数据集前，先验证嵌入模型是否加载正常：

python ./llms/vl_embedding.py

执行数据摄入和多模态嵌入：

python ./ingestion.py

第二步：运行多模态检索

你可以选择单模态、动态单模态或动态混合多模态检索。以下是最常用的动态混合多模态检索示例：

from search_engine import HybridSearchEngine

# 初始化混合搜索引擎
# 参数说明:
# dataset: 数据集名称
# embed_model_name_vl: 视觉 - 语言嵌入模型 (如 vidore/colqwen2-v0.1)
# embed_model_name_text: 文本嵌入模型 (如 BAAI/bge-m3)
# gmm: 启用基于高斯混合模型的动态检索策略
hybrid_search_engine = HybridSearchEngine(
    dataset='ViDoSeek', 
    embed_model_name_vl='vidore/colqwen2-v0.1', 
    embed_model_name_text='BAAI/bge-m3', 
    gmm=True
)

# 执行检索
query = "What is the temperature of Steam explosion?"
recall_results = hybrid_search_engine.search(query)

# 打印结果查看
print(recall_results)

第三步：运行多智能体生成

利用检索到的图像和查询进行推理生成：

from llms.llm import LLM
from vidorag_agents import ViDoRAG_Agents

# 初始化 VLM (例如使用阿里云 Qwen-VL-Max)
vlm = LLM('qwen-vl-max')

# 初始化智能体
agent = ViDoRAG_Agents(vlm)

# 运行推理
# images_path 为检索步骤返回的相关图片路径列表
answer = agent.run_agent(
    query='Who is Tim?', 
    images_path=[
        './data/ExampleDataset/img/00a76e3a9a36255616e2dc14a6eb5dde598b321f_1.jpg',
        './data/ExampleDataset/img/00a76e3a9a36255616e2dc14a6eb5dde598b321f_2.jpg'
    ]
)

print(answer)

第四步：端到端评估 (可选)

对整个流程进行自动化评估：

python eval.py \
  --experiment_type vidorag \
  --dataset ViDoSeek \
  --embed_model_name_vl vidore/colqwen2-v0.1 \
  --embed_model_name_text BAAI/bge-m3 \
  --generate_vlm qwen-vl-max