LiteRT アクセラレータ テストスイート（ATS）

LiteRT アクセラレータ テストスイート（ATS）は、LiteRT フレームワークと統合されたカスタム アクセラレータ実装の機能の正しさを検証し、パフォーマンスを測定するために使用される包括的なツールです。

概要とコア機能

ATS の主な機能は、ターゲット アクセラレータに対して事前定義された ML モデルを実行し、その結果を LiteRT の標準 CPU バックエンドと比較することです。

• 検証: このスイートは、アクセラレータによって生成された出力テンソル（アクティベーション）を、既知の正常な CPU バックエンドによって生成された出力テンソルと比較することで、数値検証を行います。これにより、アクセラレータの実装で必要な精度と正確性が維持されます。
• パフォーマンス指標: レイテンシなどの重要なパフォーマンスの詳細と関連する指標を自動的にキャプチャして記録し、ユーザーが利用できるようにします。
• 実行: テストは通常、ターゲット デバイス（Android スマートフォンなど）で実行され、adb（Android Debug Bridge）ツールを使用してファイル転送とセットアップを処理するシェル スクリプト ラッパーによって管理されます。

テストデータ（モデル）

ATS スイートは、広く使用されている .tflite モデルのコレクションをテストデータとして使用します。入力データはデータ型に基づいてランダムに生成され、必要に応じてシードできます。

含まれるモデル

次のモデルは、テスト用に自動的に含まれてダウンロードされます（変更される可能性があります）。

• hf_all_minilm_l6_v2
• hf_mobilevit_small
• qai_hub_midas
• qai_hub_real_esrgan_x4plus
• torchvision_mobilenet_v2
• torchvision_resnet18
• torchvision_squeezenet1_1
• u2net_lite
• whisper_tiny_decoder
• whisper_tiny_encoder
• yamnet
• yolo11n

手動モデルの取得

モデルは bazel run 中に自動的にダウンロードされますが、wget を使用してモデルセット全体を手動で取得することもできます。

wget -p -O <target_file> https://storage.googleapis.com/litert/ats_models.tar.gz

Bazel を使用して ATS Suite を定義する

litert_define_ats Bazel マクロを使用して、アクセラレータに固有の ATS テストターゲットを構成して定義します。

このマクロは、実行可能なターゲットを 2 つ自動的に作成します。

1. 標準のオンデバイス JIT テスト（実行と検証用）。
2. 専用の AOT「コンパイルのみ」モードテスト（ホスト コンパイル用）。

litert_define_ats の使用例

この例では、バックエンド名 example のアクセラレータに対して example_ats という名前の ATS スイートを定義します。

# Emits aot-mode and jit-mode test targets, one for running compilation test on host
# and another for running JIT and inference on device
# These targets are named with their respective suffix attribute.
litert_define_ats(
    name = "example_ats",
    backend = "example",
    compile_only_suffix = "_aot",
    do_register = [
        "*mobilenet*",
    ],
    extra_flags = ["--limit=1"],
    jit_suffix = "",
)

実行

Android を対象とした標準テスト（すべての adb オペレーションを処理）を実行するには:

# Handles environment setup, and build + push of library and data dependencies to the device,
# executes the suite on the target.
bazel run -c opt --config=android_arm64 :example_ats

AOT コンパイル テストを実行する手順は次のとおりです。

# Handle environment setup, and builds library dependencies for host platform.
# Executes the ats compile only flow. The "--compile_mode" flag is already
# bound to the program arguments.
bazel run :example_ats_aot

Linux 実行（ホスト）

ビルドを行う同じマシンで ATS を実行する Linux 実行の場合、ユーザーは :ats バイナリを直接使用する必要があります。

bazel run -c opt :ats

IoT の実行

IoT 実行の場合、ユーザーはホストでバイナリをビルドし、デバイスに手動でプッシュする必要があります。

コマンドライン フラグ

ats 実行可能ファイルは、テストとレポートを細かく制御するための複数のフラグを受け入れます。

ATS に litert_device_script ビルド ユーティリティを使用する

ATS ターゲット ユーザーの自動実行には、すべての環境設定を処理するシェル エントリ ポイントが含まれます。また、ターゲット デバイスがビルドが完了したホストと異なる場合（adb push など）、必要なライブラリのプッシュも含まれます。

この機能は、ATS ビルドが内部で使用する litert_device_script ユーティリティを通じて汎用的に提供されます。このビルド機能にアクセスするには、アクセラレータが登録プロセスを行う必要があります。ats のサポートに加えて、これらのユーティリティはスタンドアロンで、ビルドホストとは異なるデバイスで実行される cc_binary と cc_test をシミュレートするために使用できます。これには、プッシュされた依存関係が必要です。

