企业官网建设流程全解析

Gymnasium 入门指南：标准强化学习环境 API、安装方式与核心用法

【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium

Gymnasium 是面向单智能体强化学习（RL）的开源 Python 库，它为学习算法与环境之间提供一套标准通信 API，并附带一批遵循该 API 的参考环境与工具。本文以仓库根目录 README.md 为主体，结合 gymnasium/core.py、gymnasium/envs/registration.py、gymnasium/envs/init.py 与 pyproject.toml 等源码文件，系统讲解 Gymnasium 的定位、环境家族、安装方式、核心 API 与实战用法。读完本文，你将掌握如何安装 Gymnasium、如何用gym.make创建并交互环境、如何理解step/reset的返回值语义，以及环境版本号的规范含义。

项目定位：标准化的 RL 环境接口

Gymnasium 是 OpenAI Gym 的官方继任项目。它由 Gym 的原维护团队接手（OpenAI 数年前已将维护权移交给外部团队），并在此仓库中持续演进。其核心目标是：

• 为学习算法与环境的交互提供标准 API，让同一套算法代码可以在不同环境间无缝迁移；
• 内置一批符合该 API 的参考环境，覆盖从玩具级到物理仿真级的不同复杂度；
• 提供配套工具（环境检查、向量化、包装器等），帮助开发者调试与加速训练流程。

Gymnasium 的 API 面向单智能体环境；多智能体场景由同基金会维护的 PettingZoo 承接（见下文"生态与相关库"一节）。项目当前版本为 1.4.0（见 gymnasium/init.py），核心依赖仅包含 numpy、cloudpickle、typing-extensions 与 farama-notifications（见 pyproject.toml），基础安装非常轻量。

环境家族：六大类参考环境

Gymnasium 内置的环境按复杂度与实现技术分为以下家族，并支持大量第三方环境：

从源码注册表可以印证这些环境的实际登记情况。gymnasium/envs/init.py 是内置环境的注册入口，例如经典控制家族中注册了CartPole-v0、CartPole-v1、MountainCar-v0、MountainCarContinuous-v0、Pendulum-v1、Acrobot-v1等（见 gymnasium/envs/init.py）；Box2D 家族则注册了LunarLander-v3、BipedalWalker-v3、CarRacing-v3等（见 gymnasium/envs/init.py）。每个注册条目都通过register()声明了id、entry_point、max_episode_steps、reward_threshold等元信息，这正是"环境版本控制"的基础（详见下文）。

此外，仓库中还包含基于 JAX 的phys2d环境族（如phys2d/CartPole-v1，见 gymnasium/envs/init.py），体现了 Gymnasium 对 JAX 等函数式框架的扩展方向。

安装指南：基础库与按需可选依赖

安装基础库

pip install gymnasium

该命令只安装 Gymnasium 核心库本身。之所以默认不捆绑全部环境的依赖，是因为环境家族数量庞大，且部分依赖（如 Box2D、MuJoCo）在不同系统上安装可能存在问题。

按家族安装可选依赖

pyproject.toml中定义了完整的可选依赖分组（见 pyproject.toml），常用写法如下：

# 仅安装 Atari 环境所需依赖 pip install "gymnasium[atari]" # 安装所有环境的依赖 pip install "gymnasium[all]"

各分组的实际内容（以当前仓库 pyproject.toml 为准）：

值得注意的是box2d分组在不同 Python 版本下的依赖差异：Python 3.14 之前使用box2d ==2.3.10，而 3.14 及以上改用从源码构建的box2d-py ==2.3.8并额外依赖swig ==4.*（见 pyproject.toml），这正体现了 README 中所说"部分依赖在特定系统上安装可能有问题"的具体场景。

核心 API：env类的五种方法与两个空间

Gymnasium 将环境建模为简单的 Pythonenv类。作为用户，需要掌握的核心方法在 gymnasium/core.py 中有明确定义：

• step(action)：执行一个动作并推进环境状态，返回下一步观测、奖励、终止标志、截断标志与附加信息；
• reset(seed=None, options=None)：将环境重置为初始状态（每个回合开始前必须调用），返回初始观测与 info；
• render()：按初始化时指定的render_mode渲染画面，常见模式为"human"、"rgb_array"、"ansi"；
• close()：关闭环境，释放渲染窗口、数据库或网络连接等外部资源；
• unwrap()/unwrapped：剥离所有包装器，取回最底层的原始环境。

同时每个环境都带有两个核心空间属性：

