ドキュメント

compile=True と TileLang 高速パス:エンジニアリングノート

これらのノートは、compile=True と fast=True が README の記述を超えてどう振る舞うかを扱います。 #472、#576、#718 の作業中に、RTX 4070 Ti SUPER、torch 2.11、tilelang 0.1.14 で計測した結果です。 次の人がもう一度測らずに済むように置いています。

バックエンドの選択

Agent(..., backend="auto") と laya.load(..., backend="auto") はバックエンドクラス層を選びます。既定は eager のままです。明示的な backend= は compile と fast より優先され、省略すると両フラグの既存の挙動が保たれます。

  • eager:サポートされるすべてのデバイスでの標準の PyTorch forward。
  • compile:CUDA 専用の torch.compile で、動的形状と reduce-overhead モード、バケットパディング、永続的な inductor キャッシュ、インストール時の warmup を伴います。compile=True と同じ独立次元スコープを使い、既存の既定モードと CPU サポートを保ちます。LAYA_COMPILE_WARMUP=0 でバックエンドの warmup を遅らせ、LAYA_INDUCTOR_CACHE_DIR でそのキャッシュディレクトリ(既定 ~/.cache/laya/inductor)を選べます。
  • tilelang:現在の高速パスの周りのアダプタで、agent の bf16 または fp16 dtype を使います。
  • auto:TileLang がインストールされていて、サポートされる ModernBERT エンコーダと dtype があるときは CUDA 上の TileLang、そうでなければ CUDA で compile、他のデバイスでは eager。
  • onnx:laya.load(..., backend="onnx", onnx_path="model.onnx") は既存の ONNXAgent を返します。onnx_path がない場合は laya.onnx を使います。

利用できないバックエンドは、解決されたバックエンドを名指しする RuntimeWarning を出して eager にフォールバックします。バックエンドを必須にするには agent.set_backend("tilelang", strict=True) を使います。切り替えはアクティブな推論を待ちます。agent.backend はアクティブな名前を報告し、agent.backend_object はインストールされたオブジェクトを公開します。agent.set_backend("compile", warmup=False) は推論までコンパイルを遅らせるので、コンパイルエラーはそのときリクエスト上に現れます。agent.warmup() は引き続き利用できます。agent.deaccelerate() はクラス層を通じてインストールされたバックエンドを削除します。

Router は明示的な選択を Router(agent_kwargs={"backend": "auto"}) で転送します。既定ではバックエンド引数を渡さず、既存の Agent ライクなコンストラクタとの互換性を保ちます。スコープ付きの CPU OOM 再試行はバックエンドを切り離し、モデルが元のデバイスに戻ったときに復元します。

compile=True はアテンションマスクを実体化する

Eager SDPA は ModernBERT の (rows, 1, L, L) アテンションマスクをブロードキャストビューとして 扱います。compile=True が使う動的な形状の下では、inductor は最後の次元が整列していることを 証明できません。マスクをすべてのヘッドに展開し、rows x heads x L x L の実バッファに詰め込み ます。12 ヘッドの bf16 では、32 行 x 1024 token で 0.8 GB になります。

  • GPU に余裕がある場合。 このバッファは帯域を消費し、長いバッチあたり数十ミリ秒かかります。
  • GPU がほぼ満杯の場合。 キャッシュアロケータがスラッシングし、同じ呼び出しに数十秒かかる ことがあります。

ビジーな GPU で長いバッチをコンパイルするなら、バッチサイズを制限するか(predict_batch(..., batch_size=)) or use fast=True を使ってください。TileLang のアテンションは、パックされた QKV バッファを読み、系列長でマスクするので、そのようなバッファを持ちません。

