meta-pytorch/OpenEnv

# OpenEnv: Agentic 执行环境 一个用于创建、部署和使用隔离执行环境的端到端 (e2e) 框架，专为 Agentic RL 训练设计，采用 Gymnasium 风格的简单 API 构建。 [](https://pypi.org/project/openenv-core/) [](https://discord.gg/YsTYBh6PD9) [](https://colab.research.google.com/github/meta-pytorch/OpenEnv/blob/main/examples/OpenEnv_Tutorial.ipynb) [](https://meta-pytorch.org/OpenEnv/) **🚀 精选示例：** 使用 [torchforge](https://github.com/meta-pytorch/torchforge) (PyTorch 的 Agentic RL 框架) 训练 LLM 玩 21 点 (BlackJack)：[`examples/grpo_blackjack/`](examples/grpo_blackjack/) **🔥 从零到精通教程：** 来自我们的 [GPU Mode](tutorial/README.md) 讲座和其他黑客松的端到端教程。 ## 快速开始 安装 OpenEnv 核心包： ``` pip install openenv-core ``` 安装环境客户端 (例如 Echo)： ``` pip install git+https://huggingface.co/spaces/openenv/echo_env ``` 然后使用该环境： ``` import asyncio from echo_env import EchoAction, EchoEnv async def main(): # Connect to a running Space (async context manager) async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client: # Reset the environment result = await client.reset() print(result.observation.echoed_message) # "Echo environment ready!" # Send messages result = await client.step(EchoAction(message="Hello, World!")) print(result.observation.echoed_message) # "Hello, World!" print(result.reward) # 1.3 (based on message length) asyncio.run(main()) ``` 也通过 `.sync()` 包装器支持**同步用法**： ``` from echo_env import EchoAction, EchoEnv # 在同步 context manager 中使用 .sync() with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client: result = client.reset() result = client.step(EchoAction(message="Hello, World!")) print(result.observation.echoed_message) ``` 欲了解详细的快速入门，请查看 [文档页面](https://meta-pytorch.org/OpenEnv/quickstart/)。 ## 合作伙伴平台上的 OpenEnv： - [Lightning AI Studio](https://lightning.ai/environments?section=featured) - [TRL example](https://huggingface.co/docs/trl/openenv) - [Unsloth Google Colab](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb) - [ART example](https://art.openpipe.ai/integrations/openenv-integration) - [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb) ## 概述 OpenEnv 提供了一个通过简单的 Gymnasium 风格 API (`step()`, `reset()`, `state()`) 与 Agentic 执行环境进行交互的标准。Agentic 执行环境的用户可以在 RL 训练循环中使用这些简单的 API 与环境进行交互。 除了让研究人员和 RL 框架编写者更轻松外，我们还为环境创建者提供工具，使他们能够更轻松地创建更丰富的环境，并通过 HTTP 等熟悉的协议提供服务，以及使用 Docker 等规范技术进行打包。环境创建者可以使用 OpenEnv 框架创建隔离、安全且易于部署和使用的环境。 OpenEnv CLI (`openenv`) 提供了初始化新环境并将其部署到 Hugging Face Spaces 的命令。 ### RFCs 以下是 OpenEnv 活跃和历史的 RFC 列表。RFC 是针对重大更改或功能的提案。请审阅并贡献！ - [RFC 001: Baseline API and Interface Specifications](https://github.com/meta-pytorch/OpenEnv/pull/26) - [RFC 002: Discoverability of environment tools by agents](https://github.com/meta-pytorch/OpenEnv/pull/32) - [RFC 003: Add MCP (Model Context Protocol) support](https://github.com/meta-pytorch/OpenEnv/pull/224) - [RFC 004: Add delayed rewards support for trajectory-based scoring](https://github.com/meta-pytorch/OpenEnv/pull/337) - [RFC 005: Agentic Harness Integration](https://github.com/meta-pytorch/OpenEnv/pull/387) ## 架构 ### 组件概述 ``` ┌─────────────────────────────────────────────────────────┐ │ Client Application │ │ ┌────────────────┐ ┌──────────────────┐ │ │ │ EchoEnv │ │ CodingEnv │ │ │ │ (EnvClient) │ │ (EnvClient) │ │ │ └────────┬───────┘ └────────┬─────────┘ │ └───────────┼───────────────────────────────┼─────────────┘ │ WebSocket │ WebSocket │ (reset, step, state) │ ┌───────────▼───────────────────────────────▼─────────────┐ │ Docker Containers (Isolated) │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ FastAPI Server │ │ FastAPI Server │ │ │ │ EchoEnvironment │ │ PythonCodeActEnv │ │ │ │ (Environment base) │ │ (Environment base) │ │ │ └──────────────────────┘ └──────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` ### 核心组件 #### 1. Web 界面 OpenEnv 包含一个用于交互式环境探索和调试的内置 Web 界面。该 Web 界面提供： - **双窗格布局**：左侧为 HumanAgent 交互，右侧为状态观察 - **实时更新**：基于 WebSocket 的实时更新，无需刷新页面 - **动态表单**：根据环境 Action 类型自动生成的 Action 表单 - **Action 历史**：所有已执行 Action 及其结果的完整日志 Web 界面根据环境变量**有条件地启用**： - **本地开发**：默认禁用，以实现轻量级开发 - **手动覆盖**：使用 `ENABLE_WEB_INTERFACE=true` 启用 要使用 Web 界面： ``` 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()`**：初始化一个新的 episode，返回初始 `Observation` - **`step(action)`**：执行一个 `Action`，返回结果 `Observation` - **`state()`**：访问 episode 元数据 (`State`，包含 episode_id, step_count 等) #### 3. EnvClient (客户端) 用于环境通信的基类： - **默认异步**：对所有操作使用 `async with` 和 `await` - **同步包装器**：调用 `.sync()` 以获取 `SyncEnvClient` 进行同步使用 - 处理到环境服务器的 WebSocket 连接 - 包含一个在本地为相应环境启动 Docker 容器的工具 - 类型安全的 Action/Observation 解析 #### 4. 容器提供商 管理容器部署： - `LocalDockerProvider`：在本地 Docker daemon 上运行容器 - `KubernetesProvider`：部署到 K8s 集群 (未来) #### 5. 模型 类型安全的数据结构： - `Action`：环境 Action 的基类 - `Observation`：环境 Observation 的基类 - `State`：Episode 状态跟踪 - `StepResult`：结合 Observation, reward, done flag ## 项目结构 ### 面向环境创建者 使用 CLI 快速搭建新环境： ``` openenv init my_env ``` 这将创建以下结构： ``` my_env/ ├── .dockerignore # Docker build exclusions ├── __init__.py # Export YourAction, YourObservation, YourEnv ├── models.py # Define Action, Observation, State dataclasses ├── client.py # Implement YourEnv(EnvClient) ├── README.md # Document your environment ├── openenv.yaml # Environment manifest ├── pyproject.toml # Dependencies and package configuration ├── outputs/ # Runtime outputs (logs, evals) - gitignored │ ├── logs/ │ └── evals/ └── server/ ├── your_environment.py # Implement YourEnvironment(Environment) ├── app.py # Create FastAPI app ├── requirements.txt # Dependencies for Docker (can be generated) └── Dockerfile # Define container image ``` #### 依赖管理 OpenEnv 使用 `pyproject.toml` 作为主要的依赖规范： - **环境级 `pyproject.toml`**：每个环境定义自己的依赖 - **根级 `pyproject.toml`**：包含共享的核心依赖 - **服务器 `requirements.txt`**：可以从 `pyproject.toml` 为 Docker 构建自动生成 **开发工作流：** ``` # 以 editable 模式安装环境 cd my_env pip install -e . # 或者使用 uv (更快) uv pip install -e . # 在本地不使用 Docker 运行服务器 uv run server --host 0.0.0.0 --port 8000 ``` **优势：** - ✅ **客户端扩展**：在本地修改客户端类而无需更改仓库 - ✅ **更好的依赖管理**：环境之间清晰分离 - ✅ **灵活的工作流**：针对不同场景使用 pip, uv 或 Docker - ✅ **CI/CD 就绪**：自动化依赖生成和验证 有关构建环境的完整指南，请参阅 [`envs/README.md`](envs/README.md)。 ### 面向环境用户 要使用环境： 1. 安装客户端：`pip install git+https://huggingface.co/spaces/openenv/echo-env` 2. 导入：`from echo_env import EchoAction, EchoEnv` 3. 使用异步 (推荐) 或同步 API： **异步 (推荐):** ``` async with EchoEnv(base_url="...") as client: result = await client.reset() result = await client.step(action) ``` **同步 (通过 `.sync()` 包装器):** ``` 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 init my_game_env # 部署到 Hugging Face (如果需要将提示登录) cd my_game_env openenv push ``` 详细选项请参阅：`openenv init --help` 和 `openenv push --help`。 ## 设计原则 1. **关注点分离**：清晰的客户端-服务器边界 2. **类型安全**：强类型的 Action, Observation 和 State 3. **容器隔离**：每个环境在自己的容器中运行 4. **简单 API**：最小化、直观的接口 ## 开发 ### 安装 ``` # 克隆仓库 git clone https://github.com/meta-pytorch/OpenEnv.git cd OpenEnv # 以 editable 模式安装核心包 pip install -e . # 或者使用 uv (更快) uv pip install -e . ``` ### 运行测试 OpenEnv 采用模块化依赖结构：核心包是最小的，每个环境都有自己的依赖。这意味着某些测试需要特定于环境的包。 ``` # 安装 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 ``` **要运行特定于环境的测试**，请安装该环境的依赖： ``` # 示例: 安装 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 ``` 如果未安装所需的依赖项，测试将被自动跳过。 ## 系统要求 - Python 3.10+ - Docker Desktop 或 Docker Engine - FastAPI >= 0.104.0 - Uvicorn >= 0.24.0 - Requests >= 2.25.0 - 特定于环境的依赖 (例如 coding_env 的 smolagents) ## 支持的 RL 工具 本项目的目标是支持广泛的开放和封闭工具，以帮助标准化 Agentic RL 社区。如果您有一个支持 OpenEnv 环境的项目，请提交 PR 以添加您的工具名称以及指向您文档的链接。 ### torchforge 请参阅 GRPO BlackJack 训练示例：[`examples/grpo_blackjack/`](examples/grpo_blackjack/) ### TRL 请参阅 [TRL example](https://huggingface.co/docs/trl/openenv) 了解如何将 OpenEnv 环境与 GRPO 训练集成。 ### 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 example](https://skyrl.readthedocs.io/en/latest/examples/openenv.html) 了解如何使用 SkyRL 在 OpenEnv 环境上进行训练。 ### ART 请参阅 [ART example](https://art.openpipe.ai/integrations/openenv-integration) 了解如何使用 OpenEnv 环境通过 ART 训练模型。 ### Oumi 请参阅 [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb) 了解如何使用 OpenEnv 环境通过 Oumi 训练模型。 ## 示例环境 | Environment | Description | |---|---| | [Echo Environment](envs/echo_env/README.md) | 带元数据回显消息。非常适合测试 HTTP 服务器基础设施、学习框架基础以及验证容器部署。 | | [Coding Environment](envs/coding_env/README.md) | 通过 smolagents 进行沙盒 Python 代码执行。捕获 stdout/stderr/exit codes，支持持久化 episode 上下文，并提供详细的错误处理。 | | [Chess Environment](envs/chess_env/README.md) | 具有可配置对手和完整规则支持的国际象棋 RL 环境。 | | [Atari Environment](envs/atari_env/README.md) | 用于 RL 基准测试的经典街机学习环境任务。 | | [FinRL Environment](envs/finrl_env/README.md) | 用于算法交易实验的金融市场模拟。 | ## 社区支持与致谢 这是一个开放且以社区为中心的项目。如果您想在这里添加您的名字，请提交 pull request 并标记 @jspisak 进行审阅。谢谢！！ 支持者包括：Meta-PyTorch, Hugging Face, [Scaler AI Labs](https://scalerailabs.com), [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), Unsloth AI, Reflection AI, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/), [Scale AI](https://scale.com/) .. 我们还要感谢 Farama Foundation 的团队，因为 OpenEnv API 深受你们在 Gymnasium 上所做工作的启发。干杯！ ## 许可证 BSD 3-Clause License (参见 [LICENSE](./LICENSE) 文件)

标签：AI安全, Chat Copilot, DLL 劫持, DNS解析, Gymnasium, Hugging Face, LLM训练, PyTorch, RLHF, 凭据扫描, 分布式训练, 后训练, 大语言模型, 工具库, 开源项目, 强化学习, 执行环境, 机器学习框架, 沙箱, 环境模拟, 端到端框架, 自动化执行, 请求拦截, 逆向工具, 隔离环境