Tải Môi trường từ Hub

Tính năng EnvHub cho phép bạn tải các môi trường mô phỏng trực tiếp từ Hugging Face Hub chỉ với một dòng mã. Điều này mở ra một mô hình hợp tác mạnh mẽ và mới: thay vì các môi trường bị khóa bên trong những thư viện đơn khối, bất kỳ ai cũng có thể xuất bản các môi trường tùy chỉnh và chia sẻ chúng với cộng đồng.

EnvHub là gì?

EnvHub cho phép bạn tạo các môi trường mô phỏng robotics tùy chỉnh với các mô hình robot và kịch bản của riêng bạn, đồng thời giúp bất kỳ ai cũng có thể sử dụng chúng một cách dễ dàng thông qua framework LeRobot.

Các gói EnvHub được lưu trữ trên Hugging Face Hub và có thể được kéo về và sử dụng một cách liền mạch trong các dự án robot AI của bạn thông qua LeRobot chỉ với một dòng mã.

Nhờ có EnvHub, bạn có thể:

1. Tạo và phát hành môi trường lên Hugging Face Hub dưới dạng kho Git, và phân phối các mô phỏng vật lý phức tạp mà không cần lo lắng về việc đóng gói
2. Tải môi trường một cách động, mà không cần cài đặt chúng dưới dạng các gói
3. Phiên bản và theo dõi các thay đổi môi trường bằng ngữ nghĩa Git
4. Khám phá các tác vụ mô phỏng mới được chia sẻ bởi cộng đồng

Thiết kế này cho phép bạn chuyển từ việc khám phá một môi trường thú vị trên Hub sang chạy thử nghiệm chỉ trong vài giây, hoặc tự tạo robot và môi trường tùy chỉnh của riêng mình mà không cần lo lắng về xung đột phụ thuộc hay các quy trình cài đặt phức tạp.

Khi bạn tạo một gói EnvHub, bạn có thể xây dựng bất kỳ thứ gì bên trong nó và sử dụng bất kỳ công cụ mô phỏng nào bạn thích: đây là không gian riêng của bạn để thử nghiệm. Yêu cầu duy nhất là gói phải chứa tệp env.py định nghĩa môi trường và cho phép LeRobot tải và sử dụng gói EnvHub của bạn.

Tệp env.py này cần phải phơi bày một API nhỏ để LeRobot có thể tải và chạy nó. Cụ thể, bạn phải cung cấp một hàm make_env(n_envs: int = 1, use_async_envs: bool = False), đây là điểm vào chính cho LeRobot. LeRobot gọi nó mà không có cấu hình, cả khi chạy cục bộ lẫn khi được phục vụ. Nó nên trả về một trong các

• Một gym.vector.VectorEnv (phổ biến nhất)
• Một gym.Env đơn lẻ (sẽ được bọc tự động)
• Một dict ánh xạ {suite_name: {task_id: VectorEnv}} (cho các benchmark đa tác vụ)

Mặc định, vector env được trả về phải là SyncVectorEnv hoặc AsyncVectorEnv chưa được bọc: LeRobot lấy env_fns của nó và tự xây dựng từng môi trường. Các vector wrapper tùy chỉnh và các lớp con sẽ bị từ chối thay vì bị loại bỏ một cách im lặng.

Đối với vector wrapper do provider sở hữu hoặc các batch native trên GPU, hãy sử dụng --env.use_native_batch=true. Điều này giữ nguyên môi trường vector của repository để đánh giá theo batch cục bộ, bao gồm cả các yêu cầu tiền xử lý. Không thể kết hợp với endpoint hoặc SimRobot. API chuỗi (make_env("user/repo")) cũng giữ nguyên môi trường của provider.

env.py cũng có thể định nghĩa một từ điển tùy chọn LEROBOT_SIM mô tả môi trường (fps, control_mode, tên các thành phần; xem EnvHub và máy chủ mô phỏng). Nó được áp dụng cục bộ và khi được phục vụ.

Bắt đầu nhanh

