# CrossFormer 学习手记

Doshi、Walke、Mees、Dasari 与 Levine 的 CrossFormer 发表于 CoRL 2024，论文集于 2025 年出版。作者用约 90 万条轨迹、20 种机器人本体训练策略，并在六种真实平台上评估。下文的平台和动作定义取自正式论文，代码链接固定到用于核对的版本。[论文与书目信息][paper] · [作者项目与真机录像][site]

## 跟着一只 WidowX 机械臂

附录 C 的一项实验要求 WidowX 把胡萝卜放到盘子上，输入为语言指令和一台越肩相机的画面。另一项实验要求把蘑菇放入锅中，用预先布置并拍摄的终态照片指定目标。前者的夹爪观察来自越肩画面。作者的 Bridge 推理示例向策略提供这一相机的图像及有效时刻掩码。[论文附录 C、表 3][pdf] · [作者的推理笔记本][notebook]

| 在第 t 次决策中 | 可核对的计算 |
| --- | --- |
| 取得观测 | Bridge 笔记本取相邻五帧，将图像缩放到 224×224，堆成 `[1,5,224,224,3]`。首维是这次只处理一个样本。新帧到来，观察窗口前移一个时刻。[推理笔记本][notebook] |
| 加入任务 | 语言指令经 Universal Sentence Encoder 编码，再经 FiLM 生成通道缩放与偏移，调制 ResNet 的视觉特征。若给目标图，主相机的当前 RGB 与目标 RGB 在通道轴拼接。同一目标跨观察时刻复用。[检查点配置][config] · [视觉编码器][vision] · [输入实现][tokenizers] |
| 形成视觉 token | 从公开 ResNet-26 的步幅可推得，224×224 输入经卷积、池化、残差阶段变成 7×7×2048。展平空间轴后，每个视角每一帧有 49 个局部特征向量，再逐位置线性投影到 512 维，并加入可学习的位置表示。[视觉编码器][vision] · [输入实现][tokenizers] · [主干实现][module] |
| 融合历史 | 主干有 12 层、每层 8 个注意力头。每个观测 token 能读取同一时刻及更早时刻的有效观测。单臂每个时刻附加四个读出位置。读出位置可读取当前和之前的观测，以及同动作头的读出位置。观测侧的注意力规则排除读出位置。训练时缺失的观测由掩码处理。[论文第 3.3–3.4 节][pdf] · [注意力规则与读出位置][module] |
| 输出动作块 | 最新时刻的 4 个读出向量各通过同一单臂线性头，从 512 维变为 7 维。从接口取一个样本，得到 4×7。每行包括三个平移增量、三个姿态增量和一个夹爪指令。四行由同一次前向计算给出。[动作头][heads] · [推理接口][inference] · [动作标签比较][notebook] |
| 得到控制量 | 调用端选择 `head_name="single_arm"` 及 Bridge 的动作统计，将启用反归一化的维度还原到数据集控制尺度。机械臂收到指令，物理状态变化。下一次决策取决于相机实际拍到的新位置。[推理接口][inference] · [作者的滚动窗口][notebook] |

**一个能复算的位移。** Bridge 发布的 x 平移统计量为均值 0.0002175866 m、标准差 0.0096323751 m。举例设网络输出 0.5，该轴对应的位移为 `(0.5 × 0.0096323751 + 0.0002175866) m ≈ 5.034 mm`。统计量来自发布文件，0.5 是这道算例选的数。Bridge 的前六维启用这项换算，夹爪维度直接保留模型输出。[Bridge 数据统计文件][stats] · [还原动作的实现][inference]

**两种时间尺度。** 动作块有四行，部署端另行决定何时采集下一次观测并发送下一条指令。作者的 Bridge 笔记本沿已录视频逐帧移动窗口，逐次取预测块的第一行与示范动作比较。这里的下一帧来自已有轨迹。要在动画中演示闭环，可设定每执行一行就重新观测，让物体的实际移动影响第二次推理。动画中的扰动、关节运动、激活色阶和逐步输出数值属于这一教学例子的设定。[Bridge 推理笔记本][notebook] · [在线服务示例][server]

## 换一台机器人，哪些量会变