• action_space：合法动作空间，所有有效动作都应包含其中；
• observation_space：合法观测空间，所有有效观测都应包含其中。

step 的返回值：五元组与terminated/truncated

step的完整签名为（见 gymnasium/core.py）：

observation, reward, terminated, truncated, info = env.step(action)

• observation：执行动作后环境返回的下一个观测，属于observation_space；
• reward：执行该动作获得的奖励；
• terminated：智能体是否到达任务定义的终止状态（MDP 定义范围内），例如到达目标格或掉入熔岩；为True时需要调用reset；
• truncated：是否因 MDP 范围外的条件被截断，典型情况是超过时间限制或智能体越界；为True时同样需要调用reset；
• info：辅助诊断信息字典，可用于调试、记录日志，或包含观测中隐藏的变量、奖励分项等。

这里需要特别强调：terminated与truncated的拆分是在 Gymnasium 0.26 版本引入的重要 API 变更，它取代了旧 Gym 中含义模糊的done信号（见 gymnasium/core.py）。这一拆分对引导式（bootstrapping）强化学习算法至关重要——算法需要区分"回合因成功/失败自然结束"与"因时间限制被截断"两种情形，才能正确决定是否进行价值引导（bootstrap）。在 OpenAI Gym 早于 v26 的版本中，info里的"TimeLimit.truncated"字段承担区分职责，如今已废弃。

reset 的种子机制

reset(seed=..., options=...)中的seed参数用于初始化环境的 PRNG（np_random）与只读属性np_random_seed（见 gymnasium/core.py）：

• 传入整数时，即使环境已有 PRNG 也会重置随机数状态；
• 传入None且环境尚无 PRNG 时，会从熵源（如时间戳或/dev/urandom）选取种子；
• 传入None且环境已有 PRNG 时，不会重置随机数状态。

官方推荐的最佳实践是：环境初始化后立即调用一次带种子的reset，之后不再传入。这样既能保证实验可复现，又不会破坏后续回合的随机性。对于自定义环境，reset的第一行应调用super().reset(seed=seed)以正确实现播种逻辑。此外，如需复现动作采样，可对动作空间直接设置种子：env.action_space.seed(123)。

快速上手：CartPole-v1 完整示例

README 给出的核心示例使用经典控制环境CartPole-v1（倒立摆），这是理解 Gymnasium API 的最小完整程序：

import gymnasium as gym env = gym.make("CartPole-v1") observation, info = env.reset(seed=42) for _ in range(1000): action = env.action_space.sample() observation, reward, terminated, truncated, info = env.step(action) if terminated or truncated: observation, info = env.reset() env.close()

逐行解读其背后的 API 语义：

1. gym.make("CartPole-v1")根据注册表创建环境实例。从源码看，make会先依据 id 查找到对应的EnvSpec，合并注册参数与调用时传入的 kwargs，加载entry_point指定的环境类，然后自动依次应用多个包装器（见 gymnasium/envs/registration.py）：
   • 若未禁用，先包上PassiveEnvChecker（被动环境检查器）；
   • 默认包上OrderEnforcing（顺序强制，确保先reset再step/render）；
   • 若规格中声明了max_episode_steps，再包上TimeLimit（时间限制包装器，触发截断）。 以CartPole-v1为例，其注册信息为max_episode_steps=500、reward_threshold=475.0（见 gymnasium/envs/init.py），因此单回合最多 500 步，超过即truncated=True。
2. env.reset(seed=42)以固定种子初始化，保证实验可复现；返回的observation是长度为 4 的 numpy 数组（小车位置、速度、杆的角度、角速度），info为诊断字典。
3. env.action_space.sample()从离散动作空间Discrete(2)中随机采样，作为随机策略的动作来源；在真实算法中此处替换为智能体策略输出。
4. 回合结束处理：一旦terminated or truncated为真，立即调用env.reset()开启新回合。这是 Gymnasium API 的强制约定——step文档明确指出，当terminated or truncated达到时，必须先reset才能继续step（见 gymnasium/core.py）。
5. env.close()释放渲染等外部资源；环境也支持with上下文管理器（__enter__/__exit__会在退出时自动调用close，见 gymnasium/core.py）。

make的常用进阶参数

除了环境 id 与构造参数，make还支持以下常用参数（见 gymnasium/envs/registration.py）：

