DeepEyesV2：开源多模态智能体框架，融合工具链实现复杂场景可靠推理

一、DeepEyesV2是什么？

DeepEyesV2是一款开源的多模态智能体框架，以Qwen-2.5-VL系列模型为基础，核心创新在于将视觉理解、代码执行与网络搜索三大能力深度融合进单一推理循环，通过“冷启动微调+强化学习”双阶段训练体系，为复杂场景提供端到端的可靠推理解决方案。项目开源了完整的训练流程、高质量标注数据、预训练模型checkpoint及标准化评估工具链，支持模型自主决策工具调用策略，在真实世界理解、数学推理、搜索密集型任务等场景中表现优异，适用于多模态Agent研究、工具增强LLM开发及复杂推理任务落地，为开发者和研究者提供低门槛、高可用的技术支撑。

从本质来看，DeepEyesV2并非单一功能模型，而是一套“基础模型+工具生态+训练体系+评估标准”的全栈解决方案：以Qwen-2.5-VL-7B/32B-Instruct为多模态理解底座，通过冷启动微调（SFT）注入工具使用基础能力，再通过强化学习（RL）优化工具调用策略，最终实现“视觉理解→任务拆解→工具匹配→结果验证→推理闭环”的全流程自动化。

简单来说，DeepEyesV2的核心定位是：为多模态模型搭建“工具使用桥梁”，打破“被动理解”与“主动决策”的壁垒，使其能应对真实世界中需要动态补充信息、精确计算验证、多步骤协作的复杂任务。项目完全开源核心代码、训练数据、模型权重及评估工具，无商业使用限制，既适合科研人员探索多模态Agent的技术边界，也能满足工程师快速落地复杂推理场景的需求。

二、功能特色

DeepEyesV2的核心竞争力源于“多模态能力与工具链的深度耦合”，相比传统多模态模型和单一工具增强方案，具备以下四大核心特色：

1. 工具链深度融合：推理循环内无缝协同

传统工具增强模型常存在“工具调用与推理脱节”“多工具切换卡顿”“需手动指定工具类型”等问题，而DeepEyesV2实现了视觉理解、代码执行、网络搜索的三位一体整合，且所有工具调用均在单一推理循环内完成，无需中断推理流程，确保决策的连贯性与可靠性。

• 代码执行：Jupyter风格沙箱赋能精确计算
  内置轻量级Jupyter代码沙箱，支持Python代码实时执行，可处理数学计算、数据统计、图像特征提取、公式推导等需要精确验证的任务。沙箱状态通过Redis分布式存储，支持多轮推理中保持上下文一致性——例如先通过代码解析图像中的数据表格，再基于解析结果进行趋势分析，无需重复输入数据。同时支持代码白名单机制，仅允许安全操作（如numpy、pandas计算），规避恶意代码风险。

• 网络搜索：文本/图像双模式补全信息缺口
  集成文本搜索与图像搜索双模块：文本搜索可调用第三方API（如百度、必应）获取实时信息、专业知识（如“2025年行业标准数据”“陌生概念定义”）；图像搜索基于MMSearch-R1缓存机制，快速匹配相似图像及关联属性（如“识别未知植物后搜索其生长习性”“对比产品图像获取价格信息”），解决多模态任务中“信息缺失”“时效性不足”的问题。

• 自适应工具选择：无需手动干预的智能匹配
  模型通过训练习得“任务-工具”映射逻辑，无需开发者手动指定工具类型：面对纯文本简单问答（如“猫的天敌是什么”）直接输出答案；遇到数学题、数据处理任务自动调用代码执行；涉及未知概念、实时信息则触发网络搜索；处理图文混合任务时，自动结合视觉理解与工具能力完成推理，实现“任务复杂度→工具选择”的动态适配。

2. 双阶段高质量训练数据：筑牢模型能力根基

模型的可靠推理能力依赖高质量数据支撑，DeepEyesV2构建了“冷启动SFT数据+强化学习RL数据”的互补数据集，经过多轮人工筛选与自动清洗，确保数据的多样性、准确性与标注精细度，覆盖多模态复杂场景的工具使用需求。

两类数据均采用统一的JSON格式，可直接适配LLaMA-Factory和verl训练框架，无需额外数据转换，降低训练门槛。

3. 复杂场景适配能力：多基准测试表现优异

DeepEyesV2在多项主流基准测试中展现出强竞争力，尤其在“多模态理解+工具协作”的复杂任务中，性能显著优于传统多模态模型和单一工具增强方案：

• 真实世界理解任务：在EgoExoBench（第一/第三视角视频理解）、MME（多模态综合能力评估）中，通过视觉信息解析+环境信息搜索，任务准确率比传统多模态模型提升15%-20%，能精准处理家居导航、工业质检等场景的复杂交互需求；

• 数学与数据推理任务：在MMMath（多模态数学推理）、ChartQA（图表问答）中，通过代码执行验证计算结果，推理正确率提升25%以上，可处理几何图形计算、多维度数据统计、公式推导等复杂问题；

• 搜索密集型任务：在SearchMM（搜索密集型多模态任务）、RealWorldQA（真实世界问答）中，工具调用准确率达89%，任务完成效率提升40%，能高效处理“基于图像的产品价格查询”“陌生场景信息补全”等需要外部信息的任务；

