ライブラリの設計

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

ほとんどの演算子には、ポータブルなリファレンス実装と 1 つ以上のハードウェア固有のカーネルなど、複数のバックエンドがあり、使い慣れた単一の高レベルのエントリ ポイント(標準の jax.lax 関数など)を公開しています。このレイヤは、ユーザーにシンプルなドロップイン インターフェースを提供するように設計されています。このインターフェースは、ハードウェアと入力形状に最適なサポート対象バックエンドを自動的に選択しますが、必要に応じて特定の実装をリクエストすることもできます(tokamax.ragged_dot() を参照)。

ArgSpecs

重要なワークロード シェイプの共有カタログを維持することは、バックエンド間でカーネルを一貫してテストして最適化するために不可欠です。Tokamax は、これらの代表的な本番環境とベンチマークの形状を、オペレーターのすべての実装で共有されるワークロード仕様としてキャプチャします。これにより、継続的インテグレーション テスト、回帰ベンチマーク、自動チューニング パイプラインに、さまざまなワークフローのタグでフィルタできる信頼できる唯一の情報源が提供されます(ragged_dot の ArgSpecs をご覧ください)。

リポジトリ構造

内部実装コードは、非公開のソースツリー(tokamax/_src を参照)にあります。一方、演算子、自動チューニング、ベンチマーク、構成の公開シンボルは、最上位モジュールを介して再エクスポートされます(tokamax/__init__.py を参照)。

各演算子ディレクトリ(tokamax/_src/ops を参照)内のファイルは、一貫した命名規則に従います。ここでは、ragged dot を使用して説明します。

  • 高レベル API: 公開機能のエントリ ポイントとバックエンド ディスパッチ ロジックを定義します(api.py を参照)。
  • Op 固有の基本クラス: ポータブルなリファレンス実装を定義します(base.py を参照)。
  • バックエンドの実装: ハードウェア固有の演算子クラス、構成、ヒューリスティック、自動チューニング スペースを定義します(pallas_mosaic_tpu.py を参照)。
  • 低レベルカーネル: スタンドアロン カーネル実装と共有低レベルヘルパーをコンパニオン モジュールに分離します(pallas_mosaic_tpu_kernel.py を参照)。
  • ワークロード仕様: テスト、ベンチマーク、自動チューニング用の正規入力形状をカタログ化します(arg_specs.py をご覧ください)。
  • テストスイート: バックエンドごとのテストスイートとともに、共有のパラメータ化された正確性チェックを定義します(test_base.py をご覧ください)。

experimental ディレクトリ内のオペレーションは同様の構造に従いますが、公開 API で公開されない場合があります。これらのオペレーションは、迅速なイテレーションと探索を目的としており、頻繁に大幅に変更される可能性があります。一般的に、継続的なメンテナンスとサポートに対する期待は低くなります。

ユーザーが呼び出すべきレイヤ

エントリ ポイントの選択は、基本的に利便性と制御のトレードオフです。ほとんどのユーザーは、高レベルの Functional API を介して演算子を呼び出すことから始める必要があります。この API は、使い慣れたスタイルのインターフェースを提供し、適切なバックエンド実装を自動的に選択します。決定論的なバックエンドの選択が必要な場合、ユーザーは同じ呼び出しシグネチャを維持しながら、明示的な実装の選択を上位関数に渡すことができます。最大限の制御を行うために、ユーザーは特定の演算子実装クラスを直接インスタンス化して、カーネル ハイパーパラメータ(タイルサイズなど)をカスタマイズし、バックエンド固有の引数を渡すことができます。

演算子実装クラスを経由せずに低レベルのカーネル関数を直接呼び出すことはおすすめしません。そうすると、自動チューニング、入力検証と正規化、メタデータのシリアル化などの重要なインフラストラクチャがバイパスされます。オペレーター ラッパーは意図的に軽量に設計されているため、オーバーヘッドを大幅に削減することはできません。たとえば、適切な自動チューニング ハイパーパラメータがない場合、ユーザーはパフォーマンスが大幅に低下する可能性があります。

高度なトピック

オペレーター フュージョン

融合可能な Pallas TPU 演算子は、@tokamax.ops.op_fusion.fuse を介して、周囲の JAX プロローグとエピローグをカーネルに直接融合することをサポートしています。使用例と、融合対応カーネルと Op サブクラスの作成手順については、Operator Fusion ガイドをご覧ください。

シリアル化

カーネルは StableHLO にシリアル化できます。カーネル呼び出しは JAX カスタム呼び出しです。これはデフォルトで jax.export で禁止されているため、すべての Tokamax カーネルをエクスポートできるようにするには、tokamax.DISABLE_JAX_EXPORT_CHECKS を使用する必要があります。

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 は、次の 2 つのシリアル化を保証します。

  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),
      ...,
  )