Gymnasium环境迁移指南：从旧版Step API到新版

概述

在使用Gymnasium库创建自定义强化学习环境时，开发者可能会遇到ValueError: not enough values to unpack (expected 5, got 4)的错误。这通常是由于使用了旧版Step API导致的兼容性问题。本文将详细介绍如何正确迁移自定义环境到新版API。

问题背景

在Gymnasium的早期版本中，step()方法返回的元组包含4个元素：

1. 观察值(observation)
2. 奖励(reward)
3. 终止标志(done)
4. 信息(info)

而在新版API中，step()方法需要返回5个元素：

1. 观察值(observation)
2. 奖励(reward)
3. 终止标志(terminated)
4. 截断标志(truncated)
5. 信息(info)

迁移解决方案

1. 修改step方法

原代码中的step方法：

def step(self, action):
    # ...原有代码...
    return observation, reward, done, info

需要修改为：

def step(self, action):
    # ...原有代码...
    return observation, reward, terminated, truncated, info

2. 区分终止和截断

在新API中，环境终止分为两种情况：

• terminated: 表示环境自然终止(如游戏结束)
• truncated: 表示人为截断(如达到最大步数)

对于简单环境，可以这样处理：

terminated = done  # 保持原有done逻辑
truncated = False  # 默认不截断

3. 完整示例

修改后的WebGame类step方法应如下：

def step(self, action):
    action_map = {
        0:'w',
        1: 's', 
        2: 'no_op',
        3:'a',
        4:'d',
        5:'q'
    }
    pydirectinput.click(x=930, y=950)

    if action !=2:
        pydirectinput.press(action_map[action])
    
    done, done_cap = self.get_done()
    observation = self.get_observation()
    reward = 1 
    info = {}
    
    # 新版API返回
    terminated = done  # 环境自然终止
    truncated = False  # 无截断情况
    return observation, reward, terminated, truncated, info

4. 修改reset方法

reset方法也需要相应调整，返回元组中需要包含info字典：

def reset(self, **kwargs):
    pydirectinput.click(x=1600, y=950)
    time.sleep(1)
    pydirectinput.click(x=1225, y=950)
    time.sleep(15)
    return self.get_observation(), {}  # 返回观察值和空info字典

迁移注意事项

1. 兼容性检查：确保所有使用环境的地方都适应新的返回值结构
2. 测试验证：迁移后应进行充分测试，确保环境行为符合预期
3. 文档更新：更新环境文档，说明使用的是新版API

总结

Gymnasium新版API通过区分terminated和truncated提供了更精细的环境控制。虽然迁移需要一些修改，但这使得环境能够更准确地表达不同的终止情况。对于大多数简单环境，可以将原有done逻辑赋值给terminated，并将truncated设为False即可完成基本迁移。

理解这些概念差异有助于开发者创建更符合现代强化学习实践的环境，并为将来可能需要的更复杂场景做好准备。