벤치마크 추가

벤치마크는 LeRobot이 한 곳에서 구동하는 시뮬레이터이며, lerobot.sim을 통해 모든 사용 방식이 동일하게 동작하도록 합니다: lerobot-eval(배치된 환경, --env.type=<benchmark>), 롤아웃 및 녹화(시뮬레이션 로봇, --robot.type=sim --robot.env.type=<benchmark>), 로컬 또는 자체 Docker 이미지에서 lerobot-env-server로 서빙되는 경우입니다. 사용 방법은 Simulation: local or served를 참고하세요.

추가할 항목

두 경로 모두 동일한 환경 동작을 노출합니다:

native simulator → LocalVectorEnv, locally or on an env server → canonical NumPy observations
  → batched env or sim robot → one-time image/tensor preparation → saved policy preprocessing
  → policy → saved action postprocessing → native simulator

해당 시뮬레이터의 canonical_observation() 어댑터에 이미지 방향, 사원(quaternion) 변환 및 상태 순서를, conventions()에 제어 규약을 배치하여 평가와 롤아웃이 일치하도록 하세요. sim/integrations/utils.py는 통합(integration) 간에 공유되는 매핑에만 재사용하고, 공유 환경 코드는 시뮬레이터 이름에 따라 분기 처리하지 않아야 합니다. 새로운 벤치마크에는 environment processor가 필요하지 않습니다. 관측값은 이미 정규화된 상태로 정책 자체의 프로세서에 도달하기 때문입니다.

평가 실행 방식

lerobot-eval은 모든 벤치마크를 동일한 방식으로 평가합니다:

1. make_env()은 중첩된 {suite: {task_id: vector env}} 딕셔너리를 생성합니다.
2. eval_policy_all()은 각 작업을 한 번에 하나씩(또는 --env.max_parallel_tasks개씩) n_episodes개의 롤아웃을 실행합니다.
3. 결과물은 에피소드, 태스크, 스위트 및 전체 기준으로 집계됩니다: pc_success(성공률), avg_sum_reward, avg_max_reward. 모든 성공률에는 해당 카운트(n_episodes 중 n_success)와 퍼센트 단위의 95% Wilson 구간(pc_success_ci95)이 함께 제공됩니다. 이 구간은 에피소드 간 샘플링 노이즈만을 반영하며, 동일한 레시피의 학습 실행 간 변동성에 대해서는 아무런 정보를 제공하지 않습니다.

성공 여부는 info["is_success"]에서 가져오며, 환경이 모든 step()마다 보고합니다. 환경은 자체적으로 정의한 수치도 보고할 수 있습니다. 이러한 수치는 info["metrics"]에 저장되며, 각 이름에 대해 환경당 하나의 float 값을 매핑합니다. 이 값들은 에피소드가 종료된 단계에서 측정되어 해당 에피소드의 per_episode[i]["metrics"] 항목에 반영됩니다.

환경에서 제공해야 하는 것

환경 구조

env_fns()은 각 작업의 환경 팩토리를 빌드하지 않고 반환합니다:

def env_fns(
    task: str,
    n_envs: int,
    gym_kwargs: dict | None = None,
) -> dict[str, dict[int, list[Callable[[], gym.Env]]]]:
    """{suite: {task_id: [make_single_env] * n_envs}} for MyBenchmark."""

단일 작업 벤치마크는 {"<task>": {0: [...]}}을 반환하고, 다중 작업 벤치마크(LIBERO 등)는 {"libero_spatial": {0: [...], 1: [...], ...}, ...}을 반환합니다. LocalVectorEnv는 첫 사용 시 각 make_single_env 팩토리를 로컬 또는 서버에서 호출하며, --eval.use_async_envs=true가 설정된 경우 환경별로 별도의 프로세스에서 실행합니다.

gym.Env

class MyBenchmarkEnv(gym.Env):
    metadata = {"render_modes": ["rgb_array"], "render_fps": <fps>}

    def __init__(self, task_suite, task_id, ...):
        super().__init__()
        self.task = <task_name_string>
        self.task_description = <natural_language_instruction>
        self._max_episode_steps = <max_steps>
        self.observation_space = spaces.Dict({...})
        self.action_space = spaces.Box(low=..., high=..., shape=(...,), dtype=np.float32)

step()은 성공 여부를 info["is_success"]에 보고하며, 측정하는 기타 항목은 info["metrics"]에 담깁니다. 액션은 1차원 연속 Box입니다.

Observations는 통합의 canonical_observation() 어댑터가 이해하는 dict입니다. 재사용 가능한 기본 어댑터는 다음과 같이 매핑합니다:

기타 모든 배열은 observation.<key>로 전달됩니다. gym.Env 내에서 시뮬레이터의 출력을 이러한 키로 이름 변경하거나, 해당 통합의 어댑터에서 네이티브 표현을 처리하세요.

GPU 기반 시뮬레이터(예: EGL 렌더링을 사용하는 MuJoCo): 시뮬레이터가 __init__에서 GPU/EGL 컨텍스트를 할당하는 경우, 해당 할당을 reset()/step() 호출 시 실행되는 _ensure_env() 헬퍼로 지연시켜야 합니다. 이렇게 하면 워커 프로세스에서 생성된 환경이 오래된 GPU 핸들을 상속하지 않습니다. 패턴은 LiberoEnv._ensure_env()를 참고하세요.

컨벤션 (통합의 conventions())

conventions(kwargs)에서 시뮬레이터의 제어률, 컨트롤러 및 정렬된 구성 요소 이름을 반환합니다. 이 함수는 시뮬레이터의 옵션을 인수로 받으며, RoboTwin과 같이 액션 모드에 따라 달라질 수 있습니다. 이 값들은 구성 설정에서 누락된 항목을 채우고, 로봇, 데이터셋 및 체크포인트의 상태 및 액션 구성 요소 이름을 지정합니다. semantics의 기본값은 <type>-<control>-v1입니다. robot_type은 시뮬레이션된 본체를 나타내며, 시뮬레이션 로봇이 기록합니다. lerobot에 해당 클래스가 있는 경우 실제 로봇이 기록하는 유형(so_follower)을 사용하고, 그렇지 않으면 짧은 이름(panda, sawyer)을 사용합니다. 이 값을 지정하지 않으면 데이터셋은 sim_robot을 기록합니다.

설정 ( src/lerobot/envs/configs.py )

--env.type=<name>(및 --robot.env.type=<name>)로 사용자가 벤치마크를 선택할 수 있도록 config를 등록합니다. sim_settings()는 서버 YAML의 sim 섹션으로 시뮬레이터를 설명하며, LocalVectorEnv가 나머지를 처리합니다:

@EnvConfig.register_subclass("<benchmark_name>")
@dataclass
class MyBenchmarkEnvConfig(EnvConfig):
    task: str = "<default_task>"
    fps: int = <fps>
    obs_type: str = "pixels_agent_pos"

    @property
    def gym_kwargs(self) -> dict:
        return {"obs_type": self.obs_type}

    def sim_settings(self) -> dict:
        return {"type": "<benchmark_name>", "task": self.task, "kwargs": {"gym_kwargs": self.gym_kwargs}}

기본값과 서버 YAML의 설정을 일치시켜야 합니다. 제공되는 평가는 명령이 설명하는 환경과 다른 환경을 실행 중인 서버를 거부합니다. 기능은 환경이 생성될 때 해당 환경의 설명에서 가져오므로, 설정에서는 아무것도 선언하지 않습니다.

Checkpoint 승인

--rename_map는 모든 로봇과 마찬가지로 환경 카메라 키를 체크포인트의 학습된 키에 별칭으로 매핑합니다. CI에서는 benchmarks/benchmarks.yaml의 해당 항목 rename_map에서 가져옵니다. 이름 변경 후 체크포인트 입력이 존재해야 하며, 상태/액션 차원이 일치해야 합니다. 이름 변경으로 체크포인트 메타데이터를 복구할 수 없습니다. RGB 채널 수와 레이아웃은 승인 시점에 확인됩니다. 획득 높이/너비는 학습 메타데이터와 다를 수 있으며, 리사이즈는 정책 전처리에서 처리해야 합니다.

검증 및 CI

1. 관측 어댑터가 시뮬레이터의 원시 출력, 특히 카메라 방향과 상태 순서와 일치하는지, 그리고 환경 래퍼가 적용한 동작이 올바른지 확인하세요.
2. 로컬과 서빙된 시드 기반 reset/step 시퀀스를 비교합니다(scripts/ci/check_sim_parity.py). 결정론적 시뮬레이터의 매니페스트 항목에 parity: true를 설정하면 CI에서 실행됩니다. 터미널 동결, 성공 여부, 에피소드 길이, 렌더링 및 리소스 청소를 확인합니다.
3. 서버 코드와 네이티브 모듈에 대해 torch-disabled import 가드를 실행합니다. RoboTwin과 RoboMME과 같이 자체 torch 런타임이 필요한 시뮬레이터를 문서화합니다.
4. 로컬에서 lerobot-eval --env.type=<name> --env.task=<task> --eval.n_episodes=1 --policy.path=<checkpoint>을 실행하고, --env.server.endpoint를 사용하여 서버에 대해 실행합니다. 작업 설명과 렌더링된 카메라 뷰를 확인합니다.
5. GPU runner에서 생성된 벤치마크 작업을 실행합니다. 공유된 평가/학습 통합을 변경할 때 LIBERO 학습 스모크를 유지합니다.

