@SergioPaniego: OpenEnv 有了新家：http://github.com/huggingface/OpenEnv… 从今天起，由一个委员会协调，其中包括…

OpenEnv 有了新家：https://t.co/7L3sGSu2zB 从今天起，它由一个委员会协调，成员包括 Meta-PyTorch、Reflection、Unsloth、Modal、Prime Intellect、Nvidia、Mercor、Fleet AI 和 Hugging Face 前沿实验室，它们共同训练模型及其测试框架。https://t.co/WsyEF21w4g — # huggingface/OpenEnv 来源：https://github.com/huggingface/OpenEnv # OpenEnv：智能体执行环境 一个端到端框架，用于创建、部署和使用隔离的执行环境进行基于强化学习（RL）的智能体训练，采用类似 Gymnasium 的简洁 API 构建。 — 特色示例： 使用 torchforge (https://meta-pytorch.org/torchforge/)（PyTorch 的智能体 RL 框架）训练 LLM 玩 BlackJack：examples/grpo_blackjack/ 从零到精通教程： 来自我们的 GPU Mode 讲座和其他黑客马拉松的端到端教程。 ## 快速开始 安装 OpenEnv 包： bash pip install openenv 安装一个环境客户端（例如 Echo）： bash pip install git+https://huggingface.co/spaces/openenv/echo_env 然后使用环境： python import asyncio from echo_env import CallToolAction, EchoEnv async def main(): # 连接到一个正在运行的 Space（异步上下文管理器） async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client: # 重置环境 result = await client.reset() print(result.observation.echoed_message) # "Echo environment ready!" # 发送消息 result = await client.step( CallToolAction( tool_name="echo_message", arguments={"message": "Hello, World!"}, ) ) print(result.observation.result) # "Hello, World!" print(result.reward) asyncio.run(main()) 同步用法也通过 .sync() 包装器支持： python from echo_env import CallToolAction, EchoEnv # 使用 .sync() 进行同步上下文管理器 with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client: result = client.reset() result = client.step( CallToolAction( tool_name="echo_message", arguments={"message": "Hello, World!"}, ) ) print(result.observation.result) 有关详细快速入门，请查看文档页面 (https://huggingface.co/docs/openenv/getting-started)。 ## 概述 OpenEnv 提供了一种标准，通过简单的 Gymnasium 风格 API（step()、reset()、state()）与智能体执行环境交互。智能体执行环境的用户可以在 RL 训练循环中使用这些简单的 API 与环境交互。除了让研究人员和 RL 框架编写者更容易使用外，我们还为环境创建者提供了工具，使他们能够更轻松地创建更丰富的环境，并通过熟悉的协议（如 HTTP）和使用标准技术（如 Docker）打包来提供这些环境。环境创建者可以使用 OpenEnv 框架创建隔离、安全且易于部署和使用的环境。OpenEnv CLI (openenv) 提供了初始化新环境并将其部署到 Hugging Face Spaces 的命令。 > ⚠️ 早期开发警告 > OpenEnv 目前处于实验阶段。您可能会遇到错误、不完整的功能以及 API 在将来版本中可能变化的情况。项目欢迎 Bug 修复，但重大的更改应在实施前进行讨论，以便技术委员会和社区能够协调范围、兼容性和发布时机。建议您在问题跟踪器中表明您的贡献意图，无论是通过提交新问题还是认领现有问题。 ### RFCs 以下是 OpenEnv 当前和历史的 RFC 列表。RFC 是对重大更改或功能的提案。请审阅并贡献！ - RFC 001：基线 API 和接口规范 (https://github.com/huggingface/OpenEnv/pull/26) - RFC 002：环境工具对智能体的可发现性 (https://github.com/huggingface/OpenEnv/pull/32) - RFC 003：添加 MCP（模型上下文协议）支持 (https://github.com/huggingface/OpenEnv/pull/224) - RFC 004：添加基于轨迹评分的延迟奖励支持 (https://github.com/huggingface/OpenEnv/pull/337) - RFC 005：智能体测试框架集成 (https://github.com/huggingface/OpenEnv/pull/387) ## 架构 ### 组件概览 ┌─────────────────────────────────────────────────────────┐ │ 客户端应用程序 │ │ ┌────────────────┐ ┌──────────────────┐ │ │ │ EchoEnv │ │ CodingEnv │ │ │ │ (EnvClient) │ │ (EnvClient) │ │ │ └────────┬───────┘ └────────┬─────────┘ │ └───────────┼───────────────────────────────┼─────────────┘ │ WebSocket │ WebSocket │ (reset, step, state) │ ┌───────────▼───────────────────────────────▼─────────────┐ │ Docker 容器（隔离） │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ FastAPI Server │ │ FastAPI Server │ │ │ │ EchoEnvironment │ │ PythonCodeActEnv │ │ │ │ (Environment base) │ │ (Environment base) │ │ │ └──────────────────────┘ └──────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ### 核心组件 #### 1. Web 界面 OpenEnv 包含一个内置的 Web 界面，用于交互式环境探索和调试。Web 界面提供： - 双窗格布局：左侧为人机交互，右侧为状态观察 - 实时更新：基于 WebSocket 的实时更新，无需刷新页面 - 动态表单：根据环境 Action 类型自动生成的操作表单 - 操作历史：所有操作及其结果的完整日志 Web 界面有条件地启用，基于环境变量： - 本地开发：默认禁用，以保持轻量级开发 - 手动覆盖：使用 ENABLE_WEB_INTERFACE=true 启用 使用 Web 界面： python 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 env = YourEnvironment() app = create_web_interface_app(env, YourAction, YourObservation) 启用后，在浏览器中打开 http://localhost:8000/web 即可与环境交互。 #### 2. 环境（服务器端） 实现环境逻辑的基类： - reset()：初始化一个新回合，返回初始 Observation - step(action)：执行一个 Action，返回结果 Observation - state()：访问回合元数据（包含 episode_id、step_count 等的 State） #### 3. EnvClient（客户端） 环境通信的基类： - 默认异步：对所有操作使用 async with 和 await - 同步包装器：调用 .sync() 获取 SyncEnvClient 用于同步用法 - 处理与环境服务器的 WebSocket 连接 - 包含一个实用程序，用于在本地为相应环境启动 Docker 容器 - 类型安全的 Action/Observation 解析 #### 4. 容器提供者 管理容器部署： - LocalDockerProvider：在本地 Docker 守护进程上运行容器 - DockerSwarmProvider：部署到 Docker Swarm 集群 - KubernetesProvider：部署到 Kubernetes 集群 - UVProvider、DaytonaProvider：额外的运行时提供者 #### 5. 模型 类型安全的数据结构： - Action：环境操作的基类 - Observation：环境观察的基类 - State：回合状态跟踪 - StepResult：合并观察、奖励、完成标志 ## 项目结构 ### 针对环境创建者 使用 CLI 快速搭建新环境： bash openenv init my_env 创建如下结构： my_env/ ├── .dockerignore # Docker 构建排除 ├── __init__.py # 导出 YourAction, YourObservation, YourEnv ├── models.py # 定义 Action, Observation, State 数据类 ├── client.py # 实现 YourEnv(EnvClient) ├── README.md # 文档化你的环境 ├── openenv.yaml # 环境清单 ├── pyproject.toml # 依赖和包配置 ├── outputs/ # 运行时输出（日志、评估） - gitignored │ ├── logs/ │ └── evals/ └── server/ ├── your_environment.py # 实现 YourEnvironment(Environment) ├── app.py # 创建 FastAPI 应用 ├── requirements.txt # Docker 依赖（可生成） └── Dockerfile # 定义容器镜像 #### 依赖管理 OpenEnv 使用 pyproject.toml 作为主要依赖声明文件： - 环境级别的 pyproject.toml：每个环境定义自己的依赖 - 根级别的 pyproject.toml：包含共享的核心依赖（fastapi, pydantic, uvicorn） - 服务器的 requirements.txt：可从 pyproject.toml 自动生成，用于 Docker 构建 开发工作流： bash # 以可编辑模式安装环境 cd my_env pip install -e . # 或使用 uv（更快） uv pip install -e . # 在本地运行服务器（无需 Docker） uv run server --host 0.0.0.0 --port 8000 查看 envs/README.md 获取构建环境的完整指南。 ### 针对环境用户 使用环境： 1. 安装客户端：pip install git+https://huggingface.co/spaces/openenv/echo_env 2. 导入：from echo_env import CallToolAction, EchoEnv 3. 使用异步（推荐）或同步 API： 异步（推荐）： python async with EchoEnv(base_url="...") as client: result = await client.reset() result = await client.step(action) 同步（通过 .sync() 包装器）： python with EchoEnv(base_url="...").sync() as client: result = client.reset() result = client.step(action) 请参阅 examples/ 目录中的示例脚本。 ## CLI 命令 OpenEnv CLI 提供管理环境的命令： - openenv init - 从模板初始化新环境 - openenv push [--repo-id ] [--private] - 将环境部署到 Hugging Face Spaces - openenv serve - 在本地运行环境，支持可选的自动重载 - openenv build - 为环境构建 Docker 镜像 - openenv fork - 从 HF Hub 分叉一个 Space 到你的账户 - openenv validate - 验证环境配置 ### 快速开始 bash # 创建一个新环境 openenv init my_game_env # 部署到 Hugging Face（如果需要，会提示登录） cd my_game_env openenv push 使用 --help 查看任何命令的详细选项。 ## 开发 ### 安装 bash # 克隆仓库 git clone https://github.com/huggingface/OpenEnv.git cd OpenEnv # 以可编辑模式安装核心包 pip install -e . # 或使用 uv（更快） uv pip install -e . ### 运行测试 OpenEnv 使用模块化依赖结构：核心包最小化，每个环境有自己的依赖。这意味着某些测试需要环境特定的包。 bash # 安装 pytest（运行测试所需） uv pip install pytest # 运行所有测试（跳过需要未安装依赖的测试） PYTHONPATH=src:envs uv run pytest tests/ -v --tb=short # 运行特定测试文件 PYTHONPATH=src:envs uv run pytest tests/envs/test_echo_environment.py -v 要运行环境特定的测试，请安装该环境的依赖： bash # 示例：安装 coding_env 及其开发依赖（包含 smolagents + pytest） uv pip install -e "envs/coding_env[dev]" # 然后运行 coding_env 测试 PYTHONPATH=src:envs uv run pytest tests/envs/test_python_codeact_rewards.py -v 如果未安装所需的依赖，测试将自动跳过。 ## 集成 OpenEnv 与日益增长的 RL 框架和平台生态系统合作。如果你的项目支持 OpenEnv，请提交 PR 将其添加到此。 ### TRL 查看 TRL 示例 (https://huggingface.co/docs/trl/openenv) 了解如何将 OpenEnv 环境与 GRPO 训练集成。 ### torchforge 查看 GRPO BlackJack 训练示例：examples/grpo_blackjack/ ### Unsloth 查看基于 gpt-oss 的 2048 游戏示例：Colab notebook (https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb) ### SkyRL 查看 SkyRL 示例 (https://skyrl.readthedocs.io/en/latest/examples/openenv.html) 了解如何使用 SkyRL 在 OpenEnv 环境上进行训练。 ### ART 查看 ART 示例 (https://art.openpipe.ai/integrations/openenv-integration) 了解如何使用 OpenEnv 环境通过 ART 训练模型。 ### Oumi 查看 Oumi 示例 (https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb) 了解如何使用 OpenEnv 环境通过 Oumi 训练模型。 ### Lightning AI Lightning AI 模板 (https://lightning.ai/templates?section=featured&query=openenv) ## 示例环境 | 环境 | 描述 | |—|—| | Echo Environment | 回显消息并附带元数据。非常适合测试 HTTP 服务器基础设施、学习框架基础以及验证容器部署。 | | Coding Environment | 通过 smolagents 执行沙盒 Python 代码。捕获 stdout/stderr/退出码，支持持久化回合上下文，并提供详细的错误处理。 | | Chess Environment | 国际象棋 RL 环境，支持可配置对手和完整规则。 | | Atari Environment | 经典的街机学习环境任务，用于 RL 基准测试。 | | FinRL Environment | 金融市场模拟，用于算法交易实验。 | > 浏览完整社区环境目录，请访问 huggingface.co/docs/openenv/environments (https://huggingface.co/docs/openenv/environments)。 ## 社区支持与致谢 OpenEnv 由一个技术委员会管理，该委员会通过公共问题跟踪器、拉取请求和 RFC 流程协调项目方向、重大技术决策、RFC 和发布计划。当前委员会成员：Meta-PyTorch、Reflection、Unsloth、Modal、Prime Intellect、Nvidia、Mercor、Fleet AI 和 Hugging Face。 该项目还得到更广泛的组织社区的支持。如果你想将自己的项目或组织添加到此，请提交拉取请求供维护者审查。支持者包括：Meta-PyTorch (https://github.com/meta-pytorch)、Hugging Face (https://huggingface.co)、Scaler AI Labs (https://scalerailabs.com)、Patronus AI (https://patronus.ai)、Surge AI (https://surgehq.ai)、LastMile AI (https://www.lastmileai.dev)、Unsloth (https://unsloth.ai)、Reflection (https://reflection.ai)、vLLM (https://vllm.ai)、SkyRL (https://skyrl.readthedocs.io) (UC-Berkeley)、Lightning AI (https://lightning.ai)、Axolotl AI (https://github.com/axolotl-ai-cloud/axolotl)、Stanford Scaling Intelligence Lab (https://scalingintelligence.stanford.edu/)、Mithril (https://mithril.ai)、OpenMined (https://openmined.org/)、Fleet AI (https://fleetai.com)、Halluminate (https://halluminate.ai/)、Turing (https://www.turing.com/)、Scale AI (https://scale.com/)、Scorecard (https://www.scorecard.io/) 此外，我们还要感谢 Farama Foundation 的团队，因为 OpenEnv API 深受你们在 Gymnasium 上所做工作的启发。干杯！ ## 许可证 BSD 3-Clause 许可证（参见 LICENSE 文件）