环境

class gymnasium.Env

用于实现强化学习代理环境的主要 Gymnasium 类。

该类通过 :meth:step 和 :meth:reset 函数封装了一个具有任意幕后动态的环境。环境可以被单个智能体部分或完全观察。对于多智能体环境，请参见 PettingZoo。

用户需要了解的该类的主要API方法是：

• :meth:step - 使用返回下一个代理观察、采取该行动的奖励、由于最新行动导致环境是否终止或截断以及环境关于步骤的信息（如指标、调试信息）来更新环境。

• :meth:reset - 将环境重置为初始状态，在调用步骤之前需要执行此操作。返回一个情节的第一个代理观察结果和信息，即指标、调试信息。

• :meth:render - 渲染环境以帮助可视化代理看到的内容，示例模式有“human”、“rgb_array”、“ansi”用于文本。

• :meth:close - 关闭环境，在使用外部软件时非常重要，例如用于渲染的 pygame，数据库

环境有额外的属性供用户理解实现

• :attr:action_space - 对应于有效动作的 Space 对象，所有有效动作应包含在此空间内。

• :attr:observation_space - 对应于有效观察的空间对象，所有有效观察应包含在此空间内。

• :attr:spec - 一个环境规范，包含用于从 :meth:gymnasium.make 初始化环境的信息

• :attr:metadata - 环境的元数据，例如 {"render_modes": ["rgb_array", "human"], "render_fps": 30}。对于 Jax 或 Torch，可以通过 "jax"=True 或 "torch"=True 向用户指示。

• :attr:np_random - 环境的随机数生成器。这会在调用 super().reset(seed=seed) 时自动分配，并在访问 :attr:np_random 时评估。

参见

要修改或扩展环境，请使用 :class:gymnasium.Wrapper 类

备注

为了获得可重复的动作采样，可以使用 env.action_space.seed(123) 设置种子。

备注

对于严格的类型检查（例如，mypy 或 pyright），:class:Env 是一个带有两个参数化类型的泛型类：ObsType 和 ActType。ObsType 和 ActType 是 :meth:reset 和 :meth:step 中使用的观察和动作的预期类型。环境中的 :attr:observation_space 和 :attr:action_space 应具有类型 Space[ObsType] 和 Space[ActType]，请参阅空间的实现以找到其参数化类型。

方法

Env.step(action: ActType) → tuple[ObsType, SupportsFloat, bool, bool, dict[str, Any]]

使用代理的动作运行环境动力学的一个时间步。

当一个回合结束时（终止或截断），需要调用 :meth:reset 来重置此环境的状态以进行下一回合。

在 0.26 版本发生变更: Step API 进行了更改，移除了 done 而改为使用 terminated 和 truncated，以便更清晰地向用户表明环境何时终止或截断，这对于强化学习自举算法至关重要。

参数:

action (ActType) – 代理提供的一个用于更新环境状态的动作。

返回:

• observation (ObsType) – 由于代理动作，环境 :attr:observation_space 中的一个元素作为下一个观察。例如，一个包含 CartPole 中杆的位置和速度的 numpy 数组。

• reward (SupportsFloat) – 作为采取行动的结果的奖励。

• terminated (bool) – 代理是否达到终端状态（根据任务的MDP定义），这可以是正面的或负面的。例如，达到目标状态或从Sutton和Barto的Gridworld移动到熔岩中。如果为真，用户需要调用 :meth:reset。

• truncated (bool) – 是否满足MDP范围外的截断条件。通常，这是一个时间限制，但也可以用来指示代理物理上越界。可以用来在达到终止状态之前提前结束回合。如果为真，用户需要调用 :meth:reset。

• info (dict) – 包含辅助诊断信息（有助于调试、学习和记录）。例如，这可能包含：描述智能体性能状态的指标、观察中隐藏的变量，或组合生成总奖励的个别奖励项。在 OpenAI Gym <v26 中，它包含 “TimeLimit.truncated” 以区分截断和终止，但这一功能已被弃用，取而代之的是返回 terminated 和 truncated 变量。

• done (bool) – (已弃用) 一个布尔值，表示剧集是否已结束，在这种情况下，进一步的 :meth:step 调用将返回未定义的结果。这在 OpenAI Gym v26 中被移除，取而代之的是 terminated 和 truncated 属性。done 信号可能因不同原因而发出：可能是环境下的任务已成功解决，超过了某个时间限制，或者是物理模拟进入了无效状态。

Env.reset(*, seed: int | None = None, options: dict[str, Any] | None = None) → tuple[ObsType, dict[str, Any]]

将环境重置为初始内部状态，返回初始观察值和信息。

此方法生成一个新的起始状态，通常带有一定的随机性，以确保代理探索状态空间并学习关于环境的广义策略。这种随机性可以通过 seed 参数来控制，否则如果环境已经有一个随机数生成器，并且使用 seed=None 调用 :meth:reset，则不会重置 RNG。

因此，:meth:reset 应在初始化后（在典型使用情况下）立即使用种子调用，之后不再调用。

对于自定义环境，:meth:reset 方法的第一行应该是 super().reset(seed=seed)，这样可以正确实现种子设定。

在 v0.25 版本发生变更: return_info 参数已被移除，现在预期返回信息。

参数:

• seed (optional int) – 用于初始化环境 PRNG (np_random) 的种子和只读属性 np_random_seed。如果环境尚未拥有 PRNG 且传递了 seed=None（默认选项），将从某些熵源（例如时间戳或 /dev/urandom）中选择一个种子。然而，如果环境已经拥有 PRNG 且传递了 seed=None，PRNG 将 不会 被重置，且环境的 :attr:np_random_seed 将 不会 被更改。如果你传递一个整数，即使 PRNG 已经存在，它也将被重置。通常，你希望在环境初始化后立即传递一个整数，然后不再传递。请参考上面的最小示例以查看此范例的实际应用。

• options (optional dict) – 指定环境如何重置的附加信息（可选，取决于具体环境）

返回:

• observation (ObsType) – 初始状态的观测。这将是 :attr:observation_space 的一个元素（通常是一个 numpy 数组），类似于 :meth:step 返回的观测。

• info (字典) – 这个字典包含补充 observation 的辅助信息。它应该类似于 :meth:step 返回的 info。

Env.render() → RenderFrame | list[RenderFrame] | None

根据环境初始化时的 :attr:render_mode 计算渲染帧。

环境中的 :attr:元数据 渲染模式 (env.metadata["render_modes"]) 应包含实现渲染模式的可能方式。此外，通过 gymnasium.make 可以实现大多数渲染模式的列表版本，它会自动应用一个包装器来收集渲染的帧。

备注

由于在 __init__ 期间已知 :attr:render_mode，用于渲染环境状态的对象应在 __init__ 中初始化。

按照惯例，如果 :attr:render_mode 是：

• None (默认): 不进行渲染计算。

• “human”: 环境在当前显示器或终端中持续渲染，通常供人类观看。这种渲染应在 :meth:step 期间发生，不需要调用 :meth:render。返回 None。

• “rgb_array”: 返回一个代表环境当前状态的单帧。帧是一个形状为 (x, y, 3) 的 np.ndarray，表示 x 乘 y 像素图像的 RGB 值。

• “ansi”: 返回一个字符串 (str) 或 StringIO.StringIO，其中包含每个时间步的终端样式文本表示。文本可以包含换行符和 ANSI 转义序列（例如颜色）。

• “rgb_array_list” 和 “ansi_list”: 通过包装器 :py:class:gymnasium.wrappers.RenderCollection，可以实现基于列表的渲染模式版本（除了 Human 模式），该包装器在调用 gymnasium.make(..., render_mode="rgb_array_list") 时自动应用。收集的帧在调用 :meth:render 或 :meth:reset 后弹出。

备注

确保你的类的 :attr:元数据 "render_modes" 键包含支持的模式列表。

在 0.25.0 版本发生变更: 渲染函数已被修改，不再接受参数，而是这些参数应在初始化的环境中指定，例如 gymnasium.make("CartPole-v1", render_mode="human")

Env.close()

用户完成使用环境后，close 包含清理环境所需的代码。

这对于关闭渲染窗口、数据库或HTTP连接至关重要。在一个已经关闭的环境上调用 close 不会有任何效果，也不会引发错误。

属性

Env.action_space: spaces.Space[ActType]

对应于有效动作的 Space 对象，所有有效动作都应包含在空间内。例如，如果动作空间是 Discrete 类型并给出值 Discrete(2)，这意味着有两个有效的离散动作：0 和 1。

>>> env.action_space
Discrete(2)
>>> env.observation_space
Box(-3.4028234663852886e+38, 3.4028234663852886e+38, (4,), float32)

Env.observation_space: spaces.Space[ObsType]

对应于有效观测的空间对象，所有有效观测应包含在该空间内。例如，如果观测空间是类型为 :class:Box 且对象形状为 (4,)，这表示一个有效观测将是一个包含4个数字的数组。我们也可以通过属性检查盒子的边界。

>>> env.observation_space.high
array([4.8000002e+00, 3.4028235e+38, 4.1887903e-01, 3.4028235e+38], dtype=float32)
>>> env.observation_space.low
array([-4.8000002e+00, -3.4028235e+38, -4.1887903e-01, -3.4028235e+38], dtype=float32)

Env.metadata: dict[str, Any] = {'render_modes': []}

包含渲染模式、渲染帧率等的环境元数据

Env.render_mode: str | None = None

环境在初始化时确定的渲染模式

Env.spec: EnvSpec | None = None

环境的 :class:EnvSpec 通常在 :py:meth:gymnasium.make 期间设置

property Env.unwrapped: Env[ObsType, ActType]

返回未包装的基础环境。

返回:

Env – 基础的未包装的 :class:gymnasium.Env 实例

property Env.np_random: Generator

返回环境的内部 :attr:_np_random，如果未设置，将使用随机种子初始化。

返回:

np.random.Generator 的实例

property Env.np_random_seed: int

返回环境的内部 :attr:_np_random_seed，如果未设置，将首先使用随机整数作为种子进行初始化。

如果 :attr:np_random_seed 是直接设置的，而不是通过 :meth:reset 或 :meth:set_np_random_through_seed 设置的，种子将取值 -1。

返回:

int – 当前 np_random 的种子，如果 rng 的种子未知则为 -1

实现环境

在实现一个环境时，必须创建 :meth:Env.reset 和 :meth:Env.step 函数来描述环境的动态。更多信息，请参阅环境创建教程。

创建环境

要创建一个环境，gymnasium 提供了 :meth:make 来初始化环境以及几个重要的包装器。此外，gymnasium 提供了 :meth:make_vec 用于创建向量环境，并使用 :meth:pprint_registry 查看所有可以创建的环境。