Meta Motivo

Meta, FAIR

概述

本仓库提供了 Meta Motivo 的 PyTorch 实现及预训练模型。详细信息请参阅论文《通过行为基础模型实现零样本全身人形机器人控制》（链接）。

特性

• 我们提供了 6 个预训练的 FB-CPR 模型，用于控制 HumEnv 中定义的人形机器人模型。
• 完全可复现 的脚本，用于在 HumEnv 中评估模型。
• 完全可复现 的 FB-CPR 在 HumEnv 中的训练代码，以复现论文中的全部结果；以及 FB 在 DMC 中的训练代码，便于更快速地进行实验。

安装

该项目可以通过 pip 直接安装到您的环境中。

pip install "metamotivo[huggingface,humenv] @ git+https://github.com/facebookresearch/metamotivo.git"

它需要 Python 3.10 或更高版本。可选依赖包括 humenv["bench"] 和 huggingface_hub，用于测试、训练以及从 HuggingFace 加载模型。

预训练模型

为确保可复现性，我们提供了所有 5 个模型（metamotivo-S-X），这些模型是我们为生成 论文 中的结果而训练的，每个模型使用不同的随机种子进行训练。此外，我们还提供了最大且性能最优的模型（metamotivo-M-1），您也可以在我们的 演示页面 上对其进行交互式测试。

模型	参数量	下载链接
metamotivo-S-1	24.5M	链接
metamotivo-S-2	24.5M	链接
metamotivo-S-3	24.5M	链接
metamotivo-S-4	24.5M	链接
metamotivo-S-5	24.5M	链接
metamotivo-M-1	288M	链接

快速入门

库安装完成后，您可以轻松创建一个 FB-CPR 代理，并从 Hugging Face 模型库下载预训练模型。请注意，该模型是 torch.nn.Module 的实例，默认情况下以“推理”模式初始化（即 no_grad 和 eval 模式）。

我们提供了一些简单的代码片段来演示如何使用该模型。更多详细的示例，请参阅我们的教程：与模型交互、运行评估以及 从头开始训练。

下载预训练模型

以下代码片段展示了如何实例化模型：

from metamotivo.fb_cpr.huggingface import FBcprModel

model = FBcprModel.from_pretrained("facebook/metamotivo-S-1")

下载缓冲区

对于每个模型，我们提供：

• 训练缓冲区（可用于推理或离线训练）
• 小型奖励推理缓冲区（包含进行奖励推理所需的最少信息）

from huggingface_hub import hf_hub_download
import h5py

local_dir = "metamotivo-S-1-datasets"
dataset = "buffer_inference_500000.hdf5"  # 可用于奖励推理的小型缓冲区
# dataset = "buffer.hdf5"  # 模型的完整训练缓冲区
buffer_path = hf_hub_download(
        repo_id="facebook/metamotivo-S-1",
        filename=f"data/{dataset}",
        repo_type="model",
        local_dir=local_dir,
    )
hf = h5py.File(buffer_path, "r")
print(hf.keys())

# 创建一个 DictBuffer 对象，可用于采样
data = {k: v[:] for k, v in hf.items()}
buffer = DictBuffer(capacity=data["qpos"].shape[0], device="cpu")
buffer.extend(data)

FB-CPR 模型

FB-CPR 模型包含多个网络：

• 前向网络
• 后向网络
• 评论家网络
• 判别器网络
• 行动者网络

我们提供了用于评估这些网络的函数：

def backward_map(self, obs: torch.Tensor) -> torch.Tensor: ...
def forward_map(self, obs: torch.Tensor, z: torch.Tensor, action: torch.Tensor) -> torch.Tensor: ...
def actor(self, obs: torch.Tensor, z: torch.Tensor, std: float) -> torch.Tensor: ...
def critic(self, obs: torch.Tensor, z: torch.Tensor, action: torch.Tensor) -> torch.Tensor: ...
def discriminator(self, obs: torch.Tensor, z: torch.Tensor) -> torch.Tensor: ...

我们还提供了简单的函数，用于向模型输入提示并获得表示要执行任务的上下文向量 z：

# 奖励提示（标准和加权回归）
def reward_inference(self, next_obs: torch.Tensor, reward: torch.Tensor, weight: torch.Tensor | None = None,) -> torch.Tensor: ...
def reward_wr_inference(self, next_obs: torch.Tensor, reward: torch.Tensor) -> torch.Tensor: ...
# 目标提示
def goal_inference(self, next_obs: torch.Tensor) -> torch.Tensor: ...
# 跟踪提示
def tracking_inference(self, next_obs: torch.Tensor) -> torch.Tensor:

一旦我们有了上下文向量 z，就可以调用行动者网络来获取动作。我们提供了一个使用标准接口在环境中执行动作的函数：

def act(self, obs: torch.Tensor, z: torch.Tensor, mean: bool = True) -> torch.Tensor:

请注意，这些函数不允许梯度计算，并且处于评估模式，因为它们预期用于推理（torch.no_grad() 和 model.eval()）。如果需要训练，则应直接访问类的属性。此外，我们还为前向、后向和评论家网络定义了目标网络。

执行策略

以下是一个执行随机策略的最小示例：

from humenv import make_humenv
from gymnasium.wrappers import FlattenObservation, TransformObservation
import torch
from metamotivo.fb_cpr.huggingface import FBcprModel

device = "cpu"
env, _ = make_humenv(
    num_envs=1,
    wrappers=[
        FlattenObservation,
        lambda env: TransformObservation(
            env, lambda obs: torch.tensor(obs.reshape(1, -1), dtype=torch.float32, device=device), env.observation_space # 对于 gymnasium <1.0.0，请移除最后一个参数：env.observation_space
        ),
    ],
    state_init="Default",
)

model = FBcprModel.from_pretrained("facebook/metamotivo-S-1")
model.to(device)
z = model.sample_z(1)
observation, _ = env.reset()
for i in range(10):
    action = model.act(observation, z, mean=True)
    observation, reward, terminated, truncated, info = env.step(action.cpu().numpy().ravel())

HumEnv 中的评估

为确保论文的可重复性，我们提供了使用 HumEnv 对模型进行评估的方法。我们提供了包装器，可用于将 Meta Motivo 与 humenv.bench 的奖励、目标和跟踪评估相集成。

以下是使用包装器进行奖励评估的示例：

from metamotivo.fb_cpr.huggingface import FBcprModel
from metamotivo.wrappers.humenvbench import RewardWrapper 
import humenv.bench

model = FBcprModel.from_pretrained("facebook/metamotivo-S-1")

# 启用奖励重新标注和上下文推理
model = RewardWrapper(
        model=model,
        inference_dataset=buffer, # 参见上文如何下载并创建缓冲区
        num_samples_per_inference=100_000,
        inference_function="reward_wr_inference",
        max_workers=80,
    )
# 创建 humenv 的评估
reward_eval = humenv.bench.RewardEvaluation(
        tasks=["move-ego-0-0"],
        env_kwargs={
            "state_init": "Default",
        },
        num_contexts=1,
        num_envs=50,
        num_episodes=100
    )
scores = reward_eval.run(model)

您可以对 humenv.bench 中提供的其他评估执行相同的操作。有关完整的评估流程，请参阅 tutorial_benchmark.ipynb。

渲染基于奖励或跟踪的策略

我们展示了如何渲染一个基于奖励策略的 episode。

import os
os.environ["OMP_NUM_THREADS"] = "1"
from humenv import STANDARD_TASKS
import mediapy as media

task = STANDARD_TASKS[0]
model = FBcprModel.from_pretrained("facebook/metamotivo-S-1", device="cpu")
rew_model = RewardWrapper(
        model=model,
        inference_dataset=buffer, # 参见上文如何下载并创建缓冲区
        num_samples_per_inference=100_000,
        inference_function="reward_wr_inference",
        max_workers=40,
        process_executor=True,
        process_context="forkserver"
    )
z = rew_model.reward_inference(task)
env, _ = make_humenv(num_envs=1, task=task, state_init="DefaultAndFall", wrappers=[gymnasium.wrappers.FlattenObservation])
done = False
observation, info = env.reset()
frames = [env.render()]
while not done:
    obs = torch.tensor(observation.reshape(1,-1), dtype=torch.float32, device=rew_model.device)
    action = rew_model.act(obs=obs, z=z).ravel()
    observation, reward, terminated, truncated, info = env.step(action)
    frames.append(env.render())
    done = bool(terminated or truncated)

media.show_video(frames, fps=30)

同样，也可以轻松渲染用于跟踪运动的策略。

import os
os.environ["OMP_NUM_THREADS"] = "1"
from metamotivo.wrappers.humenvbench import TrackingWrapper 
from pathlib import Path
from humenv.misc.motionlib import MotionBuffer

