Env

class gymnasium.Env

實作強化學習 Agents 環境的主要 Gymnasium 類別。

此類別透過 step() 和 reset() 函數封裝具有任意幕後動態的環境。環境可以被單一 agents 部分或完全觀察到。對於多 agents 環境，請參閱 PettingZoo。

此類別使用者需要知道的主要 API 方法是

• step() - 使用 actions 更新環境，返回下一個 agent 觀察結果、採取該 actions 的獎勵、環境是否由於最新的 action 而終止或截斷，以及來自環境關於步驟的資訊，即指標、除錯資訊。

• reset() - 將環境重設為初始狀態，在呼叫 step 之前是必要的。返回 episode 的第一個 agent 觀察結果和資訊，即指標、除錯資訊。

• render() - 渲染環境以幫助視覺化 agent 所看到的內容，範例模式為 “human”、“rgb_array”、“ansi” 用於文字。

• close() - 關閉環境，當使用外部軟體時非常重要，例如 pygame 用於渲染、資料庫

環境具有額外的屬性供使用者理解實作

• action_space - 對應於有效 actions 的 Space 物件，所有有效 actions 應包含在 space 內。

• observation_space - 對應於有效觀察結果的 Space 物件，所有有效觀察結果應包含在 space 內。

• spec - 環境 spec，包含用於從 gymnasium.make() 初始化環境的資訊

• metadata - 環境的 metadata，例如 {“render_modes”: [“rgb_array”, “human”], “render_fps”: 30}。對於 Jax 或 Torch，可以使用 “jax”=True 或 “torch”=True 向使用者指示。

• np_random - 環境的隨機數字產生器。這會在 super().reset(seed=seed) 期間以及評估 np_random 時自動分配。

另請參閱

對於修改或擴展環境，請使用 gymnasium.Wrapper 類別

注意

為了獲得 actions 的可重現取樣，可以使用 env.action_space.seed(123) 設定 seed。

注意

對於嚴格的類型檢查（例如 mypy 或 pyright），Env 是一個具有兩個參數化類型的泛型類別：ObsType 和 ActType。ObsType 和 ActType 是 reset() 和 step() 中使用的觀察結果和 actions 的預期類型。環境的 observation_space 和 action_space 應具有類型 Space[ObsType] 和 Space[ActType]，請參閱 space 的實作以查找其參數化類型。

方法

Env.step(action: ActType) → tuple[ObsType, SupportsFloat, bool, bool, dict[str, Any]]

使用 agent actions 執行環境動態的一個時間步。

當達到 episode 結束時（terminated 或 truncated），必須呼叫 reset() 以為下一個 episode 重設此環境的狀態。

版本 0.26 變更：Step API 已變更，移除 done，改用 terminated 和 truncated，以便更清楚地向使用者說明環境何時終止或截斷，這對於強化學習引導演算法至關重要。

參數:

action (ActType) – 由 agent 提供的 action，用於更新環境狀態。

返回:

• observation (ObsType) – 環境的 observation_space 的一個元素，作為由於 agent actions 導致的下一個觀察結果。一個範例是包含 CartPole 中桿子位置和速度的 numpy 陣列。

• reward (SupportsFloat) – 採取 action 的結果獎勵。

• terminated (bool) – agent 是否達到終端狀態（根據任務的 MDP 定義），這可能是正面的或負面的。一個範例是達到目標狀態或從 Sutton 和 Barto Gridworld 進入熔岩。如果為 true，則使用者需要呼叫 reset()。

• truncated (bool) – 是否滿足 MDP 範圍之外的截斷條件。通常，這是時間限制，但也可用於指示 agent 物理上超出邊界。可用於在達到終端狀態之前提前結束 episode。如果為 true，則使用者需要呼叫 reset()。

• info (dict) – 包含輔助診斷資訊（有助於除錯、學習和記錄）。例如，這可能包含：描述 agent 效能狀態的指標、從觀察中隱藏的變數，或組合以產生總獎勵的個別獎勵項。在 OpenAI Gym <v26 中，它包含 “TimeLimit.truncated” 以區分截斷和終止，但這在返回 terminated 和 truncated 變數的情況下已被棄用。

• done (bool) – （已棄用）一個布林值，用於表示 episode 是否已結束，在這種情況下，進一步的 step() 呼叫將返回未定義的結果。這已在 OpenAI Gym v26 中移除，改用 terminated 和 truncated 屬性。done 訊號可能會因不同原因而發出：可能是環境的基礎任務已成功解決、超過了特定時間限制，或者物理模擬已進入無效狀態。

Env.reset(*, seed: int | None = None, options: dict[str, Any] | None = None) → tuple[ObsType, dict[str, Any]]

將環境重設為初始內部狀態，返回初始觀察結果和資訊。

此方法產生一個新的起始狀態，通常帶有一些隨機性，以確保 agent 探索狀態空間並學習關於環境的通用策略。這種隨機性可以使用 seed 參數控制，否則，如果環境已經有一個隨機數字產生器，並且呼叫 reset() 時 seed=None，則 RNG 不會重設。

因此，reset() 應該（在典型用例中）在初始化後立即使用 seed 呼叫，然後永遠不再呼叫。

對於自訂環境，reset() 的第一行應該是 super().reset(seed=seed)，它正確地實作了 seeding。

版本 v0.25 變更：return_info 參數已移除，現在預期返回 info。

參數:

• seed (optional int) – 用於初始化環境的 PRNG（np_random）和唯讀屬性 np_random_seed 的 seed。如果環境尚未具有 PRNG 且傳遞了 seed=None（預設選項），則將從某個熵源（例如時間戳記或 /dev/urandom）中選擇一個 seed。但是，如果環境已經具有 PRNG 且傳遞了 seed=None，則 PRNG 將不會重設，並且 env 的 np_random_seed 將不會被更改。如果您傳遞一個整數，即使 PRNG 已經存在，也會重設 PRNG。通常，您希望在環境初始化後立即傳遞一個整數，然後永遠不再傳遞。請參閱上面的最小範例，以了解此範例的實際應用。

• options (optional dict) – 指定如何重設環境的其他資訊（可選，取決於特定環境）

返回:

• observation (ObsType) – 初始狀態的觀察結果。這將是 observation_space 的一個元素（通常是 numpy 陣列），並且類似於 step() 返回的觀察結果。

• info (dictionary) – 此字典包含補充 observation 的輔助資訊。它應該類似於 step() 返回的 info。

Env.render() → RenderFrame | list[RenderFrame] | None

計算在環境初始化期間由 render_mode 指定的渲染幀。

環境的 metadata 渲染模式（env.metadata[“render_modes”]）應包含實作渲染模式的可能方式。此外，大多數渲染模式的列表版本是透過 gymnasium.make 實現的，它會自動應用 wrapper 來收集渲染幀。

注意

由於 render_mode 在 __init__ 期間已知，因此用於渲染環境狀態的物件應在 __init__ 中初始化。

依照慣例，如果 render_mode 是

• None（預設）：不計算渲染。

• “human”：環境在目前的顯示器或終端機中持續渲染，通常供人使用。此渲染應在 step() 期間發生，並且不需要呼叫 render()。返回 None。

• “rgb_array”：返回表示環境目前狀態的單一幀。幀是一個 np.ndarray，形狀為 (x, y, 3)，表示 x 乘 y 像素圖像的 RGB 值。

• “ansi”：返回字串 (str) 或 StringIO.StringIO，其中包含每個時間步的終端機樣式文字表示形式。文字可以包含換行符和 ANSI 跳脫序列（例如，用於顏色）。

• “rgb_array_list” 和 “ansi_list”：列表型版本的渲染模式是可能的（除了 Human），透過 wrapper，gymnasium.wrappers.RenderCollection，它在 gymnasium.make(..., render_mode="rgb_array_list") 期間自動應用。收集的幀在呼叫 render() 或 reset() 後彈出。

注意

請確保您的類別的 metadata "render_modes" 鍵包含支援模式的列表。

版本 0.25.0 變更：render 函數已變更為不再接受參數，而是這些參數應在環境初始化中指定，即 gymnasium.make("CartPole-v1", render_mode="human")

Env.close()

在使用者完成使用環境後，close 包含清理環境所需的程式碼。

這對於關閉渲染視窗、資料庫或 HTTP 連線至關重要。在已關閉的環境上呼叫 close 沒有任何效果，也不會引發錯誤。

屬性

Env.action_space: spaces.Space[ActType]

對應於有效 actions 的 Space 物件，所有有效 actions 應包含在 space 內。例如，如果 action space 的類型為 Discrete 並給出值 Discrete(2)，則表示有兩個有效的離散 actions：0 & 1。

>>> env.action_space
Discrete(2)
>>> env.observation_space
Box(-inf, inf, (4,), float32)

Env.observation_space: spaces.Space[ObsType]

對應於有效觀察結果的 Space 物件，所有有效觀察結果應包含在 space 內。例如，如果觀察 space 的類型為 Box 且物件的形狀為 (4,)，則表示有效的觀察結果將是一個包含 4 個數字的陣列。我們也可以使用屬性檢查 box 邊界。

>>> env.observation_space.high
array([4.8000002e+00, inf, 4.1887903e-01, inf], dtype=float32)
>>> env.observation_space.low
array([-4.8000002e+00, -inf, -4.1887903e-01, -inf], dtype=float32)

Env.metadata: dict[str, Any] = {'render_modes': []}

環境的 metadata，包含渲染模式、渲染 fps 等

Env.render_mode: str | None = None

在初始化時確定的環境的渲染模式

Env.spec: EnvSpec | None = None

環境的 EnvSpec，通常在 gymnasium.make() 期間設定

property Env.unwrapped: Env[ObsType, ActType]

返回基礎未封裝的環境。

返回:

Env – 基礎未封裝的 gymnasium.Env 實例

property Env.np_random: Generator

返回環境的內部 _np_random，如果未設定，將使用隨機 seed 初始化。

返回:

`np.random.Generator` 的實例

屬性 Env.np_random_seed: int

返回環境內部的 _np_random_seed，如果未設定，則會先使用隨機整數作為種子進行初始化。

如果 np_random_seed 是直接設定，而不是通過 reset() 或 set_np_random_through_seed() 設定，則種子將取值 -1。

返回:

int – 當前 np_random 的種子，如果 rng 的種子未知，則為 -1

實作環境

在實作環境時，必須建立 Env.reset() 和 Env.step() 函數來描述環境的動態。 更多資訊，請參閱環境建立教學。

建立環境

要建立環境，gymnasium 提供了 make() 來初始化環境以及幾個重要的包裝器。 此外，gymnasium 提供了 make_vec() 用於建立向量環境，要查看所有可以建立的環境，請使用 pprint_registry()。