企业官网建设流程全解析

vla-evaluation-harness 是一个"用一套框架评测任意 VLA（视觉-语言-动作）模型在任意机器人仿真基准上表现"的统一评测框架。它的结果录制（Recording）与可观测性（Observability）链路设计非常干净：评测结果默认落盘到 SQLite 数据库，用vla-eval export导出 JSON/JSONL，再通过 tracking 模块把指标镜像到 wandb / trackio 仪表盘。本文带你走通这条完整链路，看懂每一步的存储结构、关键参数和排错要点。

一、结果录制默认开启，零配置即得完整数据

很多评测工具要手动开启日志才能拿到数据，而 vla-evaluation-harness 的策略相反：episode 结果与逐步（step）数据默认持久化，视频默认关闭。你不需要写任何配置，跑完一次评测就会得到：

• 输出目录下的recording-<eval_id>.sqlite数据库文件；
• 每集（episode）结束时的状态、指标、步数、耗时、失败原因；
• 每一步的 step 行数据（由 benchmark 实现自行声明要记录哪些字段）。

需要覆盖默认策略时，才引入配置或参数：

每集产物（JSONL、视频）默认使用带基准作用域的路径模板：{benchmark_safe_name}/task{task_idx:04d}_ep{episode_id:04d}_{status}，文件名自带success/fail状态，方便直接按目录翻找失败案例。录制核心的实现在 src/vla_eval/recording.py。

二、SQLite 数据库内部：6 张表撑起整条链路

recording-<eval_id>.sqlite是整条可观测性链路的"唯一事实源"。schema 定义在 recording.py 的SCHEMA_SQL中，核心表如下：

这里有两个值得新手注意的设计：

1. 多进程安全写入：RecordingStore每个进程持有一条连接，用BEGIN IMMEDIATE事务 +synchronous=EXTRA串行化写入。模型 server 进程（通过StepRecorder）和评测 harness 进程（通过EpisodeRecorder）可以把字段写进同一行，按"字段级最后写入者胜"合并，互不丢失。
2. 可重入：episode_results以(sid, eid)为主键做 upsert，orchestrator 重试同一集不会产生脏数据。

三、分片并行：N 个进程共享同一个 SQLite

并行评测是这个框架的主打优化（上图中 LIBERO 批量并行比顺序执行快 47×）。关键在于：所有分片不各写各的 JSON，而是通过同一个--eval-id写入同一个recording-<eval_id>.sqlite。

• work_queue表实现了基于 SQLite 的轻量任务队列：分片按"认领-完成"领取工作项，空闲分片会自动去帮进度最落后的分片补位，避免都堆到同一个任务上；
• 分片崩溃后重新用相同--eval-id运行，队列里的未完成项会被自动重试；
• 单分片运行结束后自动导出；多分片则在所有分片退出后执行一次vla-eval export。

注意事项：所有写入方都要能写该数据库及其所在目录，共享存储必须支持 SQLite 的锁与同步机制（这也是 RFC 中强调的运维要点，见 docs/rfcs/0006-episode-sharding.md）。

四、一条命令导出结果：vla-eval export

评测跑完后，把 SQLite 里的快照"物化"成人读文件只需一条命令：

vla-eval export results/recording-<eval_id>.sqlite -o exported/

该命令由 src/vla_eval/results/export.py 实现，行为包括：

• 先对数据库做一致性快照备份，再逐集写出每集 JSONL（step 行序列）和每基准的 aggregate JSON（任务/基准两级聚合指标，如mean_success）；
• 写文件走"临时文件 + 原子替换"，中断不会留下半截产物；
• 若work_queue中还有未完成项或分片未齐，会在 aggregate 里标记"partial": true并列出未完成项，提示你用相同--eval-id补跑；
• 终端同步打印按任务的成功率汇总表（≥50% 绿色、否则红色，错误集单独标黄告警），聚合逻辑在 src/vla_eval/results/collector.py。

实际评测数据仓库里就能看到导出产物，例如 xvla_libero_10_merged.json、dbcogact_libero_10_merged.json，以及各基准的原始recording-*.sqlite。完整复现流程（生成EVAL_ID→ 分片运行 →export）参考 docs/reproductions/running-guide.md。

五、wandb / trackio 跟踪：与 SQLite 共用同一个 eval_id

想在看板上实时观察评测进度，只需在基准配置里加一个顶层块：

tracking: report_to: wandb # "wandb" | ["wandb", "trackio"] | "all" | "none"

tracking 模块（src/vla_eval/tracking.py）借鉴了 HuggingFace transformers 的集成模式，对新手友好的点在于：

• 生命周期钩子：on_eval_begin → on_benchmark_begin → on_episode_end → on_benchmark_end → on_eval_end，每个 episode 结束即上报bench/task/指标名形式的展平指标，基准结束后写入聚合值到 run summary；
• run 收敛：tracker 注入id=<eval_id>+resume="allow"，使实时运行（vla-eval run）和导出路径（vla-eval export）收敛到同一个 wandb run，不会一个评测产生两条记录；
• 配置解耦：project、entity、API key 全部走后端原生环境变量（WANDB_*/TRACKIO_*），框架不代管凭据；后端库需自行pip install wandb/pip install trackio；
• 容错：任一 tracker 上报失败只记日志，绝不中断评测；report_to: "all"会自动跳过未安装的库。

分片场景下有个细节：逐集（per-episode）上报只发生在实时路径，聚合指标的上报推迟到vla-eval export阶段执行，保证分片汇总后指标只发一次。

六、附赠能力：逐集视频录制

排查"为什么这集失败了"时，mp4 视频是最直观的调试手段。默认关闭是为了省盘，需要时--record-video一行命令开启。视频采用流式编码（逐帧写盘，内存 O(1)），文件名在收尾时才按最终状态（success/fail）落定，实现见 src/vla_eval/benchmarks/video.py。

七、关键路径速查

一句话总结：跑完评测 → 拿到recording-<eval_id>.sqlite→vla-eval export导出人读结果 → （可选）tracking.report_to同步到 wandb/trackio。整条链路以eval_id为主键贯穿，SQLite 存全量事实，导出给人看，tracker 给仪表盘看，各取所需又互不冲突。