• 工具组合任务：在多步骤复杂任务（如“解析图像数据→计算关键指标→对比行业标准→生成报告”）中，模型能自主组合代码执行与搜索工具，工具使用效率比SFT阶段提升30%，避免无效调用与重复操作。

4. 可解释的动态行为分析：助力技术迭代与落地

DeepEyesV2不仅提供模型能力，还通过实验揭示了多模态智能体的任务自适应规律，为开发者优化模型、适配场景提供明确指引：

• 模型会根据任务复杂度动态调整工具调用策略：简单任务（如“识别图像中的物体”）仅依赖视觉理解；中等复杂度任务（如“计算图像中物体数量”）调用单一工具；高复杂度任务（如“分析图像数据并生成行业对比报告”）组合使用多种工具；

• 强化学习阶段显著提升模型的“上下文感知能力”：处理多轮对话或多步骤任务时，模型能记忆前序工具调用结果，避免重复计算或搜索，例如先通过代码提取图像中的销售数据，后续分析趋势时直接复用该数据，提升推理效率；

• 开源了完整的行为分析工具：开发者可通过behavior_analysis/目录下的脚本，可视化模型在不同任务中的工具调用轨迹、决策路径，快速定位模型短板（如某类任务工具调用不精准），针对性优化训练数据或参数。

三、技术细节

DeepEyesV2的技术架构围绕“基础层-工具层-训练层-应用层”四层设计，各模块分工明确、协同高效，确保多模态理解与工具链的深度融合，以下是核心技术细节解析：

3.1 技术架构总览

DeepEyesV2的四层架构形成了“能力支撑-工具赋能-模型优化-场景落地”的完整链路，各层核心组件、作用及依赖环境如下表所示：

3.2 核心技术模块详解

（1）基础模型适配与改造

DeepEyesV2选择Qwen-2.5-VL-7B/32B-Instruct作为基础模型，主要基于三点核心考量：① 该模型具备业界领先的多模态理解能力，支持图像、文本的深度语义关联，指令跟随性优异；② 开源可商用，无二次开发限制；③ 模型架构灵活，支持LoRA轻量化微调，降低训练硬件门槛。

为适配工具调用需求，项目对基础模型进行了轻量化改造：

• 输入层优化：支持“图像路径/URL+文本指令+工具调用轨迹”的混合输入格式，通过视觉编码器处理图像信息，与文本信息融合为统一嵌入向量；

• 输出层增强：增加“工具调用标记模块”，支持模型生成标准化的工具调用指令（如{"tool":"code_execution","input":"python代码"}），确保工具能精准解析；

• 上下文管理：扩展模型上下文窗口至4096 tokens，支持长序列工具调用轨迹与多轮推理的上下文存储。

（2）双阶段训练流程：从“会用工具”到“用好工具”

DeepEyesV2的训练分为“冷启动微调”和“强化学习”两个阶段，循序渐进提升模型的工具使用能力与推理可靠性：

① 冷启动微调（Cold Start SFT）：掌握工具使用基础能力

• 核心目标：让模型学会“工具调用语法”“任务-工具匹配逻辑”“工具结果整合方法”，例如识别数学题时生成合法Python代码，收到工具返回结果后能提炼关键信息并输出最终答案；

• 训练框架：基于LLaMA-Factory实现，支持LoRA轻量化微调，仅训练模型的部分参数（如注意力层），降低硬件需求（单张A100 40GB即可启动7B模型训练）；

• 数据处理：使用DeepEyesV2_SFT数据集，每条样本包含“输入（图文）+工具调用指令+工具返回结果+最终答案”的完整链路，训练时模型学习“输入→工具调用→结果整合”的端到端映射；

• 快速启动脚本：项目提供cold_start/run_cold_start.sh，用户可通过修改参数快速启动训练，核心配置示例如下：

  # 冷启动微调核心配置
  MODEL_NAME_OR_PATH="Qwen/Qwen-2.5-VL-7B-Instruct" # 基础模型路径
  DATA_PATH="honglyhly/DeepEyesV2_SFT" # 数据集路径（Hugging Face或本地）
  OUTPUT_DIR="./cold_start_sft_model" # 模型保存目录
  MAX_SEQ_LENGTH=4096 # 最大序列长度
  BATCH_SIZE=8 # 批次大小（显存不足可设为4）
  LEARNING_RATE=2e-5 # 学习率
  NUM_TRAIN_EPOCHS=3 # 训练轮数
  GRADIENT_ACCUMULATION_STEPS=4 # 梯度累积步数
  USE_PEFT=True # 启用LoRA微调
  LORA_RANK=8 # LoRA秩
  FP16=True # 启用FP16精度加速训练
  
  # 启动训练命令
  python -m llmtuner.train \
   --model_name_or_path $MODEL_NAME_OR_PATH \
   --data_path $DATA_PATH \
   --output_dir $OUTPUT_DIR \
   --max_seq_length $MAX_SEQ_LENGTH \
   --batch_size $BATCH_SIZE \
   --learning_rate $LEARNING_RATE \
   --num_train_epochs $NUM_TRAIN_EPOCHS \
   --gradient_accumulation_steps $GRADIENT_ACCUMULATION_STEPS \
   --use_peft $USE_PEFT \
   --lora_rank $LORA_RANK \
   --fp16 $FP16

