LeRobot documentation

EnvHub:在 Hub 上共享模拟器

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

EnvHub:在 Hub 上共享模拟器

EnvHub 环境是一个 Hugging Face Hub 仓库,其中包含一个 env.py 文件,该文件按照 LeRobot 的约定构建 Gymnasium 环境(参见 环境)。该文件即为完整的集成:无需向 LeRobot 提交拉取请求,也无需发布软件包。一旦该文件上传至 Hub,任何人都可以:

  • 使用 lerobot-eval 在其上 evaluate 策略,
  • 使用 lerobot-rollout、lerobot-record、lerobot-teleoperate 和 lerobot-replay 将其作为机器人驱动,可与它所模拟的真实机器人互换,
  • 在本地、其自身的 Python 环境中运行,或者通过基于该仓库构建的 Docker 镜像中的 lerobot-env-server 进行服务化部署,从而确保模拟器的依赖项与策略的依赖项互不冲突。

本页介绍如何使用 EnvHub 环境,以及编写并发布环境所需的一切。仿真 深入讲解相关命令;添加基准测试 针对 LeRobot 在其 CI 中维护的基准测试。

使用 EnvHub 环境

在 EnvHub 环境集合 中浏览已发布的环境,或在 Hub 上搜索 envhub 标签。

示例使用 lerobot/so101-tabletop-mujoco:一个 SO-101 机械臂、四个方块和一个盒子放置在桌面上,通过 MuJoCo 进行仿真。其状态和动作与使用 use_degrees=True 的真实 so101_follower 一致。

提供

从 LeRobot 源代码检出(镜像基于其构建),并为容器提供 Docker 和 GPU 访问权限:

lerobot-env-server --envhub=lerobot/so101-tabletop-mujoco@<commit> --trust_remote_code=true --docker=true

首次使用时,该命令会构建一个包含该仓库及其 requirements.txt 的镜像,并在 localhost:7448 上启动服务器。--trust_remote_code=true 表示您同意在容器内运行该仓库的代码:请先阅读 env.py、requirements.txt 和 packages.txt,并固定您阅读过的 commit,以确保运行的正是该代码且结果可复现。如果不设置此参数,服务器将拒绝启动。客户端需要安装 remote 额外依赖(pip install 'lerobot[remote]')。

服务器也可以运行在另一台机器上,例如 GPU 工作站或云实例,而策略则运行在您的机器上:请参阅 服务器运行位置。

评估策略

lerobot-eval \
  --policy.path=<your SO-101 checkpoint> \
  --env.type=envhub --env.hub_path=lerobot/so101-tabletop-mujoco@<commit> \
  --env.server.endpoint=tcp/127.0.0.1:7448 \
  --rename_map='{"observation.images.front": "observation.images.camera1", "observation.images.wrist": "observation.images.camera2"}' \
  --eval.n_episodes=10 --eval.batch_size=1

观测数据以 observation.images.<camera> 和 observation.state 的形式到达策略;--rename_map 将它们映射到检查点训练时使用的名称。

像机器人一样驱动它

相同的环境是一个机器人:--robot.type=sim,环境选项位于 --robot.env.* 下。使用真实的 SO-101 主臂对其进行遥操作,就像操作真实的从臂一样:

lerobot-teleoperate \
  --robot.type=sim --robot.env.type=envhub --robot.env.hub_path=lerobot/so101-tabletop-mujoco@<commit> \
  --robot.env.server.endpoint=tcp/127.0.0.1:7448 \
  --teleop.type=so101_leader --teleop.port=/dev/ttyACM0 --teleop.id=my_leader \
  --fps=30 --display_data=true

lerobot-record 接受相同的选项来录制数据集,lerobot-rollout 用于运行策略。数据集会像真实的跟随器一样,记录环境声明的机器人本体,此处为 so_follower。有关回合、频率和录制的详细信息,请参阅 运行仿真机器人。

在本地运行

如果不使用 --env.server.endpoint(或 --robot.env.server.endpoint),环境将在你的进程中运行。请在 LeRobot 旁边安装其 requirements.txt,并添加 --env.trust_remote_code=true(--robot.env.trust_remote_code=true):你的进程将运行该仓库的 env.py。在托管模式下,你的进程永远不会运行它,因此客户端无需授权:服务器的 --trust_remote_code=true 已涵盖此情况。

从本地文件夹