Việc tải một môi trường từ Hub đơn giản như sau:

from lerobot.envs import make_env

# Load a hub environment (requires explicit consent to run remote code)
env = make_env("lerobot/cartpole-env", trust_remote_code=True)

**Security Notice**: Loading environments from the Hub executes Python code from third-party repositories. Only use `trust_remote_code=True` with repositories you trust. We strongly recommend pinning to a specific commit hash for reproducibility and security.

Cấu trúc kho

Để môi trường của bạn có thể được tải từ Hub, kho lưu trữ của bạn phải chứa ít nhất:

Các tệp bắt buộc

env.py (hoặc tệp Python tùy chỉnh)

• Phải phơi bày một hàm make_env(n_envs: int, use_async_envs: bool)
• Các đối số từ khóa bổ sung của make_env là các tùy chọn riêng của môi trường: --env.make_env_kwargs='{"episode_length": 900}' truyền chúng (--robot.env.make_env_kwargs đối với robot mô phỏng), và một server nhận chúng bằng --sim.kwargs='{make_env_kwargs: {episode_length: 900}}'
• Hàm này nên trả về một trong các giá trị sau:
  • Một gym.vector.VectorEnv (phổ biến nhất)
  • Một gym.Env đơn lẻ (sẽ được bọc tự động)
  • Một dict ánh xạ {suite_name: {task_id: VectorEnv}} (cho các benchmark đa tác vụ)

Tùy chọn

requirements.txt

• Liệt kê các phụ thuộc bổ sung mà môi trường của bạn cần
• Người dùng sẽ cần cài đặt thủ công những thành phần này trước khi tải môi trường của bạn

LEROBOT_SIM trong env.py

• Một từ điển ở cấp module mô tả môi trường khi nó được phục vụ bởi simulator server, do đó nó bắt đầu với một lệnh duy nhất
• Mọi khóa đều là tùy chọn; các kho không có LEROBOT_SIM vẫn hoạt động với các giá trị mặc định
• robot_type là kiểu mà robot thực ghi lại (so_follower, omx_follower) khi lerobot có một class cho thân robot, để các bộ dữ liệu mô phỏng và thực tế khớp nhau

README.md

• Tài liệu hóa môi trường của bạn: nhiệm vụ mà nó triển khai, không gian quan sát/hành động, phần thưởng, v.v.
• Bao gồm các ví dụ sử dụng và bất kỳ hướng dẫn cài đặt đặc biệt nào

.gitignore

• Loại bỏ các tệp không cần thiết khỏi kho lưu trữ của bạn

Cấu trúc kho lưu trữ mẫu

my-environment-repo/
├── env.py                 # Main environment definition (required)
├── requirements.txt       # Dependencies (optional)
├── README.md             # Documentation (recommended)
├── assets/               # Images, videos, etc. (optional)
│   └── demo.gif
└── configs/              # Config files if needed (optional)
    └── task_config.yaml

Tạo kho lưu trữ môi trường của bạn

Bước 1: Xác định môi trường của bạn

Tạo một tệp env.py với một hàm make_env:

# env.py
import gymnasium as gym

# Optional: describes the environment to the simulator server (see "Optional Files").
LEROBOT_SIM = {"fps": 50, "control_mode": "position"}

def make_env(n_envs: int = 1, use_async_envs: bool = False):
    """
    Create vectorized environments for your custom task.

    Args:
        n_envs: Number of parallel environments
        use_async_envs: Whether to use AsyncVectorEnv or SyncVectorEnv

    Returns:
        gym.vector.VectorEnv or dict mapping suite names to vectorized envs
    """
    def _make_single_env():
        # Create your custom environment
        return gym.make("CartPole-v1")

    # Choose vector environment type
    env_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv

    # Create vectorized environment
    vec_env = env_cls([_make_single_env for _ in range(n_envs)])

    return vec_env

Bước 2: Kiểm thử cục bộ

Trước khi tải lên, hãy kiểm tra môi trường của bạn cục bộ:

import numpy as np

from lerobot.envs.configs import HubEnvConfig

# Build the envs from the local folder that holds env.py, as lerobot-eval and the env server do
envs = HubEnvConfig(hub_path="./my-env", trust_remote_code=True).create_envs(n_envs=2)

# Verify it works
suite_name = next(iter(envs))
env = envs[suite_name][0]
obs, info = env.reset(seed=0)
print({key: value.shape for key, value in obs.items()})  # LeRobot keys, e.g. observation.state
env.step(np.zeros(env.action_space.shape, np.float32))
env.close()

Bước 3: Tải lên Hub

Tải kho lưu trữ của bạn lên Hugging Face:

# Install huggingface_hub if needed
pip install huggingface_hub

# Login to Hugging Face
hf auth login

# Create a new repository
hf repos create my-org/my-custom-env

# Initialize git and push
git init
git add .
git commit -m "Initial environment implementation"
git remote add origin https://huggingface.co/my-org/my-custom-env
git push -u origin main

Hoặc sử dụng API Python huggingface_hub:

from huggingface_hub import HfApi

api = HfApi()

# Create repository
api.create_repo("my-custom-env", repo_type="space")

# Upload files
api.upload_folder(
    folder_path="./my-env-folder",
    repo_id="username/my-custom-env",
    repo_type="space",
)

Tải Môi trường từ Hub

Cách sử dụng cơ bản

from lerobot.envs import make_env

# Load from the hub
envs_dict = make_env(
    "username/my-custom-env",
    n_envs=4,
    trust_remote_code=True
)

# Access the environment
suite_name = next(iter(envs_dict))
env = envs_dict[suite_name][0]

# Use it like any gym environment
obs, info = env.reset()
action = env.action_space.sample()
obs, reward, terminated, truncated, info = env.step(action)

Nâng cao: Cố định vào các phiên bản cụ thể

Để đảm bảo khả năng tái lập và bảo mật, hãy cố định vào một bản sửa đổi Git cụ thể:

# Pin to a specific branch
env = make_env("username/my-env@main", trust_remote_code=True)

# Pin to a specific commit (recommended for papers/experiments)
env = make_env("username/my-env@abc123def456", trust_remote_code=True)

# Pin to a tag
env = make_env("username/my-env@v1.0.0", trust_remote_code=True)

Đường dẫn tệp tùy chỉnh

Nếu định nghĩa môi trường của bạn không nằm trong env.py:

# Load from a custom file
env = make_env("username/my-env:custom_env.py", trust_remote_code=True)

# Combine with version pinning
env = make_env("username/my-env@v1.0:envs/task_a.py", trust_remote_code=True)

Môi trường bất đồng bộ

Để đạt hiệu suất tốt hơn với nhiều môi trường:

envs_dict = make_env(
    "username/my-env",
    n_envs=8,
    use_async_envs=True,  # Use AsyncVectorEnv for parallel execution
    trust_remote_code=True
)

Tham khảo định dạng URL

Định dạng URL của hub hỗ trợ một số mẫu sau:

EnvHub và máy chủ mô phỏng

Mặc định, các môi trường EnvHub chạy bên trong tiến trình đánh giá: make_env tải xuống env.py của kho lưu trữ, và các phụ thuộc của nó được cài đặt cạnh LeRobot. Để tách biệt phụ thuộc của môi trường khỏi phụ thuộc của chính sách, hãy phục vụ nó bằng máy chủ mô phỏng thay thế. Một lệnh sẽ xây dựng một image chứa kho lưu trữ cùng requirements.txt của nó, và khởi động máy chủ:

lerobot-env-server --envhub=username/my-env@<commit> --docker=true

Ngoài requirements.txt (được cài đặt theo quy tắc của pip, nên các dòng --extra-index-url hoạt động bình thường), image còn cài đặt các gói apt được liệt kê trong file tùy chọn packages.txt, mỗi gói một dòng, giống như trong Hugging Face Spaces. Image là Ubuntu thuần: trình điều khiển GPU đến từ host, còn các thư viện CUDA đến từ các Python wheel cần chúng (torch, Isaac Sim).

Việc truyền --envhub là sự đồng ý rõ ràng để chạy mã của kho lưu trữ, giống như trust_remote_code=True. Hãy ghim một commit. Sau đó, đánh giá dựa trên nó như bất kỳ môi trường nào khác, bằng cách thêm endpoint của nó:

lerobot-eval --policy.path=<checkpoint> \
  --env.type=envhub --env.hub_path=username/my-env@<commit> --env.server.endpoint=tcp/127.0.0.1:7448 \
  --rename_map='{"observation.images.front": "observation.images.camera1"}' \
  --eval.n_episodes=10

Nếu không có --env.server.endpoint, cùng một lệnh sẽ chạy môi trường cục bộ (với --trust_remote_code=true); một robot mô phỏng sẽ nhận các tùy chọn tương tự dưới --robot.env.*.

Máy chủ đọc tần suất điều khiển, quy ước hành động và tên các thành phần từ LEROBOT_SIM của kho lưu trữ, và sử dụng giá trị mặc định cho những gì không được khai báo. Ghi đè một giá trị trên dòng lệnh, giá trị này sẽ ưu tiên hơn kho lưu trữ, ví dụ --sim.fps=15.

Để được phục vụ, một môi trường phải tuân theo các quy ước sau:

• make_env trả về các môi trường vector được xây dựng từ các nhà máy môi trường riêng lẻ (SyncVectorEnv/AsyncVectorEnv, như trong các ví dụ ở trên) hoặc một gym.Env đơn lẻ. Máy chủ sẽ tự xây dựng các môi trường của nó từ những nhà máy đó và đóng chúng khi phiên kết thúc.
• env.py được thực thi một lần cho mỗi tiến trình máy chủ, do đó nó có thể giữ trạng thái trên toàn bộ tiến trình, chẳng hạn như một ứng dụng mô phỏng chỉ có thể khởi động một lần (SimulationApp của Isaac Sim).
• Observations là các từ điển mà LeRobot đọc cục bộ: pixels (một ảnh HWC uint8 hoặc một từ điển các camera), agent_pos và environment_state, dưới dạng mảng NumPy.
• Các hành động là một Box liên tục một chiều.
• Các episode kết thúc thông qua terminated/truncated hoặc _max_episode_steps (mặc định là 500), và info["is_success"] báo cáo kết quả thành công. Văn bản nhiệm vụ được lấy từ thuộc tính task_description (hoặc task) của môi trường.
• LEROBOT_SIM là tùy chọn, nhưng hãy khai báo nó bất cứ khi nào các giá trị mặc định (30 fps, điều khiển vị trí) không khớp với môi trường của bạn.

Để xem ví dụ, hãy tham khảo bộ sưu tập môi trường EnvHub: lerobot/so101-tabletop-mujoco (MuJoCo) và lerobot/so101-tabletop-isaac (Isaac Sim, được cài đặt thông qua requirements.txt và packages.txt) phục vụ cùng một cảnh SO-101 với cùng các quan sát, hành động và LEROBOT_SIM.

Kho lưu trữ được tải xuống máy của bạn bằng thông tin đăng nhập Hugging Face của bạn (HF_TOKEN hoặc hf auth login), do đó các kho lưu trữ riêng tư cũng hoạt động, và quá trình xây dựng hình ảnh không bao giờ nhìn thấy token. --envhub cũng nhận một thư mục cục bộ chứa env.py, để phục vụ một môi trường trước khi đẩy nó lên: lerobot-env-server --envhub=./my-env --docker=true. --build=true chỉ xây dựng lại những gì đã thay đổi: các gói apt khi packages.txt thay đổi, các yêu cầu khi requirements.txt thay đổi, và nếu không thì chỉ là các tệp của kho lưu trữ. Hãy thử môi trường mới cục bộ trước (xem Bước 2: Kiểm thử cục bộ).

Môi trường đa nhiệm

