LiteRT CLI 101: semplifica i tuoi workflow di AI Edge

1. 🏁 Introduzione e panoramica della CLI

Ti diamo il benvenuto nel codelab pratico su LiteRT CLI 101. Questa guida è pensata per accompagnarti passo dopo passo dalla configurazione dell'ambiente zero al deployment dell'intelligenza perimetrale ottimizzata.

🌟 Sfondo

L'AI on the edge richiede di portare modelli neurali complessi direttamente su cellulari, indossabili e hardware incorporato.

• LiteRT (in precedenza TensorFlow Lite / TFLite) è il framework on-device di Google per il deployment di ML e GenAI ad alte prestazioni su piattaforme edge, tramite conversione, runtime e ottimizzazione efficienti.
• LiteRT CLI integra gli stack Google AI Edge in un comando shell autonomo (litert) per semplificare i workflow di sviluppo correlati a LiteRT, tra cui la conversione, la quantizzazione, la compilazione, l'esecuzione, il benchmarking e la visualizzazione dei modelli LiteRT (TFLite) su vari hardware (CPU / GPU / NPU) su piattaforme (desktop, mobile o cloud).

2. 🔄 Flussi di lavoro di base: conversione, quantizzazione ed esecuzione

In questa sezione, eseguiamo un ciclo di vita completo di modellazione Edge AI con la CLI LiteRT: wrapper del modello PyTorch ➔ conversione di tracciamento ➔ quantizzazione del modello ➔ inferenza desktop ➔ benchmark delle prestazioni.

Per il supporto interattivo del notebook Jupyter di questa sezione, prova Esegui come notebook.

📝 Fase 1: prepara uno script wrapper del modello PyTorch

Crea resnet18.py nella directory corrente. Espone hook di tracciamento dinamico in modo che il generatore di grafici possa acquisire le forme:

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),)

🔄 Fase 2: converti un modello PyTorch in LiteRT utilizzando LiteRT Torch

Richiama il convertitore LiteRT Torch per creare un modello di destinazione .tflite Float32 standard:

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

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

📉 Fase 3: quantizza i pesi a INT8

Applica schede delle ricette dinamiche e solo con il peso per ridurre le dimensioni di circa 4 volte:

# 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

🚀 Fase 4: esegui l'inferenza in locale

Esegui operazioni di test con parametri di input fittizi per verificare i blocchi delle prestazioni:

# 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

📊 Fase 5: esegui il benchmark del rendimento del modello

Misura metriche di alta precisione, tra cui latenza media, costi di inizializzazione, velocità effettiva di esecuzione della CPU e footprint di memoria attiva dinamica:

# 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. 🔌 Configurazione e verifica dell'ambiente locale

Creiamo una sandbox isolata e pulita sulla tua workstation (macOS o Linux)

Ti consigliamo di utilizzare uv (un gestore di pacchetti Python di nuova generazione basato su Rust) per download di dipendenze e configurazione dinamica ultraveloci. Puoi anche utilizzare pip standard all'interno di un ambiente virtuale Python.

🔌 Opzione A: configurazione ultra rapida (uv)

L'utilizzo di uv isola le librerie in pochi secondi, eliminando i conflitti della cache dell'ambiente.

# 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

🐍 Opzione B: configurazione standard (pip)

Se uv non è presente, utilizza le configurazioni standard dell'ambiente virtuale 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

🛠️ Opzione C: configurazione locale modificabile

Se stai sviluppando o testando direttamente all'interno del clone della directory di origine del repository:

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

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

🔍 Verifica della configurazione

Verifica che il percorso indirizzi correttamente il comando litert:

litert --help

Bloccanti delle credenziali proxy aziendale / indice semplice privato:se le installazioni della build non vanno a buon fine con 401 Unauthorized a causa di regole di indice personalizzate private, forza la ricerca a indirizzare direttamente a PyPI standard:

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

💡 Il catalogo centrale di riferimenti ai modelli (model-ref)

Per mantenere robusti gli script e lo sviluppo, la CLI LiteRT implementa un catalogo dei modelli centralizzato:

• Formato: assegna un nome univoco (alias) a un modello scaricato o importato, ad esempio mobilenet.
• Varianti: utilizza i due punti di destinazione per fare riferimento alle varianti ottimizzate, ad esempio mobilenet:int8 o mobilenet:gpu.
• Semplicità: tutti i comandi della CLI accettano direttamente questo alias senza percorso, risolvendo automaticamente l'archiviazione fisica dei file al volo.

4. 📲 Implementazione e profilazione dei dispositivi

Ottimizziamo ulteriormente il modello eseguendo benchmark locali di alta precisione, eseguendo il deployment su target hardware USB reali, implementando delegati hardware, compilando Ahead-of-Time ed eseguendo benchmark sul cloud.

