遷移指南 - v0.21 至 v1.0.0¶

Gymnasium 是 OpenAI Gym v0.26 的分支，它從 Gym v0.21 引入了重大的破壞性變更。在本指南中，我們簡要概述了從 Gym v0.21（許多教學課程都是針對此版本編寫的）到 Gym v0.26（以及後續版本，包括 1.0.0）的 API 變更。對於仍停留在 v0.21 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()  # agent policy that uses the observation and info
    observation, reward, done, info = env.step(action)

    env.render(mode="human")

env.close()

v0.26 及更高版本（包括 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()  # agent policy that uses the observation and info
    observation, reward, terminated, truncated, info = env.step(action)

    done = terminated or truncated

env.close()

種子和隨機數生成器¶

Gym v0.26 環境中已移除 Env.seed()，改用 Env.reset(seed=seed)。這樣可以確保僅在環境重置時才變更種子。移除 seed 的原因是某些環境使用的模擬器無法在單個 episode 內變更隨機數生成器，而必須在新 episode 開始時進行。我們知道在某些情況下，控制隨機數生成器非常重要，在這些情況下，如果環境使用內建的隨機數生成器，使用者可以使用 np_random 屬性手動設定種子。

Gymnasium v0.26 已變更為使用 numpy.random.Generator 而不是自訂隨機數生成器。這表示已移除多個函數（例如 randint），改用 integers。雖然某些環境可能使用外部隨機數生成器，但我們建議使用封裝器和外部使用者可以存取和利用的 np_random 屬性。

環境重置¶

在 v0.26+ 中，reset() 接受兩個可選參數並返回一個值。這與 v0.21 形成對比，v0.21 不接受任何參數並返回 None。這兩個參數分別是用於設定隨機數生成器的 seed 和允許在重置時將其他資料傳遞到環境的 options。例如，在經典控制中，options 參數現在允許使用者修改狀態邊界的範圍。有關更多詳細資訊，請參閱原始 PR。

reset() 進一步返回 info，類似於 step() 返回的 info。這很重要，因為 info 可以包含在下一步中使用或儲存的指標或有效動作遮罩。

為了更新較舊的環境，我們強烈建議在 reset() 的第一行呼叫 super().reset(seed=seed)。這將自動使用種子值更新 np_random。

環境步進¶

在 v0.21 中，step() 的類型定義是 tuple[ObsType, SupportsFloat, bool, dict[str, Any]，表示下一個觀察值、步進的獎勵、episode 是否完成以及來自步進的其他資訊。由於重現性問題（將在稍後的部落格文章中詳細說明），我們已將類型定義變更為 tuple[ObsType, SupportsFloat, bool, bool, dict[str, Any]]，新增了一個額外的布林值。這個額外的布林值對應於較舊的 done，現在變更為 terminated 和 truncated。這些變更已在 Gym v0.26 中引入（在 v25 中預設關閉）。

對於希望更新的使用者，在大多數情況下，在 step() 中將 done 替換為 terminated 並將 truncated=False 應可解決大多數問題。但是，對於 episode 截斷而非終止有原因的環境，應仔細閱讀相關的 PR。對於循環遍歷環境的使用者，他們應修改 done = terminated or truncated，如範例程式碼所示。對於訓練庫，主要差異是將 done 變更為 terminated，以指示是否應進行引導。

TimeLimit 封裝器¶

在 v0.21 中，當代理在未達到終端狀態的情況下達到時間限制時，TimeLimit 封裝器會在 info 字典中新增一個額外的鍵 TimeLimit.truncated。

在 v0.26+ 中，此資訊改為透過上一節中描述的 truncated 返回值傳達，如果代理達到時間限制（無論是否達到終端狀態），則該值為 True。舊的字典條目等效於 truncated and not terminated

環境渲染¶

在 v0.26 中，引入了一個新的渲染 API，以便在初始化時固定渲染模式，因為某些環境不允許即時變更渲染模式。因此，使用者現在應在 gym.make 中指定 render_mode，如上方的 v0.26+ 範例程式碼所示。

如需更完整的變更說明，請參閱此摘要。

已移除的程式碼¶

GoalEnv - 這已移除，需要它的使用者應重新實作環境或使用包含此環境實作的 Gymnasium Robotics。
from gym.envs.classic_control import rendering - 這已移除，改為鼓勵使用者實作自己的渲染系統。Gymnasium 環境是使用 pygame 編碼的。
Robotics 環境 - Robotics 環境已移至 Gymnasium Robotics 專案。
Monitor 封裝器 - 此封裝器已替換為兩個獨立的封裝器：RecordVideo 和 RecordEpisodeStatistics