② 强化学习（RL）：优化工具调用策略

• 核心目标：解决冷启动微调模型“工具调用不精准、效率低、复杂任务不会组合工具”的问题，通过奖励机制强化优质工具调用策略，提升推理可靠性与效率；

• 训练框架：基于火山引擎开源的verl库实现，该库专为LLM强化学习设计，支持PPO（Proximal Policy Optimization）、DPO（Direct Preference Optimization）等经典算法，兼容多模态模型；

• 训练流程：

1. 轨迹生成：使用冷启动微调后的模型处理DeepEyesV2_RL数据集，生成“任务→工具调用轨迹→结果”的样本；

2. 奖励计算：通过评估服务器对生成样本打分，奖励维度包括“任务完成度（权重0.5）、工具调用效率（权重0.3）、结果准确性（权重0.2）”，对无效调用、重复调用施加惩罚；

3. 模型更新：基于PPO算法，以奖励信号为目标更新模型参数，强化优质工具调用策略，弱化低效策略；

• 环境依赖：强化学习需提前部署三大组件：

• 代码沙箱集群：部署多个Jupyter沙箱实例，通过Redis共享状态，缓解高并发下的代码执行压力；

• 搜索模块：配置文本搜索API（可替换为自定义接口）和图像搜索缓存，确保搜索能力稳定；

• 评估服务器：基于Flask搭建，实时接收模型生成的轨迹样本并返回奖励分数。

（3）工具链集成技术：无缝协同的核心保障

① 代码沙箱技术细节

• 工作流程：模型生成标准化工具调用指令后，工具管理器解析指令类型，若为代码执行则将代码发送至空闲的Jupyter沙箱实例；沙箱执行代码并捕获输出结果（包括打印日志、生成的文件、图像），通过Redis存储结果并返回给模型；模型结合结果继续推理，形成闭环；

• 状态管理：每个推理会话分配独立的沙箱状态（变量、已执行代码、生成文件），通过会话ID关联Redis中的状态数据，支持多轮推理上下文延续；

• 容错机制：沙箱执行超时（默认30秒）或代码报错时，自动返回错误信息，模型可选择重新生成代码或调整工具调用策略，确保推理不中断。

② 网络搜索模块技术细节

• 文本搜索：支持自定义API对接，开发者可替换为百度搜索、必应搜索或私有知识库搜索，通过search_utils.py中的text_search函数修改调用逻辑，示例如下：

  def text_search(query, api_type="baidu"):
    if api_type == "baidu":
      # 百度搜索API调用（需替换为自身密钥）
      api_key = "your_baidu_api_key"
      secret_key = "your_baidu_secret_key"
      search_url = f"https://aip.baidubce.com/rest/2.0/ssearch/v1/websearch?query={query}&ak={api_key}&sk={secret_key}"
      response = requests.get(search_url, timeout=10)
      # 提取前3条核心结果
      results = [item["title"] + "：" + item["abstract"] for item in response.json()["result"]["items"][:3]]
      return "\n".join(results)
    elif api_type == "private":
      # 私有知识库搜索逻辑
      pass
    return "搜索结果获取失败，请重试"

• 图像搜索：基于MMSearch-R1缓存机制，将输入图像转换为特征向量，与缓存库中的图像特征匹配，返回相似图像的关联信息（如物体属性、场景描述），缓存库支持增量更新，可添加自定义图像数据；

• 缓存优化：搜索结果自动缓存至本地（默认缓存有效期24小时），相同或相似查询可直接返回缓存结果，降低网络依赖与延迟。

（4）评估体系：多维度量化模型性能

DeepEyesV2集成VLMEvalKit作为核心评估工具，构建了“多维度、多场景”的评估体系，确保模型性能可量化、可对比：

• 评估维度：涵盖四大核心指标——多模态理解准确率（图像/文本语义理解正确率）、工具调用准确率（工具类型匹配正确率）、任务完成率（复杂任务端到端完成比例）、推理效率（平均推理耗时）；

• 基准测试集：内置EgoExoBench（第一/第三视角视频理解）、MMMath（多模态数学推理）、SearchMM（搜索密集型任务）、ChartQA（图表问答）、RealWorldQA（真实世界复杂问答）等主流数据集，覆盖多模态智能体的核心应用场景；

• 评估流程：用户通过evaluation/run_eval.sh脚本启动评估，脚本自动加载模型、处理测试数据、调用工具执行推理、计算指标并生成可视化报告，核心配置示例如下：

  MODEL_PATH="honglyhly/DeepEyesV2_7B_1031" # 模型路径（预训练或自定义训练模型）
  DATASETS="EgoExoBench,MMMath,SearchMM,ChartQA" # 待评估数据集
  OUTPUT_REPORT="./evaluation_report" # 评估报告保存目录
  BATCH_SIZE=4 # 评估批次大小
  USE_TOOLS=True # 启用工具评估（关闭则仅评估基础理解能力）
  
  # 启动评估命令
  python -m vlmeval.run \
   --model $MODEL_PATH \
   --datasets $DATASETS \
   --output $OUTPUT_REPORT \
   --batch_size $BATCH_SIZE \
   --use_tools $USE_TOOLS \
   --deepeyes_tool_manager_config "./tool_manager_config.yaml"

