I-BFM 使用指南

I-BFM 是开源的人形机器人–物体交互行为基础模型。它用 forward–backward 表示和无监督强化学习，学出人形机器人、物体和接触的共同表示；下游任务只需给出一个奖励函数，就能推断出对应的意图向量，让同一个策略完成搬箱、推箱、踢箱等交互，不需要为每个任务再训练。

在搬箱任务中，I-BFM 无扰动时的成功率为 94.3%，机器人摔倒后仍有 89.3%；作为对比，基于规划的基线方法在机器人摔倒后只有 1.3%。

资源入口：

本节介绍 I-BFM 的工作原理、发布内容和环境配置。完成本节后，你可以下载发布的模型，并在仿真中运行一次搬箱任务。

想先看效果，可以打开项目页的 Live MuJoCo Session，在浏览器中运行搬箱和键盘控制。

1. 共享表示。 I-BFM 用 forward–backward（FB）表示学习人形机器人、物体和接触的耦合动力学。Backward 编码器把状态映射到 256 维的意图空间，策略以意图向量 z 为条件输出动作。

2. 无监督预训练。 预训练时不针对任何具体任务，混合使用 LaFAN 动作（30%）、搬箱动作（40%）和踢箱动作（30%）作为行为先验，在仿真中在线交互。

3. 双时间尺度目标。 训练同时使用短时的交互目标和较长时的目标（目标视野 8 步），让策略在不同时间尺度上都能控制交互。

4. 奖励推断。 给出下游任务的奖励函数，用 replay 中的样本按这个奖励加权，就能算出完成该任务的意图向量 z，策略不需要再训练。

5. 任务控制器。 搬箱、推箱、踢箱各有一个控制器，按阶段（接近、对准、抬起、搬运、放下、倒地起身等）切换预先推断好的意图向量，形成闭环。

仓库不包含实机部署程序。

注意 训练源码沿用上游 BFM-Zero 的 CC BY-NC 4.0 许可证，仅限非商业用途。

1. git lfs pull 下载模型的两段权重、LaFAN 动作和搬箱 / 踢箱动作缓存。

2. restore_checkpoint.sh 先核对两段的 SHA-256，再拼接成 checkpoints/ibfm-166m/model/model.safetensors 并核对结果。成功时打印 Restored …；已经还原过时打印 Checkpoint is already restored.。

3. uv sync 在 ibfm/.venv 中按 uv.lock 安装依赖。

注意 没有执行 git lfs pull 时，两段权重只是几百字节的指针文件，restore_checkpoint.sh 会因 SHA-256 不符而退出。先运行 git lfs pull，再重新还原。

提示 本文后续命令都在 ibfm/ 目录中运行。

在没有显示器的机器上，用无窗口模式跑 100 步搬箱：

脚本先生成一个随机场景，再加载发布模型运行。结束时打印轨迹、控制器摘要和高度测试结果的路径（Trace:、Controller:、Height tests:），说明模型和环境都已就绪。

有桌面环境时，直接运行 ./tasks/carry_box/run_interactive.sh，会打开 MuJoCo 窗口并录制视频，见 2.2 节。

本节用发布模型在 MuJoCo 中运行三个交互任务。三个任务共用同一个模型，区别在于任务控制器和使用的意图向量。命令都在 ibfm/ 中运行。

打开查看窗口时，可以用键盘改变目标或制造干扰：

查看窗口使用 GLFW，需要桌面环境。搬箱脚本在没有设置 DISPLAY 时默认使用 :1；如果你的显示器编号不同，先在终端中设置正确的 DISPLAY。

机器人走向箱子、对准、抱起，搬到目标位置后放下；中途倒地会先起身再继续。

脚本依次做两件事：

1. 生成随机场景：机器人与箱子相距 1.5–2.0 m，目标高度 0.65 m，结果写入 tasks/carry_box/random_height_scene/。

2. 运行搬箱控制器：箱子为 0.30 m 的立方体，质量 0.70 kg。

搬箱的 R 键有额外作用：先给当前一轮记分，再把箱子放到 0.15–0.80 m 之间的一个随机高度，开始新一轮。每一轮记录是否成功抱起，以及箱子中心与目标的三维距离；距离小于 0.20 m 记为放置成功。

常用环境变量：

输出写在 tasks/carry_box/interactive/random_height_<RECORD_TAG>/：

机器人先绕到箱子后方、对准，再用手推着箱子走向目标。目标默认在箱子初始位置沿 X 方向 2.0 m 处；判定到达时，除了箱子与目标的水平距离要在阈值（默认 0.40 m）以内，控制器还会检查箱子是否已经停稳、平放在地面上。第一个参数可以指定输出目录名，例如 ./tasks/push_box/run_interactive.sh test1。

输出 <OUTPUT_ROOT>/<名称>/push_box.mp4、rollout.csv 和 summary.json。

机器人用脚接触箱子，把它踢向目标。目标在箱子初始位置沿 X 方向 2.0 m 处，目标标记半径为 0.20 m。踢箱脚本默认打开窗口、不录视频、在 CPU 上推理。

输出 rollout.csv 和 summary.json，录制时另有 kick_box.mp4。

