litert-google-tensor

Google Tensor 上的 LiteRT：为应用编译、基准测试和打包

适用于 Pixel TPU 的三种可脚本化工作流：

1. 使用公开的 LiteRT Python API（ai_edge_litert.aot），在本地 Linux x86_64 上，或在 Google Colab 虚拟机上（通过 --colab 和 google-colab-cli），将普通的 .tflite 编译为 Google Tensor AOT 编译版 .tflite。适用于使用 macOS/Windows 或没有 Linux 设备的用户。
2. 使用 LiteRT 的 benchmark_model 在已连接的 Pixel 上对编译后的模型进行 基准测试，仅使用 NPU；还可选择与 CPU 基线对比，并包含 TPU 瓷块耗时（纯 TPU 计算时间）和每次推理的 TPU 能耗。
3. 为 Android（Gradle）应用将编译后的构建打包为 Google Play AI 包，其中包含 Google Tensor NPU 运行时和 Kotlin 加载器（或者，对于已随应用发布 Google Tensor 构建版本的情况，仅提供需要替换的文件）；在用户同意后将方案应用到 项目，并在 Pixel 上检查应用。

所有操作都在用户的终端中同步运行；脚本不会启动后台进程，并且始终会清理推送到 手机上的内容或在 Colab 上分配的资源。以下所有路径均相对于此技能的目录 （SKILL_DIR）。

路径	用途
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 模块，或更新现有 AI 包
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 的操作。本地编译（不带 --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）	-	-
主机操作系统	Linux x86_64，>= 16 GB RAM	任意操作系统（colab CLI 位于 PATH 上；在远程 Colab Linux x86_64 VM 上运行）	任意安装了 adb 的操作系统	任意可安装 ai-edge-litert 的操作系统（编译 venv 的 Linux x86_64 主机可用）
Python 环境	本地 venv，安装 versions.json 中指定版本的 ai-edge-litert + ai-edge-litert-sdk-google-tensor（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，Pixel 10/11 已启用 USB 调试	-	-	必需	第 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 文件的绝对路径。确认文件存在。
目标	仅检查、仅编译、仅基准测试、编译 + 基准测试，或为应用打包（步骤 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。当需要在已有文件旁生成第二个构建文件时，将其命名为 <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 单元时间	默认启用，无需询问：会进行第二次带钩子的 NPU 运行。使用 --no-tile-time 可关闭；仅当使用 --no-tile-time --no-power 时，才会跳过带钩子的运行本身（它会重复 NPU 运行，因此慢速模型耗时大约会翻倍）。
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 构建版本（AI 包在其 src/main/assets 下包含类似 model#group_Google_Tensor_G5 的文件夹）。如果已发布，则属于更新（步骤 5b）：询问项目根目录（包含 settings.gradle.kts 或 settings.gradle 的文件夹）。资源包、模型文件、设备组、交付模式和应用模块随后均从项目中获取，因此无需询问这些信息。
待打包的构建	每个目标 SoC（Tensor_G5、Tensor_G6）各需一个已编译构建，以及编译它们时使用的未编译原始模型（应用的 CPU 路径）。先编译缺少的目标（步骤 2）；构建版本按 SoC 区分，因此 Pixel 11 需要 Tensor_G6 构建。更新时，为应用已发布的每个 SoC 构建版本。
交付模式	仅适用于新集成（更新沿用应用现有设置）。当 Google Play 将模型安装到手机上时：install-time（默认；随应用安装，首次启动时即可使用）、fast-follow（安装后立即下载）或 on-demand（应用请求时下载）。用一句话解释每种模式（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 sidecar 文件，也报告 Compile info 行）。只有目标包含基准测试时，才继续步骤 3。没有 sidecar 文件（在其他位置编译，标志未知）：如果只是要了解速度，则直接对该文件进行基准测试，并说明“编译标志未知”；如果用户需要了解构建方式（或希望进行可复现的比较），则使用默认值将原始模型编译到新的 --output-name，并比较 SHA-256（对两个文件运行 sha256sum，或查看新 sidecar 中的 output_sha256）：编译过程具有确定性，因此哈希值相同即可证明现有文件是使用默认值构建的（references/compile-flags.md）。切勿通过 --overwrite 来确认。
1	普通（未编译）模型	如果要编译，则转到步骤 2；这是 --cpu-baseline 的正确文件
2	已编译，但目标 SoC 与 --expect-target 不同	已编译模型因 SoC 而异（Tensor_G5 文件无法在 Tensor_G6 TPU 上运行，Tensor_G6 文件也无法在 Tensor_G5 TPU 上运行；没有运行时回退，且 --allow-mismatch 只会产生调度错误）。告知用户手机的 SoC，然后按以下顺序提供选项：使用项目中同一模型现有的 *_Google_<phone target>.tflite 构建（先用此检查进行验证；除非用户提出要求，否则不要对其进行基准测试）、连接匹配的手机，或为该手机的目标 SoC 重新编译原始未编译导出文件。
3	不是 .tflite 文件 / 文件缺失	修正路径
4	由其他工具链编译：使用了 Edge TPU 自定义操作（edgetpu-custom-op...），而不是 LiteRT 的 DISPATCH_OP	此处不可用：LiteRT 无法重新编译，也无法在 Google Tensor TPU 上运行；CPU 也无法运行它（因此它也不能作为 --cpu-baseline 或 --fallback；脚本会拒绝此文件）。请索取用于编译它的原始模型，并对其进行编译（步骤 2）

LiteRtStamp 是权威依据（_Google_Tensor_G5 后缀只是命名惯例），它会记录 SoC，但不会记录编译器标志：这些信息来自 compile_model.py 在输出文件旁写入的 <model>.compile.json sidecar 文件；如果没有该文件，应说明“标志未知”，而不是猜测。

步骤 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，或在 Colab 上编译但没有本地 Linux venv 的情况：将 google-colab-cli 安装到 ~/.venvs/colab-cli （了解 --colab 的工作方式）。 绝不要要求用户在终端中运行 OAuth 命令：如果 --colab 需要一次性 OAuth，请在聊天中显示打印出的 URL，询问用户验证码，然后使用 --colab-auth-code <CODE> 重新运行。

• 安装任何内容之前，先告知用户。使用真实的 tarball 路径运行打印出的命令，绝不要自行填写 LiteRT 版本：运行时和 SDK 包必须是同一版本（版本不同时显示 WARNING；版本相同但与固定版本不同时显示 NOTE）。只有用户明确要求使用夜间版时，才使用 -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），并且绝不会覆盖已存在的输出（退出码 2），除非指定 --overwrite。报告中仍留在 CPU 上的运算意味着严格的 NPU 基准测试会失败（步骤 3，--allow-cpu-fallback）。所有编译器、脚本和 Colab 选项请参阅：references/compile-flags.md。

• 如果编译器因内部错误崩溃，或用户报告使用默认设置时发生过这种情况（无需重现崩溃），请使用 --truncation-type half --sharding-intensity maximum（公开 FAQ 中的建议），并告知用户生成该产物时使用了哪些标志。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 与手机的 SoC 不同，脚本会拒绝运行（退出码为 4；--dry-run 从不连接手机，因此无法证明两者匹配），并从 versions.json 中的存储桶发布版本一次性获取 benchmark_model 和 libLiteRtDispatch_GoogleTensor.so（会缓存；downloaded from <url> 表示首次下载——请告知用户获取了什么），运行严格的 NPU 基准测试，再进行一次挂钩的 NPU 测试，以获取 TPU 瓦片时间和 TPU 能耗，并在全新的 /data/local/tmp/litert_benchmark/run-* 目录中对未编译模型运行可选的 CPU 基线测试；即使失败，脚本也会删除该目录。脚本会将 report.md、results.json 和日志写入 --output-dir（退出码为 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 和 dispatch 库必须来自同一个存储桶发布版本（默认设置会确保这一点；--benchmark-url .../binaries/<release>/android_arm64/benchmark_model 可指定其他版本，dispatch 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>

• 绝不手动输入、四舍五入或“整理”数字，也绝不重用先前运行或本技能示例中的值——请复制脚本输出。摘要行中的文字数字必须与表格中的值逐字一致。绝不要修改 report.md（脚本输出）；如果用户希望保存结果，请在其旁边写入 summary.md。
• 撰写摘要和备注前，请阅读撰写报告（无 CPU 基线、合并的编译与基准测试任务、运行次数、CPU 回退、混合 LiteRT 发布版本、低于 1x 的加速比、TPU 瓦片时间/能耗）。

步骤 5 - 为应用打包（Gradle）

两种情况（步骤 0，“新集成或更新”）；打包内容及脚本的检查方式见：references/app-integration.md。

• **5a - 新集成：**由 LiteRT 自带的导出器根据现有文件生成的 AI pack（字节完全相同，不重新编译）、作为安装时功能模块的 Google Tensor NPU 运行时（来自 Google Maven）、供应用 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:** ... 区块，再添加一行（用通俗语言说明交付模式或判定结果，并写上“下一步：<output-dir>/INTEGRATION.md”或 UPDATE.md），然后询问：“集成计划已准备就绪（INTEGRATION.md）。你要我将其应用到你的项目吗？”（或者“更新计划已准备就绪（UPDATE.md）。...”）。如果用户同意，转到步骤 6。发布到 Google Play 仍由用户负责。

退出码：0 表示成功；2 表示输入错误（文件缺失、SoC 重复、名称无效、输出已存在、构建与其 sidecar 不一致，或项目无法按原样通过 --update-project 更新）；3 表示模型类型错误（未编译却使用 --compiled，或已编译却使用 --fallback）；5 表示 LiteRT 无法导入或其导出器 API 已更改（消息中包含修复方法）；7 表示导出后验证失败（--output-dir 中不会留下任何内容）。

步骤 6 - 将计划应用到用户的项目（用户同意时）

由你应用计划；用户只需批准一次。进行任何更改前，展示完整计划并取得一次批准。然后，对于每项风险操作，分别征求同意（检查会标记这些操作）：升级 Android Gradle 插件或 Kotlin、添加 Kotlin、提高 minSdk、将应用限制为 arm64-v8a（不支持该架构的设备将无法再安装应用）、更改应用的 LiteRT 版本、替换与打包内容不同的项目文件、移除 SoC。用户拒绝某项操作时应跳过；说明不进行该操作会导致哪些功能无法使用。

• **6a - 新集成：**计划是只读检查中标记为 fail 的项目（任何 python3 均可，不需要 LiteRT），每项都附有修复方法：

  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 中的流程操作（备份、按项目自身风格合并编辑、重新检查、构建一次）。绝不删除或重新格式化无关代码，也绝不修改签名配置。

第 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 虚拟机进程在后台运行：此处的每条命令都有超时限制，并会在进入下一步前返回（除非传入 --keep-colab-session，否则 compile_model.py --colab 会停止它启动的 Colab 虚拟机）。
• 切勿猜测编译标志，也不要在未询问的情况下覆盖现有输出（compile_model.py 会以状态码 2 退出；请使用 --output-name，或在使用 --overwrite 前先征求同意）。
• 必须使用 package_ai_pack.py 为应用打包（它会调用 LiteRT 的导出器并验证结果）；如果应用已提供 Google Tensor 版本，还必须使用 --update-project（步骤 5b）。切勿手动创建或编辑 AI pack 文件夹、设备目标 XML 或运行时模块，也切勿将新软件包的 ai_packs/ 复制到现有 pack 上：应用的组名称以及 CPU 副本的位置可能不同。
• 必须先询问用户是否可以更改其项目，展示完整计划并获得一次批准；对于每项有风险的操作（步骤 6），以及使用 install_and_verify.py --uninstall-first 前，都必须另行征求同意。切勿更改签名配置。
• 切勿将编译后的构建放到应用在 CPU 上运行的位置（基础资源、--fallback）：只能放原始的未编译模型。
• 切勿代用户发布到 Google Play、签名或上传任何内容；此技能仅执行到打包和本地测试步骤为止。

故障排除

每条脚本错误都会指出修复方法；请在 references/troubleshooting.md 中查找对应的错误行或退出代码。

公开参考资料

LiteRT NPU 指南、 Google Tensor with LiteRT、 编译标志、 Tensor SDK 常见问题解答、 发行说明 / 兼容性、 benchmark_model、 实践教程、 Play 端侧 AI。

贡献

如需贡献或修改此技能或其参考资料，请在进行更改前遵循 贡献指南。