バックエンド登録

litert_device_script（つまり ATS）で使用する新しいアクセラレータを有効にするには、必要なライブラリを litert_device_common.bzl Bazel ファイルに登録する必要があります。登録は、LiteRT がそのアクセラレータで動作するために必要な、ビルド可能なライブラリまたは事前コンパイルされたライブラリのセットにマッピングされる一意の「バックエンド」名に基づいています。

登録手順

1. BackendSpec 関数を定義する: 新しいアクセラレータの仕様を含む辞書を返す関数を作成します。

2. ライブラリを指定（libs）: 共有ライブラリの Bazel ターゲット パスと、デバイス リンカーがそれを見つけるために必要な環境変数（LD_LIBRARY_PATH）の詳細を示すタプルのリストです。

   • Dispatch ライブラリ: ランタイム実行に必要です。
   • コンパイラ プラグイン ライブラリ: AOT コンパイル モードで必要です。

3. ライブラリ名を指定（plugin、dispatch）: プラグインとディスパッチ ライブラリのファイル名を指定します。

4. Spec を登録する: 新しい Spec 関数をメインの _Specs 関数に統合して、一意のバックエンド ID で使用できるようにします。

登録の例（_ExampleSpec）

litert_device_common.bzl の次のコードは、「example」アクセラレータが登録される方法を示しています。

def _ExampleSpec():
    return {
        # The unique backend ID
        "example": BackendSpec(
            id = "example",
            libs = [
                # Dispatch Library and how to find it on device
                ("//third_party/odml/litert/litert/vendors/examples:libLiteRtDispatch_Example.so", "LD_LIBRARY_PATH"),
                # Compiler Plugin Library
                ("//third_party/odml/litert/litert/vendors/examples:libLiteRtCompilerPlugin_Example.so", "LD_LIBRARY_PATH"),
            ],
            plugin = "libLiteRtCompilerPlugin_Example.so",
            dispatch = "libLiteRtDispatch_Example.so",
        ),
    }

# ... (Other specs are defined here)

def _Specs(name):
    # Your new spec function must be included here
    return (_QualcommSpec() | _GoogleTensorSpec() | _MediatekSpec() | _CpuSpec() | _GpuSpec() | _ExampleSpec())[name]

litert_device_exec での登録の活用

登録したら、新しい backend_id で litert_device_exec と関連するマクロを使用します。このマクロは、必要なライブラリと指定されたデータファイルをターゲット バイナリに自動的にバンドルします。

cc_binary(
    name = "example_bin",
    srcs = ["example_bin.cc"],
)

litert_device_exec(
    name = "example_bin_device",
    backend_id = "example",  # Uses the libraries registered under "example"
    data = [
        "//third_party/odml/litert/litert/test:testdata/constant_output_tensor.tflite",
    ],
    target = ":example_bin",
)

このターゲット（bazel run ... :example_bin_device）を実行すると、次のようになります。

1. example_bin C++ バイナリをビルドします。
2. バイナリ、libLiteRtDispatch_Example.so、libLiteRtCompilerPlugin_Example.so、.tflite ファイルをデバイスにプッシュします。
3. adb shell を使用してバイナリを実行します。

デバイスパスに関する注: デバイス上のファイルの正規の場所は、Bazel のランファイル ツリー（特に /data/local/tmp/runfiles/runfiles_relative_path）をミラーリングします。デバイス スクリプトは、ダイナミック リンカーの適切なパスの設定を自動的に処理します。

コンパイル モード（AOT）

事前（AOT）コンパイル ステップをサポートするアクセラレータの場合、ATS は専用の「コンパイル モード」で実行できます。

• 目的: このモードは、ターゲット デバイスではなく、ワークステーション（ホストマシン）で実行するように設計されています。指定されたターゲット ハードウェアのモデルをコンパイルしますが、実行はしません。
• 出力: コンパイルされたすべてのモデルが、ワークステーション上の指定されたディレクトリに出力されます。
• アクティベーション: ATS ビルドマクロは、ライブラリがホスト プラットフォーム用にビルドされる aot の特定のターゲットを出力します。このフローは --compile_mode フラグを使用して任意のバイナリで有効にできますが、aot ビルドの引数に自動的にバインドされます。

今後の展開

このスイートは、完全なモデルに加えて、単一オペレーション（ops）専用のテストを含むように拡張される予定です。