vla-evaluation-harness是什么？一个框架统一评估任意VLA模型的完整指南
vla-evaluation-harness是什么？一个框架统一评估任意VLA模型的完整指南
vla-evaluation-harness 是一个开源的 VLA（Vision-Language-Action，视觉-语言-动作）模型统一评估框架：只需把模型接入一次、把机器人仿真基准接入一次，就能在 LIBERO、CALVIN、SimplerEnv 等 18 个仿真基准上跑通任意 VLA 模型的交叉评估矩阵，并提供高达 47 倍的批量并行加速。本文带你从零了解它的架构、安装与快速上手方法。
一、为什么需要统一的 VLA 模型评估框架？
如果你做过机器人基础模型的研究，大概率遇到过这些痛点：
- 每个基准一套环境：LIBERO、CALVIN、ManiSkill、RoboCasa 各有各的依赖、观察格式和评估协议，团队往往被迫为每个基准维护私有的 eval 分支；
- 结果不可比：不同代码库跑出来的分数口径不一致，Bug 修复也互相不流通；
- 缺少真实时间条件测试：几乎没有框架能在"推理期间环境仍在运行"的实时条件下做评估。
vla-evaluation-harness 的思路是：通过抽象层彻底解耦模型与基准。基准封装在 Docker 容器里保证可复现，模型以服务化（Model Server）方式独立运行，二者通过 WebSocket 通信——模型集成一次，基准集成一次，整个交叉评估矩阵自动填好。
核心组件的设计说明见 docs/architecture.md。
二、架构速览：模型在容器外，基准在容器内
整个评估流程由 4 个角色协作完成：
| 组件 | 职责 |
|---|---|
| Orchestrator（CLI） | 读取配置、创建基准、管理 episode 生命周期 |
| Benchmark | 异步环境接口，封装具体仿真器逻辑 |
| EpisodeRunner | 执行单条 episode：重置环境 → 循环发送观察、接收动作 → 记录结果 |
| Model Server | 运行你的模型推理，只需实现 predict() |
隔离模型示意如下：宿主机上的 Model Server 通过 WebSocket（msgpack 序列化）与 Docker 容器内的 Benchmark 通信，容器可选挂载 GPU 用于渲染。这种设计让不同基准的依赖冲突被彻底隔绝，每个基准都有独立的 Docker 镜像（定义在 docker/ 目录下）。
配置则采用扁平 YAML：一个文件包含服务器地址、输出目录、基准类导入路径与任务参数，完整配置会随结果一起保存，方便复现。示例见 docs/rfcs/0004-benchmark-and-episode-execution.md。
三、快速上手：两步跑通第一次评估
环境要求 Python 3.8+，安装只有一行命令：
pip install vla-eval
评估采用"双终端"模式——一个终端起模型服务（GPU 侧），一个终端跑基准客户端：
# 终端 1：启动模型服务（宿主机 GPU 上运行）
vla-eval serve --config configs/model_servers/db_cogact/libero.yaml
# 终端 2：等 /health 返回 200 后，运行评估（基准默认跑在 Docker 里）
vla-eval run --config configs/benchmarks/libero/smoke_test.yaml
跑完后结果以 JSON 形式写入 results/ 目录。换模型、换基准也是同样的模式，比如 SimplerEnv + X-VLA：
vla-eval serve --config configs/model_servers/xvla/simpler_widowx.yaml
vla-eval run --config configs/benchmarks/simpler/widowx_vm.yaml
所有开箱即用的配置都在 configs/ 下按 benchmarks/ 和 model_servers/ 两个维度组织，每个目录配有 README 说明。想跳过 Docker 做本地开发可以加 --no-docker；没有 Docker 守护进程时还能用 --runtime charliecloud 无 root 运行同一镜像（见 docs/runtimes.md）。
💡 仓库还提供了一组 AI Agent 技能，可辅助你添加新基准、新模型服务与运行评估，位于 skills/ 目录，如 skills/add-benchmark/SKILL.md。
四、支持矩阵：18 个基准 × 13+ 模型服务
这是目前规模最大的开源 VLA 评估矩阵。部分已复现（reproduced）的组合包括：
| 类别 | 已复现（✓） |
|---|---|
| 基准 | LIBERO、SimplerEnv、CALVIN、LIBERO-Plus、RoboMME、MolmoSpaces-Bench |
| 官方模型 | OpenVLA、π₀ / π₀-FAST、GR00T N1.6、OFT、X-VLA、VLANeXt、MolmoBot |
| LeRobot 桥接 | π₀.₅、GR00T N1.7、MolmoAct2、VLA-JEPA（单一配置服务任意 LeRobot PreTrainedPolicy） |
复现报告逐一核对了各模型论文的公开分数，例如 π₀.₅ 在 LIBERO 上复现出 100%、GR00T N1.7 复现 99%、X-VLA 在 LIBERO 上 97.4%（公开 98.1%），完整对照表见 docs/reproductions/README.md。项目还附带聚合了 2456 个模型 × 18 个基准的 Leaderboard 数据与构建脚本，位于 leaderboard/ 目录。
五、批量并行评估：14 小时压缩到 18 分钟
顺序评估一个完整基准动辄数小时。框架提供了两层正交的并行化：
- Episode 分片（环境并行）：把
(task, episode)对切分给 N 个独立进程，共用同一个模型服务，辅助脚本 scripts/run_sharded.sh 一键拉起所有分片并自动导出； - 批量推理（GPU 并行）：
BatchPredictModelServer将多个进程的推理请求攒成一个 batch 做单次前向，只需在模型服务配置中设置max_batch_size > 1。
两层相乘的效果相当惊人：
以 DB-CogACT 7B + LIBERO Spatial + 1× H100 为例，顺序模式约 14 小时，50 分片 + batch=16 的并行模式只要约 18 分钟，吞吐量从 ~11 obs/s 提升到 ~486 obs/s（47×）。
如何选出最优分片数与 batch 大小？框架给出了"需求/供给"调优方法：需求 λ(N) 度量环境侧吞吐，供给 μ(B) 度量模型侧吞吐，工作点满足 λ(N) < 80%·μ(B*) 以避免队列堆积：
仓库自带 experiments/bench_demand.py 与 experiments/bench_supply.py 两个测量脚本，配合 docs/tuning-guide.md 即可为任意"模型+基准"组合推导最佳配置。
六、Python API：训练过程中随手评估
不想跑 CLI？一个函数调用即可在训练脚本中完成评估，模型直接由调用进程提供：
import vla_eval
results = vla_eval.evaluate(MyModelServer(model), "configs/benchmarks/libero/smoke_test.yaml")
print(results[0]["mean_success"])
完整示例见 examples/pusht_train_eval/——一个自包含项目：在自己的环境里训练，每 N 步调用 vla_eval.evaluate 做评估，pip install vla-eval 即可使用，无需 clone 本仓库。API 细节见 docs/python-api.md。
七、可观测性：记录、导出与追踪
- Recording：默认持久化每条 episode 的结果与逐步数据到 SQLite（
recording-<eval_id>.sqlite），可用vla-eval export导出每-episode JSONL 与聚合 JSON；需要回放视频时设置record_video: true； - Tracking：一行
tracking: report_to: wandb即可把聚合指标镜像到 wandb / trackio 面板，live 运行与导出路径共享同一个 run ID。
八、常见问题
Q：和 LeRobot 等自带评估脚本相比，优势是什么？ A：解耦 + 可复现。基准跑在固定 Docker 镜像里，模型以服务化接入，同一套协议评估所有组合，并已有多个模型在 2pp 内复现论文分数。
Q：必须装 Docker 吗？
A：默认用 Docker 隔离基准依赖，但可以 --no-docker 本地运行，或用 --runtime charliecloud 无守护进程、无 root 运行。
Q：没有 GPU 能跑吗？
A：支持 --render cpu 把仿真器渲染放到 CPU，把 GPU 完整让给模型推理，详见 docs/render-backends.md。
结语
vla-evaluation-harness 用"Docker 隔离基准 + 服务化模型 + WebSocket 协议"三件套，把 VLA 模型评估从"每个基准一套私改代码"变成了"选两个 YAML 配置，跑两条命令"。如果你需要横向对比多个 VLA 模型、复现论文分数，或在训练循环中持续评测，这个项目值得一试。
- 想了解设计理念：docs/design-philosophy.md
- 想复现具体模型分数：docs/reproductions/
- 想为新基准/新模型提 PR：CONTRIBUTING.md