ActionCodec2

ActionCodec2

把机械臂的动作转成紧凑的词元，也能转回去，提供 34 个现成的分词器变体。适合训练读写机器人动作的模型的机器人研究人员。

由 ZibinDong 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：ActionCodec2 是一个机器人动作的分词器。它把一段机械臂运动转成一小串词元，让语言类模型能够学习，也能把词元转回运动。模型卡列出了 34 个变体，它们共用同一个运行时，区别在于精度和词表大小。

适合谁：它适合训练视觉语言动作模型、需要把连续运动变成词元的机器人研究人员。

行业 | 谁在用 | 怎么用 | 例子
机器人 | 机器人学习研究人员 | 把机械臂轨迹分词用于模型训练 | 对一段录下的抓取放置动作编码
AI 研究 | VLA 模型构建者 | 选一个符合自己精度和词表预算的变体 | 对比 1 mm 和 10 mm 的变体
仿真 | 有录制片段的团队 | 在自己的数据上拟合分词器 | 在自己机器人的片段上训练分词器
教育 | 学生 | 研究动作怎样变成词元再变回来 | 检查来回转换有多大损失

如果你不做机器人动作方面的工作，可以跳过它，因为这个模型不处理文本、图像或音频。

用在哪里：

• 使用 transformers 库、允许远程代码的 Python 代码
• Windows、macOS 或 Linux，下载需要 Python
• 机器人策略的训练流程，词元会送进模型

用途 | 适合谁 | 得到什么
对机器人动作编码 | 研究人员 | 一段动作片段的词元序列
把词元解码成动作 | 策略构建者 | 重建出的动作，有损
拟合自定义分词器 | 有自己数据的团队 | 一个用自己的片段构建并保存的分词器

如何设置：

• 你电脑上的 Python
• numpy、scipy、torch、5.2 及以上但低于 6 的 transformers、huggingface-hub 和 pyyaml 这几个包
• 选一个变体名称，因为模型卡列了很多

1. 用 pip 安装这些 Python 包。
2. 用变体名称和动作空间加载处理器。
3. 对你的动作编码，或把词元解码回来。

pip install numpy scipy torch "transformers>=5.2,<6" huggingface-hub pyyaml

pip install -U huggingface_hub
hf download ZibinDong/ActionCodec2

如何使用：你按变体名称加载一个编解码器，传入形状为时间步乘维度的动作，再得到词元。模型卡的示例用的是一条末端执行器机械臂，每一步有七个数值。

import numpy as np
from transformers import AutoProcessor
codec = AutoProcessor.from_pretrained(
    "ZibinDong/ActionCodec2", variant="paper-o1-5mm-4k-2bin-1p2ms",
    action_space="single_eef_delta", trust_remote_code=True,
)
actions = np.zeros((1, 16, 7), dtype=np.float32)
tokens = codec.encode(actions, fps=15)
restored = codec.decode(tokens, fps=15)

如果想在自己的片段上训练分词器，模型卡给出了这两行。

codec.fit(episodes, fps=15)
codec.save_pretrained("./my-tokenizer")

示例：研究人员加载论文版变体，传入一段 16 步的机械臂动作。编解码器返回这段动作的词元。把它们解码就得到动作的近似值，因为模型卡说重建是有损的。

新手与专家：如果你是新手，先用全零数据运行示例，再换成录制的轨迹。先用模型卡示例里的论文版变体，再去探索其他变体。

如果你熟悉这个领域：模型卡介绍了一阶和二阶分词器、三个版本，以及每个配置从 1K 到 16K 的词表预算。输入会被重采样到 15 Hz，旋转用旋转向量表示，夹爪用绝对的张开比例。双臂按时间交错，词元不会跨手臂合并。

选择变体和动作空间
按帧率传入动作
编解码器重采样到 15 Hz
把动作编码成词元
需要时把词元解码回来

注意事项：

版本 | 说明
Paper | 作者随论文发布的两个阶数的分词器
Extended | 经过更多数据清洗后重新训练，精度和词表选择更多
Sparse | 标准和高动态的一阶分词器，夹爪为二值或 21 级

• Limits: 重建是有损的，绝对布局还需要当前状态。
• Trust: 加载时用到远程代码，所以运行之前要先审阅。
• Cleaning: 默认关闭，只在拟合分词器时才会生效。
• License: Apache 2.0。
• Cost to run: 未提及。
• Data it reaches: 它把文件复制到你的电脑，只处理你传入的动作数据。

Hugging Face 上的数据（2026年11月13日）

• 任务：robotics
• 框架：transformers
• 最近 30 天下载：217
• 点赞：3
• 许可证：apache-2.0
• 标签：transformers, actioncodec2, robotics, action-tokenization

链接

• 模型：https://huggingface.co/ZibinDong/ActionCodec2
• 文件：https://huggingface.co/ZibinDong/ActionCodec2/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download ZibinDong/ActionCodec2

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。