LiteRT CLI 101：简化边缘 AI 工作流程

1. 🏁 简介和 CLI 概览

欢迎参加LiteRT CLI 101 动手操作 Codelab！本指南旨在引导您从零环境设置到部署优化的边缘智能，一步步完成整个过程。

🌟 背景

边缘 AI 需要将复杂的神经模型直接引入手机、可穿戴设备和嵌入式硬件。

• LiteRT （以前称为 TensorFlow Lite / TFLite ）是 Google 的设备端框架，用于在边缘平台上高效部署高性能 ML 和生成式 AI，通过高效的转换、运行时和优化实现。
• LiteRT CLI 将 Google AI Edge 堆栈集成到独立的 Shell 命令 (litert) 中，以简化与 LiteRT 相关的开发工作流，包括在各种硬件（CPU / GPU / NPU）上跨平台（桌面设备、移动设备或云端）转换、量化、编译、运行、基准测试和可视化 LiteRT (TFLite) 模型。

2. 🔄 基本工作流：转换、量化和运行

在本部分中，我们将使用 LiteRT CLI 执行完整的边缘 AI 建模生命周期：PyTorch 模型封装容器 ➔ 跟踪转换 ➔ 模型量化 ➔ 桌面设备推断 ➔ 性能基准。

如需获得本部分的交互式 Jupyter 笔记本支持，请尝试以笔记本形式运行。

📝 第 1 阶段：准备 PyTorch 模型封装容器脚本

在当前目录中创建 resnet18.py。它会公开动态跟踪钩子，以便图表构建器可以捕获形状：

import torch
import torchvision

def get_model(batch_size: int = 1) -> torch.nn.Module:
  model = torchvision.models.resnet18(
      weights=torchvision.models.ResNet18_Weights.IMAGENET1K_V1
  )
  model.eval()
  return model

def get_args(batch_size: int = 1) -> tuple[torch.Tensor, ...]:
  return (torch.randn(batch_size, 3, 224, 224),)

🔄 第 2 阶段：使用 LiteRT Torch 将 PyTorch 模型转换为 LiteRT

调用 LiteRT Torch 转换器来构建标准 Float32 .tflite 目标模型：

# Convert PyTorch source to LiteRT
litert convert resnet18.py --output resnet18

# Verify target was exported
ls -lh resnet18/resnet18.tflite

📉 第 3 阶段：将权重量化为 INT8

应用动态配方卡和仅权重配方卡，将大小缩小约 4 倍：

# 1. Dynamic Range Quantization (Dynamic activations + static INT8 weights)
litert quantize resnet18/resnet18.tflite \
  --recipe dynamic_wi8_afp32 \
  --output resnet18/resnet18_int8_dynamic.tflite

# 2. Weight-Only Quantization (Float32 activations + static INT8 weights)
litert quantize resnet18/resnet18.tflite \
  --recipe weight_only_wi8_afp32 \
  --output resnet18/resnet18_int8_weight_only.tflite

🚀 第 4 阶段：在本地运行推断

使用虚拟输入参数执行测试操作，以验证性能块：

# Run original Float32 model inference
litert run resnet18/resnet18.tflite --desktop --cpu

# Run optimized Dynamic INT8 model inference
litert run resnet18/resnet18_int8_dynamic.tflite --cpu --iterations 1

📊 第 5 阶段：对模型性能进行基准测试

衡量高精度指标，包括平均延迟时间、初始化费用、CPU 执行吞吐量和动态活跃内存占用空间：

# Benchmark original Float32 model
litert benchmark resnet18/resnet18.tflite --desktop --cpu

# Benchmark optimized Dynamic range INT8 model
litert benchmark resnet18/resnet18_int8_dynamic.tflite --desktop --cpu

3. 🔌 本地环境设置和验证

让我们在工作站（macOS 或 Linux）上构建一个隔离的干净沙盒

我们建议使用 uv （下一代基于 Rust 的 Python 软件包管理器），以实现超快的依赖项下载和动态设置，您还可以在 Python 虚拟环境中使用标准 pip 。

🔌 选项 A：超快速设置 (uv)

