LeRobot documentation
EnvHub:在 Hub 上共享模拟器
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=truelerobot-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.txt | no | 服务器镜像中需要安装的 Python 包 env.py |
packages.txt | no | Ubuntu 软件包,每行一个,安装在服务器镜像中 |
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_names | observation.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 仓库。
按照 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()将其视为机器人:状态和动作名称,以及摄像头视图:
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 显示摄像头画面。从该文件夹启动服务,该服务会根据您的
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.py | lerobot/so101-tabletop-mujoco |
user/repo@revision | 位于某个提交、分支或标签的 env.py | lerobot/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=envhub | EnvHub 环境(对于模拟机器人,使用 --robot.env.type=envhub) |
--env.hub_path | 该仓库,请参阅 Hub 路径 |
--env.trust_remote_code | 同意在你的进程中运行该仓库的代码;在提供服务时无需此操作 |
lerobot-env-server --trust_remote_code=true | 同意在服务器上运行该仓库的代码,这是通过 --envhub 或 YAML 提供该仓库所必需的 |
--env.make_env_kwargs | make_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。在授予权限之前:
- 阅读
env.py、requirements.txt和packages.txt。 - 固定您阅读时的提交。
- 更推荐以容器方式运行:在容器内,代码看到的是其镜像和服务器的配置,而不是您本地的文件。该容器会共享宿主机的网络。
故障排除
| 错误 | 修复 |
|---|---|
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 |