| 真机 | 论文评估中的输入与任务 | 动作头一次输出 |
| --- | --- | --- |
| WidowX、Franka | 越肩相机。Franka 的实验包括使用海绵把松果扫入簸箕。 | 单臂 4×7，末端位姿增量与夹爪，单臂设置的频率范围为 5–15 Hz。 |
| ALOHA 双臂 | 顶视相机和两路腕部相机。双臂推理服务还接收 14 维本体感知。拔笔帽需要两臂协作。 | 双臂 100×14，两臂的关节及夹爪位置目标，论文第 3.3 节给出 20 Hz。 |
| LoCoBot、Tello | 前视图及局部目标图。LoCoBot 的图规划器选择下一张子目标图，Tello 用同一导航头转弯并保持固定飞行高度。训练集未含无人机轨迹。 | 导航 4×2，每行是相对当前位置的平面路点。 |
| Unitree Go1 | 59 维本体感知，评估任务是向前行走。 | 四足 1×12，四条腿的目标关节位置，20 Hz。 |

表中的形状按「预测步数 × 每步动作维数」记。论文第 3.3 节和作者发布的四个动作头配置可交叉核对。平台种类与头数不同，同一类接口能服务多种本体。[论文第 3.3 节、附录 C][pdf] · [发布配置][config] · [双臂推理服务][server]

ALOHA 的服务维护最多五次观测和最多一百个近期预测块。若启用时间集成，它从这些块取出都指向**当前实际时刻**的那一行，再按权重平均。如已有三块，就取最早块的第 3 行、上一块的第 2 行和新块的第 1 行。默认权重参数为零，三项等权。调用端也能请求整个动作块。以 20 Hz 计算，100 个控制周期覆盖 5 秒，期间可以继续接收观测和修订指令。[作者服务的缓存、选行与加权实现][server]

## 训练时从哪里得到答案

示范轨迹同时记录观测和控制动作。训练时，把适用动作头预测的每个有效分量与对应示范分量相减，取绝对值，再对掩码有效项平均。除了动作头，误差信号也经反向传播更新共享主干。这使不同本体的数据可以训练共同的表示，同时保留各自控制接口的单位和维数。训练目标图从同一轨迹的后续观测采样。部署时由用户或任务提供目标图。[论文第 3.2–3.4 节][pdf] · [预训练配置][pretrain] · [掩码与 L1 损失实现][heads]

附录表 3 中，WidowX 把胡萝卜放上盘子的成功率为 0.33（12 次试验），把蘑菇放进锅中为 0.25（12 次），ALOHA 拔笔帽为 0.80（10 次）。导航评分是完成的子目标比例，Go1 的评分按专家策略的步行回报归一化。论文第 5 节指出，现有结果支持在一套策略中兼容多类控制接口，尚未显示显著的跨本体正迁移。[论文表 3 及第 5 节][pdf]

## 影片中的真实罐子轨迹

“把罐子移到锅的左边”来自 Bridge 0.1.0 训练集第 0 个分片的第 0 条 TFRecord 记录。原始样本有 38 个时刻，图像为 640×480 的 PNG。样本载荷的 SHA-256 为 `1c6d2f8bfc759dd4d8d36f68b629c0406e7741cabaf03cca5086a7966a228dfb`。第 10 章取第 37 帧作为图像目标，依次移过第 3–7、4–8、5–9 帧的五帧窗口。这样能用同一条记录，比较连续观测对应的动作。下表列的是记录原有的示范控制量。[原始 RLDS 分片][shard] · [作者单臂推理示例][notebook]

| 最后一帧（从 0 计） | 示范 Δx（mm） | 示范 Δy（mm） | 示范 Δz（mm） | 夹爪 |
| --- | ---: | ---: | ---: | --- |
| 7 | +1.020 | +13.666 | −7.140 | 开 |
| 8 | +7.174 | +10.384 | −6.053 | 开 |
| 9 | +13.286 | +8.200 | −1.498 | 开 |

第 7、8 帧记录的末端 x 坐标分别为 199.965 mm 和 194.649 mm，相减为 −5.316 mm。该值来自观测字段 `state`，表中第一行的 +1.020 mm 则来自标签字段 `action/world_vector`。片中蓝圈为人工标出的指尖，金色标记用来标识本次离线推理的结果。原始图像由 Homer Walke 等人制作，收录于 *BridgeData V2*（CoRL 2023），按 CC BY 4.0 许可使用。影片通过 Manim 缩放图像并叠加讲解标记。[数据集作者与许可][bridge] · [许可全文][ccby] · [RLDS 数据字段][schema]

