Gymnasium项目迁移指南：从v0.21到v1.0.0的API变更解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00803/article/details/148418854

Gymnasium项目迁移指南：从v0.21到v1.0.0的API变更解析

Gymnasium An API standard for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym) 项目地址: https://gitcode.com/gh_mirrors/gy/Gymnasium

前言

Gymnasium作为强化学习领域的重要工具库，其API在v0.26版本进行了重大调整。本文将从技术实现角度，详细解析从v0.21到v1.0.0版本的核心变更，帮助开发者顺利完成迁移工作。

基础API变更对比

v0.21版本典型代码结构

import gym
env = gym.make("LunarLander-v3", options={})
env.seed(123)  # 设置随机种子
observation = env.reset()  # 重置环境

done = False
while not done:
    action = env.action_space.sample()
    # 返回四元组：观察值、奖励、结束标志、信息字典
    observation, reward, done, info = env.step(action)
    env.render(mode="human")  # 实时渲染

env.close()

v1.0.0版本典型代码结构

import gym
env = gym.make("LunarLander-v3", render_mode="human")  # 渲染模式在初始化时指定
observation, info = env.reset(seed=123, options={})  # 重置时设置种子

done = False
while not done:
    action = env.action_space.sample()
    # 返回五元组：新增终止状态标志
    observation, reward, terminated, truncated, info = env.step(action)
    done = terminated or truncated  # 需要手动组合两种结束状态

env.close()

核心变更详解

1. 随机数生成机制重构

技术背景： v0.21使用自定义RNG系统，而v1.0.0改用NumPy的Generator接口，这符合科学计算领域的标准实践。

变更细节：

移除env.seed()方法
种子设置改为通过reset(seed=seed)实现
内部使用np_random属性管理随机状态

迁移建议：

# 旧版
env.seed(42)

# 新版
env.reset(seed=42)
# 如需直接访问RNG
random_num = env.np_random.integers(0, 10)

2. 环境重置接口增强

技术改进：

新增options参数：支持传递环境配置
返回info字典：提供重置时的附加信息

典型应用场景：

# 设置初始状态范围
observation, info = env.reset(
    seed=42,
    options={"x_range": [-0.1, 0.1]}
)

3. 步进(step)返回结构优化

问题背景：原done标志无法区分"真正终止"和"人为截断"两种场景，影响算法训练。

新设计：

terminated：符合MDP的终止状态
truncated：非MDP因素导致的截断

示例说明：

# 迷宫环境到达终点
terminated=True, truncated=False

# 步数超过限制但未达终点
terminated=False, truncated=True

4. 时间限制包装器变更

行为变化：

移除info['TimeLimit.truncated']
通过truncated返回值体现

等效关系：

# 旧版判断逻辑
timeout = info.get('TimeLimit.truncated', False)

# 新版判断逻辑
timeout = truncated and not terminated

5. 渲染系统改进

架构调整：

渲染模式改为初始化时指定
移除实时模式切换能力

使用示例：

# 初始化时确定渲染方式
env = gym.make("CartPole-v1", 
    render_mode="human"  # 或"rgb_array"
)

# 移除旧版render()参数
frames = env.render()  # 不再需要mode参数

已移除组件说明

GoalEnv接口：由Gymnasium Robotics项目专门维护
经典控制渲染器：推荐使用Pygame实现自定义渲染
机器人环境：迁移至独立子项目
Monitor包装器：拆分为：
- RecordVideo：视频录制
- RecordEpisodeStatistics：数据统计

迁移实践建议

逐步替换策略：
- 首先更新reset和seed相关代码
- 然后处理step返回值的解构
- 最后调整渲染逻辑
测试要点：
- 随机种子的一致性
- 终止条件的正确处理
- 渲染输出的兼容性
常见问题排查：
- 若见到done未定义错误，检查是否替换为terminated
- 渲染报错时确认是否在make时指定了render_mode