四、应用场景

基于“多模态理解+工具链融合+可靠推理”的核心能力，DeepEyesV2可广泛应用于需要动态决策、信息补全、精确计算的复杂场景，覆盖办公、工业、教育、科研等多个领域：

1. 智能办公自动化：高效处理复杂图文文档

• 核心需求：办公场景中大量图文混合文档（如带图表的报告、PDF合同、Excel数据报表）需要手动提取数据、计算分析、信息验证，流程繁琐且易出错；

• 应用落地：

• 图文报告分析：自动提取PDF报告中的图表（柱状图、折线图），调用代码执行数据统计（平均值、增长率、占比），生成可视化分析结果，无需手动录入数据；

• 合同合规审核：识别合同中的图文条款（如金额、期限、责任条款），搜索相关法律法规或公司内部制度，验证条款合规性，标记风险点并给出修改建议；

• 多源数据整合：整合Excel、CSV、图像表格中的多源数据，通过代码合并去重、格式标准化，自动生成汇总报告，支持导出为Word/Excel格式。

2. 机器人视觉交互与自主决策

• 核心需求：服务机器人、工业机器人需要基于第一视角视觉信息，结合环境动态变化，自主完成导航、操作、交互等任务，需实时补充环境信息并验证操作结果；

• 应用落地：

• 家庭服务机器人：通过摄像头识别家居环境（如家具位置、障碍物、用户需求手势），搜索家具布局信息规划导航路径，调用代码分析用户手势语义（如“调高空调温度”），自主控制智能家居设备；

• 工业质检机器人：识别生产零件的图像（如金属零件表面缺陷、电子元件引脚间距），调用代码测量尺寸、分析缺陷面积，与行业标准数据对比，生成质检报告，不合格产品自动标记；

• 导购服务机器人：识别顾客手持商品图像，搜索商品价格、优惠活动、搭配建议，实时通过语音或屏幕反馈给顾客，支持“图像查询+实时推荐”的闭环服务。

3. 教育辅助：复杂多模态问题精准解答

• 核心需求：学生面对图文混合的复杂题目（如数学几何题、物理实验题、生物图像分析题）时，需要分步解析、精确计算、原理补充，传统教辅工具难以满足深度需求；

• 应用落地：

• 多模态数学解题：解析几何图形题（如三角形面积计算、圆与直线位置关系），生成Python代码验证推导过程，分步展示计算步骤，结合搜索补充公式原理，帮助学生理解逻辑；

• 科学实验分析：处理物理/化学实验图像（如反应速率曲线、电路连接图），调用代码拟合数据、计算实验误差，搜索实验原理与注意事项，辅助学生完成实验报告；

• 跨学科知识问答：解答图文结合的跨学科问题（如“根据气候分布图分析某地区农业发展优势”），整合地理图像理解、数据统计、农业知识搜索，提供全面且有依据的答案。

4. 科研数据分析：加速多模态科研流程

• 核心需求：科研人员需要处理大量实验图像数据（如细胞切片、CT影像、光谱图），进行特征提取、数据建模、文献对比，流程耗时且需专业工具支持；

• 应用落地：

• 生物医学研究：分析细胞切片图像、CT影像，调用代码提取特征（如细胞数量、病灶大小、灰度值分布），与已发表文献中的数据对比，验证实验结论；

• 物理/化学实验分析：处理实验数据图表（如压力-温度曲线、反应转化率图表），用代码拟合函数、计算相关系数，搜索同类研究的实验方法，优化自身实验设计；

• 论文写作辅助：整合多组实验数据，自动生成论文所需的可视化图表（折线图、热力图、散点图），搜索相关文献补充引言或讨论部分的理论支撑，提升论文写作效率。

5. 智能家居与环境自适应控制

• 核心需求：智能家居需要基于用户指令与环境图像，自主调整设备状态，需结合实时环境信息（如天气、光照、用户行为）动态决策；

• 应用落地：

• 环境自适应控制：识别室内环境图像（如窗户状态、光照强度、人员活动），搜索实时天气信息，自动控制窗帘（光照强时关闭）、空调（温度过高时降温）、灯光（人员离开时关闭）；

• 安全监控预警：识别监控图像中的异常行为（如老人摔倒、儿童接触危险物品、陌生人闯入），调用代码分析行为特征，搜索紧急联系人信息，自动发送告警通知（短信、APP推送）；

• 个性化场景定制：基于用户拍摄的家居图像与文本指令（如“打造观影场景”），搜索设备联动方案，自动调整灯光亮度、窗帘闭合度、音响音量，实现一键场景切换。

6. 电商运营与内容创作：数据驱动的精准运营

• 核心需求：电商从业者需要分析商品图像、挖掘市场数据、优化营销内容，需结合商品视觉特征与实时市场信息制定策略；

• 应用落地：

• 商品定价优化：识别商品图像（如服装款式、电子产品外观），搜索同类商品的市场价格、销量数据，调用代码分析价格弹性，给出最优定价建议，提升转化率；

• 营销内容创作：基于商品图像生成营销文案，搜索热门关键词（如“2025夏季流行色”）优化文案SEO，调用代码生成商品详情页的图文排版（如主图+细节图组合）；

• 用户需求挖掘：分析用户上传的穿搭图像、使用场景图像，搜索相似风格商品，推荐搭配组合，生成个性化购物清单，提升用户复购率。