使用 uv 可在几秒钟内隔离库，从而清除环境缓存冲突。

# Create active workspace sandbox
uv venv --clear --python=3.13 --seed
source .venv/bin/activate

# Install litert-cli from pypi
uv pip install litert-cli-nightly

🐍 选项 B：标准设置 (pip)

如果不存在 uv，请使用标准 Python 虚拟环境配置：

# Create active workspace sandbox
python3 -m venv .venv
source .venv/bin/activate

# Install litert-cli from pypi
pip install --upgrade pip setuptools wheel
pip install litert-cli-nightly

🛠️ 选项 C：可修改的本地设置

如果您直接在仓库源目录克隆中进行开发或测试：

# Create active workspace sandbox
uv venv --clear --python=3.13 --seed
source .venv/bin/activate

# Install from local directory root
uv pip install -e .

🔍 设置验证

验证您的路径是否正确路由 litert 命令：

litert --help

企业代理 / 私有简单索引凭据阻止程序： 如果构建安装因私有自定义索引规则而失败并显示 401 Unauthorized，请强制查找直接路由到标准 PyPI：

export UV_INDEX_URL=https://pypi.org/simple

💡 中央模型参考目录 (model-ref)

为了确保脚本和开发的稳健性，LiteRT CLI 实现了集中式模型目录：

• 格式：为下载或导入的模型分配一个唯一的名称（别名），例如 mobilenet。
• 变体：使用目标冒号引用经过优化的变体，例如 mobilenet:int8 或 mobilenet:gpu。
• 简洁性：所有 CLI 命令都直接接受此无路径的 别名，自动即时解析物理文件存储！

4. 📲 设备部署和分析

让我们通过运行高精度本地基准、部署到真实的 USB 硬件目标、实现硬件委托、提前编译和云端基准测试来进一步优化。

对于此部分，您需要连接已启用 ADB 的 Android 设备。如需在设备上启用 USB 调试，请执行以下操作：

• 依次前往设置 > 关于手机 。
• 点按版本号 7 次，直到看到“您现在处于开发者模式！”。
• 返回到设置 > 系统 > 开发者选项 （或在某些设备上依次前往设置 > 开发者选项 ）。
• 开启 USB 调试 。

📊 本地分析指标

下载 EfficientNet-B1 并分析桌面主机上的性能统计信息：

# Download and register model alias in central catalog
litert download litert-community/efficientnet_b1 --file "*.tflite" --output efficientnet
litert import efficientnet/efficientnet_b1.tflite --model-ref efficientnet_b1

# Run high-precision benchmark on desktop CPU
litert benchmark efficientnet_b1 --desktop --cpu

观察基准日志中的关键性能标头：

• Model initialization：启动结构化网络的时间。
• Warmup (avg)：编译开销时间。
• Inference (avg)：原始数学处理时间。
• Overall footprint：执行期间消耗的峰值 RAM。

📲 目标 A：移动 CPU（USB 连接）

连接已启用 USB 调试的 Android 设备，然后进行部署：

# 1. Confirm device connection
adb devices

# 2. Push and execute model on mobile CPU
litert run efficientnet_b1 --android --cpu

CLI 会自动将模型推送到目标设备，执行推理循环，并将输出管道返回！

🎮 目标 B：移动 GPU

使用 OpenCL 或 WebGPU 将繁重的工作负载动态卸载到 GPU：

# Benchmark model performance on mobile GPU
litert benchmark efficientnet_b1 --android --gpu

# Run inference with GPU acceleration and CPU fallback
litert run efficientnet_b1 --android --accelerator gpu,cpu

⚙️ 目标 C：JIT Android NPU

将执行参数直接分流到现代芯片组上的 NPU：

# Run with on-device JIT NPU acceleration
litert run efficientnet_b1 --android --accelerator npu,cpu

• 警告：设备端运行时中的动态图表构建会因初始化 JIT 预热延迟而受到严重影响。

🚀 目标 D：AOT 编译的 NPU

离线预编译以绕过运行时 JIT 开销并实现最大加速：

# 1. Offline compile for Qualcomm SM8750 NPU (Linux host)
litert compile efficientnet/efficientnet_b1.tflite --target sm8750

# 2. Execute compiled AOT binary with zero JIT warmup latency
litert run efficientnet_b1_Qualcomm_SM8750.tflite --android --npu

☁️ 云端分析 (Google AI Edge Portal)

将测试推送到 Google Cloud 设备场中的远程硬件配置文件。

# Log in to your Google Cloud project
gcloud auth login

# Push benchmark metrics to Pixel 7 CPU
litert benchmark efficientnet_b1 --gcp --device "pixel 7" --cpu --gcp-project "your-project-id"

# Push benchmark metrics to Snapdragon GPU targets
litert benchmark efficientnet_b1 --gcp --devices "pixel 7, sm-s931u1" --gpu --gcp-project "your-project-id"

5. 🧠 高级主题：LLM 和语音识别

让我们通过转换和运行大型语言模型 (LLM) 和自动语音识别 (ASR) 模型来探索高级模型。

💬 生成式 AI (LLM)

边缘 LLM 受内存限制。我们通过应用仅权重 INT4/INT8 量化来解决此问题，在将权重压缩的同时将执行通道保留在 Float32 中：

# 1. Automated download & conversion from Hugging Face
litert convert Qwen/Qwen1.5-0.5B-Chat --output models/qwen

# 2. Quantize model weights to INT4
litert convert Qwen/Qwen1.5-0.5B-Chat \
  --quantize-recipe weight_only_wi4_afp32 \
  --output models/qwen_w4

# 3. Generation once
litert lm run models/qwen/model.litertlm --prompt "Introduce San Francisco."

# 4. Interactive chat
litert lm run models/qwen/model.litertlm

🎙️ 语音处理 (ASR)

Whisper 或 Parakeet 等 ASR 模型同时具有编码器和解码器模块。我们可以使用签名密钥 对特定模块进行基准测试：

# 1. Download prepackaged Whisper-Tiny
litert download litert-community/whisper-tiny --file "whisper_tiny_30s_f32.tflite" --output "models/whisper_tiny"

# 2. Profile audio encoding
litert benchmark models/whisper_tiny/whisper_tiny_30s_f32.tflite --android --gpu --signature-key "encode"

# 3. Profile text token decoding loop
litert benchmark models/whisper_tiny/whisper_tiny_30s_f32.tflite --android --cpu --signature-key "decode"

6. 🤖 在智能体编码中使用

LiteRT CLI 对智能体友好，您可以将其直接与编码智能体集成。

以下是一些示例。将 LiteRT CLI 技能 SKILL.md 添加到编码智能体（例如 Google Antigravity）中，然后尝试使用如下提示。

💡 转换、量化、基准测试和报告提示

“下载 FP32 模型 litert-community/efficientnet_b1，将其量化为 INT8 动态范围 (–recipe dynamic_wi8_afp32)，然后在连接的 Android 设备的 GPU 上对原始 FP32 模型和新量化的 INT8 模型进行基准测试。比较平均延迟时间并报告吞吐量加速。”

💡 NPU 编译和基准测试提示

“确认我是否连接了 USB 调试 Android 设备。如果处于活跃状态，请下载 litert-community/efficientnet_b1 并针对 Qualcomm sm8750 NPU 进行离线 (AOT) 编译。将目标模型写入 ./models/compiled，将模型推送到手机，运行设备端推断，并验证零 JIT 预热延迟时间。”

7. 🚀 恭喜及后续步骤

🎉 太棒了！您已完成 LiteRT CLI 101 Codelab！

您现在已掌握边缘 ML 开发技能：

• 将 PyTorch 模型转换为 LiteRT 模型。
• 将模型权重量化为 INT4/INT8。
• 在移动 CPU/GPU/NPU 上运行模型。
• 针对 NPU 进行编译。
• 在桌面设备、移动设备和云端进行基准测试。
• 转换和运行 LLM 模型。
• 在智能体编码中使用。

🔗 资源

• LiteRT CLI：https://github.com/google-ai-edge/LiteRT-CLI
• LiteRT：https://ai.google.dev/edge/litert
• 示例: https://github.com/google-ai-edge/LiteRT-CLI/tree/main/examples