huggingface/OpenEnv

Gymnasium 스타일의 간단한 API를 사용하여 구축된, 에이전트 기반 강화학습 (agentic RL) 훈련을 위한 격리된 실행 환경을 생성, 배포 및 사용하는 엔드투엔드 (e2e) 프레임워크입니다.

주요 예시: torchforge (PyTorch의 에이전트 기반 RL 프레임워크)를 사용하여 LLM이 블랙잭 (BlackJack)을 플레이하도록 훈련하기: examples/grpo_blackjack/

Zero to Hero 튜토리얼: 우리의 GPU Mode 강의 및 기타 해커톤에서 제공하는 엔드투엔드 튜토리얼입니다.

OpenEnv 패키지 설치:

pip install openenv

환경 클라이언트 설치 (예: Echo):

pip install git+https://huggingface.co/spaces/openenv/echo_env

그 다음 환경 사용:

import asyncio
from echo_env import CallToolAction, EchoEnv
async def main():
...

.sync() 래퍼 (wrapper)를 통한 동기식 사용 (Synchronous usage) 도 지원합니다:

from echo_env import CallToolAction, EchoEnv
# 동기식 컨텍스트 매니저를 위해 .sync() 사용
with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:
...

상세한 빠른 시작 가이드는 문서 페이지를 확인하세요.

OpenEnv는 step(), reset(), state()와 같은 간단한 Gymnasium 스타일의 API를 통해 에이전트 기반 실행 환경과 상호작용할 수 있는 표준을 제공합니다. 에이전트 기반 실행 환경의 사용자들은 이러한 간단한 API를 사용하여 강화학습 (RL) 훈련 루프 중에 환경과 상호작용할 수 있습니다.

연구자와 RL 프레임워크 작성자들을 더 쉽게 만드는 것 외에도, 환경 제작자들이 더 풍부한 환경을 만들고 HTTP와 같은 친숙한 프로토콜을 통해 제공하며 docker와 같은 표준 기술로 패키징할 수 있도록 돕는 도구들을 제공합니다. 환경 제작자들은 OpenEnv 프레임워크를 사용하여 격리되고 안전하며 배포 및 사용이 용이한 환경을 구축할 수 있습니다.

OpenEnv CLI (openenv)는 새로운 환경을 초기화하고 이를 Hugging Face Spaces에 배포할 수 있는 명령어를 제공합니다.

⚠️ 초기 개발 경고 (Early Development Warning)
OpenEnv는 현재 실험적인 단계에 있습니다. 버그, 미완성된 기능, 그리고 향후 버전에서 변경될 수 있는 API가 발생할 수 있음을 인지해야 합니다. 본 프로젝트는 버그 수정(bugfixes)을 환영하지만, 기술 위원회와 커뮤니티가 범위, 호환성 및 출시 시기를 조정할 수 있도록 중대한 변경 사항은 구현 전에 반드시 논의되어야 합니다. 이슈 트래커(issue tracker)에 새로운 이슈를 등록하거나 기존 이슈를 선점함으로써 기여 의사를 밝히는 것을 권장합니다.

아래는 OpenEnv를 위한 현재 진행 중이거나 과거의 RFC 목록입니다. RFC는 주요 변경 사항이나 기능에 대한 제안서입니다. 검토하고 기여해 주세요!

• RFC 001: 기본 API 및 인터페이스 사양 (Baseline API and Interface Specifications)
• RFC 002: 에이전트에 의한 환경 도구의 발견 가능성 (Discoverability of environment tools by agents)
• RFC 003: MCP (Model Context Protocol) 지원 추가
• RFC 004: 궤적 기반 점수 산정 (trajectory-based scoring)을 위한 지연된 보상 (delayed rewards) 지원 추가
• RFC 005: 에이전틱 하네스 통합 (Agentic Harness Integration)

┌─────────────────────────────────────────────────────────┐
│ Client Application │
│ ┌────────────────┐ ┌──────────────────┐ │
...

OpenEnv에는 대화형 환경 탐색 및 디버깅을 위한 내장 웹 인터페이스가 포함되어 있습니다. 웹 인터페이스는 다음과 같은 기능을 제공합니다:

2분할 레이아웃 (Two-Pane Layout): 왼쪽에는 인간-에이전트 (Human-Agent) 상호작용, 오른쪽에는 상태 관찰 (state observation) 배치
실시간 업데이트 (Real-time Updates): 페이지 새로고침 없이 WebSocket 기반의 라이브 업데이트 제공
동적 양식 (Dynamic Forms): 환경의 액션 타입 (Action types)을 기반으로 자동 생성되는 액션 양식
액션 히스토리 (Action History): 수행된 모든 액션과 그 결과에 대한 전체 로그

웹 인터페이스는 환경 변수에 따라 조건부로 활성화됩니다:

로컬 개발 (Local Development): 가벼운 개발을 위해 기본적으로 비활성화됨
수동 오버라이드 (Manual Override): ENABLE_WEB_INTERFACE=true로 설정하여 활성화

웹 인터페이스를 사용하려면:

from openenv.core.env_server import create_web_interface_app
from your_env.models import YourAction, YourObservation
from your_env.server.your_environment import YourEnvironment
...

활성화되면 http://localhost:8000/web을 여십시오.

브라우저에서 환경과 상호작용하십시오.

환경 로직 구현을 위한 베이스 클래스 (Base class):

reset(): 새로운 에피소드를 초기화하며, 초기 Observation을 반환합니다.

step(action): Action을 실행하며, 결과인 Observation을 반환합니다.

state(): 에피소드 메타데이터(episode_id, step_count 등을 포함한 State)에 접근합니다.

환경 통신을 위한 베이스 클래스:

기본적으로 비동기 방식 (Async by default): 모든 작업에 async with 및 await를 사용하십시오.
동기 래퍼 (Sync wrapper): 동기식 사용을 위해 .sync()를 호출하여 SyncEnvClient를 가져오십시오.

• 환경 서버와의 WebSocket 연결을 처리합니다.
• 해당 환경을 위해 로컬에서 Docker 컨테이너를 실행하는 유틸리티를 포함합니다.
• 타입 안전(Type-safe)한 액션/관측(action/observation) 파싱을 제공합니다.

컨테이너 배포 관리:

LocalDockerProvider: 로컬 Docker 데몬에서 컨테이너를 실행합니다.
DockerSwarmProvider: Docker Swarm 클러스터에 배포합니다.
KubernetesProvider: Kubernetes 클러스터에 배포합니다.
UVProvider, DaytonaProvider: 추가적인 런타임 프로바이더입니다.

타입 안전 데이터 구조 (Type-safe data structures):

Action: 환경 액션을 위한 베이스 클래스
Observation: 환경 관측을 위한 베이스 클래스
State: 에피소드 상태 추적
StepResult: 관측(observation), 보상(reward), 종료 플래그(done flag)를 결합

CLI를 사용하여 새로운 환경을 빠르게 스캐폴딩(scaffold)하십시오:

openenv init my_env

다음과 같은 구조가 생성됩니다:

my_env/
├── .dockerignore # Docker 빌드 제외 항목
├── __init__.py # YourAction, YourObservation, YourEnv를 내보냄
...

OpenEnv는 pyproject.toml을 주요 의존성 명세로 사용합니다:

환경 레벨 (Environment-level): 각 환경은 자체 pyproject.toml에 의존성을 정의합니다.
루트 레벨 (Root-level): 공유 코어 의존성(fastapi, pydantic, uvicorn)을 포함하는 pyproject.toml
서버 (Server): Docker 빌드를 위해 requirements.txt로부터 pyproject.toml을 자동 생성할 수 있습니다.

개발 워크플로우 (Development Workflow):

# 환경을 편집 가능 모드(editable mode)로 설치
cd my_env
pip install -e .
...

환경 구축에 대한 전체 가이드는 envs/README.md를 참조하십시오.

환경을 사용하려면:

• 클라이언트 설치:
  pip install git+https://huggingface.co/spaces/openenv/echo_env

• 임포트:
  from echo_env import CallToolAction, EchoEnv

• 비동기(Async) (권장) 또는 동기(Sync) API 사용:

비동기 (recommended):

async with EchoEnv(base_url="...") as client:
result = await client.reset()
result = await client.step(action)

동기 (Sync) (.sync() 래퍼 사용):

with EchoEnv(base_url="...").sync() as client:
result = client.reset()
result = client.step(action)

예제 스크립트는 examples/ 디렉터리에서 확인하십시오.

OpenEnv CLI는 환경을 관리하는 명령어를 제공합니다:

• 템플릿으로부터 새 환경 초기화: openenv init <env_name>
• Hugging Face Spaces에 환경 배포: openenv push [--repo-id <repo>] [--private]
• 선택적 자동 재로드와 함께 로컬에서 환경 서비스: openenv serve
• 환경의 Docker 이미지 빌드: openenv build
• HF Hub의 Space를 계정으로 포크(fork): openenv fork <space-id>
• 환경 구성 유효성 검사: openenv validate

# 새 환경 생성
openenv init my_game_env
# Hugging Face에 배포 (필요한 경우 로그인 프롬프트 표시)
...

자세한 옵션은 모든 명령어에 --help를 붙여 실행하십시오.

# 리포지토리 클론
git clone https://github.com/huggingface/OpenEnv.git
cd OpenEnv
...

OpenEnv는 모듈식 의존성 구조를 사용합니다: 핵심 패키지는 최소한이며, 각 환경은 자체적인 의존성을 가집니다. 이는 일부 테스트가 환경별 패키지를 필요로 함을 의미합니다.

# pytest 설치 (테스트 실행에 필수)
uv pip install pytest
# 모든 테스트 실행 (설치되지 않은 의존성이 필요한 테스트는 건너뜀)
...

환경별 테스트를 실행하려면, 해당 환경의 의존성을 설치하십시오:

# 예시: 개발 의존성(smolagents + pytest 포함)과 함께 coding_env 설치
uv pip install -e "envs/coding_env[dev]"
# 그리고 coding_env 테스트 실행
...

필요한 의존성이 설치되지 않은 경우 테스트는 자동으로 건너뜁니다.

OpenEnv는 성장하는 RL (강화학습) 프레임워크 및 플랫폼 생태계와 함께 작동합니다. 만약 귀하의 프로젝트가 OpenEnv를 지원한다면, 여기에 추가하기 위해 PR (Pull Request)을 열어주세요.

OpenEnv 환경을 GRPO (Group Relative Policy Optimization) 학습과 통합하는 방법은 TRL 예시를 참조하세요.

GRPO BlackJack 학습 예시를 참조하세요: examples/grpo_blackjack/

gpt-oss 기반의 2048 게임 예시를 참조하세요: Colab notebook

SkyRL을 사용하여 OpenEnv 환경에서 학습하는 방법은 SkyRL 예시를 참조하세요.

ART를 사용하여 OpenEnv 환경으로 모델을 학습하는 방법은 ART 예시를 참조하세요.

Oumi를 사용하여 OpenEnv 환경으로 모델을 학습하는 방법은 Oumi 예시를 참조하세요.

환경	설명
Echo Environment	메타데이터와 함께 메시지를 에코(Echo)합니다. HTTP 서버 인프라 테스트, 프레임워크 기초 학습, 컨테이너 배포 검증에 이상적입니다.
...

커뮤니티 환경의 전체 카탈로그는 huggingface.co/docs/openenv/environments에서 찾아볼 수 있습니다.

OpenEnv는 공개 이슈 트래커(issue tracker), 풀 리퀘스트(pull requests), RFC 프로세스를 통해 프로젝트 방향, 주요 기술적 결정, RFC, 릴리스 계획을 조정하는 기술 위원회(technical committee)에 의해 운영됩니다. 현재 위원회 멤버: Meta-PyTorch, Reflection, Unsloth, Modal, Prime Intellect, Nvidia, Mercor, Fleet AI, 그리고 Hugging Face입니다.

이 프로젝트는 더 넓은 조직 커뮤니티의 지원을 받고 있습니다. 귀하의 프로젝트나 조직을 여기에 추가하고 싶다면, 유지 관리자의 검토를 위해 풀 리퀘스트(pull request)를 열어주세요.

지원 기관은 다음과 같습니다: Meta-PyTorch, Hugging Face, Scaler AI Labs, Patronus AI, Surge AI, LastMile AI, Unsloth, Reflection, vLLM, SkyRL (UC-Berkeley), Lightning AI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, OpenMined, Fleet AI, Halluminate, Turing, Scale AI, Scorecard

또한 OpenEnv API가 여러분이 Gymnasium에서 수행한 작업으로부터 큰 영감을 받았기에, Farama Foundation 팀에게 감사를 표합니다. 건승을 빕니다!

BSD 3-Clause License (LICENSE 파일을 참조하세요)