五、使用方法

DeepEyesV2提供了完整的“环境准备-数据准备-训练-推理-评估”流程，新手可按以下步骤快速上手，开发者也可基于自身需求灵活调整配置：

5.1 环境准备

（1）系统与硬件要求

• 操作系统：Linux（Ubuntu 20.04+/CentOS 7+），推荐使用Linux（Windows部分工具依赖兼容性较差，MacOS仅支持推理不支持训练）；

• 硬件要求：

• 冷启动微调：至少1张GPU（显存≥16GB，推荐A100 40GB/RTX 3090），CPU≥16核，内存≥64GB；

• 强化学习训练：至少2张GPU（显存≥24GB，推荐A100 80GB），CPU≥32核，内存≥128GB（需支持沙箱集群与Redis分布式存储）；

• 推理部署：GPU显存≥12GB（7B模型）/32GB（32B模型），CPU≥8核，内存≥32GB；

• 网络要求：需联网下载模型、数据集、依赖包，强化学习与推理阶段需访问外部搜索API（或配置私有知识库）。

（2）依赖安装步骤

1. 创建并激活独立Python环境（推荐Python 3.10）：

   conda create -n deepeyesv2 python=3.10
   conda activate deepeyesv2

2. 安装基础依赖（PyTorch、Transformers等）：

   # 安装PyTorch（适配CUDA 11.8，其他版本需对应调整）
   pip3 install torch==2.1.0+cu118 torchvision==0.16.0+cu118 torchaudio==2.1.0+cu118 -f https://download.pytorch.org/whl/torch_stable.html
   
   # 安装Hugging Face生态工具
   pip install transformers==4.38.2 datasets==2.18.0 peft==0.8.2 accelerate==0.30.1 huggingface_hub==0.22.2
   
   # 安装数据处理与可视化依赖
   pip install numpy==1.26.4 pandas==2.2.1 scikit-learn==1.4.2 matplotlib==3.8.4 seaborn==0.13.2
   
   # 安装工具链依赖
   pip install flask==2.3.3 redis==5.0.1 requests==2.31.0 jupyter==1.0.0 ipykernel==6.29.3 fastapi==0.104.1 uvicorn==0.24.0 gradio==4.19.2

3. 安装训练与评估框架：

   # 安装LLaMA-Factory（冷启动微调依赖）
   git clone https://github.com/hiyouga/LLaMA-Factory.git
   cd LLaMA-Factory
   pip install -e .
   cd ..
   
   # 安装VLMEvalKit（评估依赖）
   git clone https://github.com/open-compass/VLMEvalKit.git
   cd VLMEvalKit
   pip install -e .
   cd ..

4. 安装强化学习依赖（verl库）：

   cd reinforcement_learning
   pip install -e . # 安装verl核心库
   bash scripts/install_deepeyes.sh # 安装DeepEyes额外依赖（工具链集成相关）
   cd ..

5.2 数据准备

DeepEyesV2的训练数据需从Hugging Face下载，支持自动加载与手动下载两种方式，数据格式统一，无需额外转换：

（1）自动加载（推荐）

训练脚本可直接通过Hugging Face数据集名称加载数据，无需手动下载，核心配置如下：

• 冷启动SFT数据：honglyhly/DeepEyesV2_SFT

• 强化学习RL数据：honglyhly/DeepEyesV2_RL

示例：在冷启动微调脚本中直接指定DATA_PATH="honglyhly/DeepEyesV2_SFT"，脚本会自动下载并加载数据。

（2）手动下载（网络不稳定时使用）

1. 访问Hugging Face数据集页面：

• SFT数据：https://huggingface.co/datasets/honglyhly/DeepEyesV2_SFT

• RL数据：https://huggingface.co/datasets/honglyhly/DeepEyesV2_RL

2. 下载核心文件：train.json（训练集）、val.json（验证集）、images/（图像文件夹）；

3. 按以下目录结构存放数据（项目data/目录下）：

   data/
   ├── sft/
   │  ├── train.json
   │  ├── val.json
   │  └── images/ # 存放SFT数据对应的图像文件
   └── rl/
     ├── train.json
     ├── val.json
     └── images/ # 存放RL数据对应的图像文件

（3）数据格式说明

每条样本为JSON格式，包含完整的“输入-工具调用-结果-答案”链路，示例如下：

{
 "id": "sft_00123",
 "image": "images/sft/industrial_part_005.png", # 图像路径（相对路径或URL）
 "text": "请分析图像中工业零件的表面缺陷面积，判断是否符合行业标准（行业标准：缺陷面积≤5mm²）", # 任务指令
 "tool_calls": [ # 工具调用轨迹（支持多工具组合）
  {
   "tool": "code_execution", # 工具类型：code_execution/text_search/image_search
   "input": "import cv2\nimport numpy as np\n# 读取图像并转换为灰度图\nimg = cv2.imread('images/sft/industrial_part_005.png')\ngray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)\n# 阈值处理提取缺陷区域\nret, thresh = cv2.threshold(gray, 200, 255, cv2.THRESH_BINARY_INV)\n# 计算缺陷面积（假设像素与实际尺寸比例为1:0.1mm）\ndefect_area = cv2.countNonZero(thresh) * 0.01\nprint(f'缺陷面积：{defect_area:.2f}mm²')",
   "output": "缺陷面积：3.25mm²" # 工具返回结果
  },
  {
   "tool": "text_search",
   "input": "工业零件表面缺陷面积 行业标准",
   "output": "根据GB/T XXXX-2024标准，该类工业零件表面缺陷面积应≤5mm²"
  }
 ],
 "answer": "经分析，图像中工业零件的表面缺陷面积为3.25mm²，符合GB/T XXXX-2024行业标准（缺陷面积≤5mm²）" # 最终答案
}

