迁移指南 - v0.21 到 v1.0.0¶

Gymnasium 是 OpenAI Gym v0.26 <https://github.com/openai/gym/releases/tag/0.26.2>_ 的一个分支，它从 Gym v0.21 <https://github.com/openai/gym/releases/tag/v0.21.0>_ 引入了大量重大变更。在本指南中，我们简要概述了从 Gym v0.21（许多教程以此为基础编写）到 Gym v0.26 的 API 变化。对于仍停留在 v0.21 API 的环境，请参阅 指南 </content/gym_compatibility>_。

v0.21 的示例代码¶

import gym
env = gym.make("LunarLander-v3", options={})
env.seed(123)
observation = env.reset()

done = False
while not done:
    action = env.action_space.sample()  # agent policy that uses the observation and info
    observation, reward, done, info = env.step(action)

    env.render(mode="human")

env.close()

v0.26 的示例代码¶

import gym
env = gym.make("LunarLander-v3", render_mode="human")
observation, info = env.reset(seed=123, options={})

done = False
while not done:
    action = env.action_space.sample()  # agent policy that uses the observation and info
    observation, reward, terminated, truncated, info = env.step(action)

    done = terminated or truncated

env.close()

种子和随机数生成器¶

Env.seed() 已从 Gym v0.26 环境中移除，取而代之的是 Env.reset(seed=seed)。这使得种子只能在环境重置时更改。移除 seed 的原因是，某些环境使用无法在单个剧集中更改随机数生成器的模拟器，必须在新剧集开始时进行更改。我们意识到在某些情况下控制随机数生成器非常重要，在这些情况下，如果环境使用内置的随机数生成器，用户可以通过属性 :attr:np_random 手动设置种子。

Gymnasium v0.26 改为使用 numpy.random.Generator 而不是自定义的随机数生成器。这意味着一些函数，如 randint，被移除，取而代之的是 integers。虽然某些环境可能使用外部随机数生成器，但我们建议使用属性 :attr:np_random，包装器和外部用户可以访问和利用该属性。

环境重置¶

在 v0.26 中，:meth:reset 接受两个可选参数并返回一个值。这与不接受任何参数并返回 None 的 v0.21 形成对比。这两个参数是用于设置随机数生成器的 seed 和允许在重置时向环境传递额外数据的 options。例如，在经典控制中，options 参数现在允许用户修改状态边界范围。更多详情请参见原始 PR <https://github.com/openai/gym/pull/2921>_。

:meth:reset 进一步返回 info，类似于 :meth:step 返回的 info。这一点很重要，因为 info 可以包含在下一步中使用或保存的指标或有效动作掩码。

为了更新旧的环境，我们强烈建议在 :meth:reset 方法的第一行调用 super().reset(seed=seed)。这将自动使用种子值更新 :attr:np_random。

环境步骤¶

在 v0.21 中，:meth:step 的类型定义为 tuple[ObsType, SupportsFloat, bool, dict[str, Any]，表示下一个观察值、步骤中的奖励、是否完成该集以及步骤中的附加信息。由于即将在博客文章中详细讨论的可重复性问题，我们将类型定义更改为 tuple[ObsType, SupportsFloat, bool, bool, dict[str, Any]]，增加了一个额外的布尔值。这个额外的布尔值对应于旧的 done，现在改为 terminated 和 truncated。这些更改在 Gym v0.26 <https://github.com/openai/gym/releases/tag/0.26.0>_ 中引入（在 v25 <https://github.com/openai/gym/releases/tag/0.25.0>_ 中默认关闭）。

对于希望更新的用户，在大多数情况下，将 done 替换为 terminated 并在 :meth:step 中使用 truncated=False 应该能解决大多数问题。然而，对于那些有理由进行剧集截断而不是终止的环境，应该阅读相关的 PR <https://github.com/openai/gym/pull/2752>_。对于在环境中循环的用户，他们应该按照示例代码所示修改 done = terminated or truncated。对于训练库，主要区别是将 done 更改为 terminated，以指示是否应该或不应该进行引导。

TimeLimit 包装器¶

在v0.21中，:class:TimeLimit 包装器在代理达到时间限制而未达到终止状态时，在 info 字典中添加了一个额外的键 TimeLimit.truncated。

在v0.26中，这一信息通过上一节中描述的 truncated 返回值来传达，如果代理达到时间限制，无论是否达到终止状态，该值均为 True。旧的字典条目等同于 truncated and not terminated

环境渲染¶

在v0.26中，引入了一个新的渲染API，使得渲染模式在初始化时被固定，因为某些环境不允许动态更改渲染模式。因此，用户现在应该在gym.make中指定:attr:render_mode，如上面的v0.26示例代码所示。

如需更全面的变更解释，请参阅此 总结 <https://younis.dev/blog/render-api/>_。

已移除代码¶

GoalEnv - 此功能已被移除，需要此功能的用户应重新实现该环境或使用包含此环境实现的 Gymnasium Robotics。
from gym.envs.classic_control import rendering - 这一行代码已被移除，取而代之的是用户实现自己的渲染系统。Gymnasium 环境使用 pygame 编写。
机器人环境 - 机器人环境已迁移到 Gymnasium Robotics <https://robotics.farama.org/>_ 项目。
监视器包装器 - 这个包装器被替换为两个独立的包装器，:class:RecordVideo 和 :class:RecordEpisodeStatistics