LiteRT CLI 101：簡化 Edge AI 工作流程

1. 🏁 簡介與 CLI 總覽

歡迎參加 LiteRT CLI 101 實作程式碼研究室！本指南將逐步說明如何從零開始設定環境，到部署最佳化的邊緣智慧。

🌟 背景

邊緣 AI 需要將複雜的神經網路模型直接帶入行動電話、穿戴式裝置和嵌入式硬體。

• LiteRT (舊稱 TensorFlow Lite / TFLite)：Google 的裝置端架構，可透過高效轉換、執行階段和最佳化功能，在邊緣平台部署高效能機器學習和生成式 AI。
• LiteRT CLI 將 Google AI Edge 堆疊整合至獨立的殼層指令 (litert)，簡化 LiteRT 相關的開發工作流程，包括在各種硬體 (CPU / GPU / NPU) 上轉換、量化、編譯、執行、基準化及視覺化 LiteRT (TFLite) 模型，適用於各種平台 (桌機、行動裝置或雲端)。

2. 🔄 基本工作流程：轉換、量化及執行

在本節中，我們將使用 LiteRT CLI 執行完整的 Edge AI 模型化生命週期：PyTorch 模型包裝函式 ➔ 追蹤轉換 ➔ 模型量化 ➔ 電腦推論 ➔ 效能基準。

如要以互動式 Jupyter Notebook 支援本節，請嘗試以筆記本形式執行。

📝 階段 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

公司 Proxy / 私人簡單索引憑證封鎖程式：如果建構安裝作業因私人自訂索引規則而失敗 (錯誤訊息為 401 Unauthorized)，請強制將查詢直接路由至標準 PyPI：

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

💡 中央模型參考目錄 (model-ref)

為確保指令碼和開發作業的穩定性，LiteRT CLI 實作了集中式模型目錄：

• 格式：為下載或匯入的模型指派專屬名稱 (別名)，例如 mobilenet。
• 變化版本：使用目標半形冒號參照最佳化變化版本，例如 mobilenet:int8 或 mobilenet:gpu。
• 簡單：所有 CLI 指令都會直接接受這個無路徑的 別名，並自動即時解析實體檔案儲存空間！

4. 📲 裝置部署與設定檔

讓我們進一步最佳化，方法是執行高精確度的本機基準、部署至實際的 USB 硬體目標、實作硬體委派、編譯 Ahead-of-Time，以及雲端基準測試。

在這部分，您需要連線已啟用 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 (大型語言模型)

邊緣大型語言模型受記憶體限制，為解決這個問題，我們採用「僅限權重 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，並離線 (AOT) 編譯 Qualcomm sm8750 NPU。將目標模型寫入 ./models/compiled，將模型推送至手機，執行裝置端推論，並驗證 JIT 熱身延遲時間為零。」

7. 🚀 恭喜完成課程及後續行動建議

🎉 太棒了！您已完成 LiteRT CLI 101 程式碼研究室！

您現在已具備相關技能，可掌握邊緣機器學習開發作業：

• 將 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