OpenVLHarness - 让多模态模型在视觉空间里调用工具与代码的免训练框架

OpenVLHarness 是一个面向多模态大模型（MLLM）的智能体框架，目标是把已有的视觉语言模型变成「基于证据的视觉推理器」。据项目自述，它的核心思路是让模型自己选择工具、阅读工具返回的证据，并持续多步推理直到能够作答；整个过程不需要微调，而是通过模型原生的工具调用能力驱动现有权重。它适合希望在不重新训练模型的前提下，为视觉问答、目标定位、空间理解、多模态检索等任务搭建可解释推理流程的研究者与工程团队，也适合需要复现论文实验、或把工具调用能力接入自有模型服务的开发者。

维护者与状态

项目由 uclanlp 维护，仓库创建于 2026-10-15，最后一次提交时间为 2026-10-29。截至 2026-11-04，仓库获得 369 个星标。项目目前尚无正式 release，README 中提到的「release 包含的预设配置」指的是代码仓库中的配置文件，而非打包发布的版本号。项目另有一个项目主页，用于展示逐项基准结果、与其他 harness 的对比以及录制的推理轨迹。

主要能力

以下能力均据项目 README 自述整理，属于维护者的描述，未经本站独立验证。

• 免训练接入。项目称其通过模型原生的工具调用工作，不进行任何微调，直接复用骨干模型已有的权重。
• 九类任务级能力接口。包括视觉定位（按文本定位目标，返回框、掩码与标注图）、OCR、深度估计、相机轨迹估计、局部放大、文本搜索、图像搜索、网页访问，以及一个 Python 代码代理。每类接口都把底层工具输出整理成模型可读的观察结果，例如标注图、摘要和紧凑的数值数据。
• 多模态记忆。图像、框、掩码、深度图与网页引用在整个问题期间保持可寻址，后续工具与代码可以在此基础上继续计算；每个新问题开始时记忆会重置。
• Python 代码代理。骨干模型在独立上下文中编写并执行代码，对已存储的框、掩码、深度图等工具结果做计算。README 举例说明：代理可以先定位物体、估计深度并计算它们的空间关系，也可以裁剪不熟悉的物体、做视觉匹配，再到网页上核实答案。
• 模型注册表。项目为论文八个骨干中的七个提供预设，并覆盖 Qwen3-VL Instruct 的全部尺寸以及 OpenAI 的 GPT-5 至 GPT-6.1 系列模型；使用其他已注册模型时，复制同族预设并改动一行即可。

README 还给出了一组平均分结果：在四个领域共 22 个基准上，七个骨干相对不带工具的同一模型平均提升 9.7 至 12.6 分。这些数字来自项目自述，逐项结果与轨迹在项目主页上。

使用入口

代码托管在 uclanlp/OpenVLHarness，项目介绍与结果展示见 OpenVLHarness 项目主页。

据 README，运行需要 Python 3.10 或更新版本。从源码检出安装的步骤如下：

git clone https://github.com/uclanlp/OpenVLHarness.git
cd OpenVLHarness
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[qwen,server]'

该命令会安装智能体、Qwen 分词器支持与工具路由。模型服务需要单独的环境与依赖；如果只是作为客户端连接已有的路由，执行 pip install -e . 即可，使用 Qwen 做本地上下文计数或导出原始轨迹时再加 qwen 附加项，跑基准测试则需要 eval 附加项。

启动流程大致分三步：选择预设配置（如 qwen3_8b_paper.yaml）、准备模型与工具服务、启动路由并提问。README 给出的路由启动命令为：

python -m openvlharness.services.server --config configs/agent/qwen3_8b_paper.yaml

随后可用 /health 与 /backend-status 两个接口检查路由状态。README 特别说明，这两项检查只反映路由是否在线、注册了多少工具以及并发上限；GPU 工作节点不可达、缺少 Serper 密钥、缺少图床配置等问题，会在首次调用相应工具时才暴露。

许可与限制

项目采用 MIT 许可证。

据 README，使用前需要了解以下边界与前置条件：

• 依赖外部服务。要跑满九类能力，需要自行准备模型服务、感知服务与搜索服务。感知侧包括 SAM 3、PaddleOCR-VL 与 Depth Anything 3，它们作为独立 GPU 服务运行在路由之后。
• 搜索工具需要付费 API。三个搜索工具调用 Serper，这是一个付费的 Google 搜索 API，提供免费起步额度；密钥通过 SERPER_API_KEY 或 SERPER_API_KEY_FILE 配置。反向图搜还要求提供一个 Serper 能抓取的查询图 URL，可用内置图床配合隧道，或使用 Amazon S3、Google Cloud Storage 存储桶生成签名 URL。
• 辅助模型是硬性依赖。所有预设都使用 Qwen3-VL-8B-Instruct 做多模态搜索摘要与网页内容抽取，与主模型无关。8B 预设可与主模型共用同一服务，32B 预设则需要第二个服务实例；共用会牺牲吞吐，因为搜索摘要与网页抽取要排在智能体轮次之后。若要精确复现论文或保持高并发吞吐，应另起一个 Qwen3-VL-8B 实例并把 AUXILIARY_MODEL_BASE_URL 指向它。
• 预设覆盖不全。论文八个骨干中有一个未包含在预设里；论文附录中 Qwen2.5-VL-7B-Instruct 的结果使用了本仓库未包含的单独配置。
• 降级可观测。/backend-status 会报告 degradations，统计因辅助模型超时或输出不可用而回退到原始内容的搜索与网页访问次数、查询图无法通过公开 URL 抓取的图像搜索次数，以及因额度耗尽、密钥无效或需要付款而被 Serper 拒绝的调用次数。README 称健康的路由应保持这些计数为零。

以上限制与配置细节均来自项目自述，实际部署前建议对照仓库中的模型服务与工具服务指南逐项确认。