程式庫設計

Tokamax 的設計旨在標準化及簡化一般開發人員在核心編寫、最佳化、維護和正式環境使用方面的流程。做法是透過基礎類別和共用基礎架構,讓程式庫中的所有運算子在結構良好的架構中繼承和實作。

運算子層

Tokamax 基礎類別

tokamax.Op 是 Tokamax 的基礎類別,也是程式庫中每個運算子的基礎。叫用任何衍生運算子時,這個層會自動處理下列功能:

  • 引數繫結:在執行任何運算之前,基礎類別會將呼叫端的引數正規化並驗證為單一標準表示法,以便快取、經驗法則和核心執行作業都能透過 BoundArguments 物件,以統一的方式推論工作負載,無論輸入內容是以何種方式傳遞 (請參閱 op.bind())。
  • 裝置驗證:為了及早發現硬體不相符的問題,運算子會在執行前,根據目標加速晶片驗證裝置支援,但從 CPU 主機進行跨平台程式碼編譯時,仍可略過這項檢查 (請參閱 op.supported_on()、bypass_device_check=True 和 config.cross_compile(True))。
  • 批次擷取:由於最佳核心設定 (Config) 通常取決於完整批次問題大小,而非單一配量,因此當運算子向量化 (jax.vmap) 時,基礎類別會擷取周圍的批次維度,以便啟發式和自動調整快取針對實際工作負載形狀進行最佳化 (請參閱 op._capture_batched_args())。
  • 設定解析:為了提供強大的現成效能,而不需要手動調整,只要呼叫端未提供核心超參數,基礎類別就會自動解析核心超參數,並在磁碟式自動調整快取中重複使用先前自動調整的設定 (如有),或改用內建的啟發式方法 (請參閱 BoundArguments.default_config)。
  • StableHLO 中繼資料序列化:為了讓編譯後的程式可供檢查,以便進行離線剖析和自動調整,基礎類別會將運算子中繼資料嵌入降階圖,讓下游工具可以直接從編譯後的模組或效能設定檔,重建執行的運算子和輸入內容 (形狀、類型等) (請參閱 _tokamax_metadata())。
  • 正向執行和自訂 VJP:由於標準自動微分通常無法有效區分專用硬體核心,因此基礎類別會將正向和反向執行協調為一組,讓正向傳遞在梯度計算期間,直接將中間值傳遞至自訂反向核心 (請參閱 op._fwd()) 和對 jax.custom_vjp 的呼叫。

運算專屬基礎類別

每個運算子系列都會定義自己的基礎類別,該類別繼承自基礎運算子類別,並建立所有後端共用的合約 (例如,請參閱 RaggedDot):

  • 參考實作:每個運算子基礎類別都提供可攜式、純 JAX 參考實作,涵蓋完整數學規格,包括梯度 (如適用)。這可做為數值正確性測試的基準真相,並保證在任何硬體上都能正常運作 (請參閱 RaggedDot._fwd())。
  • 標準繫結:使用者可以透過多種方式表達相同的數學運算,例如傳遞不同形式的遮罩、精確度設定或維度規格,因此運算子基礎類別會正規化輸入內容,並預先檢查形狀和類型相容性,讓個別硬體後端只需處理單一可預測的輸入格式 (請參閱 RaggedDot.bind())。

運算實作類別

這些類別提供硬體專屬的核心實作,使用者可以直接例項化及叫用。每個實作項目都會繼承運算子專屬的基礎類別,並提供後端專屬行為 (例如 PallasMosaicTpuRaggedDot):

  • 核心功能:定義實際的硬體核心執行作業,通常使用 Pallas 等核心語言。當作業需要專門的反向傳遞時,梯度核心通常會模擬為其本身的一級運算子實作,以便獨立設定、調整和測試。雖然最低層級的核心程式碼通常會分解為獨立的輔助檔案,以實現模組化,但這個類別是叫用該核心的主要介面 (請參閱 PallasMosaicTpuRaggedDot._fwd())。
  • 設定:由於硬體核心通常會公開效能旋鈕 (例如圖塊大小、管道階段或記憶體緩衝策略),因此每個後端都會定義專屬設定結構,讓使用者或自動化工具控制核心的分區、編譯和執行方式 (請參閱 Config)。
  • 啟發式:並非所有工作負載都已預先自動調整,因此每個後端都會提供內建啟發式,根據問題維度、資料類型和加速器規格選擇合理的預設調整參數 (請參閱 _get_heuristics_config())。
  • 自動調整搜尋空間:對於重視尖峰效能的工作負載,每個後端都會為特定問題形狀定義有效參數組合的自動調整搜尋空間,讓自動調整器能對候選項目進行基準測試,並找出最快的設定 (請參閱 _get_autotuning_configs())。
  • 實作專屬驗證:硬體核心通常有比一般數學運算更嚴格的要求,例如維度對齊規則或有限的資料類型支援。每項實作都會驗證這些限制,並在無法處理工作負載時發出信號,讓更高層級的調度器能順利改用其他後端 (請參閱 PallasMosaicTpuRaggedDot._fwd())。

