Env

class gymnasium.Env

用於實作強化學習智能體環境的主要 Gymnasium 類別。

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

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

• step() - 使用動作更新環境，傳回下一個智能體觀察值、採取該動作的獎勵、環境是否由於最新動作而終止或截斷，以及來自環境的關於步驟的資訊，例如指標、除錯資訊。

• reset() - 將環境重置為初始狀態，在呼叫 step 之前是必要的。傳回情節的第一個智能體觀察值和資訊，例如指標、除錯資訊。

• render() - 渲染環境以協助視覺化智能體看到的内容，範例模式為「human」、「rgb_array」、「ansi」（用於文字）。

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

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

• action_space - 對應有效動作的空間物件，所有有效動作都應包含在空間內。

• observation_space - 對應有效觀察值的空間物件，所有有效觀察值都應包含在空間內。

• spec - 一個環境規格，其中包含用於從 gymnasium.make() 初始化環境的資訊

• 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 類別

注意

若要取得可重現的動作取樣，可以使用 env.action_space.seed(123) 設定種子。

注意

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

方法

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

使用智能體動作執行環境動態的一個時間步長。

當達到情節的結尾（terminated 或 truncated）時，有必要呼叫 reset() 以重置此環境的狀態以進行下一個情節。

在 0.26 版本中變更: 步驟 API 已變更，移除 done，改用 terminated 和 truncated，以讓使用者更清楚環境何時終止或截斷，這對於強化學習引導演算法至關重要。

參數:

action (ActType) – 智能體提供的動作，以更新環境狀態。

傳回:

• observation (ObsType) – 環境的 observation_space 的元素，作為由於智能體動作而產生的下一個觀察值。一個範例是包含 CartPole 中桿的位置和速度的 numpy 陣列。

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

• terminated (bool) – 代理是否達到終止狀態 (根據任務的 MDP 定義)，這可以是正向或負向的。例如，達到目標狀態，或從 Sutton 和 Barto 的網格世界中移動到熔岩中。如果為 true，使用者需要呼叫 reset()。

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

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

• done (bool) – (已棄用) 一個布林值，表示回合是否已結束，在這種情況下，進一步呼叫 step() 將會返回未定義的結果。在 OpenAI Gym v26 中，為了支持 terminated 和 truncated 屬性，此值已被移除。發出 done 訊號的原因可能有很多種：也許環境底層的任務已成功解決、超過了特定時間限制，或是物理模擬進入了無效狀態。

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

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

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

因此，(在典型使用情況下) 應該在初始化後立即使用種子呼叫 reset()，然後再也不要呼叫。

對於自訂環境，reset() 的第一行應該是 super().reset(seed=seed)，這會正確地實作種子設定。

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

參數:

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

• options (選用的字典) – 指定如何重置環境的其他資訊 (選用，取決於特定環境)

傳回:

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

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

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

依照在初始化環境期間由 render_mode 指定的方式計算渲染畫面。

環境的 metadata 渲染模式 (env.metadata[“render_modes”]) 應包含實作渲染模式的可能方式。此外，大多數渲染模式的清單版本是透過 gymnasium.make 實現的，它會自動套用一個封裝器來收集渲染的畫面。

注意

由於 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”：透過封裝器，gymnasium.wrappers.RenderCollection，可以實現基於清單的渲染模式 (Human 除外)，在 gymnasium.make(..., render_mode="rgb_array_list") 期間會自動套用。在呼叫 render() 或 reset() 之後，會將收集到的畫面彈出。

注意

請確保您的類別的 metadata "render_modes" 金鑰包含支援模式的清單。

變更版本： 0.25.0: 變更了渲染函數，不再接受參數，這些參數應該在初始化的環境中指定，即 gymnasium.make("CartPole-v1", render_mode="human")

Env.close()

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

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

屬性

Env.action_space: spaces.Space[ActType]

對應於有效動作的 Space 物件，所有有效動作都應包含在此空間中。例如，如果動作空間的類型為 Discrete 並給出值 Discrete(2)，則表示有兩個有效的離散動作：0 和 1。

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

Env.observation_space: spaces.Space[ObsType]

對應於有效觀測值的 Space 物件，所有有效觀測值都應包含在此空間中。例如，如果觀測空間的類型為 Box 且物件的形狀為 (4,)，則表示有效的觀測值將是一個包含 4 個數字的陣列。我們也可以使用屬性檢查方塊的邊界。

>>> 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': []}

包含渲染模式、渲染 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，如果未設定，則會以隨機種子初始化。

傳回:

`np.random.Generator` 的實例

property 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()。