创建和注册

Gymnasium 允许用户通过 gymnasium.make() 函数自动加载预先封装了多个重要封装器的环境。为此，环境必须事先使用 gymnasium.register() 进行注册。要获取已注册环境的规范，请使用 gymnasium.spec()；要打印整个注册表，请使用 gymnasium.pprint_registry()。

gymnasium.make(id: str | EnvSpec, max_episode_steps: int | None = None, disable_env_checker: bool | None = None, **kwargs: Any) → Env[source]

创建一个之前已通过 gymnasium.register() 或 `EnvSpec` 注册的环境。

要查找所有可用的环境，请使用 gymnasium.envs.registry.keys() 获取所有有效 ID。

参数：
返回：

一个应用了封装器的环境实例。

抛出：

Error – 如果 `id` 在 `registry` 中不存在。

更新日志

v1.0.0 - autoreset 和 apply_api_compatibility 已移除。

gymnasium.make_vec(id: str | EnvSpec, num_envs: int = 1, vectorization_mode: VectorizeMode | str | None = None, vector_kwargs: dict[str, Any] | None = None, wrappers: Sequence[Callable[[Env], Wrapper]] | None = None, **kwargs) → VectorEnv[source]

根据给定 ID 创建一个向量化环境。

要查找所有可用的环境，请使用 gymnasium.pprint_registry() 或 gymnasium.registry.keys() 获取所有有效 ID。我们将向量环境称为向量化器（vectorizor），而被向量化的环境称为基础环境或向量化环境（vectorizor(vectorized env)）。

参数：

  • id – 环境的名称。可选地，可以包含要导入的模块，例如 ‘module:Env-v0’

  • num_envs – 要创建的环境数量。

  • vectorization_mode – 所使用的向量化方法，默认为 None，这样如果环境 ID 的 `spec` 具有 vector_entry_point（非 None），则首先使用它，否则默认为 sync 以使用 gymnasium.vector.SyncVectorEnv。有效模式为 "async"、"sync" 或 "vector_entry_point"。建议使用 VectorizeMode 枚举而不是字符串。

  • vector_kwargs – 传递给向量化器环境构造函数的附加参数，例如 SyncVectorEnv(..., **vector_kwargs)。

  • wrappers – 应用于基础环境的封装器函数序列。只能在 "sync" 或 "async" 模式下使用。

  • **kwargs – 传递给基础环境构造函数的附加参数。

返回：

环境实例。

抛出：

Error – 如果 `id` 不存在，则抛出错误。

gymnasium.register(id: str, entry_point: EnvCreator | str | None = None, reward_threshold: float | None = None, nondeterministic: bool = False, max_episode_steps: int | None = None, order_enforce: bool = True, disable_env_checker: bool = False, additional_wrappers: tuple[WrapperSpec, ...] = (), vector_entry_point: VectorEnvCreator | str | None = None, kwargs: dict | None = None)[source]

在 Gymnasium 中注册一个环境，其 id 可与 gymnasium.make() 配合使用，其中 entry_point 是一个用于创建环境的字符串或可调用对象。

的 `id` 参数对应于环境的名称，语法如下：[namespace/](env_name)[-v(version)]，其中 namespace 和 -v(version) 是可选的。

它接受任意关键字参数，这些参数将传递给 `EnvSpec` 的 kwargs 参数。

参数：

  • id – 环境 ID

  • entry_point – 创建环境的入口点。

  • reward_threshold – 智能体被认为已学习环境的奖励阈值。

  • nondeterministic – 如果环境是非确定性的（即使知道初始种子和所有动作，也无法达到相同的状态）。

  • max_episode_steps – 截断前的最大 episode 步数。如果不是 None，则由 gymnasium.wrappers.TimeLimit 封装器使用。

  • order_enforce – 是否启用顺序强制封装器，以确保用户以正确的顺序运行函数。如果为 True，则 gymnasium.wrappers.OrderEnforcing 将应用于环境。

  • disable_env_checker – 是否对环境禁用 gymnasium.wrappers.PassiveEnvChecker。

  • additional_wrappers – 应用于环境的附加封装器。

  • vector_entry_point – 创建向量环境的入口点。

  • kwargs – 任意关键字参数，在初始化时传递给环境构造函数。

更新日志

v1.0.0 - autoreset 和 apply_api_compatibility 参数已移除。

gymnasium.spec(env_id: str) → EnvSpec[source]

从 registry 中检索环境 ID 的 `EnvSpec`。

参数：

env_id – 环境 ID，其预期格式为 [(namespace)/]id[-v(version)]。

返回：

环境规范（如果存在）

