uclanlp/OpenVLHarness · 上手攻略
- 仓库：uclanlp/OpenVLHarness
- 链接：https://github.com/uclanlp/OpenVLHarness
- 分类：evaluation / agent / multimodal（Python，MIT）
- 作者：spark
- 更新：2026-10-23
资料核验：README 于 2026-10-22 UTC 通过
raw.githubusercontent.com实抓（main分支），文中命令、端口、环境变量、文件名均逐字取自该版本 README。仓库卡片记录 Stars 192、周增 +154、最近提交 2026-10-20。⚠️ 本文未运行任何代码，未 clone 仓库，全部为只读公开内容核验；凡本 README 未写明处均标注 ⚠️ 未确认。
一、是什么
OpenVLHarness 是 UCLanLP（University College London NLP 组）随论文 arXiv:2610.26860 放出的官方代码，副标题是 "Real-World Visual Agentic Tool-Use with Multimodal Memory"。它的核心主张是：不微调任何权重，只靠 backbone 已有的原生 tool calling 能力，把任意多模态大模型（MLLM）变成"基于证据的视觉推理器"——模型在"视觉空间里思考和写代码"。
配套产出齐全：项目页 openvlharness.github.io、HuggingFace 上的交互 Demo Space、HuggingFace 上的评测数据集 uclanlp/OpenVLHarness-Evaluation-Datasets。
架构由三块组成：
- Capability layer（能力层）：九个任务级接口，把底层工具输出转成模型能读的观察（标注图、摘要、紧凑数值）。
- Multimodal memory（多模态记忆）：图像、boxes、masks、深度图、网页引用在整个提问周期内保持可寻址，后面的工具和代码可以叠加使用；每个新问题重置记忆。
- Python Coding Agent：backbone 在独立上下文里生成并执行 Python，对已存的 boxes / masks / 深度图等做数值计算。
九个能力与其默认后端：
| 能力 | 提供什么 | 默认后端 |
|---|---|---|
| Visual Grounding | 按文本定位物体，返回 boxes、masks 和标注图 | SAM 3 |
| OCR | 读图中文字 | PaddleOCR-VL |
| Depth Estimation | 逐像素深度，保留数值数组与可视化 | Depth Anything 3 |
| Camera Trajectory | 有序图像间相机位姿估计 | Depth Anything 3 |
| Zoom-in | 裁剪局部放大观察 | 内置图像处理 |
| Text Search | 检索并摘要网页/图片/新闻等结果 | Serper + Qwen |
| Image Search | 逆向图片搜索找视觉匹配 | Serper Lens + Qwen |
| Webpage Visit | 从网页抽取与目标相关的证据 | Serper scrape + Qwen |
| Python Coding Agent | 对已存工具结果生成并执行计算 | 主 backbone + 本地 Python |
二、解决什么问题
多模态模型的典型短板是"看不见就说得很肯定"：计数不准、深度关系判断错、细粒度 OCR 掉点、无法检索外部证据核验。已知的开源方案（如各类 tool-augmented VLM harness）大多需要训练——要造数据、要微调、要评测，改一个 backbone 就重来一遍。
OpenVLHarness 的差异化是 training-free：直接接现成权重，靠"工具能返回模型读得懂的证据 + 跨步骤可寻址的记忆 + 会算数的编码 agent"三件事把分数拉起来。README 报告在 22 个 benchmark、四个领域（counting & grounding、多模态搜索、通用 VQA 与幻觉、空间理解）上，七个 backbone 平均提升 9.7 ~ 12.6 分。README 给出的均值表（Base → +OpenVLHarness）：
| Backbone | Base | +Harness | Gain |
|---|---|---|---|
| Qwen3-VL-8B-Instruct | 34.24 | 45.41 | +11.17 |
| Qwen3-VL-32B-Instruct | 38.30 | 50.92 | +12.62 |
| Kimi K3 (max effort) | 56.43 | 66.09 | +9.66 |
| GPT-5 (medium effort) | 44.37 | 55.65 | +11.28 |
| GPT-6 Luna (medium effort) | 45.76 | 56.52 | +10.76 |
| GPT-6 Sol (medium effort) | 52.67 | 64.31 | +11.64 |
| GPT-6 Astra (medium effort) | 60.27 | 70.17 | +9.90 |
README 注明：Qwen3-VL 的结果是三次运行的均值；逐 benchmark 结果、与其它 harness 的对比、录制的轨迹都在项目页上。⚠️ 注意 README 的 Highlights 段写"七个 backbone 提升 9.7 到 12.6 分"，而上方表格列了 7 行（2 个 Qwen + Kimi + 4 个 GPT-6 系），这两处的 backbone 计数口径不完全一致（Highlight 提到"论文的八个 backbone"），具体指哪七个建议按项目页核对。
三、快速安装
要求 Python 3.10+。从源码 checkout：
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]'
这会装上 agent、Qwen tokenizer 支持和 tool router。模型服务是独立环境、独立依赖的——这是最容易踩的架构预期（见坑 1）。client 只连接已有 router 时 pip install -e . 就够；用 Qwen 做本地上下文计数或原始 trace 导出才需要 qwen extra；跑 benchmark 需要 eval extra。
要跑满九个能力，还需要额外准备四类服务：
- 模型：本地 serve Qwen，或连 GPT / Kimi endpoint，按
docs/models.md走。⚠️ 每个 preset 都需要一个 Qwen3-VL-8B-Instruct endpoint 来做搜索摘要与网页抽取（与主模型无关）；8B preset 可以和主模型共用，32B preset 需要第二个 server。 - 感知：按
openvlharness/services/tools/README.md分别启动 SAM 3、PaddleOCR-VL、Depth Anything 3，它们作为独立 GPU 服务挂在 router 后面。 - 搜索：三个搜索工具走 Serper（付费 Google Search API，有免费起步额度），key 用
SERPER_API_KEY或SERPER_API_KEY_FILE配置。 - 图片托管：逆向图片搜索还要求 Serper 能公网 fetch 到查询图——用内置 image host 配隧道，或用 S3 / GCS 存成签名 URL。
四、核心用法
4.1 选 preset
发布版包含论文八个 backbone 中七个的 agent preset：
| 主模型 | 配置文件 | API 形态 |
|---|---|---|
| Qwen3-VL-8B-Instruct | configs/agent/qwen3_8b_paper.yaml |
Chat Completions |
| Qwen3-VL-32B-Instruct | configs/agent/qwen3_32b_paper.yaml |
Chat Completions |
| GPT-5 | configs/agent/gpt5_paper.yaml |
Responses |
| GPT-6 Luna | configs/agent/gpt6_luna_paper.yaml |
Responses |
| GPT-6 Sol | configs/agent/gpt6_sol_paper.yaml |
Responses |
| GPT-6 Astra | configs/agent/gpt6_astra_paper.yaml |
Responses |
| Kimi K3 | configs/agent/kimi_k3_paper.yaml |
Chat Completions |
论文里 Qwen2.5-VL-7B-Instruct 的结果（用于与训练式 harness 在附录中对比）用的是另一份配置，本次发布不含，⚠️ 复现该行数字前需自行确认。registry 还覆盖全部 Qwen3-VL Instruct 尺寸（2B 到 235B-A22B，含 FP8 build）与 OpenAI GPT-5 到 GPT-6.1，用法是复制同族 preset 改一行。
4.2 环境变量（本地 Qwen 路线）
在 router 和 agent 两个终端都设，地址按自己部署改：
export MODEL_BASE_URL=http://127.0.0.1:8222/v1
export MODEL_API_KEY=empty
export AUXILIARY_MODEL_BASE_URL=http://127.0.0.1:8222/v1
export AUXILIARY_MODEL_API_KEY=empty
export JUDGE_MODEL=Qwen/Qwen3-VL-8B-Instruct
export JUDGE_API_BASE=http://127.0.0.1:8222/v1/chat/completions
export JUDGE_API_KEY=empty
export TOOL_SERVER_URL=http://127.0.0.1:8101
export SAM3_SERVER_URL=http://127.0.0.1:8086
export OCR_SERVER_URL=http://127.0.0.1:8085
export DEPTH_ESTIMATION_SERVER_URL=http://127.0.0.1:8087
empty 是给无鉴权本地端点用的。用 GPT / Kimi 时，在命令和 Python 例子里选对应 preset，把 MODEL_BASE_URL / MODEL_API_KEY 指向该 provider，而 auxiliary 连接仍指 Qwen。
4.3 启动 router 并自检
python -m openvlharness.services.server --config configs/agent/qwen3_8b_paper.yaml
另开终端：
curl --fail http://127.0.0.1:8101/health
curl --fail http://127.0.0.1:8101/backend-status
这两个检查只能告诉你 router 起来了、注册了多少工具、并发上限是多少。GPU worker 不可达、Serper key 缺失、图片托管缺失，都要到首次调用对应工具时才暴露。/backend-status 的 degradations 是关键健康指标，README 列了四类降级计数：search / 网页访问因辅助模型超时或输出不可用而回落到原始 provider 内容、image_host（发布出去的查询图公网不可达）、serper_account（额度耗尽 / key 无效 / 需付费）。健康 router 这几项保持为 0；日志里对应 token 是 SUMMARIZE_DEGRADED、EXTRACT_DEGRADED、IMAGE_HOST_UNREACHABLE、SERPER ACCOUNT-LEVEL FAILURE。
4.4 提问
from openvlharness.bootstrap import build_agent
agent = build_agent("configs/agent/qwen3_8b_paper.yaml")
result = agent.generate([
{"type": "image", "value": "/path/to/image.jpg"},
{"type": "text", "value": "How many bottles are visible?"},
])
print(result["prediction"])
trajectory = result["extra_records"]["trajectory"]
输入可含多张图，value 支持本地路径、HTTP(S) URL 或 data URL。返回的 trajectory 记录模型轮次、工具调用与证据，可用于排查。
错误语义（README 明确列出）：prediction 为 Error: Unable to get response from the server. 表示模型请求失败，真实原因在 result["extra_records"]["trajectory"]["error"]；没有该 key 则是模型没给出最终答案就结束了。Error: Reached the iteration limit without a final answer. 表示用满了 agent.max_iterations，trajectory 的 error 记录该上限。
五、典型适用场景
- 多模态 benchmark 复现：想在 22 个 benchmark 上验证或对比 harness 效果，且不想为每个 backbone 重训。
- 视觉计数与空间关系：定位物体 + 估深度 + 算空间关系；或裁剪陌生物体 → 视觉匹配搜索 → 网页核验答案。
- 现有 MLLM 的"外挂增强"：已有 Qwen3-VL 或 GPT-5 系列服务，想在不换权重的前提下抬分。
- 视觉 agent 的工具链参考实现：九个能力层接口 + 多模态记忆 + 编码 agent 的组合方式，本身是很好的架构样例。
不适合：只有一张 GPU、只想跑单图 VQA 的场景——为了九个能力要拉起四个独立服务，成本不成比例。
六、坑与注意（7 条）
坑 1 · 现象：以为 pip install -e '.[qwen,server]' 装完就能跑。影响：import 成功但一调用就失败，因为模型服务是独立环境、独立依赖，README 明确写"The model servers have separate environments and dependencies"。修复：先按 docs/models.md 把模型服务起起来，再单独装感知服务，最后才谈跑 agent。
坑 2 · 现象：忘记每个 preset 都需要一个独立的 Qwen3-VL-8B-Instruct 辅助端点。影响：32B preset 下搜索工具与网页抽取静默降级，分数低于预期且不易察觉。修复：8B preset 共用一个 server 最简单（README 称其得分落在运行噪声内，代价是吞吐——搜索摘要和网页抽取会排在 agent 轮次后面抢同一块 GPU）；要精确复现论文或要高并发，就起第二个 Qwen3-VL-8B，把 AUXILIARY_MODEL_BASE_URL 指过去。
坑 3 · 现象：只跑 /health 和 /backend-status 就宣布部署成功。影响：GPU worker 挂了、Serper key 没配、图片托管缺失，这些都不在健康检查里，要到首次调用对应工具才爆。修复：把 /backend-status 的 degradations 当作持续监控项，接入日志 token SUMMARIZE_DEGRADED / EXTRACT_DEGRADED / IMAGE_HOST_UNREACHABLE / SERPER ACCOUNT-LEVEL FAILURE 的告警。
坑 4 · 现象：逆向图片搜索报 IMAGE_HOST_UNREACHABLE。影响：Image Search 能力实际不可用，且错误发生在公网 fetch 而非本地，很容易误判成 Serper 配额问题。修复：给查询图准备 Serper 能访问的 URL——用内置 image host 配隧道，或把图上传到 S3 / GCS 交给 Serper 签名 URL；照 openvlharness/services/tools/serper_text_search/README.md 走。
坑 5 · 现象：以为 coding tool 有沙箱。影响：README 用 > [!WARNING] 强调——coding 工具在 agent 宿主机上以你的用户权限跑生成的 Python，有网络和文件系统访问权，其执行 timeout 不是沙箱。这是本仓库最大的攻击面。修复：在适合你数据隔离要求的环境里跑 agent，动手前先读 SECURITY.md 与 openvlharness/services/tools/python_coding_agent/README.md；绝不把不可信图像/问题喂进未隔离的实例。
坑 6 · 现象：结论数字对不上论文。影响：花几小时 GPU 却复现不出来。修复：论文里 Qwen2.5-VL-7B-Instruct 那一行用的配置本次发布不含；Qwen3-VL 结果 README 说明是三次运行均值，单次跑分落在噪声外很正常；逐 benchmark 对比与其他 harness 的差异在项目页而非 README。
坑 7 · 现象：版本漂移导致子命令/配置名对不上。影响：照旧文章抄 configs/agent/*.yaml 或环境变量名可能直接报错。修复：本文所有路径与变量取自 2026-10-22 实抓的 main 分支 README，无 release tag 锚点（⚠️ 未确认仓库是否有已发布 release），使用前请核对自己 clone 的 commit；per-model 的模型 revision 与 serving 版本在 docs/models.md 里。
七、与同类对比
- vs 训练式 tool-augmented VLM harness（论文附录用来对比的那类）：它们靠微调把工具能力烧进权重，跨 backbone 迁移成本高；OpenVLHarness training-free，换模型只改 preset 一行，代价是收益依赖 backbone 本身的 tool calling 能力。
- vs 通用 agent 框架（LangGraph / AutoGen / CrewAI）：那些是文本 agent 编排框架，不解决"视觉证据"问题；OpenVLHarness 的能力层直接返回 boxes/masks/深度数值数组与标注图，是多模态特有的证据形态。
- vs 商用视觉 API：调 SAM 3 / PaddleOCR-VL / Depth Anything 3 / Serper 本身很便宜，但 OpenVLHarness 的价值在组合与记忆——九个工具跨步骤共享一份可寻址记忆，再由编码 agent 做数值聚合，这套编排自己搭成本不低。
- vs 自己写脚本调 SAM + OCR：功能重叠但没有迭代式证据链与 trajectory 可审计，评测也没法复现。
八、一句话推荐结论
推荐：做多模态 agent 研究或评测、且手上有多卡环境的人，值得花半天把它跑起来——training-free 加 22 benchmark 平均 ~10 分的提升在本领域属于高性价比方案，代码与数据集都开源。
不推荐：单卡用户、只想跑单图 VQA、或需要在生产环境直接托管 agent 编码执行的团队——先按坑 1、2、5 估算一遍资源与安全成本，很可能不划算。
来源：
- 仓库 README（raw.githubusercontent.com/uclanlp/OpenVLHarness/main/README.md，2026-10-22 UTC 实抓，截取 Highlights / How it works / Results / Installation / Quick start / Evaluation 段）
- README 内引用的文档：docs/models.md、SECURITY.md、openvlharness/services/tools/README.md、openvlharness/services/tools/python_coding_agent/README.md（未逐个 fetch，故相关细节标 ⚠️）
- README 引用的 arXiv:2610.26860、项目页 openvlharness.github.io、HF Space / HF Datasets（未 fetch）
- 组织内卡片：organized/repo_cards/4558-uclanlp-openvlharness.md
⚠️ 未确认清单：论文八个 backbone 的确切编号口径；论文的逐 benchmark 数字；是否存在 release tag；SAM 3 / PaddleOCR-VL / Depth Anything 3 的具体版本与 GPU 配置（README 说在 tools 指南里，本次未取）；代码许可证为 MIT（来自仓库卡片，README 末尾 License 段未取到）。