企业官网建设流程全解析

第一次跑 LIBERO 的时候，我一度怀疑自己拿到了假数据。同样是一段夹取动作，有的 demo 里 action 的数值范围在 ±0.05 附近，有的任务里旋转分量能到 ±0.2，夹爪分量又长期贴着 -1 和 1 两个值。更让我懵的是，翻遍官方仓库和数据集说明文档，它似乎并没有像图像那样有一套明确的前后处理流程。这个看不见、摸不着、却又确实存在的“动作归一化”，就是 LIBERO 从“能跑通”到“跑得好”之间最大的一道坎。

这篇文章想聊的就是这件事。我会从 LIBERO 官方数据集里 Action 的真实结构出发，拆开“归一化”这个词背后混在一起的三层含义，然后沿着代码把一条 action 从 HDF5 文件到 loss 的完整路径走一遍，最后给出一套我实际验证过的排查和归一化方案。无论你是刚接触 LIBERO 的新手，还是已经在做终身学习和机器人策略复现的老手，这篇文章应该都能帮你省下好几个周末的调试时间。

1. 先搞清楚 LIBERO 的动作到底长什么样

1.1 LIBERO 是拿来干嘛的

LIBERO（Lifelong Robot Learning Benchmark）是一个面向机器人长期学习场景的仿真基准，专门用来评估“学会新任务同时不忘旧任务”的能力。它由多个任务套件组成，最常用的是 Spatial、Object、Goal、Long 四套，合计 130 个左右的任务。任务内容都是桌面操作，比如把碗推到目标位置、把方块放到特定的颜色区域、按顺序完成一串动作等。

整个基准的数据收集和评估都在 robosuite 仿真环境中完成，采集对象是 Franka 机械臂。每个任务提供约 50 条人类或脚本生成的演示轨迹，每条轨迹包含视觉观测（顶视图、前视图）、关节状态、末端执行器位姿以及动作序列。训练时模型输入通常是“观测 + 语言指令”，输出是一段动作序列或单个动作步。

之所以 LIBERO 会被广泛使用，是因为它把“终身学习”这件事做成了一个可重复的考试题。但既然是一套考试题，题目数据里每个字段的语义就必须清清楚楚。Action 恰好是这里最容易含糊的字段。

1.2 Action 的 7 维结构：增量动作而不是绝对位姿

LIBERO 官方数据集里，每个时间步的 action 是 7 维向量，顺序大致为：

• 前 3 维：末端执行器在笛卡尔空间的位置增量 delta position，单位是米；
• 中间 3 维：末端执行器姿态的增量 delta rotation，单位是弧度；
• 最后 1 维：夹爪开合控制量。

这套动作不是“末端执行器的下一帧绝对位姿”，而是“相对于当前位姿应该怎么动”。也就是说，策略网络输出的不是一个目标位置，而是一个位移量，由仿真器中的控制器把这个位移量叠加到当前状态上，再通过逆运动学映射到关节力矩。

这一点特别容易被忽略。很多人第一次拿到数据，看到 action 数值很小，以为官方做过了归一化。其实不是，它只是“增量动作”的自然结果。控制周期短、步长小，增量自然就小。换句话说，这个动作空间的“小”是由机器人控制器特性决定的，而不是后处理归一化造成的。

理解这层区别是全文的关键。后续所有关于不透明性的争论，基本都源于“增量动作的小范围”和“主动归一化的小范围”容易被混淆。

1.3 官方数据集的存储格式与动作字段

LIBERO 官方数据集以 HDF5 格式分发，每个任务对应一个.hdf5文件。文件内部结构大致包含：

• data/demo_0/actions：演示轨迹的动作数组，形状为(T, 7)；
• data/demo_0/obs/agentview_rgb、eye_in_hand_rgb：图像序列；
• data/demo_0/obs/joint_states：关节角度序列；
• 其他辅助字段如末端执行器位姿。

这个存储结构本身没有任何归一化标识。图像是 0 到 255 的 uint8，关节角度是弧度，动作是浮点数，没有专门的 scale 或 offset 字段写在属性里。

这就有意思了。很多 CV 数据集会在打包时把图像归一化到 [0, 1]，或者在元数据里写明 mean 和 std。但 LIBERO 数据集的动作字段没有这种待遇。为什么？因为官方训练代码里，对动作的处理根本不是“读数据时统一归一化”，而是分散在环境配置、训练脚本甚至模型输出层里。这就为“不透明性”埋下了种子。

2. 三种“归一化”被混为一谈

2.1 环境层的动作缩放：控制器替你完成了一半归一化

