# LeRobot 的按轨迹留出评估可使用更大范围的归一化统计量

团队可以将机器人轨迹划分出来用于评估，同时使用范围超出训练轨迹的预处理统计量。我们追踪了一条 LeRobot 训练路径，并检查了一个公开元数据快照。在假设的 40 条训练轨迹和 10 条评估轨迹划分中，保存的状态和动作范围各有 6 个维度中的 3 个超出了训练轨迹的范围。这是对已保存元数据的比较，并非观察到的训练运行或模型性能结果。这个例子说明，审核留出集时，除了轨迹列表，还应检查提供给处理器的统计量。

## 数据划分与统计量是两个独立决策

在 [LeRobot 提交 `7910c20`](https://github.com/huggingface/lerobot/blob/7910c20a75834ad3fa6a9792df4d44a614d1bba6/src/lerobot/datasets/factory.py) 中，配置的 `eval_split` 会按所选轨迹列出的第一个任务分组，并将每组最后的 `ceil(group size × eval_split)` 条轨迹分配给评估集。[默认配置](https://github.com/huggingface/lerobot/blob/7910c20a75834ad3fa6a9792df4d44a614d1bba6/src/lerobot/configs/default.py)没有划分评估集；下面的示例特意设置了这一划分。代码使用轨迹列表、同一个数据集根目录和同一个修订版本，分别构建训练和评估数据集对象。

[数据集元数据加载器](https://github.com/huggingface/lerobot/blob/7910c20a75834ad3fa6a9792df4d44a614d1bba6/src/lerobot/datasets/dataset_metadata.py)会单独加载 `meta/stats.json`。在检查的[训练路径](https://github.com/huggingface/lerobot/blob/7910c20a75834ad3fa6a9792df4d44a614d1bba6/src/lerobot/scripts/lerobot_train.py)中，新建且未恢复训练的 Diffusion 策略如果没有预训练处理器路径，构建处理器时会接收数据集元数据中的统计量。默认的 [Diffusion 配置](https://github.com/huggingface/lerobot/blob/7910c20a75834ad3fa6a9792df4d44a614d1bba6/src/lerobot/policies/diffusion/configuration_diffusion.py)对状态和动作使用最小—最大归一化。源码追踪仅适用于该配置和版本；其他策略、覆盖配置、预训练或恢复的处理器、格式及版本可能有所不同。

![所选轨迹划分，以及保存的统计量通向新建 Diffusion 归一化器的独立路径](https://sapien1.com/research/lerobot-split-normalization/figures/zh-Hans/stats-path.svg)

我们没有执行数据集加载器或任何策略。该图描述的是在上述条件下检查到的源码路径，并非实际运行的记录。

## 一个元数据示例

公开的 [`lerobot/svla_so101_pickplace` 快照，修订版本 `f641879`](https://huggingface.co/datasets/lerobot/svla_so101_pickplace/tree/f641879e22172be7e8161d5e6c1503c2d2feb657)描述了 50 条轨迹和 11,939 帧。全部 50 条轨迹记录的第一个任务分组键相同。如果没有预先选定或排除任何轨迹，且 `eval_split=0.2`，所检查的规则会将 40 条轨迹分配给训练集，10 条分配给评估集。其轨迹摘要分别声明了 9,180 帧和 2,759 帧。

保存的 `observation.state` 和 `action` 统计量各自报告的计数均为 11,939。它们的最小值和最大值数组与全部 50 条轨迹摘要的汇总结果相符，绝对和相对容差均为 `1e-6`。直接与假设的 40 条训练轨迹汇总得到的极值相比，每个特征保存的范围都在 6 个维度中的 3 个上延伸得更远。以 `math.isclose` 的 `1e-6` 相对和绝对容差为标准，要求差异超出容差后，维度数量仍然不变。

| 特征 | 保存范围超出训练轨迹范围的维度数 | 最窄训练轨迹范围占保存范围的比例 |
| --- | ---: | ---: |
| `observation.state` | 6 个中有 3 个 | 84.3% |
| `action` | 6 个中有 3 个 | 84.2% |

![最窄训练轨迹范围相对于保存范围的比例：状态为 84.3%，动作为 84.2%](https://sapien1.com/research/lerobot-split-normalization/figures/zh-Hans/range-comparison.svg)

每个百分比都是该特征 6 个维度中最小的范围宽度比值；两行不一定描述同一个维度。条形比较的是宽度，而不是范围的起点或终点。40 条轨迹的计算包含这些轨迹声明的所有帧。实际采样器可能丢弃尾部帧、采样窗口或采用其他选择规则，因此这不是对真实优化器所用位置的测量。

留出轨迹的摘要也使全部轨迹的汇总范围在每个特征的 3 个维度上超出了 40 条训练轨迹的汇总范围。保存的统计量在所述容差内与全部轨迹的汇总结果相符，但我们没有独立确认保存文件的生成方式，也没有验证底层帧文件。如果将这些保存的范围提供给上文所述的新建最小—最大处理器，更宽的边界可能改变其缩放尺度。这个示例并未表明任何历史任务加载了什么、某个数据集是否适合某个策略，或分数是否发生了变化。

## 检查重新计算的范围

常见的指导原则是在训练集上拟合依赖数据的预处理，并将得到的变换一致地应用于评估数据。[Scikit-learn 对数据泄漏的讨论](https://scikit-learn.org/stable/common_pitfalls.html#data-leakage)解释了这一一般原则。此前的一篇 [LeRobot 问题报告](https://github.com/huggingface/lerobot/issues/2851)也提出过对全局统计量和验证的担忧；我们的检查没有验证该报告中报告的机器人行为，也没有诊断其原因。另一个 [SO-101 数据集卡片](https://huggingface.co/datasets/Samisaliveagain/so101_wm/blob/6de54268d238ac883870b136fd19b39d5591c8de/README.md)已经为受控评估区分了仅基于训练集的统计量和完整数据集的元数据。我们没有检查该数据集自身的计数或文件。

检查重新计算路径时，应像检查数据划分一样仔细。在固定版本中，[`recompute_stats` 辅助函数](https://github.com/huggingface/lerobot/blob/7910c20a75834ad3fa6a9792df4d44a614d1bba6/src/lerobot/datasets/dataset_tools.py)默认使用数值数据路径，扫描数据集根目录下的 Parquet 文件并遍历其中的轨迹索引，而不直接按 `dataset.episodes` 筛选。如果这些文件仍包含两个分区，仅传入一个已按轨迹筛选的对象，并不能证明得到的数值统计量只基于训练集。该辅助函数会将统计量写入该根目录，并保留未重新计算的特征的现有统计量；默认跳过图像和视频特征。我们没有运行该辅助函数，也没有修改数据集。其文档字符串已说明它会遍历所有轨迹，[数据集工具指南](https://huggingface.co/docs/lerobot/using_dataset_tools)也介绍了重新计算操作。

在将留出集结果视为独立结果之前，应记录所选轨迹 ID、数据集修订版本、每项统计量的来源和特征范围，以及实际使用的处理器配置。确认拟议的仅基于训练集的计算读取了预期的数据行，并在评估时复用适当的训练集衍生变换。分别检查图像、视频和相对动作特征，因为它们可能经过不同路径。预训练或恢复的处理器可能有自己保存的统计量，因此应检查实际检查点和覆盖配置，再判断其行为。

## 我们的检查方法

我们阅读了固定版本的源码，没有导入或运行 LeRobot。我们的[分析脚本](https://sapien1.com/research/lerobot-split-normalization/analyze.py)会验证源码哈希，临时下载小型元数据表，并使用 DuckDB 1.4.4 计算假设的数据划分和最小值、最大值比较。脚本正常运行后会删除临时表。[汇总结果](https://sapien1.com/research/lerobot-split-normalization/observations.json)不保留任务标签、单条轨迹 ID 或逐轨迹统计量。[源码检查工具包](https://sapien1.com/research/lerobot-split-normalization/source-check.zip)包含一个脚本，可在不运行上游代码的情况下验证选定的固定版本源码结构，同时包含上游许可证和署名信息。[图表生成器](https://sapien1.com/research/lerobot-split-normalization/render-assets.py)可根据汇总结果复现两张示意图。我们没有使用任何录制内容、原始帧、模型、训练任务或基准测试任务。

在安装了 Python 3.11 和 DuckDB 1.4.4 的 macOS 或 Linux 上复现：

```
python3.11 -m venv .lerobot-stats-venv
.lerobot-stats-venv/bin/python -m pip install duckdb==1.4.4
.lerobot-stats-venv/bin/python analyze.py > observations-reproduced.json
unzip source-check.zip -d lerobot-source-check
.lerobot-stats-venv/bin/python lerobot-source-check/source-check.py
```

该数据集的[固定版本卡片](https://huggingface.co/datasets/lerobot/svla_so101_pickplace/blob/f641879e22172be7e8161d5e6c1503c2d2feb657/README.md)将其标记为 Apache-2.0；这一标记不能确定每项底层素材的权利状况。源码检查工具引用了 LeRobot 中的简短表达式；其固定版本许可证和版权署名已包含在检查工具包中。sapien1 提供其原创脚本供下载和本地执行；未声明允许修改或再分发这些贡献的额外许可。源数据集和上游代码的使用条款各自独立。
