Gymnasium VectorEnv 完全指南：make_vec 批量并行环境、自动重置与向量化包装器实战解析

Gymnasium VectorEnv 完全指南make_vec 批量并行环境、自动重置与向量化包装器实战解析【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/GymnasiumGymnasium 的向量化环境Vector Environment是单智能体强化学习训练流水线的核心基础设施它把多个独立副本环境打包成一批batch在一次step调用中并行推进所有子环境从而获得接近线性的每秒步数加速。本文以官方 API 文档 docs/api/vector.md 为骨架结合 gymnasium/vector/vector_env.py、gymnasium/vector/sync_vector_env.py 与 gymnasium/envs/registration.py 等源码系统讲解VectorEnv的接口设计、gymnasium.make_vec的创建流程、三种向量化模式、自动重置Autoreset机制、同步/异步实现差异以及向量化包装器的使用读完即可在训练循环中正确、高效地使用向量环境。VectorEnv向量化环境的统一抽象gymnasium.vector.VectorEnv是所有向量化环境的抽象基类其设计目标是同时运行同一个环境的多个独立副本并在reset与step中批量打包observations、rewards、terminations、truncations与info。类定义位于 gymnasium/vector/vector_env.py并通过 gymnasium/vector/init.py 导出。Gymnasium 内置两种通用向量环境实现SyncVectorEnv —— 在单个进程中用 for 循环串行推进所有子环境AsyncVectorEnv —— 通过多进程并行推进子环境吞吐更高但引入进程通信开销。批量数据的打包规则理解VectorEnv的关键是理解它的批量化batching语义。官方文档与基类 docstring 明确指出rewards、terminations、truncations打包为形状(num_envs,)的 NumPy 数组observations与actions的打包方式取决于观察/动作空间的类型总体优化目标是适配神经网络输入输出例如 Box 空间直接堆叠成(num_envs, *shape)的数组Discrete 空间则生成MultiDiscrete形式的批空间info保持为字典结构每个 key 对应所有子环境在该维度上的数据同时自动附带一个以_为前缀的布尔掩码如_key标记第i个子环境是否提供了该 key 的信息。这种聚合逻辑实现在基类的_add_info方法中gymnasium/vector/vector_env.py标量类型的 info 值会被填充进np.zeros(num_envs, dtypetype(value))数组np.ndarray会被填充进(num_envs, *value.shape)数组字典类型的值会递归调用_add_info而其他未知对象则落入 NumPy object 数组。特别的final_obs键会被单独处理以便用户在未批处理的观测数组层面直接访问最终观测。核心属性一览基类为使用者暴露了如下关键属性官方文档逐一给出了语义定义属性含义num_envs向量环境中子环境的数量action_space批处理后的动作空间step的输入必须是该空间的合法元素observation_space批处理后的观察空间reset/step返回的观测是该空间的合法元素single_action_space单个子环境的动作空间single_observation_space单个子环境的观察空间spec环境的EnvSpec通常在gymnasium.make_vec时写入见 gymnasium/envs/registration.pymetadata环境元数据包含渲染模式、渲染 fps、以及autoreset_mode等render_mode环境的渲染模式语义与单个Env.render_mode一致closed向量环境是否已被关闭此外基类还提供了unwrapped返回底层未包装环境、np_random内部np.random.Generator未设置时自动以随机种子初始化与np_random_seed内部随机种子若直接给np_random赋值而未通过reset设置则为-1三个附加属性以及render()、close()、close_extras()等方法相关实现见 gymnasium/vector/vector_env.py。使用 make_vec 创建向量环境官方文档指出创建向量环境时Gymnasium 提供gymnasium.make_vec作为gymnasium.make的向量化等价函数。二者参数风格保持一致make_vec额外引入几个专门控制向量化的参数。其签名定义于 gymnasium/envs/registration.pydef 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: Any, ) - gymnasium.vector.VectorEnv参数详解参数类型默认值说明idstr/EnvSpec必填环境 ID如CartPole-v1或直接传入EnvSpec对象也支持module:Env-v0形式的模块导入写法num_envsint1要创建的并行运行的子环境数量vectorization_modeVectorizeMode/str/NoneNone向量化方式sync、async或vector_entry_point为None时若环境 spec 定义了vector_entry_point则优先使用它否则回退到sync。推荐使用枚举VectorizeMode而非字符串vector_kwargsdictNone传给向量化器构造函数的额外参数即SyncVectorEnv(..., **vector_kwargs)或AsyncVectorEnv(..., **vector_kwargs)wrappers包装器函数序列None依次应用于每个基环境的包装器函数仅在sync与async模式下可用**kwargs任意—传给基环境构造函数的额外参数例如g9.81、render_mode...三个向量化模式由VectorizeMode枚举定义gymnasium/envs/registration.pyASYNC async、SYNC sync、VECTOR_ENTRY_POINT vector_entry_point。当显式传入的字符串无法解析时会抛出ValueError并列出合法取值。最小可用示例官方文档与 vector_env.py 的 docstring 给出了完整可运行示例import gymnasium as gym envs gym.make_vec(CartPole-v1, num_envs3, vectorization_modesync, wrappers(gym.wrappers.TimeAwareObservation,)) envs gym.wrappers.vector.ClipReward(envs, min_reward0.2, max_reward0.8) print(envs) # ClipReward, SyncVectorEnv(CartPole-v1, num_envs3) print(envs.num_envs) # 3 print(envs.action_space) # MultiDiscrete([2 2 2]) observations, infos envs.reset(seed123) # observations: shape (3, 5) 的 float64 数组3 个子环境 × 5 维观测含 TimeAware 时间步维度 # infos: {} _ envs.action_space.seed(123) actions envs.action_space.sample() observations, rewards, terminations, truncations, infos envs.step(actions) # rewards: array([0.8, 0.8, 0.8]) 被 ClipReward 裁剪 # terminations: array([False, False, False]) # truncations: array([False, False, False]) envs.close()注意几点实战细节wrappers参数作用于每个子环境make_vec内部在create_single_env中先make再逐层套包装器见 gymnasium/envs/registration.py而作用于整个向量环境的包装器如gym.wrappers.vector.ClipReward则需要手动包在make_vec的返回值上。envs.action_space是批空间Discrete 批化为MultiDiscrete因此采样出的actions天然具有(num_envs,)形状可直接喂给step。make_vec内部会将num_envs、vectorization_mode、vector_kwargs、wrappers等写入env.unwrapped.specgymnasium/envs/registration.py保证向量环境可以被完整重建与gym.make写入 spec 的逻辑对称。seed 与 options 的批量语义VectorEnv.reset(seed..., options...)支持三种 seed 形式gymnasium/vector/sync_vector_env.pyseedNone每个子环境使用随机种子seedint按[seed, seed1, ..., seedn-1]分配给n个子环境seedlist[int]长度必须等于num_envs逐项对应。options中还有一个向量化特有的键reset_mask传入形状为(num_envs,)的np.bool_数组时只重置掩码为True的子环境其余子环境保持原状态继续——这在需要选择性重置如 episode 中途部分环境结束的场景非常有用。同样地step返回的terminations/truncations是形状(num_envs,)的布尔数组。自动重置Autoreset模式训练算法不应为了等待某个子环境 episode 结束而阻塞整个批次。为此向量环境可以在子环境terminated or truncated时自动重置它同时把该步的奖励、终止与截断信息返回给调用方下一步才真正执行新 episode 的观测。这是向量环境正确实现训练算法的关键机制。Gymnasium 通过AutoresetMode枚举gymnasium/vector/vector_env.py提供三种模式模式值语义NEXT_STEPNextStep默认模式。子环境在terminated or truncated后的下一次step才被重置该步返回 0 奖励、False终止/截断标志并携带final_obs/final_infoSAME_STEPSameStep子环境在 episode 结束的同一步内完成重置并把结束帧的观测作为final_obs放入 infoDISABLEDDisabled完全关闭自动重置假设用户/算法自行处理重置同步实现中的分支逻辑清晰可见gymnasium/vector/sync_vector_env.py。在NEXT_STEP模式下step结束时用self._autoreset_envs np.logical_or(self._terminations, self._truncations)记录哪些子环境将在下一步被重置SAME_STEP模式下则在同一step内将final_obs与final_info写入 info 后立即reset。使用注意事项文档亦给出警告向量环境使用的模式应能在metadata[autoreset_mode]中查到make_vec与VectorObservationWrapper都会检查该键缺失时发出警告见 gymnasium/envs/registration.py并非所有向量实现与训练算法都支持全部模式例如VectorObservationWrapper只接受NEXT_STEP或DISABLED传入其他模式会抛出ValueErrorgymnasium/vector/vector_env.py官方对三种模式的完整行为描述可参考 Farama 基金会发布的 Vector-Autoreset-Mode 规范文档。同步与异步向量环境SyncVectorEnv串行 for 循环SyncVectorEnv 在单个进程内以 for 循环串行推进每个子环境。构造参数为SyncVectorEnv( env_fns: Sequence[Callable[[], Env]], copy: bool True, observation_mode: str | tuple[Space, Space] same, autoreset_mode: str | AutoresetMode AutoresetMode.NEXT_STEP, )env_fns可调用对象序列逐个调用即创建子环境。支持传入参数不同的工厂函数例如官方 docstring 中的例子[lambda: gym.make(Pendulum-v1, g9.81), lambda: gym.make(Pendulum-v1, g1.62)]——这正是make_vec之外手动构造向量环境的常见方式此时spec为Nonerepr显示为SyncVectorEnv(num_envs2)。copyTruereset/step返回观测的深拷贝防止调用方修改数组破坏内部缓冲追求极致性能可设False但需自担别名风险。observation_mode控制观察空间的批化方式。same要求所有子环境观察空间完全相等different允许形状/长度相同但高低界不同的空间批化内部使用batch_differing_spaces也可以直接传入(single_observation_space, observation_space)二元组自定义批空间。构造时会对所有子环境做一致性校验same模式下观测空间不等价、different模式下形状/dtype不一致、动作空间不匹配都会抛出RuntimeErrorgymnasium/vector/sync_vector_env.py。除reset/step/close外SyncVectorEnv还实现了批量环境管理方法call(name, *args, **kwargs)对每个子环境调用名为name的方法或直接取属性返回结果元组get_attr(name)等价于call(name)批量读取属性set_attr(name, values)批量设置属性values可以是标量应用到所有子环境或长度等于num_envs的列表/元组长度不符会抛ValueError。AsyncVectorEnv多进程并行AsyncVectorEnv 将每个子环境放入独立进程通过管道pipe通信step一次性把动作发往所有工作进程再统一收集结果从而在环境计算密集时获得并行加速。其构造参数在SyncVectorEnv基础上增加了shared_memoryTrue使用共享内存传递观测避免大数组的序列化拷贝与max_processes等选项。选择async的典型代价是进程创建与 IPC 的开销因此在环境本身计算量很小时sync反而可能更快。如何选择 vectorization_modemake_vec的vectorization_modeNone时采用如下决策链gymnasium/envs/registration.py若该环境 ID 在注册表中声明了vector_entry_point自定义向量化入口例如部分第三方环境优先使用它否则回退到sync。显式指定vector_entry_point模式时vector_kwargs、wrappers与 spec 中的additional_wrappers均必须为空否则报错gymnasium/envs/registration.py。向量化包装器体系与单环境Env一样向量环境同样拥有完整的包装器体系基类为VectorWrappergymnasium/vector/vector_env.py构造时要求传入VectorEnv实例否则抛TypeError并代理reset/step/render/close与全部核心属性。三个功能子类与单环境包装器一一对应VectorObservationWrapper批量变换观测需实现observations(observations)对应单环境的ObservationWrapper其__init__会检查metadata[autoreset_mode]合法性VectorActionWrapper批量变换动作需实现actions(actions)对应ActionWrapperVectorRewardWrapper批量变换奖励需实现rewards(rewards)对应RewardWrapper。在 docs/api/vector/wrappers.md 中官方将向量化包装器划分为若干类别向量环境专属Vector OnlyDictInfoToList把 info 字典拆回 v0.25 之前每子环境一个 dict的旧风格、VectorizeTransformObservation、VectorizeTransformAction、VectorizeTransformReward向量化通用包装器RecordEpisodeStatistics观测类TransformObservation、FilterObservation、FlattenObservation、GrayscaleObservation、ResizeObservation、ReshapeObservation、RescaleObservation、DtypeObservation、NormalizeObservation动作类TransformAction、ClipAction、RescaleAction奖励类TransformReward、ClipReward、NormalizeReward数据转换类ArrayConversion、JaxToNumpy、JaxToTorch、NumpyToTorch。这些包装器的实际实现位于 gymnasium/wrappers/vector/ 目录覆盖 JAX、PyTorch 与 NumPy 数组的互转以及观测归一化、动作裁剪等强化学习训练中几乎必备的预处理环节用法与单环境对应包装器一致只是作用对象从单个样本变为整批样本。向量化工具函数与共享内存docs/api/vector/utils.md 汇总了 gymnasium/vector/utils/ 下的辅助工具空间批化batch_space将单个空间扩展为n个的批空间Discrete → MultiDiscrete、Box → 形状加一维的 Box 等、concatenate把观测列表拼接成批数组、iterate把批空间/批数组拆回逐子环境迭代器、create_empty_array按空间语义创建空批数组共享内存create_shared_memory、read_from_shared_memory、write_to_shared_memory供AsyncVectorEnv的shared_memoryTrue模式在进程间传递观测杂项CloudpickleWrapper用 cloudpickle 序列化环境工厂函数以便跨进程传递与clear_mpi_env_vars清除可能干扰多进程的 MPI 环境变量。与旧版 gym 的信息格式差异官方文档特别提示了一处兼容性细节reset/step的info参数在 v0.25 之前是每子环境一个字典的列表v0.25 之后改为字典 每 key 一个 NumPy 数组并附_前缀布尔掩码。若你的训练代码仍依赖旧式列表格式可通过DictInfoToList包装器做转换而无需改动上游环境。总结向量化环境把多环境并行采样从训练脚本的样板代码中解放出来gymnasium.make_vec以接近gymnasium.make的用法一键创建SyncVectorEnv/AsyncVectorEnvVectorEnv基类提供统一的空间批化、info 聚合与自动重置语义AutoresetMode三种模式适配不同训练算法向量化包装器与工具函数则覆盖了观测/动作/奖励变换、框架互转与共享内存传输等全部配套需求。从 docs/api/vector.md 出发结合 gymnasium/vector/ 与 gymnasium/wrappers/vector/ 源码你可以完整掌握向量环境从创建、使用到扩展的每一个环节直接支撑 PPO、DQN、A2C 等算法的批量采样训练循环。【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考