robosuite 的 OSC（操作空间控制）控制器本身就限制了动作的输入范围。以常见的 OSC_POSE 控制器为例，位置增量通常被限制在 ±0.05 米左右，旋转增量在 ±0.25 弧度左右，夹爪控制量在 [-1, 1] 之间。

这个限制是在环境初始化时通过控制器参数设定的，不写进数据集。也就是说，模型动作如果超出这个范围，仿真器会做截断或缩放。从效果上看，控制器把动作输入“映射”到了一个有限区间内，这本身就是一种隐式归一化，只是它不是对数据的归一化，而是对控制量的约束。

论文和代码仓库通常不会显式强调这一点。于是出现了一个经典误区：有人在分析数据集时发现 action 最小值大约是 -0.05，最大值大约是 0.05，就得出结论“官方数据集做了 min-max 归一化”。这个结论是错的，那只是控制器截断后的分布结果。

2.2 数据层的统计归一化：官方并没有默认做

在训练机器人策略时，有些框架会对动作做统计归一化，也就是计算每个维度的均值、标准差，然后做标准化：

action = (action - mean) / std

或者做 min-max 缩放：

action = (action - min) / (max - min) * 2 - 1

这一类处理在 LIBERO 官方训练代码里默认是不做的。官方默认的做法是直接把 7 维 action 当作回归目标，计算 MSE 或 L1 loss。你翻遍script_train系列脚本，会看到对图像做/ 255.0，但对动作基本不做额外变换。

这带来一个很直接的结果：如果你在某个社区项目里看到别人对 LIBERO 动作做了标准化，那不是官方行为，而是他为了训练稳定自己加的。两种做法在同一个数据集上训练出的模型，性能差异可能非常大，但论文里经常不说清楚自己到底用了哪种。

2.3 训练层的动作处理：复现项目里最乱的地方

除了“数据层面归一化”和“环境层面动作缩放”，还有第三层，就是模型输出层的动作处理。

最典型的一种做法是把动作先除以一个固定常数，让数值落在较小的区间，再用 MSE 回归。另一种做法是让模型输出经过 tanh 激活，限制在 [-1, 1]，然后反缩放为真实动作。OpenVLA 这类模型在适配 LIBERO 时，会额外用数据集统计量做归一化，再离散成动作 token。这些处理都在训练代码里，不进数据集文件。

也就是说，同一份官方数据集，到了不同项目里，动作的处理路径完全不同。有些是“直接用原始动作”，有些是“除以最大绝对值”，有些是“按维度标准化”，有些是“只看夹爪维度怎么处理”。这些都属于“训练层动作处理”。

问题在于，很多项目只把模型结构写清楚，对动作归一化策略一笔带过。于是 BibTex 里换了三四个模板，最终跑出来的分数对不上，你都不知道是模型问题还是归一化问题。这一层，才是“不透明性”最让人头痛的地方。

2.4 为什么不透明：版本、分支与文档的多重缺口

LIBERO 官方仓库经历过多次更新，数据集的版本、环境配置、控制器参数在不同 commit 之间有差异。有的版本里动作范围是 ±0.05 位置 / ±0.25 旋转；有的分支因为改了控制频率，动作的实际统计分布完全不同。

更隐蔽的是，HDF5 文件本身没有写入“动作生成时的控制器参数”。robosuite 环境脚本里虽然有参数，但数据分析师通常不会去翻环境脚本。即使翻了，还需要确认训练时用的 env_kwargs 和采数据集时是否一致。只要有一处不一致，你对动作分布的判断就会出错。

文档层面呢？LIBERO 的 README 和论文里写清楚了任务划分和评估协议，但对动作归一化几乎是零描述。这在机器人社区不算罕见，但对于想要精确复现的研究者来说，这就是一个黑箱。

3. 代码追踪：一条 Action 从 HDF5 到 loss 的真实路径

3.1 从 HDF5 到 sample：数据加载阶段发生什么

在官方代码里，数据加载通常走过get_dataset系列函数，返回一个LiberoSequenceDataset或类似对象。__getitem__返回的样本里，action 字段就是 HDF5 里的actions数组切片，基本上原样输出。

这段逻辑里没有归一化。你可能会在 obs 字典里看到图像被转换成 float 并缩放到 [0, 1]，但 actions 只是被转换成 float 而已，没有减均值、没有除标准差。这一点我们可以拿代码习惯佐证：官方训练里图像归一化是写死在 obs 处理函数中的，而 action 处理则分散在 trainer 或 policy 里。

所以如果你只看了数据加载代码，会误以为“官方没有归一化”。如果只看 trainer 代码，又可能看到某个地方调用了 normalize_action 之类的函数。两段代码放到一起，才会意识到：action 的处理链路是分段的，不是一步完成的。

3.2 训练脚本里 action 是怎么被处理的

