快速摘要
VRAG 是通义实验室开源的多模态检索增强生成框架，包含 VRAG-RL、VRAG、VimRAG 三大核心组件。 它通过强化学习驱动视觉语言模型（VLM）主动进行"从粗到细"的视觉感知，并引入多模态记忆图（Multimodal Memory Graph）将推理过程建模为有向无环图，从根本上解决了传统 RAG 在处理图片、文档、视频等视觉信息时的"状态盲区"问题。在多项权威基准测试中，VRAG-RL 相比现有方法提升了 20%～30%。 如果你正在做多模态知识库、文档问答、视频理解等相关工作，这个框架值得深入了解。往下看，莫潇羽@源码七号站 为你做更详细的原理拆解和实操指南。
一、为什么我们需要"视觉 RAG"？
在日常工作和学习中，我们接触到的信息远不止纯文本。技术手册里有大量的架构图，研究报告里有数据可视化图表，产品说明书里有爆炸图和流程图，社交媒体上更是充斥着图片和短视频。这些富含视觉信息的内容，承载着大量纯文本无法表达的关键细节——比如元素的空间位置、布局关系、颜色差异等等。
传统的检索增强生成（Retrieval-Augmented Generation，简称 RAG）技术在处理纯文本问答时已经相当成熟。它的基本思路是：先从外部知识库中检索出与问题相关的文档片段，再把这些片段作为上下文喂给大语言模型，让模型基于检索到的信息生成回答。这种方式有效缓解了大模型的"幻觉"问题，也让模型能够利用最新的外部知识。
但问题在于，一旦涉及到视觉内容，传统 RAG 就会遇到几个棘手的瓶颈。
第一个瓶颈是"视觉信息的表征困难"。 传统的文本 RAG 依赖 OCR（光学字符识别）把图片中的文字提取出来，然后按纯文本的方式进行检索和推理。但 OCR 只能提取文字，无法捕捉图表中元素的位置关系、颜色编码、布局结构等视觉语义信息。一张复杂的流程图，OCR 可能只能提取出零散的文字标签，完全丢失了流程的逻辑走向。
第二个瓶颈是"固定流水线的僵化"。 现有的多模态 RAG 方案大多采用固定的处理流程：先检索、再把检索结果拼接到上下文里、最后让模型生成答案。这种线性的流程缺乏灵活性，模型无法根据实际需要选择"再看一眼""放大某个区域"或"换个角度重新检索"这类人类在阅读复杂文档时会自然使用的策略。
第三个瓶颈是"推理能力的不足"。 即使把视觉信息成功输入到模型中，现有方法在处理需要多步推理的视觉问题时仍然表现欠佳。模型往往只是被动地"看一眼"检索到的图片，缺乏像人类一样主动观察、逐步聚焦、反复验证的能力。
举个具体的例子来说明这些瓶颈有多严重。假设一份产品报告中有一张柱状图，横轴是月份、纵轴是销售额，图中还用不同颜色区分了不同产品线。当用户问"哪个产品线在第二季度增长最快"时，OCR 可能只能提取出零散的数字标签，但无法理解哪个颜色对应哪个产品线，也无法判断柱子的高低变化趋势。传统的文本 RAG 面对这种问题基本无能为力。即便是一些支持图片输入的多模态方案，如果图表中文字太小或图片分辨率不够，模型也很难准确地读取具体数值。
再比如，在技术架构文档中，一张系统架构图可能包含几十个组件和它们之间的连接关系。OCR 或许能提取出组件名称，但完全丢失了组件之间的拓扑关系——哪个组件调用了哪个组件、数据流的方向是什么、哪些组件属于同一个模块等等。这些空间和拓扑信息，本质上只有通过"看图"才能获取。
正是为了解决这些问题，通义实验室推出了 VRAG 这个项目。莫潇羽@源码七号站 认为，这个项目的核心思想可以用一句话概括：让 AI 像人类一样，学会主动地、渐进地去"看"和"想"。 这不是简单地给模型"看一张图"就了事，而是赋予模型一套完整的视觉感知和推理工具，让它能够根据问题的需要，自主决定去看什么、看哪里、怎么看。
二、VRAG 项目全景：三大组件各司其职
VRAG 项目并不是一个单一的模型或算法，而是一个包含三大核心组件的完整框架体系。这三个组件分别是 VRAG、VRAG-RL 和 VimRAG，它们之间有着清晰的功能分工和递进关系。
2.1 VRAG——纯视觉 RAG 智能体
VRAG 是整个框架的基础智能体。它的核心定位是做一个"纯视觉"的 RAG 智能体（Purely Visual RAG Agent），不依赖 OCR 将图片转成文字，而是直接用视觉语言模型来处理原始的图片信息。
VRAG 最突出的特点是它的渐进式视觉感知机制（Coarse-to-Fine Visual Perception）。这个机制模拟了人类阅读复杂文档时的自然行为模式：
当我们翻开一份陌生的技术报告时，通常不会逐字逐句地从第一个字读到最后一个字。我们会先快速浏览整个页面，了解大致的结构和主题；然后把目光聚焦到与我们关注点相关的区域，比如某个数据图表或某段关键描述；接着我们可能会凑近去看图表中某根折线的具体数值，或者放大某个注释文字来获取细节信息。
VRAG 正是按照这个思路来设计视觉感知流程的。它定义了一个视觉感知动作空间（Visual Perception Action Space），包含以下几类核心动作：
- 搜索动作（Search）：模型根据当前的思考，生成一个检索查询（query），从语料库中检索相关的图片或文档页面。
- 区域选择动作（Region）：模型在检索到的图片上选定一个感兴趣的区域，用坐标框（bounding box）来标记。格式类似于
<region> [xmin, ymin, xmax, ymax] </region>。 - 裁剪与缩放动作（Crop & Scale）：在选定区域后，系统自动对该区域进行裁剪和放大，生成更高分辨率的局部图像，供模型进一步分析。
通过这些动作的组合使用，VRAG 能够从宏观到微观逐步提取视觉信息，而不是一次性把所有图片塞进上下文窗口。这种方式不仅提高了模型对复杂视觉信息的理解精度，也有效控制了视觉 token 的消耗量——因为高分辨率图片会占用大量的 token，而 VRAG 只在需要细看的时候才会放大特定区域。
2.2 VRAG-RL——强化学习训练框架
如果说 VRAG 定义了智能体"应该做什么"，那么 VRAG-RL 解决的就是"如何让智能体学会做"。VRAG-RL 是整个项目的训练框架，它创新性地把强化学习（Reinforcement Learning）引入到多模态 RAG 智能体的训练过程中。
在深入理解 VRAG-RL 之前，莫潇羽@源码七号站 先帮大家梳理一下它要解决的核心训练难题。
传统的监督微调（SFT）方法在训练 RAG 智能体时存在一个根本性的问题：标注数据很难覆盖所有可能的推理路径。 人类标注员在制作训练数据时，通常只能标注一条"标准答案路径"，但实际上达成正确答案可能有多条不同的路径。而且，面对不同的问题和不同的知识库内容，最优的检索策略和推理路径是动态变化的，很难用固定的监督信号来穷举。
强化学习的优势恰好在于此——它不需要人类告诉模型每一步该怎么做，而是让模型自己去探索，通过与环境的交互获得反馈（奖励信号），从而自主学习最优策略。
VRAG-RL 采用了 GRPO 算法（Group Relative Policy Optimization，组相对策略优化） 作为核心的强化学习训练算法。GRPO 的基本思路是：对于同一个问题，让模型生成一组（group）不同的推理轨迹（trajectory），然后以组内平均奖励为基准线，对表现好的轨迹给予正向梯度更新，对表现差的轨迹给予负向梯度更新。这种方式避免了传统 PPO 算法需要训练一个额外价值网络（value network）的开销，训练效率更高。
VRAG-RL 的奖励设计
奖励函数的设计是强化学习成败的关键，VRAG-RL 在这方面做了精心的设计，整合了三个维度的信号：
结果奖励（Outcome Reward）：评估模型最终给出的答案是否正确。这里使用了基于模型的评判方式，让一个判别模型对生成的答案和标准答案进行比对打分，得到一个 0 或 1 的结果奖励。
检索奖励（Retrieval Reward）：评估模型在与搜索引擎交互过程中，检索到的内容是否相关。如果模型改写的查询能够检索到包含答案线索的文档，那么这次检索就会获得正向奖励。这个设计非常重要，因为它弥补了用户原始提问和检索器之间的语义鸿沟——用户的问题往往是自然语言描述，不一定适合直接用来检索。
格式奖励（Pattern Reward）：确保模型的输出遵循预定义的格式规范，比如正确使用 <think>、<search>、<region> 等标签。在训练初期（冷启动阶段），格式奖励的权重会设得稍高一些，帮助模型先学会基本的交互模式。
VRAG-RL 的训练流程
整个训练过程可以概括为以下几个阶段：
冷启动阶段（Cold Start）：首先用少量的高质量 SFT 数据对基座模型进行微调，让模型掌握基本的工具调用格式（如何生成搜索查询、如何输出区域坐标等）。在这个阶段，GRPO 训练中的 KL 散度惩罚系数通常设为 0，以便给模型更大的探索空间。
强化学习阶段（RL Training）：在冷启动的基础上，模型开始与本地部署的搜索引擎进行真实交互。每一轮训练中，模型针对一个问题生成多条推理轨迹，每条轨迹包含多轮"思考-动作-观察"的交互。轨迹完成后，系统计算综合奖励，然后通过 GRPO 算法更新模型参数。
值得一提的是，VRAG-RL 的训练框架在设计上有很强的扩展性。搜索引擎是本地部署的，不需要调用外部 API，训练过程中的检索操作基本是零延迟。而且训练框架支持挂载不同的外部工具，你可以根据自己的应用场景来定制工具集。
2.3 VimRAG——记忆图驱动的推理框架
VimRAG 是整个项目中技术含量最高、也是最新发布的组件。如果说 VRAG 解决了"如何看"的问题，那么 VimRAG 解决的是"如何记住看过的东西并有效利用它们"的问题。
在多轮检索-推理的过程中，智能体需要处理不断增长的交互历史——之前检索了什么、看到了什么、做了什么判断、得出了什么中间结论。传统的做法是把所有历史记录线性地拼接起来（这就是 ReAct 范式的做法），但这种方式有两个严重的问题：
状态盲区（State Blindness）：当历史记录越来越长时，模型容易"忘记"自己之前已经做过的检索，导致重复搜索同样的内容。研究团队的实验发现，在传统的线性历史管理方式下，智能体的重复检索率高得惊人。
视觉 token 爆炸（Visual Token Explosion）：图片和视频帧在模型内部会被转换成大量的视觉 token。随着检索轮次增加，历史中积累的视觉 token 数量会迅速增长，很快就会撑爆模型的上下文窗口。
VimRAG 通过两个核心创新来解决这些问题：
多模态记忆图（Multimodal Memory Graph）
VimRAG 将智能体的推理过程建模为一个动态有向无环图（Dynamic DAG），而不是一条线性的历史记录链。图中的每个节点代表推理过程中的一个"状态"，包含了该步骤的动作类型、检索到的内容、中间思考结果等信息。节点之间的有向边则表示推理步骤之间的逻辑依赖关系。
举个例子来帮助理解。假设智能体在回答一个问题时经历了以下过程：第一步搜索到了一张包含图表的文档页面；第二步对图表区域进行了裁剪放大；第三步发现图表中引用了另一个概念，于是又进行了第二次搜索；第四步综合前面的信息给出了答案。
在传统的线性历史中，这四步会被简单地按时间顺序串联起来。但在 VimRAG 的记忆图中，第二步会作为第一步的子节点（因为裁剪是基于第一步检索结果的进一步分析），第三步可能同时依赖第一步和第二步（因为新的搜索需求来源于前两步的分析），第四步则汇总了所有前置节点的信息。
这种图结构带来了几个关键优势：
避免重复检索：通过图结构，智能体可以清楚地知道自己已经检索过哪些内容，避免冗余的重复搜索。
推理路径回溯：当需要验证某个中间结论时，可以沿着图中的边快速追溯到相关的证据节点。
记忆剪枝：图中那些被证明对最终答案没有贡献的"死胡同"节点可以被剪枝掉，只保留对推理有实际价值的信息，从而控制记忆的大小。
图调制的视觉记忆编码（Graph-Modulated Visual Memory Encoding）
解决了"记住什么"的问题后，VimRAG 还需要解决"怎么记"的问题——特别是如何高效地管理视觉 token。
VimRAG 提出了一种基于能量分配的视觉记忆编码机制。简单来说，不是所有记忆图中的视觉信息都需要以同样高的分辨率保存。VimRAG 会根据三个维度来评估每个记忆节点的重要性：
语义相关性（Semantic Relevance）：该节点的内容与当前问题的相关程度。相关性越高，保留的视觉细节越多。
拓扑位置（Topological Position）：该节点在推理图中的位置。处于推理关键路径上的节点（比如最终答案直接依赖的节点）会获得更多的 token 配额。
时间衰减（Temporal Decay）：越早期的记忆，其重要性会随时间逐渐衰减，就像人类的遗忘曲线一样。很久以前检索到的、且没有被后续推理引用的图片，其视觉 token 会被压缩甚至丢弃。
通过这种动态的 token 分配机制，VimRAG 能够在有限的上下文窗口内，把"带宽"优先分配给最重要的视觉证据。实验数据表明，这种策略平均只需要约 2700 个 token 就能在图像和视频任务上取得比全量保存更好的效果。
图引导策略优化（Graph-Guided Policy Optimization，GGPO）
GGPO 是 VimRAG 在训练层面的核心创新。它解决了标准强化学习奖励机制在多步推理任务中的一个根本性缺陷——信用分配问题（Credit Assignment Problem）。
想象一个场景：智能体执行了一条包含五步操作的推理轨迹，最终答案是错误的。在传统的基于结果的奖励机制中（outcome-based reward），这五步操作都会被"惩罚"。但事实上，前三步的检索可能是完全正确的，只是第四步的推理出了问题。如果我们不加区分地惩罚所有步骤，模型就可能错误地"忘掉"那些本来正确的检索策略。
反过来，如果一条推理轨迹碰巧得到了正确答案，但其中有两步检索是完全冗余的（检索到了无关内容），传统的奖励机制也会错误地"鼓励"这些冗余操作。
GGPO 利用记忆图的结构信息来解决这个问题。它会分析图中每个节点的实际贡献，将节点分为有效证据节点（Evidence Nodes）和噪声节点（Noise Nodes）。判断的依据是：如果把某个节点的信息去掉后，仍然能得到正确答案，那这个节点就是噪声节点；如果去掉后答案变差了，那它就是有效证据节点。
在计算策略梯度时，GGPO 会对不同类型的节点施加不同的掩码（mask）：
在成功轨迹中，噪声节点的正向梯度会被遮蔽，防止模型学到冗余操作。在失败轨迹中，有效证据节点的负向梯度会被遮蔽，避免"倒洗澡水时把孩子也倒掉"。
这种机制的数学表达虽然有些复杂，但核心逻辑其实非常直观。你可以把它理解为一个"精确的教练"——它不会因为比赛输了就批评球员的每一个动作，而是能精确指出哪些动作是好的（应该保持），哪些动作是差的（应该改进）。相比之下，传统的基于结果的奖励机制就像一个"粗放的教练"，赢了就全队表扬，输了就全队批评，这显然不利于球员的成长。
在实际训练中，GGPO 的引入让训练收敛速度明显加快，训练出的模型在不同测试配置下也表现得更加稳健。消融实验显示，与不使用图结构剪枝的标准 GSPO 方法相比，GGPO 在各种难度级别的任务上都保持了一致的优势。
三、技术架构与工作流程详解
了解了三大组件的原理后，莫潇羽@源码七号站 再来帮你从整体视角理解 VRAG 的工作流程和技术架构。
3.1 整体架构
VRAG 项目的代码仓库结构清晰，主要包含以下几个部分：
VRAG/
├── demo/ # 演示应用
│ ├── app.py # VRAG 的 Streamlit 演示
│ ├── vimrag_app.py # VimRAG 的 Streamlit 演示
│ ├── vrag_agent.py # VRAG 智能体实现
│ └── vimrag_agent.py # VimRAG 智能体实现
├── search_engine/ # 多模态检索引擎
│ ├── models/ # 嵌入模型（GVE、Qwen3-VL）
│ ├── corpus/ # 语料库和索引存储
│ ├── search_engine.py # 核心搜索引擎
│ └── search_engine_api.py # FastAPI 服务接口
├── VRAG-RL/ # 强化学习训练框架
│ ├── verl/ # 训练基础设施
│ ├── vrag_agent/ # 训练用智能体
│ └── train_grpo_qwen2_5_vl_7b.sh # 训练启动脚本
├── requirements.txt # 依赖列表
└── run_demo.sh # 一键启动脚本从架构上看，VRAG 的运行依赖三个核心模块的协同工作：
多模态搜索引擎（Search Engine）：这是整个系统的"知识后端"，负责管理语料库和执行检索。它支持图片、PDF 页面、视频片段等多种类型的视觉语料，使用先进的视觉嵌入模型（如 ColPali、GVE、Qwen3-VL 等）将视觉内容编码为向量，并建立高效的检索索引。搜索引擎通过 FastAPI 提供 RESTful 接口，默认运行在 8001 端口。
视觉语言模型（VLM）推理服务：这是系统的"推理大脑"，负责理解问题、规划推理步骤、生成检索查询、分析检索结果并最终生成答案。VRAG 使用的基座模型包括 Qwen2.5-VL-7B（经过 VRAG-RL 训练后的版本）和 Qwen3-VL 等。在本地部署模式下，模型通过 vLLM 框架提供高效的推理服务，默认运行在 8002 端口。
智能体（Agent）：这是连接搜索引擎和推理模型的"调度中枢"。它维护着推理的状态（在 VimRAG 中是记忆图），协调模型与搜索引擎之间的多轮交互，并管理视觉感知动作的执行。
3.2 推理工作流程
一次完整的 VRAG 推理过程大致如下：
第一步：问题输入。 用户提出一个问题，比如"这份技术报告中第三季度的营收趋势如何？"
第二步：初始思考。 智能体将问题输入 VLM，模型开始第一轮思考。它会分析问题的意图，判断需要什么信息，然后生成一个搜索查询。比如模型可能会输出：<think>用户想了解第三季度的营收趋势，我需要找到包含营收数据的图表。</think><search>第三季度营收趋势图表</search>
第三步：检索与观察。 搜索引擎收到查询后，从语料库中检索出最相关的图片（可能是一页包含营收图表的 PDF 页面），返回给智能体。智能体将检索到的图片插入到模型的上下文中。
第四步：深入感知（可选）。 模型查看检索到的图片后，可能发现图表太小、细节看不清。这时它会使用视觉感知动作，选择图表所在的区域进行裁剪放大：<think>图表在页面的右下角，我需要放大查看具体数据。</think><region> [450, 300, 800, 600] </region>
第五步：反复迭代。 如果放大后的图表信息已经足够回答问题，模型就会生成最终答案。如果还需要更多信息（比如需要对比上一季度的数据），模型会发起新的检索。这个过程可以进行多轮，直到模型认为信息充分为止。
第六步：生成答案。 模型综合所有收集到的视觉信息，生成最终的回答，并以 <answer> 标签包裹输出。
在 VimRAG 中，上述每一步都会作为节点被记录到多模态记忆图中，图的结构会随着推理的推进而动态演化。整个推理过程支持实时的 DAG 可视化，你可以像看流程图一样清晰地看到模型的推理路径——哪些节点是检索操作、哪些是视觉感知操作、哪些是最终的推理汇总，节点之间的依赖关系一目了然。这个可视化功能对于理解模型行为、排查推理错误非常有帮助。
另外，VRAG 还支持流式输出（Streaming Output）功能。在实际使用中，模型的回答是一个字一个字实时输出的，而不是让用户等待整个推理过程完成后才看到结果。在推理过程中，用户还可以看到模型当前正在执行的动作（比如正在搜索、正在分析图片等），增强了交互体验的透明度和可控感。
值得一提的是，VRAG 还支持扩展思考模式（Extended Thinking Mode）。开启这个模式后，模型会在每一步动作之前进行更深入、更细致的思考，产生更长的思维链。这在处理特别复杂的多步推理问题时很有用，虽然会增加一些推理时间，但通常能换来更准确的答案。
四、实际操作：从环境搭建到运行 Demo
理论讲完了，莫潇羽@源码七号站 接下来带大家走一遍实际操作流程。VRAG 提供了两种主要的使用模式：VimRAG 模式（推荐，可调用云端 API，无需本地 GPU）和 VRAG 本地模式（需要高性能 GPU）。
4.1 环境准备
首先确保你的系统安装了 Conda（Miniconda 或 Anaconda 均可），然后创建一个 Python 3.10 的虚拟环境。这里建议使用 3.10 版本，因为项目的依赖库在这个版本下经过了充分测试。
# 创建虚拟环境
conda create -n vrag python=3.10
# 激活环境
conda activate vrag接下来克隆项目代码并安装依赖：
# 克隆代码仓库
git clone https://github.com/Alibaba-NLP/VRAG.git
# 进入项目目录
cd VRAG
# 安装依赖
pip install -r requirements.txt安装过程可能需要几分钟，取决于你的网络环境。主要的依赖包括 Streamlit（用于 Web 演示界面）、FastAPI（用于搜索引擎服务）、各种深度学习库等。
4.2 使用 VimRAG 模式（推荐新手使用）
VimRAG 模式是最简单的上手方式，因为它通过云端 API 调用大模型，不需要在本地部署动辄几十 GB 的模型权重。你只需要一个 DashScope 的 API Key。
一键启动方式：
# 设置 API Key 环境变量
export DASHSCOPE_API_KEY=你的_api_key
# 一键启动
./run_demo.sh vimrag启动成功后，系统会自动开启搜索引擎和 Streamlit 演示界面。打开浏览器访问提示的地址（通常是 http://localhost:8501），你就可以看到一个交互式的演示页面了。
手动分步启动方式：
如果你想更精细地控制各个组件，也可以手动启动：
# 终端 1：启动搜索引擎
python search_engine/search_engine_api.py
# 终端 2：启动 Streamlit 演示界面
streamlit run demo/vimrag_app.py手动启动的好处是，你可以分别观察搜索引擎和前端界面的日志输出，方便排查问题。
4.3 使用 VRAG 本地模式（需要高性能 GPU）
如果你有 A100 80G 或同等级别的 GPU，可以选择完全本地化的 VRAG 模式。这种模式下，大模型也在本地运行，不依赖任何外部 API。
一键启动方式：
./run_demo.sh vrag手动分步启动方式：
# 终端 1：启动搜索引擎（端口 8001）
python search_engine/search_engine_api.py
# 终端 2：启动 vLLM 模型推理服务（端口 8002）
vllm serve autumncc/Qwen2.5-VL-7B-VRAG \
--port 8002 \
--host 0.0.0.0 \
--limit-mm-per-prompt image=10 \
--served-model-name Qwen/Qwen2.5-VL-7B-Instruct
# 终端 3：启动 Streamlit 演示界面
streamlit run demo/app.py这里需要注意几个参数：--limit-mm-per-prompt image=10 限制了每次推理请求中最多包含 10 张图片，这是为了控制显存占用；--served-model-name 设置了模型的服务名称，确保与智能体代码中的调用名称一致。
4.4 编程接口调用
除了 Web 演示界面，VRAG 也提供了编程接口，方便你集成到自己的应用中。
VimRAG 编程调用示例：
import os
from demo.vimrag_agent import VimRAG
# 创建 VimRAG 智能体实例
agent = VimRAG(
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
search_url="http://localhost:8001/search",
model_name="qwen3.5-plus",
api_key=os.environ.get("DASHSCOPE_API_KEY"),
enable_thinking=True # 开启思考模式，可以看到模型的推理过程
)
# 运行查询并流式输出结果
for event in agent.run({"query": "你的问题"}):
if event["event"] == "answer":
print(event["content"])VRAG 本地模型编程调用示例：
from demo.vrag_agent import VRAG
# 创建 VRAG 智能体实例（使用本地模型）
vrag = VRAG(
base_url="http://0.0.0.0:8002/v1",
search_url="http://0.0.0.0:8001/search",
generator=False,
api_key="EMPTY"
)
# 运行查询
answer = vrag.run("你的问题")可以看到，编程接口的使用非常简洁。enable_thinking=True 参数开启后，你可以在输出中看到模型每一步的思考过程，这对于调试和理解模型行为很有帮助。
五、构建你自己的多模态知识库
VRAG 的一个很大的实用价值在于，它允许你构建自己的多模态检索语料库。你可以把自己的文档、图片、视频等内容导入系统，构建一个专属的多模态知识库，然后用 VRAG 来进行问答。
5.1 支持的语料类型
VRAG 的搜索引擎支持三种主要的语料类型：
图片语料：最简单直接的方式。把你的图片文件（支持 JPG、PNG 等常见格式）直接放到 search_engine/corpus/ 目录下即可。搜索引擎会自动扫描目录中的图片文件，使用视觉嵌入模型对每张图片进行编码，生成可检索的向量索引。
PDF 语料：由于 VRAG 是纯视觉处理方式，PDF 文件需要先被转换成图片（每页 PDF 转换成一张图片）。项目提供了现成的转换脚本来完成这个工作。转换后的图片放入语料目录即可。这种方式的好处是完整保留了 PDF 页面的视觉布局信息——包括图表、表格、公式、图文混排等——不会像 OCR 方式那样丢失视觉语义。
视频语料：对于视频内容，VRAG 需要先将长视频切分成短片段。项目同样提供了切分脚本。切分后的视频片段会被抽帧处理，关键帧作为视觉语料被编入索引。
5.2 构建检索索引
语料准备好之后，只需要几行 Python 代码就能构建检索索引：
from search_engine.search_engine import SearchEngine
# 初始化搜索引擎（会自动扫描 corpus 目录下的语料）
engine = SearchEngine()
# 构建索引（会自动使用视觉嵌入模型对语料进行编码）
engine.build_index()索引构建过程可能需要一些时间，取决于语料库的规模和你的硬件配置。一个贴心的设计是，索引会自动定期保存检查点（checkpoint）。如果构建过程因为某些原因中断了（比如机器重启），重新运行时会自动从上一个检查点继续，不需要从头开始。这对于处理大规模语料库时非常实用。
搜索引擎目前集成了几种主流的视觉嵌入模型，包括 ColPali（一种专为文档图像设计的视觉检索模型）和 GVE（通用视觉嵌入模型）以及 Qwen3-VL 的嵌入模型。你可以根据自己的语料特点选择合适的嵌入模型。
5.3 仅启动搜索引擎
如果你只想使用 VRAG 的搜索引擎功能（比如集成到你自己的应用中），可以单独启动搜索引擎服务：
./run_demo.sh search或者手动启动：
python 