コールドスタート

  • 初回のコンパイル。 グラフごとに数十秒かかります。compile=True には 2 つのグラフが必要 です。1 つはバッチ用、もう 1 つは 1 行用で、後者は torch が特殊化します。compile=True はロード中に agent.warmup() を呼ぶようになりました。 compile_warmup=False は遅延コンパイルを復元し、agent.warmup(shapes=...) は引き続き手動で使えます。eager と TileLang のロードは自動で温まりません。これらの形状は 一般的なリクエストを覆うもので、すべての可能な形状ガードではありません。
  • warmup の失敗。 自動 warmup はベストエフォートです。失敗するとエラー(基になるコンパイラエラーを含む)を名指しする RuntimeWarning を出し、ロードは torch.compile ラッパーとコンパイル設定を無傷で保ったまま戻ります。たとえば、MSVC のない Windows は warmup が失敗しても compile=True でロードできます。後続のリクエストはコンパイル済みモデルをそのまま使い、コンパイル失敗を表面化させます。Laya はそれらを eager 実行に切り替えません。明示的な agent.warmup() 呼び出しも失敗を伝播します。失敗した自動 warmup の後も同様です。したがって、ロードの成功はコンパイル済み推論の準備完了を保証しません。
  • Laya キャッシュのオプトイン。 laya.load(..., compile=True, compile_cache=True) は、プロセス全体の TORCHINDUCTOR_CACHE_DIR が存在しない場合にのみそれを設定し、$XDG_CACHE_HOME/laya/torchinductor、XDG が未設定か絶対パスでない場合は ~/.cache/laya/torchinductor にします。既存の設定(以前の PyTorch コンパイルが設定したものを含む)が優先します。ディレクトリはロード時に作成され、ファイルシステムエラーは伝播します。compile_cache=False(既定)、eager、TileLang のロードは環境に触れません。これは古いキャッシュを移動も削除もしません。コンテナには依然として永続的な home/ボリュームが必要です。キャッシュの互換性と無効化は PyTorch が管理します。GPU、torch、コンパイラ、モデル、入力ガードの変更は再コンパイルを要することがあります。
  • 再起動をまたぐ場合。 Inductor の FX グラフキャッシュは、コンパイル済みのグラフを TORCHINDUCTOR_CACHE_DIR の下に保ちます。既定は /tmp の下で、再起動やコンテナの再起動では 残りません。永続ディレクトリ、またはコンテナのボリュームに設定すれば、2 つ目のプロセスは コンパイルせずにグラフを読み込みます。#472 の計測では、これでウォームアップが約 120 秒から 約 50 秒になりました。

オプションの CUDA グラフ

agent = laya.load("convaiinnovations/laya", compile=True,
                  compile_cache=True, compile_mode="reduce-overhead")

compile_mode は既定で "default" です。アクティブなコンパイル済みパスでは "default" と "reduce-overhead" だけが受け付けられます。eager と TileLang のロードはコンパイルオプションを無視します。CPU コンパイルは引き続き動きますが、CUDA グラフの記録は CUDA でのみ適用されます。CUDA モードには PyTorch の torch.compiler.cudagraph_mark_step_begin API が必要です。それが無い古いビルドは明示的なエラーを送出します。

動的な Dynamo グラフは形状に依存しない CUDA グラフを意味しません。新しい具象形状は、新しい Dynamo グラフなしに再び warmup と記録を要することがあります。2 つの既定の合成 warmup 形状は、すべてのリクエスト形状を事前記録しません。繰り返しの形状は恩恵を受けられますが、変化する形状は追加のレイテンシを払い、グラフプールを保持しえます。PyTorch はサポートされない操作や構成では CUDA グラフをスキップすることがあります。このモードの設定はキャプチャの保証ではありません。

Laya は各コンパイル済み CUDA forward を新しいステップとして印付け、それらの forward をエージェント間で直列化し、ロックを解放する前に両方の出力テンソルをコンパイル済みグラフの外で複製します。これにより、保持された出力がリプレイをまたいで有効に保たれます。代償は 2 回のコピーと直列化された forward 実行です。このロックは、アプリケーションが所有する無関係なコンパイル済みモデルを調整しません。CUDA グラフの反復を共有したりカスタムストリームを使う呼び出し元は、自分で調整を管理する必要があります。ディスクキャッシュは、プロセス間で、コンパイル済みコードを再利用するのであって、生きた CUDA グラフ記録やそのデバイスメモリではありません。