官方训练脚本的主体流程并不复杂：加载数据集，初始化策略，每步取 batch，前向得到 action 预测，和真实 action 算 loss，反向传播。

在常见的官方实现里，loss 计算直接基于原始动作。动作预测的输出维度是 7，真实动作也是 7，直接算均方误差。这里没有对 action 做标准化处理，也没有对 loss 项做分维度加权。夹爪那一维的 loss 和位置那一维的 loss 是一样权重的，这导致后面很多训练问题。

也有一些社区复现版本会加上normalize_action函数，比如：

def normalize_action(action, low, high): return (action - low) / (high - low) * 2 - 1

然后传--normalize参数，默认开启或默认关闭，完全看维护者心情。问题在于，这类函数经常不在 README 里写明，默认值也改来改去。你从一个旧 commit 切到新 commit，性能变化 3 到 5 个点，根本猜不到是网络结构改动还是归一化改动。

3.3 在哪里埋下不确定性：几处隐蔽分支

根据我自己的排查经验，动作归一化不确定性的主要埋点有三个。

第一个是环境加载脚本里的控制器参数。如果你在评估时用的环境控制频率或动作缩放系数与训练时不一致，模型输出的动作范围就会被“重新解释”，效果等同于改变了归一化。

第二个是动作回放时的 clip 行为。有些代码在控制真实环境时会对动作做 clip，有些不做。如果训练时动作在 [-0.05, 0.05] 但评估时 clip 到 [-0.03, 0.03]，模型表现自然会掉。

第三个是模型输出层的激活函数。有的策略头直接输出 7 维向量，有的套了一层 tanh 或 scale。这层信息往往藏在模型代码里，不画数据流图根本发现不了。

这三个埋点都很隐蔽，但它们共同决定了一个模型的真实动作分布。你只盯数据集本身，永远发现不了问题。

4. 不透明性带来的实际影响

4.1 训练尺度失衡：一个被忽视的梯度问题

如果直接拿原始 7 维 action 计算 MSE，不同维度的数值尺度差异会直接影响梯度。位置增量的量级大约是 0.01 到 0.05，旋转增量的量级大约是 0.05 到 0.25，夹爪动作则大部分时间贴着 -1 或 1。三者放在同一个 loss 里，梯度贡献天然不均衡。

位置维度 loss 太小，模型可能倾向于忽略位置误差，只要把旋转和夹爪练好，总 loss 就能降到很低。反过来，如果旋转维度数值噪声大，模型也可能在旋转上过拟合。

这种问题在单任务训练里还不致命，顶多多训练几万步。但在终身学习场景里就很麻烦：新任务如果旋转分量变化剧烈，模型会优先调整旋转相关表征，挤压其他任务的知识空间，导致灾难性遗忘更严重。

我在实际训练中观察过，把位置、旋转、夹爪三个维度分别计算 loss 并做加权，比直接算整体 MSE 能稳定提升最终成功率。这个技巧不算复杂，但因为官方代码没有提示，很多人根本想不到去做。

4.2 终身学习评估：任务间的动作分布漂移

LIBERO 的核心价值在于评估终身学习算法，比如 EWC、PackNet、EWC+ 等。这些算法通常基于对参数重要性的估计，而重要性估计依赖 loss 或梯度。

如果不同任务的动作分布差异很大，模型在不同任务上的梯度尺度也会差异很大。一个对动作尺度敏感的算法，可能把“任务 A 的旋转动作特殊性”当成“模型遗忘的关键因素”，导致正则化强度分配失误。

举个例子，某个任务需要频繁大角度旋转，另一个任务主要是平移。直接混训时，旋转维度的梯度主导模型更新，参数重要性估计会被带偏。如果先做动作归一化，让每个维度在任务间分布一致，算法对任务差异的判断会更准确。

这是一个非常实际的问题。我在跑 LIBERO-Long 套件时，多次发现 EWC 的 Fisher 信息矩阵数值范围异常，排查到最后都是因为动作分布在不同任务间漂移太大，而不是算法写错了。

4.3 复现与对比：归一化策略成了隐形超参

Benchmark 的意义在于不同论文之间的结果可对比。但如果每个团队对 LIBERO 动作的归一化处理不同，那最终分数就没有可比性。

假设论文 A 直接用原始动作训练，论文 B 对动作按维度做了标准化，论文 C 把动作除以固定最大值，三者在相同任务上的成功率可能差好几个点。当这个差异大于算法本身带来的提升时，实验对比就是失效的。

更讽刺的是，这种差异很难从论文文本中识别。因为大家通常都只写一句“we follow the official setting”，但“official setting”在不同仓库里已经被改得面目全非。我在复现某篇论文时，不得不去翻它的训练代码确认是否做了动作归一化，结果发现作者用的是自己实现的NormalizeAction类，而论文里只字未提。

