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/GymnasiumGymnasium 是面向单智能体强化学习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 内置的环境按复杂度与实现技术分为以下家族并支持大量第三方环境家族特点实现位置仓库内Classic Control经典控制基于现实问题与物理定律的经典 RL 任务状态与动作空间简单直观gymnasium/envs/classic_controlBox2D基于 box2d 物理引擎 PyGame 渲染的玩具游戏类任务gymnasium/envs/box2dToy Text玩具文本状态与动作空间为小型离散空间极易学习适合调试 RL 算法实现gymnasium/envs/toy_textMuJoCo基于物理引擎的多关节控制任务比 Box2D 环境更复杂gymnasium/envs/mujocoAtari通过 ALE 模拟器运行 Atari 2600 ROM任务复杂度跨度大由ale_py提供gymnasium[atari]可选依赖Third-party第三方社区创建的兼容 Gymnasium API 的环境需注意其针对的 API 版本必要时在gymnasium.make中使用apply_env_compatibility从源码注册表可以印证这些环境的实际登记情况。gymnasium/envs/init.py 是内置环境的注册入口例如经典控制家族中注册了CartPole-v0、CartPole-v1、MountainCar-v0、MountainCarContinuous-v0、Pendulum-v1、Acrobot-v1等见 gymnasium/envs/init.pyBox2D 家族则注册了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 为准分组主要依赖用途atariale_py 0.9Atari 2600 模拟器box2dpygame-ce、box2d/box2d-py、swigBox2D 物理渲染环境classic-controlpygame-ce经典控制环境渲染mujocomujoco、imageio、packagingMuJoCo 物理仿真toy-textpygame-ce玩具文本环境渲染jaxjax、jaxlib、flax、array-api-compatJAX 函数式环境与包装器torchtorch、array-api-compatPyTorch 张量包装器array-apiarray-api-compat、packaging数组 API 兼容支持othermoviepy、matplotlib、opencv-python、seaborn视频录制与可视化辅助all以上全部分组一键安装全部依赖值得注意的是box2d分组在不同 Python 版本下的依赖差异Python 3.14 之前使用box2d 2.3.10而 3.14 及以上改用从源码构建的box2d-py 2.3.8并额外依赖swig 4.*见 pyproject.toml这正体现了 README 中所说部分依赖在特定系统上安装可能有问题的具体场景。核心 APIenv类的五种方法与两个空间Gymnasium 将环境建模为简单的 Pythonenv类。作为用户需要掌握的核心方法在 gymnasium/core.py 中有明确定义step(action)执行一个动作并推进环境状态返回下一步观测、奖励、终止标志、截断标志与附加信息reset(seedNone, optionsNone)将环境重置为初始状态每个回合开始前必须调用返回初始观测与 inforender()按初始化时指定的render_mode渲染画面常见模式为human、rgb_array、ansiclose()关闭环境释放渲染窗口、数据库或网络连接等外部资源unwrap()/unwrapped剥离所有包装器取回最底层的原始环境。同时每个环境都带有两个核心空间属性action_space合法动作空间所有有效动作都应包含其中observation_space合法观测空间所有有效观测都应包含其中。step 的返回值五元组与terminated/truncatedstep的完整签名为见 gymnasium/core.pyobservation, reward, terminated, truncated, info env.step(action)observation执行动作后环境返回的下一个观测属于observation_spacereward执行该动作获得的奖励terminated智能体是否到达任务定义的终止状态MDP 定义范围内例如到达目标格或掉入熔岩为True时需要调用resettruncated是否因 MDP 范围外的条件被截断典型情况是超过时间限制或智能体越界为True时同样需要调用resetinfo辅助诊断信息字典可用于调试、记录日志或包含观测中隐藏的变量、奖励分项等。这里需要特别强调terminated与truncated的拆分是在 Gymnasium 0.26 版本引入的重要 API 变更它取代了旧 Gym 中含义模糊的done信号见 gymnasium/core.py。这一拆分对引导式bootstrapping强化学习算法至关重要——算法需要区分回合因成功/失败自然结束与因时间限制被截断两种情形才能正确决定是否进行价值引导bootstrap。在 OpenAI Gym 早于 v26 的版本中info里的TimeLimit.truncated字段承担区分职责如今已废弃。reset 的种子机制reset(seed..., options...)中的seed参数用于初始化环境的 PRNGnp_random与只读属性np_random_seed见 gymnasium/core.py传入整数时即使环境已有 PRNG 也会重置随机数状态传入None且环境尚无 PRNG 时会从熵源如时间戳或/dev/urandom选取种子传入None且环境已有 PRNG 时不会重置随机数状态。官方推荐的最佳实践是环境初始化后立即调用一次带种子的reset之后不再传入。这样既能保证实验可复现又不会破坏后续回合的随机性。对于自定义环境reset的第一行应调用super().reset(seedseed)以正确实现播种逻辑。此外如需复现动作采样可对动作空间直接设置种子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(seed42) 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 语义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_steps500、reward_threshold475.0见 gymnasium/envs/init.py因此单回合最多 500 步超过即truncatedTrue。env.reset(seed42)以固定种子初始化保证实验可复现返回的observation是长度为 4 的 numpy 数组小车位置、速度、杆的角度、角速度info为诊断字典。env.action_space.sample()从离散动作空间Discrete(2)中随机采样作为随机策略的动作来源在真实算法中此处替换为智能体策略输出。回合结束处理一旦terminated or truncated为真立即调用env.reset()开启新回合。这是 Gymnasium API 的强制约定——step文档明确指出当terminated or truncated达到时必须先reset才能继续step见 gymnasium/core.py。env.close()释放渲染等外部资源环境也支持with上下文管理器__enter__/__exit__会在退出时自动调用close见 gymnasium/core.py。make的常用进阶参数除了环境 id 与构造参数make还支持以下常用参数见 gymnasium/envs/registration.pymax_episode_steps覆盖注册表中声明的最大回合步数并传递给TimeLimit包装器传入-1表示不应用该包装器disable_env_checker控制是否应用PassiveEnvCheckerNone时沿用EnvSpec中的设置任意 kwargs透传给环境构造函数例如gym.make(LunarLanderContinuous-v3)与gym.make(LunarLander-v3, continuousTrue)等价因为后者的注册 kwargs 中已设置{continuous: True}见 gymnasium/envs/init.py渲染模式通过gym.make(CartPole-v1, render_modehuman)开启窗口渲染。若环境不原生支持humanmake会自动应用HumanRendering包装器render_modergb_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-v0200 步、阈值 195.0与CartPole-v1500 步、阈值 475.0见 gymnasium/envs/init.pyBox2D 家族的最新版本为LunarLander-v3。同一环境的不同版本号意味着不同的行为语义在复现论文或对比基线时务必核对所用版本。生态与相关库README 明确指出以下列表并非完整清单而是维护者最常向新手推荐的生态成员CleanRL基于 Gymnasium API 的学习库面向 RL 新人设计提供高质量的参考实现适合对照学习标准算法写法PettingZooGymnasium 的多智能体版本内置大量多智能体环境例如多智能体 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(seedseed)、返回全新对象等要求测试用例tests/ 目录下的test_core.py、test_make.py、test_env_checker.py等测试文件印证了本仓库所述 API 行为例如 step 五元组返回值、环境检查器校验逻辑与注册/创建流程。总而言之Gymnasium 通过一套简洁而严格的标准 APIresetstep五元组 两个空间 包装器体系将强化学习算法的开发从适配每个环境中解放出来。掌握本文的安装、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考