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) hoặc make_env(n_envs: int = 1, use_async_envs: bool = False, cfg: EnvConfig | None = None), đây là điểm vào chính cho LeRobot. Hàm này nên trả về một trong các đối tượng 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ụ)

Bạn cũng có thể truyền một đối tượng EnvConfig vào make_env để cấu hình môi trường (ví dụ: số lượng môi trường, tác vụ, tên camera, trạng thái ban đầu, chế độ điều khiển, độ dài episode, v.v.).

Cuối cùng, môi trường của bạn phải triển khai giao diện chuẩn gym.vector.VectorEnv để hoạt động với LeRobot, bao gồm các phương thức như reset và step.

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)
• 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

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

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ộ:

from lerobot.envs.utils import _load_module_from_path, _call_make_env, _normalize_hub_result

# Load your module
module = _load_module_from_path("./env.py")

# Test the make_env function
result = _call_make_env(module, n_envs=2, use_async_envs=False, cfg=None)
normalized = _normalize_hub_result(result)

# Verify it works
suite_name = next(iter(normalized))
env = normalized[suite_name][0]
obs, info = env.reset()
print(f"Observation shape: {obs.shape if hasattr(obs, 'shape') else type(obs)}")
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 repo 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:

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)]),
        }
    }

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. 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
4. 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
5. Thêm ví dụ: Bao gồm các ví dụ sử dụng trong README của bạn
6. Giữ cho đơn giản: Giảm thiểu các phụ thuộc khi có thể
7. 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