这提醒我们一件事：如果你要在 LIBERO 上做实验对比，必须先统一动作归一化协议，否则所有结论都是空中楼阁。

5. 实操避坑：把不透明变成透明

5.1 第一步：翻环境代码确认动作边界

拿到任何 LIBERO 数据集，不要先急着训练。先找到生成数据时用的环境脚本，确认控制器类型和参数。

重点看两个地方：控制器是不是 OSC_POSE，位置动作边界是多少，旋转动作边界是多少，夹爪控制是不是二值。通常在环境定义的_get_action_limits或类似函数里都能找到。

这一步的意义是明确“数据集的天然动作范围”，而不是自己猜。我建议把确认结果写成一个常量文件，后面所有归一化操作都以这个文件为准，而不是再凭空设边界。

5.2 第二步：写脚本统计每个维度的真实分布

就算环境里写了边界，实际数据也未必均匀分布在整个边界内。直接统计每个维度的 min、max、mean、std，是最快理解数据的方式。

import h5py import numpy as np def inspect_actions(hdf5_path, n_demos=50): actions = [] with h5py.File(hdf5_path, "r") as f: for i in range(min(n_demos, len(f["data"]))): demo = f[f"data/demo_{i}"] actions.append(demo["actions"][:]) actions = np.concatenate(actions, axis=0) print("shape:", actions.shape) print("min:", actions.min(axis=0)) print("max:", actions.max(axis=0)) print("mean:", actions.mean(axis=0)) print("std:", actions.std(axis=0)) print("percentiles:") for q in [1, 5, 50, 95, 99]: print(q, np.percentile(actions, q, axis=0))

这个脚本几乎适用于所有 LIBERO 套件。统计完你会很直观地看到：位置维度集中在 ±0.05，旋转维度通常更分散，夹爪维度几乎只有两个尖峰。这些数字会直接指导你后续的归一化方案。

5.3 第三步：选择一个可解释的归一化方案

在机器人动作归一化上，我不推荐直接按整个数据集的 min/max 做缩放。因为夹爪维度的离群点极少，但会极大拉宽 min-max 范围，导致前 6 维被压扁。

更稳的方案有两种。

方案一：按边界缩放。如果位置维度的物理边界是 ±0.05，旋转是 ±0.25，夹爪是 [-1, 1]，那就直接用这些固定边界把每个维度映射到 [-1, 1]，不做数据统计。

action_scale = np.array([0.05, 0.05, 0.05, 0.25, 0.25, 0.25, 1.0]) normalized_action = action / action_scale

这个方案的好处是逻辑透明、可逆、不会因为数据集中添了几条 demo 就改变归一化参数。

方案二：按分位数标准化。为每个维度计算 5% 和 95% 分位数，用这两个数作为缩放边界。这种方式能抵抗离群点，比 min/max 稳定，但需要提前统计，而且换数据集要重算。

方案三：按任务分别归一化。在终身学习场景里，如果任务间动作分布差异实在太大，可以按任务计算统计量，各自归一化。但这样做要非常小心：如果测试时不知道任务身份，归一化参数就无法确定；如果任务身份在训练时可知、在测试时不可知，那模型输入标准就不一致了。

我个人的默认选择是方案一，也就是固定物理边界归一化。它把“归一化”从黑箱变成了一个可读懂的代码常量，而且与 robosuite 控制器参数一致，物理意义清晰。

5.4 常见问题速查表

每个问题我都实际踩过。尤其是“loss 好看但 rollout 拉垮”，几乎成了 LIBERO 复现的经典陷阱。归根结底，问题不总出在模型，而常常出在动作数值分布不够透明。

6. 关于 LIBERO 动作归一化，我最后想说的

把这个话题翻来覆去讲完，我的结论其实很简单：LIBERO 官方动作归一化的不透明，不是你理解能力的问题，而是项目本身把归一化分散到了多个层面、多个文件、多个版本里，却从来没有统一说明。

作为使用者，最靠谱的做法不是去等官方补文档，而是自己把这条链路梳理清楚。环境控制器参数看一下，数据集动作分布统计一下，训练代码里有没有隐藏的 normalize 查一下，然后明明白白地写进自己的实验配置里。

我后来在自己的项目里定了一条规则：不管跑哪个机器人 benchmark，都要在实验记录里单独写一行“Action normalization method: fixed-boundary / stats / none”。就这么一行字，帮我避开了无数次复现灾难。

如果你正准备跑 LIBERO，希望这篇文章能帮你少走这段弯路。先不要急着训模型，花半小时把 action 的来龙去脉搞清楚，后面会顺很多。