robotwin-evaluation-tools

面向 RoboTwin 2.0 / TinyVLA 仿真评测的可复现工具骨架：统一 manifest、批量 rollout 统计、失败样本分析与文件完整性校验。

这是一个用于求职展示和二次开发的最小工程框架。示例代码不绑定私有 RoboTwin checkout、机器人资产或模型权重；把自己的评测输出接入 manifest 后，即可复现同一套统计流程。

项目简介

在 RoboTwin / VLA 项目中，真正容易出错的地方通常不是启动一次仿真，而是：

• 不同任务、不同 seed 和不同 rollout 的结果难以统一汇总；
• 失败原因没有和 episode、视频、日志建立可追溯关系；
• 数据或视频在传输后被修改，却没有被及时发现；
• “成功率”“有效样本数”“视频数量”混在一起，导致结论不可复核。

本仓库提供一个轻量、可替换的评测层，重点展示以下工程能力：

1. 用机器可读的 manifest 描述任务、episode、结果和证据文件；
2. 按任务计算 success rate、有效样本数、失败数和置信区间入口；
3. 对原始数据、rollout 视频和日志进行 SHA-256 校验；
4. 输出 JSON/CSV，便于后续画图、写报告或接入 CI；
5. 为 RoboTwin 2.0、TinyVLA、SAPIEN/CuRobo 等环境预留适配接口。

与个人项目的对应关系

在个人 RoboTwin 2.0 实践中，我曾在本地 WBCD-2026 分支/配置上完成 TinyVLA 环境搭建、训练归档和 10 个任务的批量仿真评测，并按每个任务 100 次脚本运行保存结果。该仓库抽象的就是这类“任务配置 -> rollout -> 统计 -> 证据归档”链路。

当前公开骨架不声称包含：

• RoboTwin 官方竞赛或榜单成绩；
• 真实机器人成功率（real-robot SR）；
• 任何未随仓库提供的私有数据、模型权重或资产。

功能

1. Manifest 驱动的评测

每一个任务和 episode 都通过结构化记录描述，避免从文件名猜测结果。最小字段包括：

• task：任务名；
• episode_id：episode 标识；
• success：是否成功；
• seed：随机种子；
• rollout_path：可选的视频或轨迹文件；
• log_path：可选的日志文件；
• sha256：可选的完整性摘要。

2. 批量指标汇总

示例实现会按任务输出：

• total：manifest 中的 episode 数；
• valid：通过基本字段检查的 episode 数；
• success / failure：成功与失败数量；
• success_rate：success / valid；
• failure_reasons：按失败原因计数。

真实项目中可以继续扩展 Wilson 区间、bootstrap 置信区间、按 embodiment 分层统计和跨 seed 方差。

3. SHA-256 完整性校验

对大文件采用分块读取，不把整个视频或数据集一次性加载到内存。校验结果会明确区分：

• match：摘要一致；
• mismatch：摘要不一致，需要隔离；
• missing：记录存在但文件不存在。

4. 可追溯输出

默认同时生成：

• summary.json：适合程序继续消费；
• summary.csv：适合快速查看或导入表格；
• integrity.json：适合审计和复现实验。

目录结构

robotwin-evaluation-tools/
├── configs/
│   └── example.yaml
├── examples/
│   ├── manifest.example.json
│   └── run_local_eval.py
├── src/
│   └── robotwin_eval/
│       ├── __init__.py
│       ├── cli.py
│       ├── integrity.py
│       └── metrics.py
├── tests/
│   └── test_metrics.py
├── .gitignore
├── LICENSE
├── README.md
├── pyproject.toml
└── requirements.txt

环境要求

• Python 3.10 或更高版本；
• Linux、macOS 或 Windows；
• 本仓库本身不包含 SAPIEN、CuRobo、RoboTwin 或模型权重；
• 若接入真实 RoboTwin checkout，请以对应项目的官方环境文件为准。

安装

git clone https://github.com/Airgo0911/robotwin-evaluation-tools.git
cd robotwin-evaluation-tools

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -e .

快速开始

1. 使用示例 manifest

python -m robotwin_eval.cli \
  --manifest examples/manifest.example.json \
  --output-dir outputs/example

Windows PowerShell 可以写成一行：

python -m robotwin_eval.cli --manifest examples/manifest.example.json --output-dir outputs/example

运行后会得到：

outputs/example/
├── integrity.json
├── summary.csv
└── summary.json

2. 直接调用 Python API

from pathlib import Path

from robotwin_eval.integrity import verify_manifest_files
from robotwin_eval.metrics import summarize_manifest