Đối với các bài kiểm tra có nhiều tác vụ (như LIBERO), hãy trả về một từ điển lồng nhau:

def make_env(n_envs: int = 1, use_async_envs: bool = False):
    env_cls = gym.vector.AsyncVectorEnv if use_async_envs else gym.vector.SyncVectorEnv

    # Return dict: {suite_name: {task_id: VectorEnv}}
    return {
        "suite_1": {
            0: env_cls([lambda: gym.make("Task1-v0") for _ in range(n_envs)]),
            1: env_cls([lambda: gym.make("Task2-v0") for _ in range(n_envs)]),
        },
        "suite_2": {
            0: env_cls([lambda: gym.make("Task3-v0") for _ in range(n_envs)]),
        }
    }

make_env xây dựng mọi task khi được gọi. Đối với trình mô phỏng GPU thực thi toàn bộ batch trong một world (ví dụ: Isaac Lab), hoặc một benchmark có nhiều task, hãy định nghĩa vector_env_fns trong env.py thay vì dùng cách trên, như các tích hợp của chính LeRobot đã làm. Hàm này trả về các factory, và chỉ các factory của những task được thực thi mới được gọi:

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")}}

Mỗi vector env phải có num_envs == n_envs, không được tự động reset (metadata["autoreset_mode"] = gym.vector.AutoresetMode.DISABLED), trả về các quan sát dạng batch theo định dạng ở trên, nhận một seed cho mỗi env trong reset(seed=[...]), và báo cáo info["is_success"] cho từng env. --env.make_env_kwargs sẽ được truyền vào, và cả lerobot-eval lẫn máy chủ mô phỏng đều sử dụng nó thay cho make_env. Vì một vector env đã thực hiện bước cho toàn bộ batch, hãy đánh giá với --eval.use_async_envs=false: một tiến trình worker chỉ sao chép mỗi batch quan sát giữa các tiến trình, còn một máy chủ sẽ xây dựng mô phỏng lần thứ hai, trong worker.

Xem xét về bảo mật

**Important**: The `trust_remote_code=True` flag is required to execute environment code from the Hub. This is by design for security.

Khi tải các môi trường từ Hub:

1. Đánh giá mã trước: Truy cập kho lưu trữ và kiểm tra env.py trước khi nạp
2. Ghim vào các commit: Sử dụng các hash commit cụ thể để đảm bảo khả năng tái lập
3. Kiểm tra các phụ thuộc: Xem xét requirements.txt để tìm các gói đáng ngờ
4. Sử dụng các nguồn đáng tin cậy: Ưu tiên các tổ chức chính thức hoặc các nhà nghiên cứu có uy tín
5. Đóng sandbox khi cần: Chạy mã không đáng tin trong các môi trường cách ly (container, VM)

Ví dụ về cách sử dụng an toàn:

# ❌ BAD: Loading without inspection
env = make_env("random-user/untrusted-env", trust_remote_code=True)

# ✅ GOOD: Review code, then pin to specific commit
# 1. Visit https://huggingface.co/trusted-org/verified-env
# 2. Review the env.py file
# 3. Copy the commit hash
env = make_env("trusted-org/verified-env@a1b2c3d4", trust_remote_code=True)

Ví dụ: CartPole từ Hub

Dưới đây là một ví dụ hoàn chỉnh sử dụng môi trường CartPole tham chiếu:

from lerobot.envs import make_env
import numpy as np

# Load the environment
envs_dict = make_env("lerobot/cartpole-env", n_envs=4, trust_remote_code=True)

# Get the vectorized environment
suite_name = next(iter(envs_dict))
env = envs_dict[suite_name][0]

# Run a simple episode
obs, info = env.reset()
done = np.zeros(env.num_envs, dtype=bool)
total_reward = np.zeros(env.num_envs)

while not done.all():
    # Random policy
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    total_reward += reward
    done = terminated | truncated

print(f"Average reward: {total_reward.mean():.2f}")
env.close()

Lợi ích của EnvHub