benchmarks/benchmarks.yaml은 scripts/ci/benchmark_matrix.py를 통해 매트릭스를 생성하며, .github/workflows/benchmark_run.yml이 각 항목을 실행합니다. CI 작업을 복사하는 대신 매니페스트에 항목을 추가하세요. CI는 파이프라인을 끝에서 끝까지 확인하기 위해 에피소드를 제한하며, 해당 metrics.json에는 체크포인트 리비전, 시뮬레이터 이미지 태그, 커밋 및 제한 값이 기록되고 이러한 실행은 smoke로 표시됩니다. 성공률은 정책 점수가 아닙니다. 시뮬레이터 이미지는 별도의 핀과 콘텐츠 태그를 가지며, BuildKit 캐시는 영속적 러너에서만 유지됩니다.

벤치마크 변경

통합의 canonical_observation(), conventions() 및 environment wrapper가 정책이 무엇을 보고 그 동작이 어떻게 적용되는지를 결정합니다. 이미지 방향, 상태 순서 또는 제어 속도가 잘못되면 크래시는 발생하지 않지만, 정책이 약간 잘못된 입력을 받게 되어 성공률이 떨어집니다. 이 중 하나를 변경하면 다음과 같은 사항이 수반됩니다:

• 기록되거나 합성된 관측 데이터에서 이전 출력과 새 출력을 비교하는 회귀 테스트입니다. tests/sim/integrations/test_libero.py의 test_libero_numpy_adapter_parity가 이를 보여줍니다. torch를 사용하지 않는 LIBERO 어댑터가 이전 LIBERO 프로세서와 정확히 동일한 결과를 생성함을 입증합니다.
• 풀 리퀘스트에서 점수에 대한 예상되는 영향: 없음, 또는 어떤 점수가 어떻게 변해야 하는지 그 이유.

의존성 ( pyproject.toml )

로컬 사용을 위한 새로운 선택적 의존성 그룹을 추가합니다:

mybenchmark = ["my-benchmark-pkg==1.2.3", "lerobot[scipy-dep]"]

고정 규칙:

• 재현성을 위해 벤치마크 패키지는 항상 정확한 버전으로 고정해야 합니다(예: metaworld==3.0.0).
• 필요한 경우(예: ; sys_platform == 'linux') 플랫폼 마커를 추가합니다.
• 취약한 전이 의존성이 알려진 경우 고정하세요(예: Meta-World 이미지는 MuJoCo 3.17이 mocap welds를 깨뜨리기 때문에 mujoco==3.15.0을 고정합니다).
• 벤치마크 문서 페이지에 문서 제약 사항을 명시합니다. 의존성이 LeRobot의 것과 충돌하는 경우, 제공되는 경로는 지원되는 경로입니다.

벤치마크 문서 페이지 작성

docs/source/_toctree.yml의 “Benchmarks” 섹션에 해당 페이지를 추가합니다. 각 벤치마크 페이지에는 다음을 포함해야 합니다:

• 제목 및 설명 — 벤치마크가 무엇을 테스트하는지, 그리고 왜 중요한지에 대한 1~2단락 분량의 내용.
• 링크 — 논문, GitHub 저장소, 프로젝트 웹사이트(사용 가능한 경우).
• 출처 및 라이선스 — 소스 저장소, 고정된 코드 및 자산 리비전, 그리고 각 항목의 라이선스입니다. 사용이 금지된 라이선스를 가진 벤치마크는 추가하지 마세요.
• 개요 이미지 또는 GIF.
• 사용 가능한 작업 — 작업 스위트의 개수와 간단한 설명이 포함된 표.
• 설치 — pip install -e ".[<benchmark>]" 또는 서버 명령어.
• 평가 — 재현 가능한 결과를 위해 n_episodes를 사용하는 권장 lerobot-eval 명령어.
• 정책 입력 및 출력 — 형태가 포함된 관찰 키, 액션 공간 설명.
• 학습 — lerobot-train 명령어 예시.
• 참고 결과 — 실행할 수 있는 사전 학습된 체크포인트 중 적어도 하나의 공개된 성공률, 해당 리비전, 그리고 이를 재현하는 lerobot-eval 명령어입니다. 이 값 근처에 도달하지 못하는 통합은 완료되지 않은 것입니다.

완전한 예제는 docs/source/libero.mdx 및 docs/source/metaworld.mdx를 참고하세요.