抛出：

Error – 如果环境 ID 不存在。

gymnasium.pprint_registry(print_registry: dict[str, EnvSpec] = registry, *, num_cols: int = 3, exclude_namespaces: list[str] | None = None, disable_print: bool = False) → str | None[source]

美观地打印 registry 中的所有环境。

注意

所有参数都只接受关键字参数。

参数：

  • print_registry – 要打印的环境注册表。默认为 `registry`。

  • num_cols – 排列环境的列数，用于显示。

  • exclude_namespaces – 要从打印中排除的命名空间列表。如果只需要 ALE 环境，这会很有用。

  • disable_print – 是返回所有命名空间和环境 ID 的字符串，还是将字符串打印到控制台。

核心变量

class gymnasium.envs.registration.EnvSpec(id: str, entry_point: ~gymnasium.envs.registration.EnvCreator | str | None = None, reward_threshold: float | None = None, nondeterministic: bool = False, max_episode_steps: int | None = None, order_enforce: bool = True, disable_env_checker: bool = False, kwargs: dict = <factory>, additional_wrappers: tuple[~gymnasium.envs.registration.WrapperSpec, ...] = <factory>, vector_entry_point: ~gymnasium.envs.registration.VectorEnvCreator | str | None = None)[source]

使用 gymnasium.make() 创建环境的规范。

  • id：用于通过 gymnasium.make() 创建环境的字符串。

  • entry_point：环境位置的字符串，格式为 (import path):(environment name)，或一个创建环境的函数。

  • reward_threshold：完成环境的奖励阈值。

  • nondeterministic：如果环境的观测无法在相同的初始状态、随机数生成器状态和动作下重复。

  • max_episode_steps：环境在截断前可以采取的最大步数。

  • order_enforce：是否强制执行 gymnasium.Env.reset() 在 gymnasium.Env.step() 和 gymnasium.Env.render() 函数之前运行的顺序。

  • disable_env_checker：是否在 gymnasium.make() 中禁用环境检查器封装器，默认为 False（运行环境检查器）。

  • kwargs：在初始化期间传递给环境的附加关键字参数。

  • additional_wrappers：应用于环境的附加封装器（WrapperSpec）元组。

  • vector_entry_point：要创建向量化环境的位置。

更新日志

v1.0.0 - Autoreset 属性已移除。

class gymnasium.envs.registration.WrapperSpec(name: str, entry_point: str, kwargs: dict[str, Any] | None)[source]

用于记录封装器配置的规范。

  • name：封装器的名称。

  • entry_point：创建封装器的位置。

  • kwargs：传递给封装器的附加关键字参数。如果封装器不继承自 `EzPickle`，则此值为 None。

gymnasium.envs.registration.registry

Gymnasium 的全局注册表，`gymnasium.register()` 在此存储环境规范，并且 `gymnasium.make()` 用于从此注册表创建环境。

gymnasium.envs.registration.current_namespace

创建或注册环境时的当前命名空间。默认情况下为 None，但通过 namespace() 可以修改此值以自动设置环境 ID 命名空间。

附加函数

gymnasium.envs.registration.get_env_id(ns: str | None, name: str, version: int | None) → str[source]

给定名称和（可选）版本及命名空间，获取完整的环境 ID。它是 parse_env_id() 的逆操作。

参数：

  • ns – 环境命名空间

  • name – 环境名称

  • version – 环境版本

返回：

环境 ID

gymnasium.envs.registration.parse_env_id(env_id: str) → tuple[str | None, str, int | None][source]

解析环境 ID 字符串格式 - [namespace/](env-name)[-v(version)]，其中命名空间和版本是可选的。

参数：

env_id – 要解析的环境 ID

返回：

一个包含环境命名空间、环境名称和版本号的元组。

抛出：

Error – 如果环境 ID 不是有效的环境正则表达式。

gymnasium.envs.registration.find_highest_version(ns: str | None, name: str) → int | None[source]

在注册表中，根据给定的命名空间和名称，查找环境的最高注册版本。

参数：

  • ns – 环境命名空间

  • name – 环境名称 (id)

返回：

具有匹配命名空间和名称的环境的最高版本，否则 ``None`` 将返回。

gymnasium.envs.registration.namespace(ns: str)[source]

用于修改当前命名空间的上下文管理器。

gymnasium.envs.registration.load_env_creator(name: str) → EnvCreator | VectorEnvCreator[source]

加载一个名称风格为 "(import path):(environment name)" 的环境，并返回环境创建函数，通常是环境类类型。

参数：

name – 环境名称

返回：

给定环境名称的环境构造函数。