LiteRT CLI 101: 에지 AI 워크플로 간소화

1. 🏁 소개 및 CLI 개요

LiteRT CLI 101 실습용 Codelab 에 오신 것을 환영합니다. 이 가이드는 환경 설정부터 최적화된 에지 인텔리전스 배포까지 단계별로 안내합니다.

🌟 배경

에지 AI를 사용하려면 복잡한 신경망 모델을 휴대전화, 웨어러블, 내장형 하드웨어에 직접 가져와야 합니다.

  • LiteRT (이전의 TensorFlow Lite / TFLite)는 효율적인 변환, 런타임, 최적화를 통해 에지 플랫폼에서 고성능 ML 및 GenAI 배포를 위한 Google의 온디바이스 프레임워크입니다.
  • LiteRT CLI 는 Google AI Edge 스택을 독립형 셸 명령어 (litert)에 통합하여 플랫폼 (데스크톱, 모바일 또는 클라우드) 전반의 다양한 하드웨어 (CPU / GPU / NPU)에서 LiteRT (TFLite) 모델 변환, 양자화, 컴파일, 실행, 벤치마킹, 시각화를 비롯한 LiteRT 관련 개발 워크플로를 간소화합니다.

2. 🔄 기본 워크플로: 변환, 양자화, 실행

이 섹션에서는 LiteRT CLI를 사용하여 전체 에지 AI 모델링 수명 주기(PyTorch 모델 래퍼 ➔ 추적 변환 ➔ 모델 양자화 ➔ 데스크톱 추론 ➔ 성능 벤치마크)를 실행합니다.

LiteRT CLI 101 워크플로

📝 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)에서 격리된 클린 샌드박스를 빌드해 보겠습니다.

🔌 옵션 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

💡 중앙 모델 참조 카탈로그 (model-ref)

스크립트와 개발을 견고하게 유지하기 위해 LiteRT CLI는 중앙 집중식 모델 카탈로그를 구현합니다.

모델 카탈로그 라우팅 다이어그램

  • 형식: 다운로드하거나 가져온 모델에 고유한 이름(별칭)을 할당합니다(예: mobilenet).
  • 변형: 타겟 콜론을 사용하여 mobilenet:int8 또는 mobilenet:gpu와 같은 최적화된 변형을 참조합니다.
  • 간단함: 모든 CLI 명령어는 이 경로 없는 별칭을 직접 허용하여 물리적 파일 저장소를 즉시 자동으로 확인합니다.

4. 📲 기기 배포 및 프로파일링

고정밀 로컬 벤치마크를 실행하고, 실제 USB 하드웨어 타겟에 배포하고, 하드웨어 위임을 구현하고, AOT(Ahead-of-Time)를 컴파일하고, 클라우드 벤치마킹을 실행하여 최적화를 더 진행해 보겠습니다.

타겟 배포 및 가속 옵션

📊 로컬 프로파일링 측정항목

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)에 추가하고 아래와 같은 프롬프트를 사용해 보세요.

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