Per questa parte, devi connettere un dispositivo Android con ADB abilitato. Per attivare il debug USB sul tuo dispositivo:

• Vai a Impostazioni > Informazioni sullo smartphone.
• Tocca Numero build 7 volte finché non viene visualizzato il messaggio "Ora sei uno sviluppatore".
• Torna a Impostazioni > Sistema > Opzioni sviluppatore (o Impostazioni > Opzioni sviluppatore su alcuni dispositivi).
• Attiva Debug USB.

📊 Metriche di profilazione locale

Scarica EfficientNet-B1 e crea un profilo delle statistiche sul rendimento sull'host desktop:

# 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

Osserva le intestazioni degli indicatori chiave di prestazione nel log dei benchmark:

• Model initialization: Tempo per avviare le reti strutturali.
• Warmup (avg): Timing del sovraccarico di compilazione.
• Inference (avg): il tempo di elaborazione matematica non elaborato.
• Overall footprint: picco di RAM consumata durante l'esecuzione.

📲 Target A: CPU mobile (connessione USB)

Collega un dispositivo Android con il debug USB attivato ed esegui il deployment:

# 1. Confirm device connection
adb devices

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

La CLI esegue automaticamente il push del modello sul dispositivo di destinazione, esegue il ciclo di inferenza e reindirizza gli output.

🎮 Target B: GPU mobile

Esegui l'offload dinamico dei carichi di lavoro pesanti sulla GPU utilizzando OpenCL o WebGPU:

# 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

⚙️ Target C: JIT Android NPU

Trasferisci i parametri di esecuzione direttamente sulla NPU sui chipset moderni:

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

• Avviso: le build di grafici dinamici all'interno del runtime on-device subiscono ritardi significativi di riscaldamento JIT di inizializzazione.

🚀 Target D: NPU compilata AOT

Esegui la precompilazione offline per evitare i sovraccarichi JIT di runtime e ottenere la massima accelerazione:

# 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

☁️ Profilazione cloud (Google AI Edge Portal)

Esegui il push dei test sui profili hardware remoti nelle farm di dispositivi di 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. 🧠 Argomenti avanzati: LLM e riconoscimento vocale

Esploriamo i modelli avanzati convertendo ed eseguendo i modelli linguistici di grandi dimensioni (LLM) e di riconoscimento vocale automatico (ASR).

💬 AI generativa (LLM)

Gli LLM edge sono limitati dalla memoria. Risolviamo questo problema applicando la quantizzazione Weight-Only INT4/INT8, comprimendo i pesi e mantenendo i canali di esecuzione in 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

🎙️ Elaborazione vocale (ASR)

I modelli ASR come Whisper o Parakeet hanno sia un modulo encoder che un modulo decoder. Possiamo eseguire il benchmarking per moduli specifici utilizzando le chiavi di firma:

# 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. 🤖 Utilizzo nella programmazione agentica

La CLI LiteRT è adatta agli agenti e puoi integrarla direttamente con gli agenti di programmazione.

Di seguito sono riportati alcuni esempi. Aggiungi la competenza CLI LiteRT SKILL.md al tuo agente di codifica (ad esempio Google Antigravity) e prova prompt come quelli riportati di seguito.

💡 Converti, quantizza, esegui benchmark e genera report sul prompt

"Scarica il modello FP32 litert-community/efficientnet_b1 , quantizzalo nell'intervallo dinamico INT8 (–recipe dynamic_wi8_afp32), quindi esegui il benchmark del modello FP32 originale e del nuovo modello INT8 quantizzato sulla GPU del mio dispositivo Android connesso. Confronta la latenza media e segnala l'aumento della velocità effettiva."

💡 Prompt di compilazione e benchmark della NPU

"Verifica se ho un dispositivo Android con debug USB collegato. Se è attivo, scarica litert-community/efficientnet_b1 e compila offline (AOT) per la NPU Qualcomm sm8750. Scrivi il modello di destinazione in ./models/compiled, trasferiscilo sullo smartphone, esegui l'inferenza sul dispositivo e verifica che non ci siano latenze di precompilazione JIT."

7. 🚀 Congratulazioni e passaggi successivi

🎉 Ottimo! Hai completato il codelab LiteRT CLI 101.

Ora possiedi le competenze per padroneggiare lo sviluppo di ML edge:

• Converti i modelli PyTorch in modelli LiteRT.
• Quantizza i pesi del modello in INT4/INT8.
• Esegui modelli su CPU/GPU/NPU mobile.
• Compila per NPU.
• Benchmark su computer, dispositivi mobili e cloud.
• Converti ed esegui modelli LLM.
• Utilizzo nella programmazione agentica.

🔗 Risorse

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