model = FBcprModel.from_pretrained("facebook/metamotivo-S-1", device="cpu")
track_model = TrackingWrapper(model=model)
motion_buffer = MotionBuffer(files=ADD_THE_DESIRED_MOTION, base_path=ADD_YOUR_MOTION_ROOT, keys=["qpos", "qvel", "observation"])
ep_ = motion_buffer.get(motion_buffer.get_motion_ids()[0]
ctx = track_model.tracking_inference(next_obs=ep_["observation"][1:])
observation, info = env.reset(options={"qpos": ep_["qpos"][0], "qvel": ep_["qvel"][0]})
done = False
observation, info = env.reset()
frames = [env.render()]
for t in range(len(ctx)):
    obs = torch.tensor(observation.reshape(1,-1), dtype=torch.float32, device=track_model.device)
    action = track_model.act(obs=obs, z=ctx[t]).ravel()
    observation, reward, terminated, truncated, info = env.step(action)
    frames.append(env.render())

media.show_video(frames, fps=30)

引用

@article{tirinzoni2024metamotivo,
  title={Zero-shot Whole-Body Humanoid Control via Behavioral Foundation Models},
  author={Tirinzoni, Andrea and Touati, Ahmed and Farebrother, Jesse and Guzek, Mateusz and Kanervisto, Anssi and Xu, Yingchen and Lazaric, Alessandro and Pirotta, Matteo},
}

许可证

Meta Motivo 采用 CC BY-NC 4.0 许可证授权。详情请参阅 LICENSE。

Meta Motivo 快速上手指南

Meta Motivo 是由 Meta FAIR 开源的基于行为基础模型（Behavioral Foundation Models）的人形机器人零样本控制框架。本指南帮助中国开发者快速完成环境配置并运行预训练模型。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python 版本: 3.10 或更高版本
• 核心依赖: PyTorch
• 可选依赖:
  • humenv["bench"]: 用于复现论文中的评估结果和基准测试。
  • huggingface_hub: 用于从 Hugging Face 下载预训练模型和数据缓冲区。

注意：由于涉及人形机器人仿真（HumEnv），建议在具备 GPU 加速的环境中进行训练或复杂推理，但基础推理可在 CPU 上运行。

安装步骤

本项目支持通过 pip 直接安装。推荐使用国内镜像源以加速下载过程。

1. 基础安装

执行以下命令安装核心库及 Hugging Face、HumEnv 相关依赖：

pip install "metamotivo[huggingface,humenv] @ git+https://github.com/facebookresearch/metamotivo.git" -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 验证安装

安装完成后，您可以尝试导入模块来验证环境是否正常：

from metamotivo.fb_cpr.huggingface import FBcprModel
print("Meta Motivo installed successfully!")

基本使用

以下是最小化的代码示例，演示如何加载预训练模型并在 HumEnv 环境中执行策略。

1. 加载预训练模型

Meta Motivo 提供了多个不同规模的预训练模型（如 metamotivo-S-1 到 metamotivo-M-1）。以下代码展示了如何从 Hugging Face Hub 下载并加载模型：

from metamotivo.fb_cpr.huggingface import FBcprModel

# 加载小型模型 metamotivo-S-1 (24.5M 参数)
model = FBcprModel.from_pretrained("facebook/metamotivo-S-1")

# 如果需要使用 GPU，请取消下行注释
# model.to("cuda") 

2. 下载数据缓冲区 (Buffer)

为了进行奖励推断（Reward Inference），需要下载对应的数据缓冲区文件：

from huggingface_hub import hf_hub_download
import h5py
from metamotivo.buffers import DictBuffer # 假设项目中包含此工具类，具体需参考官方 tutorial

local_dir = "metamotivo-S-1-datasets"
dataset = "buffer_inference_500000.hdf5"  # 用于奖励推断的小型缓冲区

# 下载文件
buffer_path = hf_hub_download(
    repo_id="facebook/metamotivo-S-1",
    filename=f"data/{dataset}",
    repo_type="model",
    local_dir=local_dir,
)

# 读取并构建 Buffer 对象
hf = h5py.File(buffer_path, "r")
data = {k: v[:] for k, v in hf.items()}
buffer = DictBuffer(capacity=data["qpos"].shape[0], device="cpu")
buffer.extend(data)

3. 执行策略 (最小化示例)

以下代码展示了如何初始化环境、生成任务上下文向量 z，并让智能体执行动作：

from humenv import make_humenv
from gymnasium.wrappers import FlattenObservation, TransformObservation
import torch

device = "cpu" # 或 "cuda"

# 初始化 HumEnv 环境
env, _ = make_humenv(
    num_envs=1,
    wrappers=[
        FlattenObservation,
        lambda env: TransformObservation(
            env, 
            lambda obs: torch.tensor(obs.reshape(1, -1), dtype=torch.float32, device=device), 
            env.observation_space
        ),
    ],
    state_init="Default",
)

# 加载模型并移至指定设备
model = FBcprModel.from_pretrained("facebook/metamotivo-S-1")
model.to(device)

# 采样一个随机任务上下文向量 z
z = model.sample_z(1)

# 重置环境
observation, _ = env.reset()

# 执行 10 步
for i in range(10):
    # 获取动作 (mean=True 表示使用确定性策略)
    action = model.act(observation, z, mean=True)
    
    # 环境步进
    observation, reward, terminated, truncated, info = env.step(action.cpu().numpy().ravel())
    
    if terminated or truncated:
        break

进阶提示

• 特定任务控制：若要控制机器人完成特定任务（如“向前移动”），需使用 RewardWrapper 结合下载的 buffer 进行 reward_inference 来获取特定的上下文向量 z，而非使用随机采样的 z。
• 动作追踪：若需让机器人模仿特定动作序列，可使用 TrackingWrapper 和 tracking_inference 方法。