包含 env.py 的文件夹可以在任何 Hub 仓库可用的地方使用,无论是您正在编写的环境还是您已读取的克隆: --env.hub_path=./my-env、 --robot.env.hub_path=./my-env、 --envhub=./my-env。由于它本质上仍是代码,因此需要相同的授权。若要无需构建镜像即可提供服务,请去掉 --docker=true:此时服务器将在您当前的 Python 环境中运行,并在其中安装该文件夹的 requirements.txt。

lerobot-env-server --envhub=./my-env --trust_remote_code=true                  # in your Python environment
lerobot-env-server --envhub=./my-env --trust_remote_code=true --docker=true    # in an image built from the folder

创建环境

该仓库

文件必需内容
env.py是的make_env、环境,以及可选的 LEROBOT_SIM
requirements.txtno服务器镜像中需要安装的 Python 包 env.py
packages.txtnoUbuntu 软件包,每行一个,安装在服务器镜像中
README.md是的环境模拟的内容、其观测、动作、任务、奖励和回合结束条件、运行命令以及许可证
其他no场景、机器人模型、纹理、配置文件:env.py 会在自身所在目录中查找它们,适用于所有模式

在 Hub 上将其创建为模型仓库。

Python 及依赖项

LeRobot 需要 Python 3.12 或更高版本,您的环境也是如此:在本地,env.py 在 LeRobot 的进程中运行,而服务器镜像运行的是 Ubuntu 24.04 的 Python 3.12。仅支持旧版 Python 的模拟器(例如基于 Python 3.11 的 Isaac Sim 5 和 Isaac Lab 2)在两种方式下均无法运行;请使用支持 Python 3.12 的版本(例如 RoboLab 所使用的 Isaac Sim 6 和 Isaac Lab 3)。

服务器镜像仅包含服务器所需的内容:既没有 torch,也没有 LeRobot 的其他部分。请在 requirements.txt 中列出 env.py 导入的所有内容,如果模拟器需要 torch 也请包含在内,并固定版本号。

make_env

env.py 必须定义 make_env(n_envs: int = 1, use_async_envs: bool = False, **kwargs),该函数返回 {suite_name: {task_id: vector_env}},其中每个 vector env 包含该任务的 n_envs 个环境:

def make_env(n_envs: int = 1, use_async_envs: bool = False, **kwargs):
    factory = partial(MyEnv, **kwargs)
    vector_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv
    return {"my_task": {0: vector_cls([factory] * n_envs)}}
  • 如上所述,使用每个环境的工厂函数分别构建每个向量环境,并以未包装的形式返回:LeRobot 会接收这些工厂函数并自行运行环境(参见 批次)。自定义的向量包装器或子类会被拒绝,而不是被静默丢弃。单个 gym.Env 也被接受,视为一个任务 ID 为 0 的套件。
  • 多个测试套件或任务 ID 构成一个多任务基准测试:lerobot-eval 会报告每个任务、每个套件以及整体的成功率。仿真机器人会运行由 --robot.env.task 指定的套件(默认为第一个),以及由 --robot.task_id 指定的任务。
  • kwargs 是环境自身的选项。用户通过 --env.make_env_kwargs='{"episode_length": 900}'(对于仿真机器人,使用 --robot.env.make_env_kwargs)来传递它们;服务器则通过 --sim.kwargs='{make_env_kwargs: {episode_length: 900}}' 来接收它们。
  • env.py 在每个进程中只导入一次,因此它可以保存进程级别的状态,例如只能启动一次的模拟器应用(Isaac Sim 的 SimulationApp)。

环境

每个环境都是一个遵循以下约定的 gym.Env。标准的 Gymnasium 环境通常不符合这些约定:CartPole 的观测是一个扁平向量,其动作为离散值,因此 LeRobot 会拒绝它。请封装此类环境,使其返回该观测字典以及一个连续动作 Box。

什么合约
观察一个 NumPy 数组字典:pixels(一张 HWC uint8 RGB 图像,或一个包含此类图像的字典,每个相机一张)、agent_pos(机器人的状态)以及可选的 environment_state。其他数组将直接传递
操作一维连续Box
task_description提供给策略的语言指令(回退到 task)
_max_episode_steps步数上限,超过该值后 LeRobot 将截断该回合(若未指定则为 500)
step() 返回当回合结束(成功或失败)时为 terminated,当回合被提前截断时为 truncated
info["is_success"]在每次 step() 时,任务是否已完成
info["metrics"]可选:其他需要报告的数值,{name: float};lerobot-eval 会按每个 episode 分别记录,取值于该 episode 结束时的 step

LeRobot 将观测映射到 observation.images.<camera>(对于单个未命名的图像为 observation.image)、observation.state 和 observation.environment_state。请在环境内部将模拟器的输出转换为这些约定:相机图像保持正立,状态使用与动作相同的单位和顺序(当它们共享关节时)。

如果你的模拟器会分配 GPU 或 EGL 上下文,请在首次调用 reset() 时创建它们,而不是在 __init__ 中创建,以确保在工作进程中构建的环境不会继承过期的句柄。

LEROBOT_SIM

env.py 中用于描述环境的模块级字典。它在本地和提供服务时均生效,且每个键都是可选的:

密钥含义默认
fps控制速率:每秒模拟时间内的step()次数30
control_mode动作约定:position、delta 或 eef_pose"position"
semantics观察和动作约定的名称"envhub-v1"
state_namesobservation.state 组件的名称,按顺序排列state_0, state_1, …
action_names按顺序排列的操作组件名称command_0, command_1, …
robot_type模拟机体,记录为数据集的 robot_type无(数据集记录 sim_robot)

当默认值与您的环境不匹配时,请始终声明它。未知的键会引发错误,并提示最接近的有效键。服务器的 --sim.* 选项会覆盖它,例如 --sim.fps=15。

为了让环境成为 LeRobot 支持的某个真实机器人的孪生体,请使用该机器人的名称、单位和 robot_type。这样,遥操作者就可以像驱动真实从动机器人一样驱动它,在仿真和硬件上记录的 dataset 将保持一致,在一个平台上训练的 checkpoint 也能在另一个平台上运行。对于 SO-101,即 shoulder_pan.pos … gripper.pos,单位为度,夹爪范围为 0 到 100,且 robot_type: "so_follower"。如果 LeRobot 没有针对您的机器人的类,请选择一个简短的 snake_case robot_type(panda、sawyer)。

完整示例

一个用于移动到目标点的示例,除 Gymnasium 和 NumPy 外没有其他依赖。它满足上述所有要求;请将其复制作为起点:

# env.py
from functools import partial

import gymnasium as gym
import numpy as np
from gymnasium import spaces

JOINTS = ["x.pos", "y.pos"]

# How LeRobot describes this environment, locally and when served. Every key is optional.
LEROBOT_SIM = {
    "fps": 10,
    "control_mode": "position",
    "state_names": JOINTS,
    "action_names": JOINTS,
}


class ReachEnv(gym.Env):
    """Move a point to a target on a plane. The action is the point's next position, in [-1, 1]."""

    metadata = {"render_modes": ["rgb_array"], "render_fps": 10}

    def __init__(self, image_size: int = 96, episode_length: int = 100):
        super().__init__()
        self.image_size = image_size
        self._max_episode_steps = episode_length
        self.task = "reach"
        self.task_description = "Move the blue point onto the red target."
        image = spaces.Box(0, 255, (image_size, image_size, 3), np.uint8)
        self.observation_space = spaces.Dict(
            {"pixels": spaces.Dict({"top": image}), "agent_pos": spaces.Box(-1, 1, (2,), np.float32)}
        )
        self.action_space = spaces.Box(-1, 1, (2,), np.float32)

    def reset(self, seed=None, options=None):
        super().reset(seed=seed)
        self.point = self.np_random.uniform(-1, 1, 2).astype(np.float32)
        self.target = self.np_random.uniform(-1, 1, 2).astype(np.float32)
        return self._obs(), {"is_success": False}

    def step(self, action):
        self.point = np.clip(np.asarray(action, np.float32), -1, 1)
        distance = float(np.linalg.norm(self.point - self.target))
        success = distance < 0.1
        info = {"is_success": success, "metrics": {"distance": distance}}
        # Ends on success (terminated); LeRobot truncates the episode after _max_episode_steps.
        return self._obs(), -distance, success, False, info

    def _obs(self):
        image = np.full((self.image_size, self.image_size, 3), 255, np.uint8)
        for xy, color in ((self.target, (220, 40, 40)), (self.point, (40, 40, 220))):
            col, row = ((xy + 1) / 2 * (self.image_size - 1)).astype(int)
            image[max(row - 3, 0) : row + 4, max(col - 3, 0) : col + 4] = color
        return {"pixels": {"top": image}, "agent_pos": self.point.copy()}


def make_env(n_envs: int = 1, use_async_envs: bool = False, **kwargs):
    """The EnvHub entry point. `kwargs` come from --env.make_env_kwargs."""
    factory = partial(ReachEnv, **kwargs)
    vector_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv
    return {"reach": {0: vector_cls([factory] * n_envs)}}

对于真实的模拟器,请参阅 lerobot/so101-tabletop-mujoco(MuJoCo)和 lerobot/so101-tabletop-isaac(Isaac Sim,通过 requirements.txt 和 packages.txt 安装)。它们提供相同的 SO-101 场景,具有相同的观测、动作和 LEROBOT_SIM,因此相同的策略和命令可以针对两者运行。更多环境可在 EnvHub 环境集合 中找到。

批次

lerobot-eval --eval.batch_size=N 会同时运行 N 个任务环境,并且 make_env 会接收到 n_envs=N;一个仿真机器人对应一个环境。一个批次通过以下两种方式之一进行步进。

LeRobot 对一批单环境进行步进,这是默认行为,也是大多数模拟器(MuJoCo、PyBullet 等)所需的方式。请编写一个 gym.Env 来模拟单个环境,并在 make_env 中返回 n_envs 个该环境的工厂,如上所述。LeRobot 会从这些工厂构建环境:使用 --eval.use_async_envs=true(默认值)时,每个环境都在其独立的工作进程(worker process)中运行,批次步进并行执行;使用 false 时,它们都在同一个进程中依次运行。LeRobot 仅使用这些工厂,因此 make_env 将它们构建为哪种向量类(vector class)并无区别。

您的模拟器对整个批次进行步进,当它在单个世界中持有所有环境并同时步进它们时,例如 Isaac Lab 等 GPU 模拟器。同样在 env.py 中定义 vector_env_fns,为每个任务返回一个工厂,每个工厂构建一个包含 n_envs 个环境的向量环境;LeRobot 随后会用它来替代 make_env:

from functools import partial


def vector_env_fns(task: str, n_envs: int, **make_env_kwargs):
    # {suite_name: {task_id: factory}}, each factory building one vector env of n_envs envs
    return {"suite_1": {0: partial(MyBatchedEnv, n_envs, "Task1"), 1: partial(MyBatchedEnv, n_envs, "Task2")}}

每个向量环境必须满足 num_envs == n_envs,且必须禁用自动重置(metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED)。它以上述格式返回批量观测,在 reset(seed=[...]) 中为每个环境接收一个种子,并按环境报告 info["is_success"]。--env.make_env_kwargs 会传递给该环境。由于它已经对整个批次执行了步进,请使用 --eval.use_async_envs=false 进行评估:工作进程只会将每个批次在进程间复制,而服务器则会在工作进程中第二次构建模拟器。

vector_env_fns 同样适用于包含许多任务的基准测试:调用 make_env 时会构建所有任务的环境,而只有正在运行的任务的工厂函数会被调用。

发布前进行测试

每个步骤都会使用包含 env.py 的本地文件夹来替代 Hub 仓库。

  1. 按照 LeRobot 的方式构建环境,并检查观测的键、形状和任务:

    import numpy as np
    
    from lerobot.envs import HubEnvConfig, make_env
    
    # LeRobot's make_env, which calls the make_env of your env.py
    envs = make_env(HubEnvConfig(hub_path="./my-env", trust_remote_code=True), n_envs=2)
    suite = next(iter(envs))
    env = envs[suite][0]
    obs, info = env.reset(seed=0)
    print({key: (value.shape, value.dtype) for key, value in obs.items()})
    print(env.call("task_description"))
    obs, reward, terminated, truncated, info = env.step(np.zeros(env.action_space.shape, np.float32))
    print(reward, terminated, truncated, info["is_success"])
    env.close()
  2. 将其视为机器人:状态和动作名称,以及摄像头视图:

    from lerobot.envs.configs import HubEnvConfig
    from lerobot.robots.sim_robot import SimRobot, SimRobotConfig
    
    robot = SimRobot(SimRobotConfig(env=HubEnvConfig(hub_path="./my-env", trust_remote_code=True)))
    print(robot.robot_type, list(robot.action_features))
    robot.connect()
    observation = robot.get_observation()
    robot.send_action({name: observation[name] for name in robot.action_features})
    robot.disconnect()

    当遥操作者的动作与你的动作一致时,lerobot-teleoperate --robot.type=sim --robot.env.type=envhub --robot.env.hub_path=./my-env --robot.env.trust_remote_code=true ... --display_data=true 会在你驾驶时通过 Rerun 显示摄像头画面。

  3. 从该文件夹启动服务,该服务会根据您的 requirements.txt 和 packages.txt 构建镜像,然后使用 --env.server.endpoint=tcp/127.0.0.1:7448 对其执行相同的检查:

    lerobot-env-server --envhub=./my-env --trust_remote_code=true --docker=true

    --build=true 仅重新构建发生更改的部分:当 packages.txt 更改时重新构建 apt 软件包,当 requirements.txt 更改时重新构建依赖项,否则仅重新构建仓库中的文件。

发布

将文件夹上传到 Hub 上的模型仓库,然后:

  • 请注意提交记录,并在 README 的命令中使用它:用户运行的正是你测试过的内容。
  • 在 README 中说明仓库包含的所有内容(机器人模型、场景、纹理)的许可证,以及如果您有的话,提供一个参考结果:一个检查点、其修订版本、lerobot-eval 命令以及其获得的成功率。
  • 在 README 的元数据中添加 tags: [lerobot, envhub],以便在 Hub 上找到该环境。
  • 要将其列入 EnvHub 环境集合,请在 LeRobot 的 GitHub 上提交一个 issue,并附上该仓库的链接。

更新即新的提交:固定到旧提交的用户将继续运行他们已审查的代码。

参考

Hub 路径

--env.hub_path(服务器端为 --envhub)接受以下参数:

模式加载示例
user/repo主分支中的 env.pylerobot/so101-tabletop-mujoco
user/repo@revision位于某个提交、分支或标签的 env.pylerobot/so101-tabletop-mujoco@4684f500b94d07194f2c860314c4e27cb9349e8c
user/repo:path另一个文件my-org/my-envs:envs/task_a.py
user/repo@rev:path某个修订版本中的另一个文件my-org/my-envs@v1.0:envs/task_a.py
./folder本地文件夹中的 env.py./my-env

版本

环境的版本即其在 Hub 上的提交。在 @ 之后指定的修订版本(提交、分支或标签)会在您的进程和服务器上选定其中一个:

  • 在你的进程中,该修订版本的仓库会被下载并缓存。如果不指定修订版本,每次运行都会跟踪 main 的最新提交。
  • 在服务器上,--envhub=user/repo@<revision> 会根据该修订版本的文件构建镜像,每个修订版本都会生成一个独立的镜像。如果未指定修订版本,镜像将保留构建时最新的提交,直到使用 --build=true 从最新版本重新构建。
  • 为发布版本添加标签,以便用户固定名称而非哈希值,并将main保留用于开发。为论文和对比固定一个提交:与标签或分支不同,提交无法移动。

选项

选项含义
--env.type=envhubEnvHub 环境(对于模拟机器人,使用 --robot.env.type=envhub)
--env.hub_path该仓库,请参阅 Hub 路径
--env.trust_remote_code同意在你的进程中运行该仓库的代码;在提供服务时无需此操作
lerobot-env-server --trust_remote_code=true同意在服务器上运行该仓库的代码,这是通过 --envhub 或 YAML 提供该仓库所必需的
--env.make_env_kwargsmake_env 的关键字参数;在提供服务时,请在服务器上设置它们
--env.server.endpoint在 env 服务器上运行环境;有关其他服务器选项,请参阅 Simulation
lerobot-env-server --envhub=<path>提供仓库服务;使用 --docker=true 时,在基于该仓库构建的镜像中提供服务
lerobot-env-server --sim.kwargs=...服务器的 make_env 选项,例如 '{make_env_kwargs: {episode_length: 900}}'
lerobot-env-server --sim.<key>=...覆盖 LEROBOT_SIM 值,例如 --sim.fps=15

安全

运行 EnvHub 环境会执行其代码,且使用您的权限。LeRobot 绝不会在未经您明确同意的情况下运行该代码:在您的进程中为 trust_remote_code,在服务器上为 --trust_remote_code=true。在授予权限之前:

  1. 阅读 env.py、requirements.txt 和 packages.txt。
  2. 固定您阅读时的提交。
  3. 更推荐以容器方式运行:在容器内,代码看到的是其镜像和服务器的配置,而不是您本地的文件。该容器会共享宿主机的网络。

故障排除

错误修复
Refusing to run the EnvHub environment阅读完代码后,添加 --env.trust_remote_code=true(--robot.env.trust_remote_code=true),或者提供该环境
failed to import because the dependency '<name>' is not installed在 LeRobot 旁边安装该仓库的 requirements.txt,或提供环境
requires an unwrapped SyncVectorEnv or AsyncVectorEnv返回由工厂构建的向量环境,不包含包装器
LEROBOT_SIM has unknown keys使用 LEROBOT_SIM 中列出的键;错误信息会指出最接近的键
The env server at ... runs another environment than this command describes服务器运行的环境与 --env.* 所描述的不同;请传入相同的选项,或使用您的选项重启服务器
A sim robot needs an observation.state feature with component names在观察中返回 agent_pos
images must be HWC uint8 with three channels将相机图像转换为高度 x 宽度 x 3 的uint8
Update on GitHub