API 相容性

API 相容性#

JAX 不斷發展，我們希望能夠改進其 API。也就是說，我們希望盡量減少 JAX 使用者社群的變動，並盡力避免重大變更。

JAX 版本控制#

JAX 使用基於努力的版本控制 (請參閱 JEP 25516: JAX 的基於努力的版本控制)，目前處於 Zero 版本階段。這表示對於版本 0.X.Y，遞增 Y 將會引入次要的破壞性變更，而遞增 X 將會引入主要的破壞性變更。

對於任何破壞性變更，JAX 目前遵循 3 個月的棄用政策。當對 API 進行不相容的變更時，我們將盡最大努力遵守以下程序

變更將在 CHANGELOG.md 和已棄用 API 的文件字串中宣告，並且舊版 API 將發出 DeprecationWarning。
在棄用 API 的 jax 版本發布三個月後，我們可能會隨時移除已棄用的 API。請注意，三個月是下限，並且有意選擇比許多更成熟的專案更快。實際上，棄用可能需要更長的時間，特別是如果某個功能有很多使用者。如果三個月的棄用期變得有問題，請向我們提出。

我們保留隨時變更此政策的權利。

涵蓋範圍？#

僅涵蓋公開 JAX API，其中包括以下模組

jax
jax.dlpack
jax.image
jax.lax
jax.nn
jax.numpy
jax.ops
jax.profiler
jax.random (請參閱以下詳細資訊)
jax.scipy
jax.tree
jax.tree_util
jax.test_util

並非這些模組中的所有內容都旨在公開，隨著時間的推移，我們正在努力區分公開和私有 API。公開 API 記錄在 JAX 文件中。此外，我們的目標是所有非公開 API 都應以底線作為名稱前綴，儘管我們尚未完全遵守這一點。

未涵蓋範圍？#

明確的私有 API#

任何以底線作為前綴的 API 或匯入路徑都是明確私有的，並且可能會在 JAX 版本之間變更，恕不另行通知。我們正在努力將所有私有 API 移動到 jax._src，以更清楚地說明這些預期。

舊版內部 API#

此外，還有幾個舊版模組目前公開了一些沒有底線的私有 API，包括

jax.core
jax.interpreters
jax.lib
jax.util

我們正在積極努力棄用這些模組及其包含的 API。在大多數情況下，此類棄用將遵循 3 個月的棄用期，但這並非總是可行。如果您使用任何此類 API，請預期它們很快就會被棄用，並尋找替代方案。

實驗性和範例程式庫#

以下模組包含用於實驗或示範目的的程式碼，並且 API 可能會在版本之間變更，恕不另行通知

jax.experimental
jax.example_libraries

我們理解某些使用者依賴 jax.experimental，因此在大多數情況下，我們針對變更遵循 3 個月的棄用期，但這並非總是可行。

JAX extend#

jax.extend 模組包含半公開的 JAX 內部 API，這些 API 旨在供下游專案使用，但不具有與主要 JAX 套件相同的穩定性保證。如果您的程式碼使用 jax.extend，我們強烈建議針對 JAX 的每夜版本進行 CI 測試，以便在潛在變更發布之前捕獲它們。

有關 jax.extend 的詳細資訊，請參閱 jax.extend 模組文件，或設計文件 jax.extend：用於擴充功能的模組。

數值和隨機性#

確切的數值運算值不保證在 JAX 版本之間穩定。實際上，確切的數值不一定在給定的 JAX 版本中、跨加速器平台、在 jax.jit 內或外等情況下穩定。

對於固定的 PRNG 金鑰輸入，jax.random 中偽隨機函數的輸出可能會因 JAX 版本而異。相容性政策僅適用於輸出分佈。例如，運算式 jax.random.gumbel(jax.random.key(72)) 可能會在不同的 JAX 版本中傳回不同的值，但 jax.random.gumbel 仍將是 Gumbel 分佈的偽隨機產生器。

我們盡力減少對偽隨機值進行此類變更的頻率。當發生變更時，會在變更日誌中宣告變更，但不遵循棄用週期。在某些情況下，JAX 可能會公開暫時的組態旗標，以還原新行為，以協助使用者診斷和更新受影響的程式碼。此類旗標將持續一個棄用視窗的時間長度。