5.3 冷启动微调（SFT）：快速注入工具使用能力

1. 进入冷启动微调目录：

   cd cold_start

2. 修改训练脚本run_cold_start.sh（根据硬件配置调整参数）：

   # 基础模型路径（本地路径或Hugging Face模型名）
   MODEL_NAME_OR_PATH="Qwen/Qwen-2.5-VL-7B-Instruct"
   # 数据路径（自动加载Hugging Face数据或本地数据）
   DATA_PATH="honglyhly/DeepEyesV2_SFT" # 本地数据路径："../data/sft"
   # 模型输出目录
   OUTPUT_DIR="./sft_model_7b"
   # 训练参数
   MAX_SEQ_LENGTH=4096 # 最大序列长度（根据模型上下文窗口调整）
   BATCH_SIZE=8 # 批次大小（显存不足可设为4或2）
   LEARNING_RATE=2e-5 # 学习率（7B模型推荐2e-5，32B模型推荐1e-5）
   NUM_TRAIN_EPOCHS=3 # 训练轮数（数据量充足时可设为2-3轮）
   GRADIENT_ACCUMULATION_STEPS=4 # 梯度累积步数（小批次时增大以提升训练稳定性）
   USE_PEFT=True # 启用LoRA微调（降低硬件需求）
   LORA_RANK=8 # LoRA秩（默认8，可调整为4-16）
   FP16=True # 启用FP16精度（加速训练并节省显存）

3. 启动训练：

   bash run_cold_start.sh

4. 训练完成后，模型会保存至OUTPUT_DIR目录，核心文件包括adapter_config.json（LoRA配置）、adapter_weights.bin（LoRA权重）、tokenizer_config.json（Tokenizer配置），可直接用于推理或后续强化学习。

5.4 强化学习（RL）：优化工具调用策略

强化学习需先部署依赖环境，再启动训练，步骤如下：

（1）部署代码沙箱集群

1. 克隆代码沙箱仓库：

   git clone https://github.com/Visual-Agent/jupyter_sandbox.git
   cd jupyter_sandbox

2. 启动Redis服务（存储沙箱状态与推理上下文）：

   # 安装Redis（Ubuntu系统）
   sudo apt-get update && sudo apt-get install redis-server -y
   # 启动Redis（后台运行，端口6379）
   redis-server --port 6379 --daemonize yes
   # 验证Redis是否正常运行（返回PONG则成功）
   redis-cli ping

3. 启动多个沙箱实例（缓解并发压力）：

   # 启动3个沙箱实例，端口分别为8888、8889、8890
   python start_sandbox.py --port 8888 --redis_host localhost --redis_port 6379
   python start_sandbox.py --port 8889 --redis_host localhost --redis_port 6379
   python start_sandbox.py --port 8900 --redis_host localhost --redis_port 6379

（2）配置搜索模块

1. 文本搜索API配置：修改reinforcement_learning/search_utils.py中的text_search函数，替换为自身的搜索API密钥（如百度、必应），或对接私有知识库；

2. 图像搜索缓存配置：下载DeepEyesV2_Search_Cache缓存文件（https://huggingface.co/honglyhly/DeepEyesV2_Search_Cache），解压至`reinforcement_learning/search_cache/`目录。

（3）启动评估服务器

cd reinforcement_learning/evaluation_server
python server.py --port 5000 # 启动评估服务器，端口5000（需与训练配置一致）

（4）启动强化学习训练

1. 进入强化学习目录：

   cd reinforcement_learning

2. 修改训练配置文件configs/deepeyes_rl.yaml：

   model:
    base_model: "Qwen/Qwen-2.5-VL-7B-Instruct" # 基础模型路径
    sft_lora_path: "../cold_start/sft_model_7b" # 冷启动SFT模型的LoRA权重路径
    use_peft: True # 启用LoRA微调
    lora_rank: 8 # 与SFT阶段保持一致
   data:
    rl_data_path: "honglyhly/DeepEyesV2_RL" # RL数据路径（Hugging Face或本地）
    batch_size: 4 # 训练批次大小
    max_seq_length: 4096 # 最大序列长度
   tool:
    code_sandbox_ports: [8888, 8889, 8900] # 沙箱实例端口
    redis_host: "localhost" # Redis服务器地址
    redis_port: 6379 # Redis端口
    search_cache_path: "./search_cache" # 图像搜索缓存路径
    text_search_api_type: "baidu" # 文本搜索API类型（与search_utils.py对应）
   evaluation:
    server_url: "http://localhost:5000" # 评估服务器地址
    reward_weights: [0.5, 0.3, 0.2] # 任务完成度、工具效率、结果准确性的权重
   training:
    learning_rate: 1e-6 # 强化学习学习率（低于SFT阶段）
    num_train_epochs: 2 # 训练轮数（避免过拟合）
    ppo_clip_ratio: 0.2 # PPO裁剪系数
    batch_size: 4 # PPO批次大小
    gradient_accumulation_steps: 4 # 梯度累积步数
   output:
    dir: "./rl_model_7b" # 强化学习模型保存目录

3. 启动训练：

   python train.py --config configs/deepeyes_rl.yaml

5.5 模型推理：快速验证效果

使用预训练模型或自定义训练的模型进行推理，支持单条样本推理与批量推理，示例如下：

（1）单条样本推理（Python代码）

from transformers import AutoModelForCausalLM, AutoTokenizer
from deepeyes.tool_manager import ToolManager

# 初始化工具管理器（配置沙箱、Redis、搜索模块）
tool_manager = ToolManager(
  code_sandbox_ports=[8888, 8889, 8900],
  redis_host="localhost",
  redis_port=6379,
  search_cache_path="./reinforcement_learning/search_cache",
  text_search_api_type="baidu"
)

# 加载模型与Tokenizer
model_path = "honglyhly/DeepEyesV2_7B_1031" # 预训练模型或自定义训练模型路径
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
  model_path,
  trust_remote_code=True,
  device_map="auto", # 自动分配GPU/CPU
  torch_dtype="auto" # 自动选择数据类型（FP16/FP32）
).eval() # 推理模式

# 多模态输入（图像路径+文本指令）
image_path = "./data/example/industrial_part.png" # 图像路径（本地或URL）
text指令 = "分析图像中工业零件的表面缺陷面积，判断是否符合行业标准"

# 构建输入
inputs = tokenizer.from_list_format([
  {"image": image_path},
  {"text": text指令}
])

# 生成推理结果（启用工具调用）
with torch.no_grad():
  outputs = model.generate(
    **inputs,
    max_new_tokens=2048, # 最大生成长度
    temperature=0.7, # 温度参数（控制随机性）
    tool_manager=tool_manager # 传入工具管理器
  )

# 输出结果
result = tokenizer.decode(outputs[0], skip_special_tokens=True)
print("推理结果：")
print(result)

（2）可视化推理（Gradio界面）

项目提供Gradio可视化推理界面，方便快速验证效果：

cd demo
python gradio_demo.py --model_path "honglyhly/DeepEyesV2_7B_1031" --tool_manager_config "../tool_manager_config.yaml"

启动后访问终端输出的URL（如http://localhost:7860），即可通过上传图像、输入文本指令，可视化查看模型推理过程与结果（包括工具调用轨迹、返回结果）。

5.6 模型评估：量化性能表现

1. 进入评估目录：

   cd evaluation

2. 修改评估脚本run_eval.sh：

   # 模型路径（预训练或自定义训练模型）
   MODEL_PATH="honglyhly/DeepEyesV2_7B_1031"
   # 待评估的数据集（多个数据集用逗号分隔）
   DATASETS="EgoExoBench,MMMath,SearchMM,ChartQA"
   # 评估报告输出目录
   OUTPUT_REPORT="./eval_report"
   # 评估参数
   BATCH_SIZE=4 # 评估批次大小（根据显存调整）
   USE_TOOLS=True # 启用工具评估（关闭则仅评估基础理解能力）
   TOOL_MANAGER_CONFIG="../tool_manager_config.yaml" # 工具管理器配置文件

3. 启动评估：

   bash run_eval.sh

4. 评估完成后，输出目录会生成eval_results.json（详细指标数据）和eval_report.pdf（可视化报告），包含各数据集的准确率、工具调用效率、任务完成率等指标，方便对比模型性能。

六、常见问题解答（FAQ）

1. 环境安装时出现依赖冲突怎么办？

• 核心原因：不同依赖包版本不兼容（如Transformers与PEFT版本不匹配）；

• 解决方案：① 优先使用conda创建独立环境，避免系统Python环境干扰；② 严格按照“依赖安装步骤”中的版本号安装，例如Transformers=4.38.2、PEFT=0.8.2；③ 若出现冲突提示，根据错误信息降级冲突包（如pip install transformers==4.37.0）；④ 参考项目GitHub Issues（若有）获取官方兼容依赖列表。

2. 数据下载速度慢或下载失败？

• 核心原因：Hugging Face官网网络访问不稳定；

• 解决方案：① 使用Hugging Face镜像站点（如https://hf-mirror.com/）下载，修改`datasets.load_dataset`的`download_config`参数指定镜像；② 手动下载数据集压缩包，解压后按要求存放至data/目录，训练时指定本地数据路径；③ 下载图像文件时，可先下载核心样本（如前1000条）用于测试，完整数据后续分批次下载；④ 确保网络环境稳定，使用wget -c命令断点续传大文件。

3. 代码沙箱启动后无法连接？

• 核心原因：Redis服务未启动、沙箱端口被占用、防火墙拦截；

• 解决方案：① 验证Redis服务状态（redis-cli ping返回PONG），未启动则执行redis-server --port 6379 --daemonize yes；② 检查沙箱端口是否被占用（netstat -tuln | grep 8888），若被占用则修改start_sandbox.py的--port参数（如改为8891）；③ 开放沙箱端口与Redis端口（sudo ufw allow 8888、sudo ufw allow 6379）；④ 确保tool_manager.py中的redis_host和redis_port与部署时一致（默认localhost:6379）。

4. 强化学习训练时损失波动大或不收敛？

• 核心原因：学习率过高、批次大小过小、奖励函数设计不合理、数据质量差；

• 解决方案：① 降低学习率（如从1e-6降至5e-7），避免模型参数更新幅度过大；② 增大批次大小或梯度累积步数（如gradient_accumulation_steps=8），提升数据分布稳定性；③ 调整奖励函数权重（如增加“结果准确性”权重至0.3），对无效调用施加更严厉惩罚；④ 过滤RL数据中的无效样本（如错误工具调用、无意义结果），确保数据质量；⑤ 减少训练轮数（如从2轮改为1轮），避免过拟合。

5. 模型推理速度慢，如何优化？

• 核心原因：模型参数量大、工具调用耗时、未启用加速策略；

• 解决方案：① 选择更小参数量的模型（7B模型比32B模型推理速度快3-5倍）；② 关闭不必要的工具（如仅需视觉理解时，通过tool_manager.disable_tools(["text_search", "image_search"])禁用搜索模块）；③ 启用GPU加速策略（如torch.compile(model)、使用FP16/INT8量化推理）；④ 减少max_new_tokens（如从2048改为1024），仅保留必要推理步骤；⑤ 部署模型量化版本（如使用GPTQ/AWQ量化，显存占用降低50%以上）。

6. 模型工具调用不精准（如无需调用工具却触发调用）？

• 核心原因：SFT数据中工具调用场景覆盖不足、强化学习奖励函数未惩罚无效调用；

• 解决方案：① 增加SFT数据中“无需工具”的样本比例，让模型学会区分任务复杂度；② 在强化学习阶段，对无效工具调用设置负奖励（如奖励值-0.5）；③ 调整工具调用阈值（在tool_manager.py中设置tool_call_threshold=0.7，默认0.5，阈值越高越不容易触发工具调用）；④ 推理时通过force_no_tool=True强制禁用工具（适用于简单任务）；⑤ 针对特定任务（如纯文本问答）微调模型，强化“无需工具”的决策逻辑。

7. 模型无法识别图像或图像理解错误？

• 核心原因：图像路径错误、图像格式不支持、模型视觉编码器未正确加载；

• 解决方案：① 确认图像路径为绝对路径或项目相对路径，且图像格式为JPG/PNG（不支持GIF/WEBP）；② 检查模型是否支持多模态输入（Qwen-2.5-VL系列默认支持，自定义基础模型需确保添加视觉编码器）；③ 预处理图像（调整尺寸至224×224，与模型输入要求一致）；④ 增加图像相关的SFT样本（如不同场景、不同分辨率的图像），提升模型视觉理解能力；⑤ 验证图像是否损坏（通过cv2.imread读取图像，若返回None则图像损坏）。

8. 评估时部分基准测试未通过或指标过低？

• 核心原因：评估数据集未完整下载、工具配置错误、模型未适配该类任务；

• 解决方案：① 检查评估数据集是否完整（如EgoExoBench需下载视频帧与标注文件），缺失则重新下载；② 确认评估时工具已启用（USE_TOOLS=True），且工具管理器配置正确；③ 针对表现差的任务（如数学推理），增加该类任务的SFT数据，单独进行微调；④ 调整评估批次大小，避免显存溢出导致评估中断；⑤ 参考论文中的训练配置（如学习率、训练轮数），重新训练模型。

七、相关链接

• 项目开源仓库：https://github.com/Visual-Agent/DeepEyesV2

• 官方论文链接：https://arxiv.org/abs/2511.05271

• 预训练模型Checkpoint：https://huggingface.co/honglyhly/DeepEyesV2_7B_1031

• 项目官方主页：https://visual-agent.github.io/

• SFT训练数据集：https://huggingface.co/datasets/honglyhly/DeepEyesV2_SFT

• RL训练数据集：https://huggingface.co/datasets/honglyhly/DeepEyesV2_RL（强化学习训练数据）

• 图像搜索缓存：https://huggingface.co/honglyhly/DeepEyesV2_Search_Cache（图像搜索加速缓存库）

• 代码沙箱仓库：https://github.com/Visual-Agent/jupyter_sandbox（工具链核心组件，代码执行沙箱）

八、总结

DeepEyesV2作为一款开源多模态智能体框架，以“工具链深度融合”为核心创新，成功将视觉理解、代码执行、网络搜索能力整合进单一推理循环，通过“冷启动微调+强化学习”双阶段训练体系，为复杂场景提供了可靠的端到端推理解决方案。该框架具备工具调用自适应、训练数据高质量、技术架构清晰、应用场景广泛等显著优势，在真实世界理解、数学推理、搜索密集型任务等多个基准测试中表现优异，且提供了完整的训练流程、推理接口与评估工具，降低了多模态Agent的开发与落地门槛。无论是多模态智能体领域的科研人员，还是需要解决复杂推理任务的工程师，都能通过该框架快速搭建原型、优化模型、落地应用。作为完全开源的项目，DeepEyesV2的代码、数据与模型权重无商业使用限制，为相关领域的技术交流与创新提供了重要支撑，是当前工具增强型多模态智能体领域的优秀实践案例。