Env

class gymnasium.Env[source]

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

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

此类的用户需要了解的主要 API 方法有：

  • step() - 使用动作更新环境，返回下一个智能体观察、采取该动作的奖励、环境是否因最新动作而终止或截断，以及环境关于该步的信息（例如度量、调试信息）。

  • reset() - 将环境重置到初始状态，在调用 step 之前必需。返回一个回合的第一个智能体观察以及信息（例如度量、调试信息）。

  • render() - 渲染环境以帮助可视化智能体所见，示例模式包括“human”（人工）、“rgb_array”（RGB数组）、“ansi”（ANSI文本）。

  • close() - 关闭环境，在使用外部软件（如用于渲染的 pygame、数据库）时非常重要。

环境具有额外属性，供用户理解其实现：

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

  • observation_space - 对应有效观察的 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]][source]

使用智能体动作运行环境动力学的一个时间步。

当一个回合结束时（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 的 Gridworld 中达到目标状态或进入熔岩。如果为 True，用户需要调用 reset()。

  • truncated (bool) – MDP 范围之外的截断条件是否满足。通常，这是一个时间限制，但也可以用来表示智能体物理上越界。可以在达到终止状态之前提前结束回合。如果为 True，用户需要调用 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]][source]

将环境重置到初始内部状态，并返回一个初始观察和信息。

此方法通常会生成一个新的起始状态，并带有一些随机性，以确保智能体探索状态空间并学习关于环境的通用策略。这种随机性可以通过 seed 参数控制；否则，如果环境已经有随机数生成器并且 reset() 调用时 seed=None，则 RNG 不会被重置。

因此，在典型用例中，reset() 应该在初始化后立即使用种子调用，之后不再调用。

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

v0.25 版本更新: return_info 参数已移除，现在期望返回 `info`。

参数:

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

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

返回:

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

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

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

根据环境初始化时 render_mode 指定的方式计算渲染帧。

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

注意

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

按照惯例，如果 render_mode 是：

  • None（默认）：不计算任何渲染。

  • “human”（人工）：环境在当前显示器或终端中持续渲染，通常供人类观看。此渲染应在 step() 期间发生，render() 无需调用。返回 None。

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

  • “ansi”（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 版本更新: `render` 函数不再接受参数，这些参数应在环境初始化时指定，例如 gymnasium.make("CartPole-v1", render_mode="human")

Env.close()[source]

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

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

属性

Env.action_space: spaces.Space[ActType]

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

>>> env.action_space
Discrete(2)
>>> env.observation_space
Box(-inf, inf, (4,), float32)
Env.observation_space: spaces.Space[ObsType]

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

>>> 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': []}

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

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 的种子，如果 RNG 的种子未知则为 -1。

实现环境

在实现环境时，必须创建 Env.reset() 和 Env.step() 函数来描述环境的动力学。更多信息，请参阅环境创建教程。

创建环境

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