benchmarks/bench_compile_defaults.py で、コールド/再起動のタイミング、メモリ、キャッシュカウンタを再現できます。記録された計測を参照してください。

AOTInductor:まだ

チェックポイントと GPU アーキテクチャごとに事前コンパイル済みの成果物を配布する (torch._inductor.aoti_compile_and_package)と、コンパイルを完全になくせます。torch 2.11 では、パッケージングで止まります:

  • エクスポートは成功する。 DecisionModel の torch.export は約 5 秒で成功し、動的な rows、 markers、tokens を扱えます。tokens は 16 の倍数として宣言する必要があります(16 * Dim(...))。 通常の range は、エクスポータ自身の L % 8 整列ガードを通りません。これは上と同じマスク整列 です。
  • パッケージングは失敗する。 失敗の仕方は、プログラムをどうエクスポートしたかで決まります:
    • autocast の下では、プログラムが dtype アサートを持ち、AOTI が autocast の外でそれに 引っかかります:Tensor dtype mismatch! Expected: torch.bfloat16, Got: torch.float32。
    • autocast なしの bf16 コピーからでは、トレースがフォワード内で失敗します: mat1 and mat2 must have the same dtype。DecisionModel.forward は action head の前に、 プールされた state と信頼度特徴を fp32 にアップキャストし、autocast が通常それを調整します。

したがって成果物の道には、dtype を明示した action head が必要です。その入力を head の dtype に キャストするか、head を fp32 で動かすかのどちらかです。

TileLang の可搬性:カーネルは CUDA 専用

tilelang は CUDA、HIP、Metal、WebGPU、および C バックエンド用のターゲットを登録します。AMD や Apple のハードウェアがない場合に答えられる問いは、laya/tl_kernels.py がそもそも CPU 向けに lower できるかどうかでした。Linux x86-64 で tilelang.compile(kernel.prim_func, target=...) を使って調べました:

target 結果
"cpu" 最初に拒否される:Target cpu is not supported。tilelang の CPU バックエンドは "c"。
"llvm" Cannot find global function target.build.llvm。この wheel は LLVM バックエンドを積んでいない。
"c" C に lower され CPU テンソルで動くが、言語の一部分に限られる。

すべての Laya カーネルが "c" で失敗し、原因は 3 つのうちのいずれかです:

カーネル target="c" での失敗 使う構文
gemm_kernel, gemm_geglu_kernel CPU fill only supports local and global buffers, but got dst scope local.fragment T.alloc_fragment アキュムレータ
add_ln_kernel CPU reduce only supports local src and local/local.var dst buffers fragment 上の T.reduce_sum / T.reduce_max
rope_kernel Cannot convert type bfloat16 to C type bf16 テンソル
attn_kernel T.alloc_fragment で失敗 fragment

C バックエンドは次を受け付けます:

  • fp32 の要素ごとのループ(T.Parallel);
  • T.Pipelined。これは通常のループに lower されます;
  • T.alloc_local アキュムレータを持つ T.gemm。これはスカラーの三重ループに lower されます。

したがって CPU 版は、ターゲットフラグではなく第 2 のカーネル群になります。その GEMM はブロック 化されないスカラーループになり、標準のフォワードが CPU ですでに使っている MKL/oneDNN の経路とは 競合しません。同じ 3 つの構文は、HIP と Metal で最初に確認すべきものでもあります:fragment、 GemmWarpPolicy を持つ T.gemm、bf16/fp16 対応です。

2 番目の表の 1 行目を再現するには:tilelang.compile(K.gemm_kernel(768, 768).prim_func, target="c")。