litert-google-tensor

LiteRT on Google Tensor：アプリ向けのコンパイル、ベンチマーク、パッケージ化

Pixel TPU 用のスクリプト化された 3 つのワークフローです。

1. 公開 LiteRT Python API（ai_edge_litert.aot）を使用して、通常の .tflite を Google Tensor AOT コンパイル済みの .tflite に変換します。Linux x86_64 上でローカルに実行するか、ユーザーが macOS／Windows を使用している場合、または Linux マシンを持っていない場合は、Google Colab VM 上で実行します（google-colab-cli 経由で --colab を指定）。
2. 接続した Pixel 上で LiteRT の benchmark_model を使用して、コンパイル済みモデルを NPU のみでベンチマークします。必要に応じて CPU のベースラインも併せて測定し、TPU タイル時間（純粋な TPU 計算時間）と推論あたりの TPU エネルギーも含めます。
3. コンパイル済みビルドを、Google Tensor NPU ランタイムと Kotlin ローダーを含む Android（Gradle）アプリ用の Google Play AI パックとしてパッケージ化します（Google Tensor ビルドをすでに配布しているアプリの場合は、置き換えるファイルのみを用意します）。ユーザーが同意した場合は計画をプロジェクトに適用し、Pixel でアプリを確認します。

すべてユーザーのターミナルで同期的に実行されます。スクリプトがバックグラウンドプロセスを起動することはなく、Colab に割り当てたリソースや、スマートフォンに転送したファイルは必ずクリーンアップします。以下のパスはすべて、このスキルのディレクトリ（SKILL_DIR）からの相対パスです。

Path	Purpose
assets/versions.json	スクリプトで使用する LiteRT のバージョン（単一の情報源）
scripts/check_compiled.py	この .tflite はすでに Tensor 向けにコンパイルされていますか？
scripts/compile_model.py	AOT コンパイル（ローカルの Linux x86_64 または --colab）
scripts/benchmark_on_device.py	adb で転送 -> ベンチマーク -> 解析 -> クリーンアップ
scripts/package_ai_pack.py	コンパイル済みビルドからアプリ用の AI パックと Gradle モジュールを作成、または既存のパックを更新
scripts/install_and_verify.py	アプリをビルドし、Google Play と同様にインストールして、NPU／CPU の結果を読み取る
assets/templates/	Gradle、Kotlin、INTEGRATION.md、UPDATE.md のテンプレート（package_ai_pack.py）
references/compile-flags.md	API、コンパイラフラグ、スクリプトのオプション、--colab
references/benchmark-flags.md	ベンチマークの内容、バイナリ、レポートの作成、出力例
references/app-integration.md	アプリ向けのパッケージ化：内容、確認項目、提供方法、計画の適用、Pixel での確認
references/troubleshooting.md	症状 -> 対処方法の表
references/contributing.md	メンテナー向け：新しい LiteRT リリースへの対応

すべてのスクリプトは --help と --dry-run をサポートしており、Python 3 の標準ライブラリのみで動作するため、任意の python3 で実行できます。ただし、LiteRT をインポートする 2 つの例外があります。ローカルでのコンパイル（--colab、--dry-run、--print-install を指定しない compile_model.py）には、仮想環境のインタープリターを使用する必要があります（<venv>/bin/python SKILL_DIR/scripts/compile_model.py ... を実行するか、先に仮想環境を有効にしてください）。また、実際に package_ai_pack.py を実行する場合（--dry-run または --check-project を指定しない場合）は、ai-edge-litert がインストールされた Python が必要です（コンパイル用の仮想環境を使用できます。Beta SDK は不要です）。

前提条件（ユーザーには最初に伝えてください）

必要なもの	コンパイル（ローカル）	コンパイル（--colab）	ベンチマーク	パッケージ化（アプリ）
Google Tensor SDK Beta へのアクセス - https://services.google.com/fb/forms/tensor_ml_sdk_experimental_access から申し込みます（概要：https://developers.google.com/edge/litert/next/tensor-sdk）。Google から litert_plugin_compiler.tar.gz のダウンロードリンクがメールで届きます。これがないとコンパイラーをインストールできません。	必須	必須（--sdk-tarball または --sdk-url）	-	-
ホスト OS	Linux x86_64、RAM 16 GB 以上	任意の OS（PATH 上に colab CLI が必要。リモートの Colab Linux x86_64 VM で実行）	adb が使える任意の OS	ai-edge-litert をインストールできる任意の OS（コンパイル用 venv の Linux x86_64 ホストで動作します）
Python 環境	versions.json に記載されたバージョンの ai-edge-litert と ai-edge-litert-sdk-google-tensor を含むローカル venv（compile_model.py --print-install）	任意のローカル python3 と google-colab-cli（compile_model.py --print-install --colab）。SDK は Colab VM に自動でインストールされます	任意の python3（標準ライブラリのみ）	ai-edge-litert がインストールされた Python（コンパイル用 venv を使用できます。SDK パッケージは不要です）
PATH 上の adb、USB デバッグを有効にした Pixel 10/11	-	-	必須	ステップ 7（アプリのインストールと確認）
アプリの Gradle がサポートする JDK（JAVA_HOME）、Android SDK、プロジェクトの ./gradlew	-	-	-	ステップ 6～7（ビルド、インストール）。bundletool は一度だけダウンロードされます
libLiteRtDispatch_GoogleTensor.so - 公開 LiteRT バイナリバケットから自動でダウンロードされます（benchmark_model と同じディレクトリ）。または --dispatch-lib で指定します	-	-	必須	-（アプリでは Google Maven から取得します）
インターネット接続	pip install 時に一度	必須（Colab VM と pip install）	benchmark_model と dispatch lib の取得時に一度（~/.cache/litert-google-tensor/ にキャッシュされます）。ローカルで指定する場合は不要	-（アプリの Gradle ビルドで LiteRT Maven アーティファクトをダウンロードします）

対応ターゲット：公開 Tensor SDK ドキュメントに記載されている Tensor_G5（Pixel 10 ファミリー）と Tensor_G6（Pixel 11 ファミリー）です。Pixel 9 以前は対応していません。

ステップ 0 - パラメーターを収集する

不足している情報だけをユーザーに尋ねてください。値を決して捏造しないでください。

パラメーター	入手方法
モデルパス	.tflite への絶対パスです。ファイルが存在することを確認します。
目的	check only、compile only、benchmark only、compile + benchmark、またはアプリ用にパッケージ化（手順 5）です。依頼内容から判断します（「TPU と CPU でどれくらい速いか」＝必要に応じてコンパイルし、CPU をベースラインとしてベンチマークを実行、「アプリに入れて」／「デプロイして」＝パッケージ化）。依頼されていないデバイスでの実行は追加しないでください。
対象 SoC	コンパイルの場合は、ユーザーが指定したデバイスを優先します（Pixel 10 ファミリー＝Tensor_G5、Pixel 11 ファミリー＝Tensor_G6）。別の Pixel が接続されていても同様です。ベンチマークの場合は、接続されているスマートフォンで判断します。adb shell getprop ro.soc.model の結果が Tensor G5 なら Tensor_G5、Tensor G6 なら Tensor_G6 です（ベンチマークスクリプトがこの判定と適用を行います）。
出力パス	デフォルトは <output-dir>/<stem>_Google_<target>.tflite です。compile_model.py は既存ファイルの上書きを拒否します（終了コード 2）。既存ファイルに対して check_compiled.py を実行して再利用するか、--output-name を指定するか、確認を取ったうえで --overwrite を指定します。既存ファイルの隣に 2 つ目のビルドが必要な場合は、<stem>_Google_<target>.<YYYYMMDD-HHMM>.tflite（例：--output-name model_Google_Tensor_G5.20260107-0930.tflite）という名前にするか、フラグのバリエーションの場合は <stem>_Google_<target>.<flag-summary>.tflite（...G5.half-maxsharding.tflite など）という名前にします。ファイルを識別しやすいよう、_Google_<target> の部分は残してください。
デバイスのシリアル番号	adb devices に複数のデバイスが表示される場合のみ必要です。
ディスパッチライブラリ／ベンチマークバイナリ	省略可能です。どちらも同じ公開バケットディレクトリから自動ダウンロードされ、キャッシュされます。特定のビルドをユーザーが希望する場合、またはホストがオフラインの場合のみ確認してください。その場合は、--benchmark-bin <benchmark_model> と --dispatch-lib <libLiteRtDispatch_GoogleTensor.so | dir | .zip | .aar>（および環境変数 LITERT_GOOGLE_TENSOR_DISPATCH_LIB）を指定すると、ローカルコピーを使用し、ネットワークに接続しません。
CPU ベースライン	省略可能です。未コンパイルの元のモデルのパスが必要です。コンパイル済みファイルしか提供されていない場合はパスを確認してください（ベンチマークスクリプトはここにコンパイル済みファイルが指定されると、終了コード 2 で拒否します）。
実行回数／モード	デフォルトはウォームアップ 5 回／計測 50 回、パフォーマンスモードは burst です。benchmark_model は回数を最小値として扱い、さらにウォームアップを最低 0.5 秒、計測を最低 1 秒実行するため、高速なモデルは指定回数より多く実行されます。ユーザーが正確な回数を指定した場合は、その旨を伝え、下限を無効にするか確認してください（--extra-arg=--min_secs=0 --extra-arg=--warmup_min_secs=0）。「定常状態」／「持続的」というリクエストには --performance-mode sustained_performance を使用します。
TPU タイル時間	デフォルトで有効です。確認は不要です。フックを使った 2 回目の NPU パスです。--no-tile-time で無効にできます。フックを使ったパス自体をスキップするには --no-tile-time --no-power を指定します（NPU 実行を繰り返すため、低速なモデルでは所要時間がおよそ 2 倍になります）。
TPU エネルギー	デフォルトで有効です。確認は不要です。同じフック付きパスの電力指標（TPU レールの推論あたりのエネルギー）です。--no-power でスキップできます。電力フックの修正より前のディスパッチライブラリを使う場合、スクリプトは電力計測を無効にし、その理由を伝えます。
コンパイルモード	デフォルトはローカル Linux x86_64 です。ホストが Linux x86_64 以外（macOS／Windows／ARM）の場合、またはユーザーが Google Colab でのコンパイルを希望する場合は --colab を使用します。実行前に Beta tarball のパス（--sdk-tarball／GOOGLE_TENSOR_SDK_BETA）または URL（--sdk-url／GOOGLE_TENSOR_ML_SDK_URL）を確認してください。
コンパイラーフラグ	デフォルトではコンパイラーの既定値を使用します。フラグを指定するのは、ユーザーから求められた場合、または問題のトラブルシューティングに必要な場合のみです（references/compile-flags.md を参照）。
アプリのデプロイレベル	パッケージ化ジョブのみが対象です。事前確認は不要です。手順 5 の後で、計画の準備ができたこと（INTEGRATION.md、更新の場合は UPDATE.md）を伝え、プロジェクトに適用するか確認してください（手順 6）。その後、Pixel にアプリをインストールし、NPU が使われていることを確認するか提案してください（手順 7）。
新規統合または更新	パッケージ化ジョブのみが対象です。アプリがすでに Google Tensor ビルドを同梱しているか（src/main/assets 配下に model#group_Google_Tensor_G5 のようなフォルダーがある AI パック）確認してください。同梱している場合は更新（手順 5b）なので、プロジェクトルート（settings.gradle.kts または settings.gradle があるフォルダー）を確認します。パック、モデルファイル、デバイスグループ、配信モード、アプリモジュールはプロジェクトから取得するため、これらは確認しないでください。
パッケージ化するビルド	対象 SoC ごとにコンパイル済みビルドを 1 つ（Tensor_G5、Tensor_G6）、およびそのビルド元の未コンパイルの元のモデル（アプリの CPU パス）が必要です。不足している対象のビルドは先にコンパイルしてください（手順 2）。ビルドは SoC ごとに必要なため、Pixel 11 には Tensor_G6 ビルドが必要です。更新の場合は、アプリがすでに同梱しているすべての SoC のビルドが必要です。
配信モード	新規統合のみが対象です（更新ではアプリの既存設定を維持します）。Google Play がモデルをスマートフォンにインストールする方法として、install-time（デフォルト。アプリと同時にインストールされ、初回起動時から使用可能）、fast-follow（インストール直後にダウンロード）、on-demand（アプリから要求されたときにダウンロード）があります。それぞれを 1 文で説明し（references/app-integration.md）、ユーザーに希望がない場合はデフォルトを使用します。
パック名／モデル名、アプリモジュール	新規統合のみが対象です。デフォルトは、パック名が元のファイル名を有効な名前にしたもの、モデル名がパック名、アプリモジュールが app、Kotlin パッケージが com.example.litert です。ユーザーのプロジェクトと異なる場合（別のアプリモジュール名、ユーザー独自のパッケージ）のみ確認してください。
クイックテスト（省略可能）	新規統合のみが対象です。bundletool の設定前に自分の Pixel でモデルを試したい場合に提案してください。--quick-test を指定すると、各ビルドのコピーと ./gradlew installDebug -PtensorQuickTest=<SoC> の手順が追加され、ビルドと NPU ランタイムがデバッグ APK に含まれます。ローカルテストのみが対象で、リリースビルドには影響しません。

コマンドまたは計画のみ（ユーザーが何も実行しないよう指示しています）

何も実行しないでください。読み取り専用のスクリプトも実行しないでください。実際に実行した場合と同じ手順を、同じ順序で、ユーザーが貼り付けて実行できるコマンドとして提示してください。

1. すべての入力モデルに対して、インストールやコンパイルのコマンドより先に check_compiled.py を実行する手順を示してください（ステップ 1）。コンパイル済みの出力だけを後から確認しても不十分です。
2. インストールについては、インストールに必要なコマンドを生成するコマンドとして python3 SKILL_DIR/scripts/compile_model.py --print-install [--colab] を提示してください（ステップ 2a）。次に、ユーザーのパスを入れた状態の出力行（仮想環境、pip install の前に実行する export GOOGLE_TENSOR_SDK_BETA=<their tarball>）を示し、各バージョンは <version printed by --print-install> としてください。versions.json や記憶からバージョン番号を転記してはいけません。
3. 結果は、推定も含めて一切提示しないでください。レイテンシ、速度向上、メモリ、オフロードされた演算数は、スクリプトの出力からのみ提示できます。結果がどこに表示されるかを説明してください（ベンチマークの場合は、benchmark_on_device.py が出力し、report.md として保存する表です）。
4. 計画がユーザーのアプリプロジェクトに変更を加える場合（ステップ 6）、ユーザーが承認するまでプロジェクトには何も変更されないと伝え、最後に適用するかどうかを尋ねてください。

ステップ 1 - モデルがすでにコンパイル済みか確認する

python3 SKILL_DIR/scripts/check_compiled.py /abs/path/model.tflite [--expect-target Tensor_G5]

関連するすべてのモデルファイル（コンパイルまたはベンチマークするモデル、CPU ベースラインファイル、再利用しようとしている既存の出力ファイル）に対して実行します。ベンチマークジョブでは、まずスマートフォンを確認し（adb shell getprop ro.soc.model を実行すると Tensor G5 または Tensor G6 が表示されます）、アンダースコア形式を --expect-target に渡します（Tensor G5 -> --expect-target Tensor_G5）。これにより、「コンパイル済みか」と「このスマートフォン用か」の両方を一度に確認できます（通常のモデルはどちらの場合も終了コード 1 になります）。ベンチマークスクリプトでも再度一致を検証します（終了コード 4）。

終了コード	意味	次のアクション
0	Google Tensor 用にコンパイル済み（SoC が表示されます）	コンパイルをスキップし、SoC を報告します（.compile.json サイドカーファイルがあれば、Compile info の行も報告します）。目的にベンチマークが含まれる場合のみ、ステップ 3 に進みます。サイドカーファイルがない場合（別の場所でコンパイルされ、フラグが不明）：単に「どれくらい速いか」を知りたいジョブでは、そのままファイルをベンチマークし、「コンパイルフラグは不明です」と伝えます。ユーザーがビルド方法を知りたい場合（または再現可能な比較を希望する場合）は、新しい --output-name を指定して元のモデルをデフォルト設定でコンパイルし、SHA-256 を比較します（両方のファイルに対する sha256sum、または新しいサイドカーファイルの output_sha256）。コンパイルは決定的なので、ハッシュが一致すれば、既存のファイルがデフォルト設定でビルドされたことを確認できます（references/compile-flags.md）。確認のために --overwrite を使用してはいけません。
1	通常の（未コンパイル）モデル	コンパイルする場合はステップ 2 に進みます。これは --cpu-baseline に指定する正しいファイルです
2	--expect-target とは異なる SoC 用にコンパイル済み	コンパイル済みモデルは SoC 固有です（Tensor_G5 ファイルは Tensor_G6 TPU では実行できず、Tensor_G6 ファイルは Tensor_G5 TPU では実行できません。実行時のフォールバックはなく、--allow-mismatch を指定してもディスパッチエラーが発生するだけです）。スマートフォンの SoC をユーザーに伝え、次の順に選択肢を提示します。同じモデルをこのプロジェクト内でビルドした既存の *_Google_<phone target>.tflite（まずこの確認を実行して検証し、ユーザーの許可なしにベンチマークしないこと）、対象に合ったスマートフォンの接続、または元の未コンパイルのエクスポートをスマートフォンのターゲット向けに再コンパイルすること。
3	.tflite 形式ではない／見つからない	パスを修正します
4	別のツールチェーンでコンパイル済み：LiteRT の DISPATCH_OP ではなく、Edge TPU のカスタム演算子（edgetpu-custom-op...）を使用	ここでは使用できません。LiteRT では再コンパイルできず、Google Tensor TPU 上でも実行できません。また、CPU でも実行できないため、--cpu-baseline や --fallback にも使用できません（スクリプトでも拒否されます）。コンパイル元のモデルを依頼し、それをコンパイルします（ステップ 2）

LiteRtStamp が正式な判定基準です（_Google_Tensor_G5 サフィックスは命名規則にすぎません）。SoC は記録されますが、コンパイラフラグは記録されません。フラグは compile_model.py が出力ファイルの隣に書き込む <model>.compile.json サイドカーファイルに記録されます。このファイルがない場合は、推測せず「フラグは不明です」と伝えてください。

ステップ 2 - コンパイルする（Linux x86_64 または --colab を使用する Google Colab）

2a. 初回の環境設定

SDK の pip パッケージにはコンパイラー自体は含まれていません。インストール時に、GOOGLE_TENSOR_SDK_BETA が指す Beta tarball を展開します（公開 codelab と同じ手順です）。最初に tarball のパスをユーザーに尋ねてから、versions.json でスキルが指定している LiteRT バージョンのインストールコマンドを表示します。

python3 SKILL_DIR/scripts/compile_model.py --print-install [--colab]

ローカル Linux x86_64（--print-install）：任意の python3 で実行でき、コメント行（指定バージョン、最終確認日時と環境、対応する Python の範囲、このホストと Python が条件を満たすかどうか）に続いて、次の内容が表示されます。

python3 -m venv ~/.venvs/litert-tensor && source ~/.venvs/litert-tensor/bin/activate
pip install --upgrade pip
export GOOGLE_TENSOR_SDK_BETA=/abs/path/litert_plugin_compiler.tar.gz   # from the Beta e-mail
pip install --no-cache-dir ai-edge-litert==<pinned> ai-edge-litert-sdk-google-tensor==<pinned>

リモートの Google Colab（--print-install --colab）— macOS、Windows、x86 以外の Linux、またはローカルの Linux venv を使わず Colab でコンパイルする場合：google-colab-cli を ~/.venvs/colab-cli にインストールします（--colab の仕組み）。OAuth のためにターミナルコマンドを実行するようユーザーに求めないでください。--colab で初回の OAuth が必要な場合は、表示された URL をチャットに提示してユーザーにコードを尋ね、--colab-auth-code <CODE> を付けて再実行します。

• 何かをインストールする前に、ユーザーに伝えてください。実際の tarball パスを指定して、表示されたコマンドを実行し、LiteRT のバージョンを自分で入力しないでください。ランタイムと SDK のパッケージは同じバージョンである必要があります（異なる場合は WARNING、互いには一致するが指定バージョンと異なる場合は NOTE が表示されます）。ユーザーが明示的に nightly を求めた場合に限り、-nightly パッケージを使用します。
• --print-install で Python のバージョンに関する警告が表示された場合は、対応範囲内の python3.N を使って venv を作成します。インストールエラーについては、references/troubleshooting.md を参照してください。

ユーザーがまだ Beta にアクセスできない場合： その旨を明確に伝えてください。Google から tarball のリンクがメールで届くまで（上記の登録フォームから申し込み）、コンパイラーはインストールできません。その間は何もインストールせず、Colab VM も割り当てないでください（--colab は colab new の前に tarball を確認します）。今すぐできることとして、ユーザーのファイルに対して check_compiled.py を実行し、ホストとスマートフォンの SoC を確認して、--dry-run／--print-install を実行してください。

2b. コンパイル

# Local Linux x86_64 (using the virtualenv's interpreter):
python3 SKILL_DIR/scripts/compile_model.py /abs/path/model.tflite \
  --target Tensor_G5 --output-dir /abs/path/compiled

# Remote Google Colab VM (any OS, any local python3 + google-colab-cli):
python3 SKILL_DIR/scripts/compile_model.py /abs/path/model.tflite \
  --target Tensor_G5 --colab --sdk-tarball /abs/path/litert_plugin_compiler.tar.gz \
  --output-dir /abs/path/compiled
# -> /abs/path/compiled/model_Google_Tensor_G5.tflite

スクリプトはコンパイルレポートを表示し、Tensor のスタンプを再検証して、<output>.compile.json（フラグ、オフロードされた演算子数／合計数、パッケージのバージョン、SHA-256）を書き込みます。また、--overwrite が指定されていない限り、既存の出力を上書きしません（終了コード 2）。レポートで CPU に残っている演算子がある場合、厳密な NPU ベンチマークは失敗します（手順 3、--allow-cpu-fallback）。コンパイラー、スクリプト、Colab のすべてのオプションについては、references/compile-flags.md を参照してください。

• コンパイラーが内部エラーでクラッシュした場合、またはデフォルト設定でクラッシュしたとユーザーから報告された場合（クラッシュを再現する必要はありません）は、公開 FAQ の案内に従って --truncation-type half --sharding-intensity maximum を使用し、どのフラグで成果物が生成されたかをユーザーに伝えてください。half は数値精度を変えるため（TPU 上で 16 ビット浮動小数点数を使用）、このモデルを頼りにする前に、出力を元のモデルと照合して検証するようユーザーに伝えてください。

• コンパイルのみのジョブについては、スクリプトの出力とサイドカーの情報だけを使って報告してください。

  **コンパイル済み：** <出力パス>（"Compiled model written to" 行の <バイト数>）
  **ターゲット／フラグ：** <サイドカーの cli_flags、または "--target X (compiler defaults)">
  **オフロードされた演算子：** <"Ops offloaded to the TPU" 行の <N / M>>
  **LiteRT：** <サイドカーの "packages" に、スクリプトで表示された WARNING／NOTE 行があれば追加>
  **検証済み：** check_compiled.py -> <その Status 行>
  

終了コード：0 成功、2 入力不正、3 コンパイル済み、4 非対応のホスト、5 LiteRT パッケージまたは Beta コンパイラーライブラリが見つからない（メッセージにインストール方法を含む）、6 コンパイル失敗（コンパイラーのログエラーを表示）、7 出力の検証失敗。

ステップ 3 - デバイスでベンチマークを実行する

python3 SKILL_DIR/scripts/benchmark_on_device.py \
  --model /abs/path/compiled/model_Google_Tensor_G5.tflite \
  [--cpu-baseline /abs/path/model.tflite] [--serial SERIAL] \
  [--dispatch-lib /abs/path/libLiteRtDispatch_GoogleTensor.so] \
  [--output-dir /abs/path/results]

このスクリプトは、スマートフォンとは異なる SoC 用にコンパイルされたモデルを拒否します（終了コード 4。--dry-run はスマートフォンに接続しないため、SoC が一致するかどうかの証明にはなりません）。versions.json のバケットリリースから benchmark_model と libLiteRtDispatch_GoogleTensor.so を一度取得し（キャッシュされます。downloaded from <url> は初回ダウンロードを意味するため、何を取得したかをユーザーに伝えてください）、厳密な NPU ベンチマーク、TPU タイル時間と TPU エネルギーを計測するフック付きの 2 回目の NPU 実行、およびオプションの CPU ベースラインを、コンパイルされていないモデルに対して、新しい /data/local/tmp/litert_benchmark/run-* ディレクトリで実行します。このディレクトリは失敗時も含めて削除されます。結果は --output-dir に report.md、results.json、ログとして書き込まれます（終了コード 2／3／4 または --dry-run の場合は何も書き込まれません）。各ステップとフラグについては、references/benchmark-flags.md を参照してください。

このスクリプトは設計上、NPU 専用です（--extra-arg でアクセラレーターを切り替えることはできず、コンパイルされていないモデルは終了コード 2 で拒否されます）。GPU または非 Tensor の実行（benchmark_model --use_gpu=true などを直接実行する場合）は、このスキルの対象外です。その他のオプション（--num-runs、--performance-mode、--signature、--allow-cpu-fallback、--no-tile-time、--no-power など）は --help に記載されています。

• オフラインのホスト： --benchmark-bin と --dispatch-lib の両方を指定してください。そのうえで --dry-run を実行すると、スマートフォンにもネットワークにも接続せずに、両方のバイナリについて user-provided: <path> が表示されます。これは、ユーザーが最初に求めている証明です。
• バイナリのバージョン： benchmark_model とディスパッチライブラリは、同じバケットリリースのものを使用してください（デフォルトではそうなります。--benchmark-url .../binaries/<release>/android_arm64/benchmark_model で別のリリースを指定すると、ディスパッチの URL もそれに合わせて切り替わります）。由来情報の md5 が versions.json の verified.binaries と異なる場合は、--refresh-binary を指定して再実行してください（詳細）。

ステップ 4 - レポート

レポートに手入力する内容はありません。benchmark_on_device.py は Markdown の見出しと表を出力します（report.md と、results.json の markdown フィールドにも保存されます）。すべての値はデバイスまたは実行結果から読み取られたものです。このブロックをそのまま貼り付け、スクリプトでは把握できないコンテキストだけを追加してください。

**Summary:** <NPU "Inference avg" from the table> ms on the TPU vs <CPU "Inference avg"> ms on the CPU (<the N.NNx value from the script's "NPU speed-up vs CPU" line>); peak memory <NPU> vs <CPU> MB; <strict NPU | CPU fallback allowed>. TPU tile time <"TPU tile time / inference" row> ms per inference. TPU energy <"TPU energy / inference" row> mJ per inference.

<header and table exactly as printed by benchmark_on_device.py, including any "Unexpected log lines" section>

**Notes:** <what the Log check line reports: "none" when both logs show 0 unexpected lines and no profiler retry; otherwise each unexpected line with its meaning from references/benchmark-flags.md or troubleshooting.md, plus anything the user should validate>

何も実行されなかった場合（チェックの終了コード 2、ベンチマークの終了コード 2／3／4／5、デバイスなし）も、記憶ではなく出力に基づいて、同じ方法で報告してください。

**Not run:** <the script's ERROR line verbatim>

- Device: <the "Device: ..." line printed by benchmark_on_device.py, or the `adb devices -l` line>
- Model: <the "Status: ..." line from check_compiled.py>
- Nothing was pushed to or removed from the phone.

**Options:** <the next actions from step 1 / troubleshooting, most specific first>

• 数値を入力、丸め、または「整形」してはいけません。また、このスキルの以前の実行や例の値を再利用してはいけません。スクリプトの出力をそのままコピーしてください。文章中の数値（Summary 行）は、表の値と一字一句同じでなければなりません。report.md（スクリプトの出力）は編集しないでください。ユーザーが回答を保存したい場合は、その隣に summary.md を作成してください。
• Summary と Notes を書く前に、レポートの作成を読んでください（CPU ベースラインなし、コンパイルとベンチマークの同時実行、実行回数、CPU フォールバック、LiteRT リリースの混在、1 倍未満の高速化、TPU タイル時間／エネルギー）。

ステップ 5 - アプリ向けにパッケージ化する（Gradle）

2 つのケース（ステップ 0「新規統合または更新」）について、パッケージに含まれるものと スクリプトによる確認方法は、references/app-integration.md を参照してください。

• 5a - 新規統合： LiteRT 独自のエクスポーターが、元のファイルからそのまま作成した AI パック（バイト単位で同一で、再コンパイルなし）、Google Maven から取得するインストール時機能モジュールとしての Google Tensor NPU ランタイム、アプリの CPU パス用の元のモデル、Kotlin ローダー、およびユーザーのプロジェクトで残っているすべての手順を記載した INTEGRATION.md。
• 5b - 更新（アプリがすでに Google Tensor ビルドを同梱している場合）： --update-project はプロジェクトを読み取り、アプリ独自のパスと名前で置き換えるファイルと、 UPDATE.md のみを準備します。

# 5a -> <fallback dir>/app_package/<pack name>/INTEGRATION.md and the modules
<venv>/bin/python SKILL_DIR/scripts/package_ai_pack.py \
  --compiled /abs/path/compiled/model_Google_Tensor_G5.tflite \
  [--compiled /abs/path/compiled/model_Google_Tensor_G6.tflite] \
  --fallback /abs/path/model.tflite \
  [--delivery install-time|fast-follow|on-demand] [--pack-name NAME] \
  [--model-name NAME] [--app-module app] [--kotlin-package com.example.litert] \
  [--quick-test] [--output-dir /abs/path/app_package/NAME]

# 5b -> <fallback dir>/app_update/<pack>/UPDATE.md, update.json, files/<paths>
<venv>/bin/python SKILL_DIR/scripts/package_ai_pack.py \
  --update-project /abs/path/to/app-project \
  --compiled /abs/path/compiled/model_Google_Tensor_G5.tflite \
  [--compiled /abs/path/compiled/model_Google_Tensor_G6.tflite] \
  --fallback /abs/path/model.tflite \
  [--pack-name NAME] [--model-name NAME] [--cpu-asset PATH|none]

1. まずすべてのファイルに対して check_compiled.py を実行し（ステップ 1）、厳格なベンチマークに合格したビルドをパッケージ化します（ステップ 3）。
2. まず --dry-run を実行し（任意の python3 を使用）、その後 ai-edge-litert がインストールされた Python で実際に実行します。スクリプトは入力の不一致を拒否し、自身が書き込んでいないディレクトリを置き換えることはありません。
3. 5b では、判定結果とファイル一覧をユーザーに示します。drop-in（モデルファイルのみ変更）、structural（UPDATE.md のセクション 2 にその他の変更を記載。変更を列挙し、ほかの作業に進む前に対応方法を尋ねてください）、または up-to-date のいずれかです。Runtime の device チェックは、新しいビルドがアプリ独自のランタイムライブラリで厳格なベンチマークに合格する必要があることを意味します（UPDATE.md のセクション 4）。
4. スクリプトの **Packaged:** ... または **Update plan:** ... ブロックをそのまま貼り付け、1 行を追加します（提供方法、または判定結果を平易な言葉で示し、「次の手順：<output-dir>/INTEGRATION.md」または UPDATE.md と記載）。そのうえで、次のように尋ねます。「統合計画の準備ができました（INTEGRATION.md）。プロジェクトに適用しますか？」（または「更新計画の準備ができました（UPDATE.md）。...」）。はいの場合はステップ 6 に進みます。Google Play への公開はユーザーが行います。

終了コード：0 成功、2 不正な入力（ファイルがない、SoC が重複している、名前が無効、出力先が存在する、ビルドとサイドカーファイルが異なる、またはプロジェクトを --update-project でそのまま更新できない）、3 モデルの種類が不正（--compiled に未コンパイルのモデルを指定、--fallback にコンパイル済みモデルを指定）、5 LiteRT をインポートできない、またはエクスポーター API が変更された（メッセージに修正方法が記載されています）、7 エクスポート後の検証に失敗（--output-dir には何も残りません）。

ステップ 6 - ユーザーのプロジェクトに計画を適用する（ユーザーが承諾した場合）

計画を適用します。ユーザーから承認を得るのは 1 回です。変更を加える前に、計画全体を示し、1 回の承認を得てください。その後、リスクのある項目ごとに個別に確認します（チェック時に該当項目が示されます）：Android Gradle プラグインまたは Kotlin のアップグレード、Kotlin の追加、minSdk の引き上げ、アプリを arm64-v8a に限定すること（対応していないデバイスにはアプリをインストールできなくなります）、アプリの LiteRT バージョンの変更、パッケージ内のファイルと異なるプロジェクトファイルの置き換え、SoC の削除。項目が承認されなかった場合はスキップし、その項目がないと動作しない内容を説明します。

• 6a - 新規統合： 計画は、読み取り専用チェック（任意の python3 を使用し、LiteRT は不要）の fail 項目と、それぞれの修正方法です：

  python3 SKILL_DIR/scripts/package_ai_pack.py --check-project /abs/path/to/app-project \
    --package <output-dir of step 5a> [--app-module app] [--json]
  

• 6b - 更新： 計画は UPDATE.md（ファイルの表とセクション 2）です。

references/app-integration.md の 手順に従ってください（バックアップ、プロジェクト独自のスタイルに合わせて変更を統合、再チェック、ビルドを 1 回）。無関係なコードを削除したり、フォーマットし直したりしないでください。また、署名設定には手を加えないでください。

ステップ 7 - Pixel にインストールして確認する（ユーザーが同意した場合）

ユーザーのアプリをビルドし、Google Play と同じ方法で接続中の Pixel にインストールし（スマートフォンのデバイスグループ向けの bundletool ローカルテスト）、ローダーの LITERT_TENSOR_RESULT 行を読み取ります。

python3 SKILL_DIR/scripts/install_and_verify.py --project /abs/path/to/app-project \
  [--app-module app] [--variant debug|release|<flavor>Debug] [--serial <id>] \
  [--uninstall-first] [--dry-run]

まず --dry-run を実行します。スマートフォン、デバイスグループ、NPU の経路が想定されているかどうかが表示されます。終了コード 7 は、アプリがすでにインストールされており、ローカルテストでは更新できないことを意味します。ユーザーに確認してから（アンインストールするとスマートフォン上のアプリデータが削除されます）、--uninstall-first を指定して再実行してください。アプリは TensorModelLoader.load() を呼び出す必要があります。特定の画面でモデルを読み込む場合は、スクリプトが待機している間にその画面を開くようユーザーに伝えてください。スクリプトのブロックをそのまま報告してください。"path":"npu" が成功を示します。アプリをビルドできるスマートフォンで "path":"cpu" と表示された場合、npu_error に理由が示されます。要件と終了コードについては、references/app-integration.md を参照してください。

ルール

• コンパイルまたはベンチマークを行う前に、対象となるモデルファイルすべてについて、必ず check_compiled.py を実行してください。コンパイラーはコンパイル済みモデルを再コンパイルできず、TPU は未コンパイルのモデルを実行できません。
• デバイスの SoC がモデルのスタンプと一致していることを必ず確認してください（ベンチマークスクリプトが確認します）。Tensor_G5 モデルを Tensor_G6 のスマートフォンで使うと、不明瞭なディスパッチエラーが発生し、デバッグに余計な手間がかかります。
• --cpu-baseline には、必ず元の未コンパイルモデルを使用してください。コンパイル済みモデルには、NPU でしか実行できない DISPATCH_OP ノードが含まれています。
• 実行ごとのデバイスディレクトリは必ずクリーンアップしてください（自動で行われます。実行が中断された場合は、まずベースディレクトリの内容を一覧表示し、その後 run-* エントリーのみを削除します：adb shell ls -la <base> と adb shell rm -rf <base>/run-*。<base> は /data/local/tmp/litert_benchmark または使用した --device-dir です）。ベースディレクトリ自体を rm -rf で削除してはいけません。ユーザーが独自のバイナリやモデルをそこに保存している場合があります。
• --use_cpu=true と --require_full_delegation=true を同時に指定してはいけません。この組み合わせでは benchmark_model が異常終了します。
• システムのインタープリターにパッケージをインストールしたり、ユーザーに伝えずにインストールしたりしてはいけません。LiteRT の固定バージョンが他の作業に影響しないよう、仮想環境を使用してください。
• インストールコマンドやダウンロード URL に LiteRT のバージョン番号を自分で入力してはいけません。compile_model.py --print-install とスクリプトのデフォルト URL から取得してください。いずれも versions.json を参照するため、すべてのジョブで、組み合わせて検証済みのバージョンを使用できます。別のリリースを使用するのは、ユーザーから求められた場合のみです（--benchmark-url、またはそのバージョンの pip ペアを指定します）。その場合は、レポートにその旨を記載してください。固定バージョンの変更はメンテナーの作業です（references/contributing.md）。
• macOS、Windows、または ARM のホストをコンパイルの妨げとみなしたり、ブラウザーから手動で Colab ノートブックを操作する手順を案内したりしてはいけません。compile_model.py --colab を直接実行してください。
• adb、ベンチマーク、または Colab VM のセッションをバックグラウンドで実行したままにしてはいけません。ここでの各コマンドにはタイムアウトが設定されており、次のステップに進む前に終了します（compile_model.py --colab は、--keep-colab-session を指定しない限り、作成した Colab VM を停止します）。
• コンパイルフラグを推測したり、確認せずに既存の出力を上書きしたりしてはいけません（compile_model.py は終了コード 2 で終了します。--output-name を使用するか、--overwrite の前に確認してください）。
• アプリ向けのパッケージ化には、必ず package_ai_pack.py を使用してください（LiteRT のエクスポーターを呼び出して、結果を検証します）。アプリがすでに Google Tensor ビルドを出荷している場合は、--update-project（ステップ 5b）も使用してください。AI パックのフォルダー、デバイスターゲット設定の XML、ランタイムモジュールを手動で作成または編集してはいけません。また、新しいパッケージの ai_packs/ を既存のパックにコピーしてはいけません。アプリのグループ名や CPU コピーの配置場所が異なる場合があります。
• ユーザーのプロジェクトを変更する前に、必ず計画全体を提示して承認を得てください。リスクのある項目（ステップ 6）ごとに個別に確認し、install_and_verify.py --uninstall-first の実行前にも確認してください。署名設定は絶対に変更してはいけません。
• コンパイル済みビルドを、アプリが CPU で実行する場所（ベースアセット、--fallback）に配置してはいけません。配置できるのは元の未コンパイルモデルのみです。
• ユーザーに代わって Google Play に公開したり、署名したり、何かをアップロードしたりしてはいけません。このスキルの範囲は、パッケージ化とローカルテストの手順までです。

トラブルシューティング

スクリプトのエラーにはそれぞれ修正方法が記載されています。references/troubleshooting.md で、エラーの行または終了コードを確認してください。

公開資料

LiteRT NPU ガイド、 LiteRT を使用した Google Tensor、 コンパイルフラグ、 Tensor SDK のよくある質問、 リリースノート／互換性、 benchmark_model、 ハンズオンラボ、 オンデバイス AI 向け Google Play。

貢献

このスキルまたはその参考資料に貢献、あるいは変更を加える場合は、 変更を行う前に貢献ガイドラインに従ってください。