PredActor 使用指南

PredActor（Predictive Action Diffusion）是开源的人形机器人扩散控制策略。它根据机器人最近几步的本体感知和可选的任务命令，同时预测未来的全身状态和关节动作：预测的状态留在策略内部，供引导使用；动作直接发给关节控制器，不需要单独的跟踪器。

在机器人机载的 Jetson Orin NX 上，PredActor 以 50 Hz 运行，完整控制回调的中位耗时为 16.790 ms，p95 为 19.383 ms，都低于 20 ms 的控制周期。

资源入口：

本节介绍 PredActor 的工作原理、发布内容和环境配置。完成本节后，你可以在本机打开浏览器评测界面，用文本命令控制仿真中的机器人。

DAgger 数据聚合和真机部署代码尚未发布。在 MuJoCo 中能运行只说明软件和权重兼容，不代表真机安全；上真机需要另外做控制、安全和硬件验证。

1. 读入本体感知。 控制频率 50 Hz（周期 0.02 秒）。每个周期读入最近 4 步的观测：关节位置、关节速度、重力投影、基座线速度、基座角速度和上一步动作，每步 96 维。文本条件策略再拼上 512 维的文本语义向量。

2. 联合生成状态和动作。 一个 Transformer 扩散模型同时去噪未来 20 步（0.4 秒）的全身状态（30 个刚体的位置、速度和根节点状态）和 29 维关节动作。发布的文本条件配置每个周期做 5 步 DDIM 去噪。

3. 只执行动作。 取当前一步的动作直接发给关节 PD 控制器。预测的未来状态不交给任何跟踪器，只留在策略内部。

4. 两种引导。 CFG（classifier-free guidance）强化训练中学过的条件，例如文本命令；CG（classifier guidance，界面中叫全身引导）对预测的未来状态施加目标，例如前进、横向、转向速度和骨盆高度，在去噪过程中把状态推向目标，进而影响动作。

5. 观测只用本体感知。 推理时状态流从条件中直接去噪，不需要外部估计的全身状态作为输入。

模型和数据放在 Hugging Face 仓库 MasterYip/PredActor_Artifacts，下载后位于仓库根目录下被 Git 忽略的 Artifacts/ 中：

uv sync --locked 按 uv.lock 建好 Python 3.10 环境，其中包含评测器、MuJoCo、浏览器界面和训练所需的依赖。评测不需要 Isaac Sim。

提示 评测命令都带 --locked，保证运行时环境与锁文件一致；uv run --locked 会直接使用这个环境，不需要先激活。

--filter 按 Hugging Face 仓库中的路径前缀筛选，checkpoints 会下载 1.3 节表格中的三个 checkpoint，motions/g1_152fk 下载动作数据。下载完成后，脚本会核对每个文件的字节数和 SHA-256。

已下载且大小一致的文件会被跳过。网络中断后重跑同一命令，只会补下缺失或大小不对的文件。

这条命令加载 PDP051 策略和 MotionCLIP 编码器，启动 MuJoCo 仿真，并在浏览器中打开 http://127.0.0.1:8765/。页面中出现机器人、步数（STEP）开始增加，说明评测环境正常。在 CLIP command 输入框中输入 walk 并回车，机器人应从站立切换为行走。

确认训练环境可以用 smoke 测试，不需要下载任何数据：

它生成一份确定性的小数据集，用缩小的模型跑一步优化并检查保存的 checkpoint。通过时打印 PREDACTOR_TRAINING_SMOKE_PASS 和记录文件路径。smoke 只确认代码路径能跑通，不代表模型质量。

本节在浏览器评测界面中运行策略：用文本命令选择行为，用速度引导、手柄或目标点控制方向，并用鼠标施加外力。命令都在仓库根目录运行。

不带参数时使用发布的 PDP051 策略。常用选项：

完整选项用 uv run --locked predactor-eval --help 查看。

在没有显示器的服务器上，用无头方式启动，再把端口转发到本机浏览器：

<用户名>@<服务器地址> 换成你登录服务器的账号。端口 8765 已被占用时，加 --web-port 8766 换一个端口。

1. 在右侧 CLIP command 面板中选择 TEXTOP。

2. 在输入框中输入动作描述，按回车或点击 ↑。界面提示的示例有 walk、jog、run、squat down、jump up、raise hand、kick。

3. 面板中显示当前生效的命令。启动时的默认命令是 stand。

文本经 MotionCLIP 编码成 512 维向量，作为策略的条件输入。

注意 训练数据只有 152 段动作，描述越复杂越可能得不到预期的行为。先用上面列出的简单命令确认效果。

INTERP 模式把多条"起点 → 终点"语义方向按权重叠加，得到连续变化的条件：

1. 在 CLIP command 面板中选择 INTERP，面板列出默认的命题：零向量 → stand、stand → walk、walk → run、stand → squat down、get down → raise hand。默认只有第一条的权重为 1，其余为 0。

2. 拖动某一行的权重滑块。起点或终点为零向量（Ø）时，权重范围是 0–1；两端都是文本时为 −1 到 1。

3. 用 + 添加命题，最多 16 条；可以改写每条的起点和终点文本。

4. 点击 APPLY。各条命题按权重相加并归一化后，作为新的条件。

Whole-body guidance 面板直接对预测的未来状态施加速度目标：

1. 确认面板标题旁的开关为 Enabled。

2. SOURCE OWNER 选 WEB，用界面滑块控制；选 JOY，用手柄控制（见 2.6 节）。

3. 拖动 Forward、Lateral、Yaw，分别设定前进、横向和转向速度目标。

4. Gain Kp 是引导强度，默认 1.00，范围 0–4；设为 0 相当于不引导。

Activation manager 中的高级选项可以按引导类型选择作用的身体部位和观测项，一般不需要改动。点击其中的 ↺ 恢复默认。

文本命令和全身引导可以同时使用：文本选择"怎么动"（如行走或慢跑），引导决定"往哪走、多快"。

Destination follow 根据目标点自动生成速度目标：

1. 在 X、Y、Z 中输入世界坐标系中的目标位置。

2. 点击 SET，设定目标并开启跟随。机器人转向并朝目标移动；水平距离进入到达半径后，速度目标归零，机器人停下。

3. 到达后如果机器人被推离目标超过重新跟随半径，会再次开始跟随。

4. 点击 CANCEL 关闭跟随并清除目标。

Controller tuning 中的参数点击 APPLY 后生效：

评测器默认自动查找 Linux 手柄设备（--web-joystick-device auto），按 Xbox 手柄的键位解析（--web-joystick-type xbox_new）。启动时检测到手柄，全身引导的来源会自动设为 JOY；Controller 面板显示按键状态。以下操作在来源为 JOY 时生效：

点击 Controller 面板的 ? 可以查看当前手柄的键位。

用 --web-perturb 启动后，可以在仿真画面中用鼠标推机器人：

橙色箭头显示拖动的方向和大小。力和力矩的上限默认为 120 和 30，可用 --web-perturb-max-force 和 --web-perturb-max-torque 调整。仿真画面工具栏中的 ↺（Reset MuJoCo robot）重置机器人；勾选 AUTO RESET 后，机器人跌倒时自动重置。页面顶部的 ❚❚ 暂停评测。

把 run_dir 设为训练时打印的输出目录（见 5.4 节）：

训练时保存的 resolved_config.yaml 决定加载哪种策略和文本编码器。无条件基线（见 5.2 节）同样可以输入文本命令，但文本对它没有作用。

评测结束后，输出目录中有：

本节在 Isaac Lab 中让发布的 RLTracker 教师策略执行动作库中的动作，记录 PredActor 训练所需的状态–动作轨迹。采集使用单独的 conda 环境，命令在仓库根目录运行。

在 uv 环境中下载教师策略和 152 段动作：

下载后的默认位置：

安装脚本依次完成：

1. 确认当前 Python 是 3.10，否则退出。

2. 安装 PyTorch 2.5.1（CUDA 12.1）和 Isaac Sim 4.5.0。

3. 把 Isaac Lab v2.1.0 的固定提交下载到 PredActor/collection/.deps/IsaacLab，只安装采集用到的 4 个扩展。

4. 安装仓库自带的 RLTracker 任务、RSL-RL 运行时和 CUDA 正向运动学库。

5. 全程使用 PredActor/collection/constraints.txt 锁定版本，最后运行 pip check。

成功时最后一行是 PredActor collection environment is ready.。

提示 访问 PyPI 较慢时，用阿里云镜像安装 Python 包；PyTorch 和 Isaac Sim 仍从各自的 CUDA / NVIDIA 索引下载： PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple bash PredActor/collection/install.sh 网络中断后重跑同一命令，已完成的下载和 Isaac Lab 代码会被复用。

在采集环境中运行：

脚本检查采集代码、教师策略和动作文件是否就位，输出一段 JSON。status 为 PASS、motion_count 为 152 时可以开始采集。

确定性模式（deterministic）让每段动作从头到尾执行指定次数：152 段 × 50 次 = 7,600 个 episode。执行失败的 episode 会重新分配，不计入总数。结果写入 Artifacts/dataset/g1_152fk_raw/motion.zarr。

完整选项用 bash PredActor/collection/collect_dataset.sh --help 查看。

注意 确定性模式在进度超过 90% 后，如果连续 1800 秒没有新 episode 完成，会提前结束，避免卡在执行不了的动作上。因此实际 episode 数可能少于 7,600，训练前看一下采集日志中的最终数量。

1. 把动作放在 Artifacts/motions/<动作集名>/<动作名>/motion.npz。

2. 采集时加 --motion_file "<动作集名>/*"。episode 总数为匹配到的动作数乘以 --samples_per_motion。

3. 标注时用同一个匹配模式设置 input.motion_pattern（见 4.3 节）。

本节给采集到的每一帧加上 512 维、与文本对齐的 MotionCLIP 语义向量，作为文本条件训练的标签。项目把这一步叫作"数据染色"（data dyeing）。在 uv 环境中运行，先退出采集环境（conda deactivate）。

确认以下文件就位：

结果写入 Artifacts/dataset/g1_152fk/motion_dyed_text_t0.01.zarr，新增字段 motion_latent，每帧 512 维。

发布的配置直接编码原始动作，而不是采集到的样本：每段原始动作只编码一次，再按 motion_idx 附加到这段动作的所有 episode 上。编码时把 50 Hz 的轨迹重采样到 30 Hz，取 60 帧窗口，使用 xyz 位置表示，再以温度 0.01 对齐到文本词表的 CLIP 文本向量。

提示 第一次运行会下载 OpenAI 的 CLIP ViT-B/32 权重到 CLIP 缓存目录（通常是 ~/.cache/clip），需要能访问外网。

参数写成 Hydra 覆盖项加在命令末尾，例如 input.zarr_path=/path/to/motion.zarr：

clip_or_drop 的含义：样本比原始动作短时，把原始动作截到样本长度；样本更长时，丢弃这个 episode。

本节用标注后的数据做行为克隆训练，得到可以在第 2 节界面中评测的策略。在 uv 环境中、仓库根目录运行。

除最后一行外，这条命令与仓库文档中的论文配置训练命令相同；最后一行 training.save_terminal_checkpoint=true 让训练结束时保存最终权重，原因见下面的"注意"。

--cfg 选择 PredActor/diffusion_policy/config_files/ 中的配置，其后的 键=值 覆盖配置项。logging.mode=offline 让 Weights & Biases 只在本地记录；默认的 online 需要先登录 W&B。

注意 训练每 10 个 epoch 保存一次 checkpoints/latest.ckpt，epoch 从 0 开始计数。不加 training.save_terminal_checkpoint=true 时，50 个 epoch 的训练结束后 latest.ckpt 是第 40 个 epoch 的权重，而不是最终权重。

训练时，配置中的所有引导会被自动关闭；引导只在推理时生效。

无条件基线使用同一份标注数据，但不以文本为条件：

两份配置的区别：

两次训练用不同的 --exp_name，输出目录才不会混淆。

训练开始时打印输出目录，格式为 outputs/<月份-日-时-分-秒>-<配置名>-<exp_name>/，例如 outputs/October-16-22-30-05-g1prdp_cond_diffuse-predactor_bc/。目录中有：

接下来按 2.8 节在浏览器界面中评测这个模型。

本节从头训练 MotionCLIP 动作编码器，它把 60 帧动作和文本描述映射到同一个 512 维空间，第 4 节的标注用的就是它。这一流程目前是实验性的；只想复现策略训练时，直接使用发布的编码器即可。

需要两份数据，按各自的许可获取：

• 已重定向到本机器人 29 个关节的 AMASS 动作，每段一个 NPZ 文件；

• BABEL 标注的 train.json 和 val.json。

1.3 节中的 152 段动作不是完整的编码器训练数据。在 PredActor/motion_encoder/ 下按以下布局放置：

目录名和原始序列名必须与 BABEL 的 feat_p 路径对应，例如 ACCAD/<subject>/<sequence>_poses_120_jpos.npz 对应 BABEL 中 ACCAD/<subject>/<sequence>_poses.npz 的标注。文件名中的数字后缀可以不同。每个 NPZ 必须包含：

30 个刚体必须按 src/datasets/g1_amass_utils.py 中定义的顺序排列，pelvis 在首位；Isaac Lab 的刚体顺序不同，要先重排。

注意 轨迹要事先处理成 30 Hz。解析器会跳过帧率与 30 Hz 相差超过 5 Hz 的文件，它不负责 120 Hz 到 30 Hz 的转换；文件名中的数字后缀也不代表帧率。仓库 docs/motion_encoder.md 提到的公开重定向数据集，使用前要核对格式是否与上表一致，只改文件名不会转换坐标和刚体顺序。

本节之后的命令都在 PredActor/motion_encoder/ 中运行。解析器只收录有 BABEL 标注的动作，写出三个划分：

空的划分不会保存。重新生成时换一个新的输出目录。

amass_30fps_db.pt 是加载器的占位名，它会自动换成 _train.pt、_vald.pt 或 _test.pt，不需要创建这个文件。加载器把序列切成 100 帧的块，每个训练样本取其中连续 60 帧，所以短于 100 帧的序列不会产生训练样本。

先用 smoke 测试确认能跑通，输出放在单独的目录：

smoke 只检查能否执行，不代表模型质量。数据中至少要有两个描述不同的样本，文本–动作对比损失才有意义。

正式训练（也可以不激活环境，在仓库根目录运行 uv run --locked bash PredActor/motion_encoder/scripts/train_g1_xyz.sh）：

脚本使用原始配方：训练 100 个 epoch，batch size 20，学习率 1e-4，8 层 Transformer，512 维隐空间，16 个 DataLoader 进程，每 10 个 epoch 保存一次。动作模型从随机初始化开始，CLIP 文本塔一起训练；不会加载发布的编码器。第一次运行会下载 CLIP ViT-B/32 权重。

完成后，exps/g1-model-xyz-clip/ 中有 checkpoint_0100.pth.tar、opt.yaml、training.log、TensorBoard 事件文件和 training_receipt.json。checkpoint 包含动作模型和训练后的 CLIP 权重，不含优化器状态。

回到仓库根目录，把新 checkpoint 传给第 4 节的标注脚本：

之后按第 5 节重新训练策略。

注意 评测时输入的文本必须用标注数据时的同一个编码器编码。resolved_config.yaml 在训练开始时记下评测所用的编码器路径，默认是发布的 MotionCLIP checkpoint。用新编码器标注的数据训练时，在第 5 节的训练命令末尾加上 env_runner.task_cond_providers.clip_teleop.checkpoint_path=PredActor/motion_encoder/exps/g1-model-xyz-clip/checkpoint_0100.pth.tar， 让训练输出记录新编码器的路径，2.8 节的评测命令才会加载它。