创建和注册

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

创建先前使用 gymnasium.register() 或 EnvSpec 注册的环境。

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

参数：

• **id** – 环境 ID 的字符串或 EnvSpec。如果使用字符串，可以选择包括要导入的模块，例如 'module:Env-v0'。这等效于先导入模块来注册环境，然后创建环境。

• **max_episode_steps** – 一集的最大长度，可以覆盖注册的 EnvSpec max_episode_steps，并将传递的值传递给 gymnasium.wrappers.TimeLimit。使用 max_episode_steps=-1 不会将包装器应用于环境。

• **disable_env_checker** – 是否添加 gymnasium.wrappers.PassiveEnvChecker，None 将默认为 EnvSpec disable_env_checker 值，否则将使用此值。

• **kwargs** – 要传递给环境构造函数的其他参数。

返回：

应用了包装器的环境实例。

引发：

**错误** – 如果 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) → gym.vector.VectorEnv

根据给定的 ID 创建向量环境。

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

参数：

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

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

• vectorization_mode – 使用的向量化方法，默认为 None，因此如果 env id 的规格具有 vector_entry_point（不为 None），则首先使用它，否则默认为 sync 以使用 gymnasium.vector.SyncVectorEnv。有效模式为 "async"、"sync" 或 "vector_entry_point"。建议使用 VectorizeMode 枚举而不是字符串。

• vector_kwargs – 传递给向量化器环境构造函数的额外参数，即 SyncVectorEnv(..., **vector_kwargs)。

• wrappers – 一系列要应用于基本环境的包装器函数。只能在 "sync" 或 "async" 模式下使用。

• **kwargs – 传递给基本环境构造函数的额外参数。

返回：

环境实例。

引发：

错误 – 如果 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)

在 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 – 截断前允许的最大情节步数。如果未设为 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

从 registry 中检索环境 ID 的 EnvSpec。

参数：

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

返回：

如果存在，则为环境规范。

引发：

错误 – 如果环境 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

漂亮打印 registry 中的所有环境。

注意

所有参数都是关键字参数。

参数：

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

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

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

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

核心变量

class gymnasium.envs.registration.EnvSpec(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, kwargs: dict = <factory>, additional_wrappers: tuple[WrapperSpec, ...] = <factory>, vector_entry_point: VectorEnvCreator | str | None = None)

使用 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() 函数之前强制执行 gymnasium.Env.reset()。

• 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)

记录包装器配置的规范。

• 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

给定名称（可选）版本和命名空间，获取完整的环境 ID。 parse_env_id() 的反函数。

参数：

• ns – 环境命名空间

• name – 环境名称

• version – 环境版本

返回：

环境 ID

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

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

参数：

env_id – 要解析的环境 ID

返回：

环境命名空间、环境名称和版本号的元组

引发：

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

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

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

参数：

• ns – 环境命名空间

• name – 环境名称（ID）

返回：

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

gymnasium.envs.registration.namespace(ns: str)

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

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

加载具有 "(import path):(environment name)" 样式的名称的环境，并返回环境创建函数，通常是环境类类型。

参数：

name – 环境名称

返回：

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