Dành cho Tác giả Môi trường

• Phân phối dễ dàng: Không yêu cầu đóng gói PyPI
• Quản lý phiên bản: Sử dụng Git để quản lý phiên bản môi trường
• Lặp lại nhanh: Đẩy các bản cập nhật ngay lập tức
• Tài liệu: README trên Hub hiển thị đẹp
• Cộng đồng: Liên hệ trực tiếp với người dùng LeRobot

Dành cho nhà nghiên cứu

• Thử nghiệm nhanh: Nạp bất kỳ môi trường nào trong một dòng
• Tính tái lập: Cố định vào các commit cụ thể
• Khám phá: Duyệt các môi trường trên Hub
• Không có xung đột: Không cần cài đặt các gói xung đột

Dành cho Cộng đồng

• Hệ sinh thái đang phát triển: Các tác vụ mô phỏng đa dạng hơn
• Chuẩn hóa: API make_env chung
• Hợp tác: Fork và cải thiện các môi trường hiện có
• Tính khả dụng: Giảm rào cản trong việc chia sẻ nghiên cứu

Xử lý sự cố

“Từ chối thực thi mã từ xa”

Bạn phải truyền rõ ràng trust_remote_code=True:

env = make_env("user/repo", trust_remote_code=True)

“Không tìm thấy module X”

Môi trường hub có các phụ thuộc mà bạn cần cài đặt:

# Check the repo's requirements.txt and install dependencies
pip install gymnasium numpy

“Không tìm thấy make_env trong module”

env.py của bạn phải phơi bày một hàm make_env:

def make_env(n_envs: int, use_async_envs: bool):
    # Your implementation
    pass

Environment trả về kiểu không chính xác

Hàm make_env phải trả về:

• Một gym.vector.VectorEnv, hoặc
• Một gym.Env đơn lẻ, hoặc
• Một dict {suite_name: {task_id: VectorEnv}}

Thực hành tốt nhất

1. Tài liệu hóa môi trường của bạn: Bao gồm mô tả không gian quan sát/hành động, cấu trúc phần thưởng và các điều kiện kết thúc trong README của bạn
2. Thêm requirements.txt: Liệt kê tất cả các phụ thuộc kèm phiên bản
3. Khởi tạo LEROBOT_SIM: Cho phép môi trường được phục vụ bởi máy chủ mô phỏng chỉ với một lệnh
4. Thử nghiệm kỹ lưỡng: Xác minh môi trường của bạn hoạt động cục bộ trước khi đẩy
5. Sử dụng phiên bản ngữ nghĩa: Gắn thẻ các bản phát hành với số phiên bản
6. Thêm ví dụ: Bao gồm các ví dụ sử dụng trong README của bạn
7. Giữ cho đơn giản: Giảm thiểu các phụ thuộc khi có thể
8. Cấp phép cho tác phẩm của bạn: Thêm tệp LICENSE để làm rõ các điều khoản sử dụng

Hướng phát triển trong tương lai

Hệ sinh thái EnvHub cho phép những khả năng thú vị:

• Vật lý tăng tốc bằng GPU: Chia sẻ các môi trường Isaac Gym hoặc Brax
• Hiển thị chân thực: Phân phối các môi trường với đồ họa tiên tiến
• Các kịch bản đa tác nhân: Các tác vụ tương tác phức tạp
• Trình mô phỏng thực tế: Bản sao kỹ thuật số của các thiết lập vật lý
• Định dạng sinh thủ tục: Vô hạn các biến thể tác vụ
• Random hóa miền: Các pipeline DR được cấu hình sẵn

Khi ngày càng có nhiều nhà nghiên cứu và nhà phát triển đóng góp, sự đa dạng và chất lượng của các môi trường có sẵn sẽ tăng lên, mang lại lợi ích cho toàn bộ cộng đồng học máy trong lĩnh vực robot.

Xem thêm

• Tài liệu Hugging Face Hub
• Tài liệu Gymnasium
• Môi trường Hub mẫu