高階 API

大多數運算子都有多個後端,例如可攜式參考實作,以及一或多個硬體專屬核心,並提供單一熟悉的高階進入點 (例如標準 jax.lax 函式)。這個層級旨在為使用者提供簡單的插入式介面,可自動為硬體和輸入形狀選取最合適的支援後端,同時仍允許使用者在需要時要求特定實作 (請參閱 tokamax.ragged_dot())。

ArgSpecs

維護重要工作負載形狀的共用目錄,對於在後端之間一致測試及最佳化核心至關重要。Tokamax 會將這些代表性的實際工作環境和基準形狀擷取為工作負載規格,並在運算子的所有實作項目之間共用。這可為持續整合測試、迴歸基準和自動調整管道提供單一事實來源,並可依不同工作流程的標記篩選 (請參閱 ragged_dot 的 ArgSpecs)。

存放區結構

內部實作程式碼位於私人來源樹狀結構 (請參閱 tokamax/_src),而運算子、自動調整、基準測試和設定的公開符號則會透過頂層模組重新匯出 (請參閱 tokamax/__init__.py)。

在每個運算子目錄中 (請參閱 tokamax/_src/ops),檔案會遵循一致的命名慣例,這裡以不規則點為例:

  • 高階 API:定義公開功能進入點和後端調度邏輯 (請參閱 api.py)。
  • 運算子專屬基礎類別:定義可攜式參考實作 (請參閱 base.py)。
  • 後端實作:定義硬體專屬運算子類別、設定、啟發式和自動調整空間 (請參閱 pallas_mosaic_tpu.py)。
  • 低階核心:將獨立核心實作和共用低階輔助程式分隔為隨附模組 (請參閱 pallas_mosaic_tpu_kernel.py)。
  • 工作負載規格:列出用於測試、基準測試和自動調整的標準輸入形狀 (請參閱 arg_specs.py)。
  • 測試套件:定義共用的參數化正確性檢查,以及每個後端的測試套件 (請參閱 test_base.py)。

experimental 目錄中的作業遵循類似的結構,但可能不會在公開 API 中公開。這些作業旨在快速疊代和探索,可能會經常大幅變更,通常對持續維護和支援的期望較低。

使用者應呼叫哪一層

選擇進入點基本上是在便利性和控制權之間做出取捨。大多數使用者應先透過高階功能 API 呼叫運算子,該 API 提供熟悉的樣式介面,並會自動選取合適的後端實作。需要確定性後端選取時,使用者可以將明確的實作選項傳遞至高階函式,同時保留相同的呼叫簽章。如要充分掌控,使用者可以直接例項化特定運算子實作類別,自訂核心超參數 (例如圖塊大小),並傳遞後端專屬引數。

不建議直接呼叫低階核心函式,而不透過運算子實作類別。這樣做會略過重要的基礎架構,包括自動調整、輸入驗證和標準化,以及中繼資料序列化,但不會大幅節省負載,因為運算子包裝函式刻意設計得較輕量。舉例來說,如果沒有適當的自動調整超參數,使用者可能會看到明顯不理想的效能。

進階主題

運算子融合

可融合的 Pallas TPU 運算子支援透過 @tokamax.ops.op_fusion.fuse,將周圍的 JAX 前置和後置作業直接融合至核心。如需使用範例,以及編寫融合相容核心和 Op 子類別的操作說明,請參閱運算子融合指南。

序列化

核心可序列化為 StableHLO。核心呼叫是 JAX 自訂呼叫,預設在 jax.export 中禁止,需要使用 tokamax.DISABLE_JAX_EXPORT_CHECKS 才能允許匯出所有 Tokamax 核心:

from jax import export

f_grad_exported = export.export(f_grad, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS)(
    jax.ShapeDtypeStruct(x.shape, x.dtype),
    jax.ShapeDtypeStruct(scale.shape, scale.dtype),
)

請注意,使用 Tokamax 核心序列化的函式會失去標準 StableHLO 的裝置獨立性。Tokamax 提供兩項序列化保證:

  1. 在特定裝置上序列化的反序列化函式,保證會在序列化的裝置上執行。
  2. Tokamax 提供與 JAX 相同的相容性保證:6 個月的回溯相容性。

跨平台程式碼編譯和 CPU 匯出

Tokamax 核心可在 CPU 主機上匯出或跨平台編譯:

  • 明確選取實作項目 (例如 implementation="mosaic_tpu_v2") 會自動略過主機裝置驗證。
  • 或者,您也可以使用 tokamax.config.cross_compile(True) 全域啟用跨平台程式碼編譯:
with tokamax.config.cross_compile(True):
  f_exported = export.export(
      f, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS
  )(
      jax.ShapeDtypeStruct(x.shape, x.dtype),
      ...,
  )