• max_episode_steps：覆盖注册表中声明的最大回合步数，并传递给TimeLimit包装器；传入-1表示不应用该包装器；
• disable_env_checker：控制是否应用PassiveEnvChecker，None时沿用EnvSpec中的设置；
• 任意 kwargs：透传给环境构造函数，例如gym.make("LunarLanderContinuous-v3")与gym.make("LunarLander-v3", continuous=True)等价，因为后者的注册 kwargs 中已设置{"continuous": True}（见 gymnasium/envs/init.py）；
• 渲染模式：通过gym.make("CartPole-v1", render_mode="human")开启窗口渲染。若环境不原生支持"human"，make会自动应用HumanRendering包装器；render_mode="rgb_array_list"则会自动应用RenderCollection包装器来收集帧序列（见 gymnasium/envs/registration.py）。

注册表与register

所有可用环境 id 可通过gymnasium.envs.registry.keys()或gymnasium.pprint_registry()查看。环境 id 的语法为namespace/[-v(version)]，其中 namespace 与版本号均可选（见 gymnasium/envs/registration.py）。社区或第三方环境可通过gymnasium.register(id=..., entry_point=...)注册后，即可用gym.make统一创建——这构成了 Gymnasium 生态可扩展性的基础。

环境版本控制：-v后缀的意义

Gymnasium 出于可复现性考虑，对环境实行严格版本控制（见 README.md）：

• 所有环境 id 都以形如-v0的版本后缀结尾；
• 当对环境的修改可能影响学习结果时，版本号递增 1（如-v1→-v2），以避免新旧行为混淆；
• 这一约定继承自 OpenAI Gym。

实际仓库中可以看到多个版本并存的实例，例如经典控制家族同时注册了CartPole-v0（200 步、阈值 195.0）与CartPole-v1（500 步、阈值 475.0）（见 gymnasium/envs/init.py），Box2D 家族的最新版本为LunarLander-v3。同一环境的不同版本号意味着不同的行为语义，在复现论文或对比基线时务必核对所用版本。

生态与相关库

README 明确指出以下列表并非完整清单，而是维护者最常向新手推荐的生态成员：

• CleanRL：基于 Gymnasium API 的学习库，面向 RL 新人设计，提供高质量的参考实现，适合对照学习标准算法写法；
• PettingZoo：Gymnasium 的多智能体版本，内置大量多智能体环境（例如多智能体 Atari 环境）；
• Farama Foundation 环境合集：由与 Gymnasium 同一团队维护的一系列环境项目，均使用 Gymnasium API，可通过 docs/environments/third_party_environments.md 了解第三方环境的使用注意事项。

引用方式

若在学术工作中使用 Gymnasium，请引用其相关论文（arXiv 编号 2407.17032），对应的 BibTeX 条目为：

@article{towers2024gymnasium, title={Gymnasium: A Standard Interface for Reinforcement Learning Environments}, author={Towers, Mark and Kwiatkowski, Ariel and Terry, Jordan and Balis, John U and De Cola, Gianluca and Deleu, Tristan and Goul{\~a}o, Manuel and Kallinteris, Andreas and Krimmel, Markus and KG, Arjun and others}, journal={arXiv preprint arXiv:2407.17032}, year={2024} }

仓库根目录的 CITATION.cff 中亦提供了机器可读的引用元数据。

继续深入：仓库中的学习资源

掌握以上内容后，可从仓库中的以下资源继续深入：

• 完整 API 参考：核心类与方法的完整文档见 gymnasium/core.py，空间（Space）体系见 gymnasium/spaces，包装器体系见 gymnasium/wrappers，向量化环境见 gymnasium/vector；
• 环境注册机制：register/make/make_vec/spec的完整实现与EnvSpec字段说明见 gymnasium/envs/registration.py；
• 内置环境源码：各家族环境类实现分别位于 gymnasium/envs/classic_control、gymnasium/envs/box2d、gymnasium/envs/mujoco、gymnasium/envs/toy_text；
• 编写自定义环境：docs/introduction/create_custom_env.md 详细讲解如何实现一个符合 API 规范的环境（包括reset首行调用super().reset(seed=seed)、返回全新对象等要求）；
• 测试用例：tests/ 目录下的test_core.py、test_make.py、test_env_checker.py等测试文件印证了本仓库所述 API 行为，例如 step 五元组返回值、环境检查器校验逻辑与注册/创建流程。

总而言之，Gymnasium 通过一套简洁而严格的标准 API（reset+step五元组 + 两个空间 + 包装器体系），将强化学习算法的开发从"适配每个环境"中解放出来。掌握本文的安装、API 语义与环境版本规范，即可顺畅地在 Gymnasium 生态中构建、调试与复现强化学习实验。

【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium