环境

class gymnasium.Env

实现强化学习智能体环境的主要 Gymnasium 类。

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

用户需要了解的这个类主要 API 方法是

• step() - 使用动作更新环境，返回下一个智能体观测值、采取该动作的奖励、环境是否由于最新动作而终止或截断以及来自环境有关该步骤的信息，例如指标、调试信息。

• reset() - 将环境重置为初始状态，在调用 step 之前需要重置。返回一集的第一个智能体观测值和信息，例如指标、调试信息。

• render() - 渲染环境以帮助可视化智能体所看到的内容，例如模式包括“human”、“rgb_array”、“ansi”用于文本。

• close() - 关闭环境，当使用外部软件时很重要，例如用于渲染的 pygame、数据库

环境具有供用户了解实现的附加属性

• action_space - 与有效动作相对应的空间对象，所有有效动作都应包含在空间内。

• observation_space - 与有效观测值相对应的空间对象，所有有效观测值都应包含在空间内。

• spec - 一个环境规范，其中包含从 gymnasium.make() 初始化环境时使用的信息

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

• np_random - 环境的随机数生成器。这将在 super().reset(seed=seed) 期间自动分配，并在评估 np_random 时分配。

另请参见

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

注意

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

注意

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

方法

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

使用智能体动作运行环境动态的一次步。

当一集结束时（terminated or truncated），需要调用 reset() 来重置此环境的状态，以进行下一集。

在版本 0.26 中更改： Step API 已更改，删除了 done，取而代之的是 terminated 和 truncated，以便用户更清楚地了解环境何时终止或截断，这对强化学习自举算法至关重要。

参数:

action (ActType) – 智能体提供的用于更新环境状态的动作。

返回值:

• observation (ObsType) – 环境的 observation_space 中的一个元素，作为智能体动作的结果产生的下一个观测值。例如，一个 numpy 数组，包含 CartPole 中杆子的位置和速度。

• reward (SupportsFloat) – 采取该动作所获得的奖励。

• terminated (bool) – 智能体是否达到终止状态（如任务的 MDP 定义），可以是正值或负值。例如，达到目标状态或从 Sutton 和 Barto 格子世界进入熔岩。如果为真，用户需要调用 reset()。

• truncated (bool) – MDP 范围之外的截断条件是否满足。通常，这是一个时间限制，但也可能用于指示智能体物理上超出边界。可用于在达到终止状态之前过早地结束一集。如果为真，用户需要调用 reset()。

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

• done (bool) – (已弃用) 表示该回合是否结束的布尔值，如果为真，则进一步调用 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 参数控制，否则，如果环境已经有一个随机数生成器并且 reset() 被调用时 seed=None，则 RNG 不会被重置。

因此，reset() 应该（在典型使用情况下）在初始化后立即使用种子调用，然后不再调用。

对于自定义环境，reset() 的第一行应该是 super().reset(seed=seed)，它实现了正确的播种。

从版本 v0.25 开始更改： return_info 参数已被移除，现在预期返回信息。

参数:

• seed (可选 int) – 用于初始化环境的 PRNG (np_random) 和只读属性 np_random_seed 的种子。 如果环境还没有 PRNG 并且传递了 seed=None（默认选项），则将从某个熵源（例如时间戳或 /dev/urandom）中选择一个种子。 但是，如果环境已经有一个 PRNG 并且传递了 seed=None，则 PRNG 不会被重置，并且 env 的 np_random_seed 不会被改变。 如果传递一个整数，则 PRNG 将被重置，即使它已经存在。 通常，你希望在环境初始化后立即传递一个整数，然后不再传递。 请参考上面的最小示例以了解此模式的工作原理。

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

返回值:

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

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

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

根据在环境初始化期间指定的 render_mode 计算渲染帧。

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

注意

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

按照惯例，如果 render_mode 为

• None（默认）：不进行渲染计算。

• “human”：环境在当前显示器或终端中连续渲染，通常供人类使用。 此渲染应该在 step() 期间发生，不需要调用 render()。 返回 None。

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

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

• “rgb_array_list” 和 “ansi_list”：列表版本的渲染模式是可能的（除了 Human），通过包装器 gymnasium.wrappers.RenderCollection 在 gymnasium.make(..., render_mode="rgb_array_list") 期间自动应用。 收集的帧会在调用 render() 或 reset() 后弹出。

注意

确保你的类的 metadata "render_modes" 键包含支持的模式列表。

从版本 0.25.0 开始更改： 渲染函数已更改为不再接受参数，而是应该在环境初始化中指定这些参数，例如 gymnasium.make("CartPole-v1", render_mode="human")

Env.close()

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

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

属性

Env.action_space: spaces.Space[ActType]

对应于有效动作的空间对象，所有有效动作都应该包含在空间内。 例如，如果动作空间的类型为 Discrete 并给出值 Discrete(2)，则表示有两个有效的离散动作：0 & 1。

>>> env.action_space
Discrete(2)
>>> env.observation_space
Box(-inf, inf, (4,), float32)

Env.observation_space: spaces.Space[ObsType]

与有效观测相对应的空间对象，所有有效观测都应包含在空间中。例如，如果观测空间的类型为 Box 且对象的形状为 (4,)，则表示有效的观测将是包含 4 个数字的数组。我们也可以使用属性检查框边界。

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

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

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

Env.render_mode: str | None = None

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

Env.spec: EnvSpec | None = None

环境的 EnvSpec，通常在 gymnasium.make() 中设置

property Env.unwrapped: Env[ObsType, ActType]

返回基础未包装的环境。

返回值:

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

property Env.np_random: Generator

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

返回值:

`np.random.Generator` 的实例

property Env.np_random_seed: int

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

如果 np_random_seed 是直接设置而不是通过 reset() 或 set_np_random_through_seed() 设置的，则种子将取值为 -1。

返回值:

int – 当前 np_random 的种子，如果随机数生成器的种子未知，则为 -1

实现环境

在实现环境时，必须创建 Env.reset() 和 Env.step() 函数来描述环境的动态变化。有关更多信息，请参见环境创建教程。

创建环境

为了创建环境，gymnasium 提供了 make() 来初始化环境以及一些重要的包装器。此外，gymnasium 还提供了 make_vec() 用于创建向量环境，要查看可以创建的所有环境，请使用 pprint_registry()。