注意 踢箱脚本即使设置 VIEWER=0，也默认使用 GLFW。在没有桌面的机器上运行时，同时设置 MUJOCO_GL=egl 和一个有限的 MAX_STEPS，例如 VIEWER=0 MUJOCO_GL=egl MAX_STEPS=3000 ./tasks/kick_box/run_interactive.sh。

项目页公布的仿真成功率（%）：

本节说明训练用的动作数据在哪里，以及如何把自己的动作转换成训练格式。命令在 ibfm/ 中运行。

发布模型的数据配比写在 configs/data/g1_lafan_carry_kick_30_40_30.yaml，三份数据都随 git lfs pull 下载：

比例是按数据源计算的，与各数据源中的动作条数无关。

自己的动作可以是机器人状态格式的 CSV 或 NPZ。CSV 每行一帧，包含根节点位置（如 root_pos_x/y/z）、根节点四元数（如 root_quat_x/y/z/w，xyzw 顺序）和按机器人 XML 顺序排列的关节角；帧率用 --fps 指定。

1. 检查能否被正确读取：

   uv run python -m humanoidverse.tools.data_inspect \
     --robot configs/robots/g1_29dof.yaml \
     --source <你的 CSV 或 NPZ，或所在目录>
   

2. 生成数据清单并构建缓存：

   uv run python -m humanoidverse.tools.data_build \
     --robot configs/robots/g1_29dof.yaml \
     --source <你的 CSV 或 NPZ，或所在目录> \
     --name <数据集名> --fps <帧率> \
     --out <清单路径>.yaml
   

   默认按 10 秒切分（--clip-seconds），保留短于 10 秒但长于 1 秒的片段。

3. 训练时用 --data-manifest <清单路径>.yaml 指定数据（见 4.4 节）。要和发布数据混合，参照 configs/data/g1_lafan_carry_kick_30_40_30.yaml 的写法，在同一个清单中列出多个数据源并设置 weight。

清单的完整写法可以参考 configs/data/example_robot_state_auto_build.yaml。

本节按发布配置从头训练 I-BFM。需要 8 张 H200；命令在 ibfm/ 中运行。

参数是本次运行的名称，输出写在 runs/ibfm_reproduction/。名称不能包含斜杠，目录已存在时脚本拒绝覆盖。

脚本使用发布的配置：

发布模型取自这类训练的第 166,559,744 步。

训练中的随机化（来自任务配置）：箱子名义质量 0.7 kg，在 0.5–1.0 kg 间随机；关节 PD 增益在 0.75–1.25 倍间随机；控制延迟 0–1 步（一步 20 ms）；脚底摩擦在 0.4–1.25 间随机。

policies/ 中的策略只包含权重和配置，不含优化器和 replay。Replay 只在训练正常结束时写入最终的滚动 checkpoint 一次。

续训从滚动 checkpoint 中的模型和优化器继续。

注意 中途保存的 checkpoint 不含 replay，续训时 replay 要重新收集，所以续训的结果会和不中断的训练不同。

用单张 GPU 跑一个很短的训练，确认环境可用：

smoke 模式使用 16 个环境、2048 个环境步，不记录 W&B。run_train.sh 是训练入口 humanoidverse.train 的包装，会设置缓存目录后再启动；正式训练的完整参数见 scripts/train_ibfm_h200.sh。

注意 scripts/smoke_release.sh 的最后一步会读取 humanoidverse/data/examples/g1_robot_state_sample.csv，这个文件不在仓库中，该步骤会失败。只需检查训练时，用上面的命令即可。

本节用发布模型或自己训练的模型做动作跟踪、目标到达和奖励推断。命令在 ibfm/ 中运行。--model-folder 指向包含 checkpoint/ 的目录：发布模型用 tasks/common/checkpoint_ref，自己训练的模型用 runs/<名称>。

策略把参考动作编码成意图向量并在仿真中跟踪，--save-mp4 输出参考动作与策略执行的对比视频。默认数据是 humanoidverse/data/lafan_29dof_10s-clipped.pkl。

输出 zs_<编号>.pkl（意图向量）和 tracking_<编号>.mp4。

策略依次到达一组目标姿态，默认列表为 humanoidverse/data/robots/g1/goal_frames_lafan29dof.json，可用 --goal-json 替换。默认共运行 2100 步，每 100 步切换一个目标（--episode-len、--goal-switch-interval）。

奖励推断需要 replay。发布模型的 replay 在 Hugging Face 上，共 8 个分片，约 210 GiB；在 ibfm/ 中下载：

下载后，runs/ibfm_166560m_replay/checkpoint/buffers/train_rank_0/ 到 train_rank_7/ 中各有一个 buffer.hdf5 和 config.json。用其中一个分片做奖励推断：

输出 <model-folder>/reward_inference/reward_locomotion.pkl，以及每个任务一个视频。

注意 读取一个分片会把整个文件载入内存，单个分片约 28 GB，运行前确认内存足够。

提示 交互任务使用的意图向量已经推断好，放在各任务的 latents/ 目录中，运行第 2 节的任务不需要下载 replay。