训练和画图要读不同的量。作者的公开笔记本绘出 OXE 记录里的原始控制命令，便于和当时发出的指令对照。预训练程序使用 Berkeley 版本的 Bridge 数据，并把前六个动作分量重新标成相邻时刻的末端位姿差。将这种变换应用到片中的第 7 步，x 方向对应 −5.316 mm。讨论 L1 训练误差时应使用这种经处理的标签。[预训练的 Bridge 适配器][bridge-adapter] · [位姿差分定义][relabel] · [笔记本中的对照曲线][notebook]

### 三次推理和一次目标替换

下表使用本片重新运行的 CrossFormer 第 300000 步检查点，记录四行七列中的第一个数，还原为毫米。绿色示范曲线使用分片中原有的命令。模型输出由公开权重计算。[公开检查点][checkpoint] · [本片复核数据][evidence]

| 五帧观测 | 使用哪一帧作目标 | 首步 Δx（mm） | 这一步录像中的原始 x 命令（mm） |
| --- | ---: | ---: | ---: |
| 3–7 | 37 | −2.670 | +1.020 |
| 4–8 | 37 | +1.993 | +7.174 |
| 5–9 | 37 | +6.364 | +13.286 |
| 4–8 | 20 | +2.401 | +7.174 |

在观测 4–8、目标 37 的组合中，缩放到 224×224 后的像素 `[y=80,x=112]` 有六个输入分量 `[30,21,22,109,55,43]`。前三项来自当前图，后三项来自目标图。最后一帧第 17 号视觉词元投影后的第 0 分量为 −0.213405。检查点在每个注意力层的查询和键计算中加入可学习的位置表示。[网络配置][config] · [处理视觉输入的代码][tokenizers] · [逐次推理测量][evidence]

取最终时刻首个读出向量，用动作头的 x 列投影。`0.12501085 × 0.00208582 ≈ 0.00026075` 是 512 个乘积中的一个。全部相加得 0.20488885，加入偏置 −0.02058052，得到归一化预测 0.184308。换算到物理单位为 `0.2175866 + 9.6323751 × 0.184308 ≈ 1.993 mm`。[动作头实现][heads] · [逐次推理测量][evidence]

同一历史窗口将任务目标换成第 20 帧后，输出变为 +2.401 mm，两种目标对应的差值约为 +0.408 mm。四次推理的 112 个归一化分量均经过作者原版 JAX/Flax 模块复核，与本片逐层读取中间特征所用实现的最大绝对差为 0.000001133。原图、模型输入、完整动作块、中间特征与验证记录随复核数据发布。[作者模块][module] · [本片复核数据][evidence]

[bridge-adapter]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/crossformer/data/oxe/oxe_standardization_transforms.py#L34-L46
[relabel]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/crossformer/data/utils/data_utils.py#L333-L350
[shard]: https://storage.googleapis.com/gresearch/robotics/bridge/0.1.0/bridge-train.tfrecord-00000-of-01024
[schema]: https://storage.googleapis.com/gresearch/robotics/bridge/0.1.0/features.json
[bridge]: https://rail-berkeley.github.io/bridgedata/
[ccby]: https://creativecommons.org/licenses/by/4.0/
[paper]: https://proceedings.mlr.press/v270/doshi25a.html
[pdf]: https://raw.githubusercontent.com/mlresearch/v270/main/assets/doshi25a/doshi25a.pdf
[site]: https://crossformer-model.github.io/
[notebook]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/inference_pretrained.ipynb
[server]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/scripts/server.py
[module]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/crossformer/model/crossformer_module.py
[heads]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/crossformer/model/components/action_heads.py
[inference]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/crossformer/model/crossformer_model.py
[tokenizers]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/crossformer/model/components/tokenizers.py
[vision]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/crossformer/model/components/vit_encoders.py
[pretrain]: https://github.com/rail-berkeley/crossformer/blob/4a56b64411e7ec039ea6cce6bbbe65a38f677db1/scripts/configs/pretrain_config.py
[config]: https://huggingface.co/rail-berkeley/crossformer/blob/c7dea2691aed3656537c5126a0a77df84a28abd7/config.json
[stats]: https://huggingface.co/rail-berkeley/crossformer/blob/c7dea2691aed3656537c5126a0a77df84a28abd7/dataset_statistics.json
[checkpoint]: https://huggingface.co/rail-berkeley/crossformer/tree/c7dea2691aed3656537c5126a0a77df84a28abd7
[evidence]: ./evidence.zip