manifest_path = Path("examples/manifest.example.json")
summary = summarize_manifest(manifest_path)
integrity = verify_manifest_files(manifest_path)

print(summary["tasks"])
print(integrity["status"])

3. 接入自己的评测结果

把 RoboTwin 的 rollout 结果转换成下面的结构即可。字段可以增加，但不要改变 success 的语义：

{
  "schema_version": "0.1",
  "source": {
    "benchmark": "RoboTwin 2.0",
    "model": "TinyVLA",
    "evaluation_mode": "local_simulation"
  },
  "episodes": [
    {
      "task": "open_microwave",
      "episode_id": "open_microwave_seed000_000",
      "seed": 0,
      "success": true,
      "failure_reason": null,
      "rollout_path": "artifacts/open_microwave_seed000_000.mp4",
      "sha256": "<64-hex-digest>"
    }
  ]
}

指标定义与报告口径

Success rate

success_rate(task) = successful_valid_episodes(task) / valid_episodes(task)

valid 不等于“文件存在”。建议在转换阶段检查：任务名、episode id、状态长度、视频/轨迹引用、终止标记和异常标记。任何无法解释的记录应保留在审计输出中，而不是静默删除。

失败原因

建议使用有限枚举，便于跨实验比较：

collision
timeout
object_missed
controller_error
invalid_observation
nan_or_dtype_error
unknown

分母和证据

报告中必须同时写清：

• 运行次数（例如每任务 100 次）；
• 有效 episode 数；
• 成功数和失败数；
• 评测环境、模型 checkpoint 和配置；
• 结果是否为本地仿真、官方 mock 或真实机器人。

不要把选定 rollout 视频数量当成成功数量，也不要把训练 loss、mock 通过或官方协议名称当成真实机器人成绩。

数据完整性工作流

推荐的最小流程：

1. 采集或转换完成后，为原始文件生成 SHA-256 manifest；
2. 训练前验证摘要，发现不一致时将 episode 移入隔离目录；
3. 训练后对抽样视频、日志和最终 manifest 再次校验；
4. 把 summary.json、integrity.json、配置和代码版本一起归档；
5. 在报告中记录校验时间、工具版本和异常处理规则。

示例校验命令：

python -m robotwin_eval.cli \
  --manifest path/to/manifest.json \
  --output-dir outputs/run-001 \
  --verify-integrity

适配真实 RoboTwin 环境

本仓库把“评测逻辑”和“环境执行器”分开。接入真实环境时，建议新增一个 adapter，而不是把环境 import 写进指标模块：

class RoboTwinAdapter:
    """把具体 benchmark 的 rollout 输出转换为统一 episode 记录。"""

    def run_episode(self, task: str, seed: int) -> dict:
        # 1. 创建场景、加载机器人和任务资产。
        # 2. 调用 policy，按控制频率执行动作。
        # 3. 保存视频、状态、终止原因和环境版本。
        # 4. 返回符合 manifest schema 的 dict。
        raise NotImplementedError

适配时优先固定以下契约：

• observation 的相机顺序和 shape；
• action 的维度、单位、delta/absolute 语义；
• 控制频率、episode horizon 和 timeout；
• collision、成功判定和人工复核规则；
• 随机种子和场景生成方式。

测试

pytest -q

当前测试覆盖指标汇总、空任务、无效记录和成功率边界。接入具体仿真器后，应补充：

• 相机/状态 shape contract test；
• action 解码和限幅测试；
• 失败原因枚举测试；
• 多进程输出合并测试；
• 端到端 smoke rollout。

性能与扩展方向

示例实现优先保证可读性和可审计性，不承诺取代大规模 benchmark runner。可扩展方向包括：

• 多进程或 Ray 批量 rollout；
• Parquet/JSONL 流式写入；
• bootstrap/Wilson 置信区间；
• MLflow、Weights & Biases 或自建实验追踪；
• GitHub Actions 自动运行 schema 与 integrity 检查；
• 任务级可视化和失败视频索引；
• 对接 LeRobot / DexData 等统一数据格式。

贡献规范

1. 新增字段时更新 schema 示例和测试；
2. 任何指标变更都说明分母、过滤条件和兼容性；
3. 不提交模型权重、私有数据、视频或凭据；
4. PR 描述中附最小复现命令和输出摘要。

免责声明

本项目的代码和示例用于研究、学习和求职展示。示例结果不代表 RoboTwin 官方榜单结果，也不代表真实机器人部署性能。使用真实机器人前，请由有资质的工程师复核限位、碰撞检测、急停和通信故障策略。

License

本项目采用 MIT License，详见 LICENSE。

作者

傅煜（Fu Yu）

• GitHub: @Airgo0911