gallery 딥다이브
— 스마트폰 안에 AI 실험실을 짓는 법

1프로젝트 한줄 요약

gallery는 Google AI Edge의 온디바이스 생성형 AI 기능을 체험하는 실험적 앱입니다. 모델을 선택하고 준비한 다음, 휴대전화에서 답변을 생성하거나 사진·영상의 의미를 검색합니다. 이 저장소에서 배울 핵심은 AI를 호출하는 한 줄이 아니라, 모델의 준비부터 사용과 정리까지 이어지는 앱의 전체 흐름입니다.

일반적인 클라우드 챗봇에서는 서버가 모델을 실행합니다. 여기서는 LlmChatModelHelper.initialize()가 기기의 모델 파일 경로로 EngineConfig를 만들고, LiteRT-LM의 Engine과 Conversation을 생성합니다. 모델 계산을 담당하는 네이티브 엔진은 외부 의존성이며, 저장소의 Kotlin 코드는 그 엔진에 화면·데이터·도구를 연결합니다.

1-1. 한 앱 안에 세 종류의 AI 작업이 있다

Kotlin 구현은 Android/src/app/src/main/java/com/google/ai/edge/gallery/ 아래에 모여 있습니다. 파일 경로는 저장소 루트 기준입니다.

1-2. 처음 읽을 때 잡아야 할 세 가지 질문

1. 어디서 계산하는가? 파일 기반 LiteRT-LM과 시스템 관리형 AICore 경로를 구분합니다.
2. 무엇이 상태인가? 다운로드 완료, 모델 초기화 완료, 답변 생성 중은 서로 다른 상태입니다.
3. 무엇이 외부로 나가는가? 로컬 모델 계산과 모델 다운로드·원격 도구 호출을 나누어 봅니다.

2왜 주목받는가

2-1. 트렌딩 순위와 인기의 원인은 구별해서 읽자

2026-10-23 GitHub Trending Kotlin 월간 5위, 스타 25,076개라는 지표는 관심의 크기를 보여 줍니다. 다만 이 수치만으로 사람들이 어떤 기능 때문에 방문했는지는 알 수 없습니다. 아래 이유들은 README의 기능 구성과 실제 코드를 근거로 한 관심 요인에 대한 해석입니다.

• 휴대전화에서 바로 체험: README는 Android·iOS 앱과 macOS 배포를 안내합니다. 복잡한 모델 통합에 앞서 결과를 체험하는 통로가 있습니다.
• 여러 입력 방식: 채팅, Ask Image, Audio Scribe, Prompt Lab뿐 아니라 사진·영상 검색까지 같은 제품에서 비교할 수 있습니다.
• 작은 모델의 행동 연결: Mobile Actions와 Tiny Garden은 FunctionGemma 270M의 작업별 모델을 활용하는 예제입니다.
• 앱 개발로 이어지는 코드: 모델 선택·파일 관리·도구 호출·권한 UI를 함께 읽을 수 있어 직접 만든 서비스로 옮길 연결부가 보입니다.

README는 Gallery를 온디바이스 생성형 AI 체험 앱으로 소개합니다. LiteRT-LM 공식 개요와 앱의 Kotlin 구현을 함께 읽으면 런타임을 앱에 연결하는 방식을 배울 수 있습니다.

2026-10-23 GitHub 기준 최신 릴리스는 1.0.20 (2026-10-06)입니다. README는 EmbeddingGemma 2 지원과 Instant Media Search·Video Moment Finder를 새 기능으로 소개합니다. 채팅 밖의 온디바이스 활용을 보여 주는 구체적인 업데이트이며, 트렌딩 관심의 배경을 이해할 단서입니다.

2-2. 다른 선택지와 무엇을 비교해야 할까

gallery의 장점은 모든 모델에서 가장 빠르다는 증명보다, 모바일 AI 기능을 하나의 앱으로 묶은 통합 예제를 제공한다는 데 있습니다. 아래 표는 제품의 역할을 비교한 것이며, 동일 기기에서 측정한 속도 순위가 아닙니다.

llama.cpp 공식 저장소는 C/C++ LLM 추론 프로젝트입니다. Gallery와 어느 쪽이 무조건 우월한지 묻기보다, 모바일 제품 연결부를 배우려는지, 엔진 자체를 배우려는지 먼저 정하는 편이 좋습니다.

2-3. README의 표현을 코드로 한 번 더 좁혀 보기

3기술 스택 전체 지도

버전의 기본 출처는 Android/src/gradle/libs.versions.toml, 실제 적용 여부는 Android/src/app/build.gradle.kts입니다. 아래 값은 모두 커밋 8f5f2a0 기준입니다. 버전 카탈로그는 여러 의존성의 이름과 버전을 한곳에 모아 두는 장부입니다.

3-1. 프론트엔드: 브라우저가 아닌 Android 네이티브 화면

3-2. 백엔드 역할: 서버 대신 기기 안의 실행·저장 계층

이 저장소에는 별도 웹 API 서버나 모델 학습 서버 프로젝트가 없습니다. 서버 앱에서 백엔드가 맡을 계산·데이터 책임을 Android 프로세스 내부의 런타임과 저장소가 담당합니다. 원격 MCP 서버는 필요할 때 연결하는 외부 구성요소입니다.

kotlinx-serialization-json은 1.7.3, serialization 플러그인은 2.0.21로 선언되어 있습니다. Kotlin reflect와 일부 metadata 의존성은 2.4.0이며 -Xskip-metadata-version-check도 있습니다. 이 조합을 “전부 Kotlin 2.2.21”로 요약하면 중요한 차이가 사라집니다.

3-3. 인프라·빌드: 실제 CI가 말해 주는 기준

.github/workflows/build_android.yaml은 Android 변경 시 Ubuntu에서 SDK Platform 37을 준비하고 ./gradlew assembleRelease를 호출합니다. 별도 테스트 실행 단계나 APK 업로드 단계는 없습니다. JUnit·Espresso 의존성이 선언되어 있다는 사실만으로 CI가 테스트를 돌린다고 볼 수 없습니다.

.github/workflows/static.yml은 skills/를 staging/skills/에 담아 GitHub Pages로 배포합니다. 이것은 모델 추론 서버 배포가 아니라 스킬 정적 파일 배포입니다. package.json·Cargo.toml·go.mod·pyproject.toml·Dockerfile 중심의 프로젝트 구조는 확인되지 않습니다.

4아키텍처 심화 분석

다음은 Android 핵심 경로를 단순화한 구조도입니다. 스킬과 MCP는 Agent Chat에서 확장되는 경로이며, 모든 일반 채팅이 항상 외부 도구를 거치는 것은 아닙니다.

화면, 실행기, 런타임, 저장소를 구분하면 모델이나 기능이 늘어날 때 무엇을 바꿔야 하는지 설명할 수 있습니다. 각 계층을 완벽하게 독립시킨 교과서라고 보기보다, 실제 연결 방식과 예외를 배우는 사례로 읽어야 합니다.

4-1. 패턴 ① 상태와 이벤트를 나누는 MVVM·단방향 흐름

Android/src/app/src/main/java/com/google/ai/edge/gallery/ui/llmchat/LlmChatScreen.kt의 LlmChatScreen()은 ChatViewWrapper에 ViewModel·콜백·입력 옵션을 전달합니다. Android/src/app/src/main/java/com/google/ai/edge/gallery/ui/common/chat/ChatViewModel.kt는 내부의 MutableStateFlow를 외부에 StateFlow로 노출하고, addMessage()에서 새 상태를 만듭니다.

// ChatViewModel.kt의 핵심 선언
private val _uiState = MutableStateFlow(createUiState())
val uiState: StateFlow<ChatUiState> = _uiState.asStateFlow()

// addMessage()는 메시지 목록과 맵을 복사한 뒤 상태를 갱신한다.
// 핵심 동작을 읽기 쉽게 요약한 표현
_uiState.update { state ->
  state.copy(messagesByModel = newMessagesByModel)
}

읽는 쪽에는 상태 관찰 통로를, 바꾸는 쪽에는 갱신 함수를 둡니다. 다만 ChatUiState 내부에는 MutableList도 있으므로, 외부에서 바꿀 수 없는 Flow라고 해서 모든 중첩 데이터가 자동으로 불변인 것은 아닙니다. 복사해 갱신하는 실제 함수를 함께 읽으세요.

이 구조는 Compose 공식 아키텍처 문서의 “상태는 아래로, 이벤트는 위로” 흐름과 연결됩니다. 이 패턴의 이점은 화면에 다운로드·추론 세부 구현을 모두 넣지 않아도 된다는 것입니다.

4-2. 패턴 ② 런타임 전략과 Hilt 의존성 주입

Android/src/app/src/main/java/com/google/ai/edge/gallery/runtime/LlmModelHelper.kt는 initialize(), resetConversation(), runInference(), stopResponse(), cleanUp()라는 공통 계약을 정의합니다. Android/src/app/src/main/java/com/google/ai/edge/gallery/runtime/ModelHelperExt.kt의 확장 프로퍼티가 모델에 맞는 구현을 고릅니다.

// ModelHelperExt.kt의 선택 순서를 요약
val Model.runtimeHelper: LlmModelHelper
  get() {
    testingModelHelper?.let { return it }
    if (this.isAiCore) return AICoreModelHelper
    return LlmChatModelHelper
  }

이는 같은 일을 서로 다른 방법으로 수행하는 전략 패턴으로 읽을 수 있습니다. 다운로드에도 Android/src/app/src/main/java/com/google/ai/edge/gallery/data/ModelDownloader.kt라는 계약이 있고, Android/src/app/src/main/java/com/google/ai/edge/gallery/di/AppModule.kt는 @IntoMap·@RuntimeTypeKey로 LiteRT-LM과 AICore 다운로더를 등록합니다.

테스트용 testingModelHelper가 먼저 선택된다는 점도 읽을 만합니다. 비싼 모델을 매번 로드하지 않고 가짜 구현으로 흐름을 확인할 수 있는 접점이지만, 전역 가변 상태이므로 동시에 사용하는 테스트 사이의 간섭도 고려해야 합니다.

4-3. 패턴 ③ 콜백을 Flow 이벤트로 바꾸는 어댑터

Android/src/app/src/main/java/com/google/ai/edge/gallery/agent/DefaultAgentRuntimeExecutor.kt의 executeStream()은 callbackFlow를 반환합니다. 런타임이 보내는 응답 조각을 StreamToken으로, 종료를 LoopTerminated로 바꿉니다. 정의는 Android/src/app/src/main/java/com/google/ai/edge/gallery/agent/AgentEvent.kt의 sealed interface에 모여 있습니다.

// executeStream()의 결과 콜백을 단순화한 흐름
resultListener = { partialResult, done, partialThinking ->
  emitEvent(AgentEvent.StreamToken(
    token = partialResult, thinking = partialThinking, done = done
  ))
  if (done) {
    emitEvent(AgentEvent.LoopTerminated(finalResponse.toString()))
    close()
  }
}

실제 코드는 제어용 접두사를 거르고 응답을 누적하며, 오류·중단·문맥 압축 이벤트도 보냅니다. 이 덕분에 ViewModel은 엔진의 콜백 규칙 대신 앱이 이해하는 사건 목록을 처리합니다. 응답 조각 하나가 반드시 토큰 하나나 글자 하나인 것도 아닙니다.

취소 경로는 따로 확인해야 합니다. executeStream()의 awaitClose 블록 자체는 비어 있습니다. 명시적인 interrupt()는 세션 관리자의 stopResponse()를 거쳐 런타임 중단으로 이어집니다. Flow 수집 취소만 보고 네이티브 추론도 무조건 멈춘다고 단정하면 안 됩니다.

4-4. 패턴 ④ 저장소와 백그라운드 작업의 역할 분리

Android/src/app/src/main/java/com/google/ai/edge/gallery/data/DownloadRepository.kt의 DefaultDownloadRepository.downloadModel()은 URL·파일명·버전·부가 파일 정보를 WorkManager 입력으로 만듭니다. 파일 바이트를 읽는 일은 Android/src/app/src/main/java/com/google/ai/edge/gallery/worker/DownloadWorker.kt의 doWork()가 맡습니다.

// DownloadRepository.kt의 실제 작업 등록
workManager.enqueueUniqueWork(
  model.name,
  ExistingWorkPolicy.REPLACE,
  downloadWorkRequest,
)

같은 모델 이름으로 다시 요청하면 기존 작업을 교체하는 정책입니다. Worker는 임시 파일을 사용하고, 재개 시 HTTP Range를 붙이며, 약 200ms 간격으로 진행률을 알립니다. 완료 뒤 임시 확장자를 없애고 필요하면 압축을 풉니다.

WorkManager 공식 문서는 앱이 화면 밖으로 나간 뒤에도 유지할 작업을 이 라이브러리의 사용 대상으로 설명합니다. 다만 라이브러리를 쓴다고 모든 네트워크 예외가 자동 해결되지는 않습니다. 이 Worker는 IOException에서 Result.failure()를 반환하며 자동 재시도 반환과는 다릅니다.

4-5. 엔진 수명과 대화 수명은 왜 나누는가

Android/src/app/src/main/java/com/google/ai/edge/gallery/ui/llmchat/LlmChatModelHelper.kt의 LlmModelInstance는 Engine과 Conversation을 따로 보관합니다. resetConversation()은 기존 대화를 닫고 같은 엔진에서 새 대화를 만들고, cleanUp()은 모델 자원 정리를 담당합니다.

이 분리는 앱의 반응 속도와 메모리에 영향을 줍니다. 새 대화가 필요할 때 엔진을 재사용하는 경로와, 모델 자체를 바꿔 자원을 회수하는 경로를 각각 따라가면 “초기화”와 “자원 해제”를 구체적으로 이해할 수 있습니다.

4-6. 모델의 최대 문맥과 현재 설정값은 다르다

model_allowlists/1_0_20.json의 Gemma 4는 maxContextLength=32000, maxTokens=4000을 선언합니다. Android/src/app/src/main/java/com/google/ai/edge/gallery/data/ModelAllowlist.kt가 이를 설정 생성 함수로 넘기고, Android/src/app/src/main/java/com/google/ai/edge/gallery/data/Config.kt의 createLlmChatConfigs()는 최대 문맥 값이 있으면 2,000부터 그 값까지 조절하는 슬라이더를 만듭니다. 이 목록의 Gemma 4 두 항목은 기본값이 4,000입니다.

// LlmChatModelHelper.initialize()에서 엔진 예산으로 이어지는 값
val maxTokens = model.getIntConfigValue(
  key = ConfigKeys.MAX_TOKENS,
  defaultValue = DEFAULT_MAX_TOKEN,
)
// 아래는 EngineConfig의 관련 인자만 발췌한 표현
EngineConfig(
  modelPath = modelPath,
  backend = preferredBackend,
  maxNumTokens = maxTokens,
)

따라서 모델 설명의 “최대 32K”를 모든 실행이 처음부터 32K를 사용한다는 뜻으로 읽으면 안 됩니다. 이름이 maxTokens라고 해서 이 경로에서 순수 출력 길이만 나타낸다고 해석하는 것도 부정확합니다. 실제로 어떤 엔진 인자에 연결되는지 확인해야 합니다.

Android/src/app/src/main/java/com/google/ai/edge/gallery/agent/sessions/SummarizationContextCompactor.kt는 같은 설정값의 75%를 넘는 문맥에서 압축을 검토합니다. 요약을 생성한 뒤 대화를 다시 만들며, 자동 실행 여부는 기능 플래그·작업별 설정 등에도 달려 있습니다. 문맥이 길어졌다고 언제나 자동 요약되는 것은 아닙니다.

5디렉토리 구조 해부

저장소 루트에는 Android 앱, 버전별 모델 목록, 스킬 예제, 사용 문서가 있습니다. iOS용 모델 목록 파일은 있지만 Swift 앱 프로젝트는 확인되지 않습니다. README의 앱 배포 안내를 그대로 소스 디렉토리 목록으로 옮기지 않는 것이 중요합니다.

5-1. 폴더는 기술 이름보다 책임으로 읽자

5-2. 코드 규모를 숫자로 보기

아래는 .git을 제외한 파일의 물리적 줄 수입니다. 빈 줄·주석·라이선스 문구도 포함하며, 실행문 개수나 개발 난이도를 뜻하지 않습니다. HTML 안에 포함된 JavaScript는 HTML 줄 수에 들어갑니다.

Git 관리 디렉토리를 제외한 전체 파일은 635개입니다. Kotlin 구현은 Android 앱의 주 소스 경로에 모여 있습니다. 별도 Android/src/app/src/test/·Android/src/app/src/androidTest/ 디렉토리는 이 커밋에서 확인되지 않습니다.

처음에는 GalleryApp.kt → LlmChatViewModel.kt → DefaultAgentRuntimeExecutor.kt → LlmChatModelHelper.kt 순서로 읽으세요. 저장소 전체를 훑기보다 한 기능의 세로 경로를 먼저 완성하는 방법입니다.

6학습 포인트 (기술별)

6-1. Kotlin: 상태를 타입으로 표현하기

Android/src/app/src/main/java/com/google/ai/edge/gallery/data/ModelDownloadStatus.kt는 다운로드 상태를 NOT_DOWNLOADED, PARTIALLY_DOWNLOADED, IN_PROGRESS, UNZIPPING, SUCCEEDED, FAILED, UNAVAILABLE로 나눕니다. 완료 여부를 Boolean 하나로 관리하면 표현하기 어려운 상황들입니다.

// ModelDownloadStatus.kt의 데이터 구조 일부
data class ModelDownloadStatus(
  val status: ModelDownloadStatusType,
  val totalBytes: Long = 0,
  val receivedBytes: Long = 0,
  val errorMessage: String = "",
  // 나머지 속성 생략
)

배울 것: enum은 정해진 선택지를, sealed interface는 이벤트마다 다른 데이터를 표현합니다. 작은 실습: “파일은 받았지만 압축 해제 중”과 “이 기기에서 모델 사용 불가”의 화면 문구를 각각 써 보세요. 타입이 UI 문구와 버튼 상태를 설계하는 도구라는 점이 보입니다.

6-2. 코루틴: 백그라운드 실행과 취소를 함께 설계하기

LlmChatViewModelBase.generateResponse()는 코루틴에서 실행기를 사용하고, DefaultLlmSessionManager는 세션별 Mutex로 세션 변경과 문맥 압축을 조율합니다. SemanticRetrievalService.retrieveEntitiesInternal()은 I/O 디스패처로 검색을 옮기고, CancellationException을 별도로 다시 던집니다.

실습 아이디어: 초기화 중 화면 이탈, 생성 중 중지, 세션 복원을 연속으로 누르는 상황을 종이에 그려 보세요. 각 상황에서 UI 작업, Flow 수집, 네이티브 엔진 중 무엇이 멈춰야 하는지 적습니다. 취소 예외를 일반 오류로 바꾸지 않는 이유도 함께 설명해 보세요.

6-3. 임베딩과 벡터 검색: 생성형 AI와 다른 길

Android/src/app/src/main/java/com/google/ai/edge/gallery/services/semanticretrieval/OnDeviceEmbedder.kt의 인터페이스는 텍스트·이미지 등을 FloatArray로 바꿉니다. UniversalOnDeviceEmbedder는 MediaPipe UniversalEmbedder를 감싸고, 모델의 실제 입력 지원 여부와 문맥·영상 토큰 한도를 ModelInfo에서 읽습니다.

SemanticRetrievalService는 SqliteVectorStore와 SemanticRetriever를 연결합니다. GemmaEmbeddingModelStore.DEFAULT_EMBEDDING_DIMENSION은 768입니다. 초기화 실패나 Context 부재 때는 메모리 저장소로 대체하는 경로가 있으므로, 모든 실행 환경에서 영속 저장이 보장된다고 보면 안 됩니다.

답변을 만들어 내는 모델과 관련 자료를 찾아주는 모델을 구분하면, 모든 AI 기능에 대형 채팅 모델이 필요하지 않다는 점을 이해할 수 있습니다.

영상 예제: Android/src/app/src/main/java/com/google/ai/edge/gallery/customtasks/videomomentfinder/VideoMomentFinderViewModel.kt는 기본 분석 구간 2초, 구간당 프레임 2개, 구간 겹침 0초, 기본 검색 결과 5개를 선언합니다. searchForMoment()는 parent_id 메타데이터 필터로 선택한 영상의 레코드만 검색합니다.

이 필터가 검색 전에 적용되는 것이 중요합니다. 전체 영상에서 상위 5개를 고른 뒤 현재 영상만 남기면, 현재 영상의 좋은 후보가 처음부터 빠질 수 있습니다. 실습 아이디어: 영상 두 편의 가상 점수를 만들어 “필터 후 상위 K개”와 “상위 K개 후 필터”를 비교해 보세요.

6-4. 함수 호출: 모델의 제안과 앱의 실행을 구분하기

Android/src/app/src/main/java/com/google/ai/edge/gallery/customtasks/mobileactions/MobileActionsTools.kt의 turnOnFlashlight()는 직접 카메라 API를 실행하지 않습니다. FlashlightOnAction을 콜백으로 넘기고, MobileActionsViewModel.performAction()이 구체 동작으로 연결합니다.

// MobileActionsTools.kt의 핵심 동작
@Tool(description = "Turns the flashlight on")
fun turnOnFlashlight(): Map<String, String> {
  onFunctionCalled(FlashlightOnAction())
  return mapOf("result" to "success")
}

코드의 영문 설명은 모델에게 제공하는 원래 메타데이터입니다. 이 함수의 success 반환만으로 실제 손전등 켜기가 성공했다고 판정할 수는 없습니다. 도구 계층의 요청 접수와 운영체제 동작의 성공을 따로 추적하는 설계가 왜 필요한지 배울 수 있습니다.

Android/src/app/src/main/java/com/google/ai/edge/gallery/tools/RunMcpTool.kt의 runMcpTool()은 서버 도구별 alwaysAllow를 확인합니다. 매번 허용이 필요한 도구라면 AskMcpToolCallPermissionAction을 보내고 결과를 기다린 뒤 client.callTool()을 호출합니다. 모델이 함수를 선택했다는 사실이 사용자 권한을 대신하지 않습니다.

6-5. 스킬: 설명은 먼저, 긴 지침은 필요할 때

skills/README.md는 스킬의 이름·설명으로 후보를 고르고 자세한 지침을 나중에 불러오는 흐름을 설명합니다. 실제 Android/src/app/src/main/java/com/google/ai/edge/gallery/tools/LoadSkillTool.kt의 loadSkill()은 SkillsProvider.loadSkill()과 getSkillContent()로 지침을 가져옵니다.

이 방식은 모든 지침을 처음부터 넣는 비용을 줄입니다. 스킬은 모델 가중치를 바꾸지 않으며, 지침·도구·자원을 묶어 기존 모델이 할 일을 안내합니다. JavaScript 스킬은 숨겨진 WebView의 ai_edge_gallery_get_result 진입점을 사용하고, 네이티브 기능은 Intent와 연결됩니다.

실습 아이디어: 기존 스킬의 이름·설명만 보고 어떤 질문에 선택될지 예상한 뒤, 본문의 지침과 비교해 보세요. 너무 넓은 설명 두 개가 있으면 모델이 왜 혼동할 수 있는지도 적어 봅니다. 외부 API를 사용하는 스킬은 별도 통신 기능입니다.

6-6. 로컬 저장: 파일 포맷도 앱의 계약이다

Android/src/app/src/main/java/com/google/ai/edge/gallery/di/AppModule.kt는 settings.pb, user_data.pb, skills.pb, benchmark_results.pb 등의 DataStore를 만듭니다. 스키마는 Android/src/app/src/main/proto/에 있고, 대화 저장은 Android/src/app/src/main/java/com/google/ai/edge/gallery/data/ChatSessionRepository.kt와 세션 관리자를 따라가면 됩니다.

DefaultLlmSessionManager.saveSessionHistory()는 세션 ID, 시각, 원래 모델, 작업 ID, 메시지를 묶습니다. 대화 기록을 디스크에 저장하는 것과 엔진 내부의 KV 캐시를 유지하는 것은 다른 일입니다. 앱을 다시 열 때 기록을 읽어 런타임 대화를 복원하는 연결이 필요합니다.

6-7. 성능 계측: 구현과 활성화는 다른 사실

Android/src/app/src/main/java/com/google/ai/edge/gallery/common/metrics/MetricsTracker.kt에는 첫 응답 시간, 생성 속도, 메모리·전력 등을 모으는 인터페이스와 구현이 있습니다. 그러나 create()의 지역 변수 enableInferenceMetrics는 false여서 현재 경로는 NoOpMetricsTracker()를 반환합니다.

// MetricsTracker.create()의 현재 분기
val enableInferenceMetrics = false
if (!enableInferenceMetrics) {
  return NoOpMetricsTracker()
}

또한 LlmChatModelHelper.initialize()의 enableBenchmark도 false입니다. README의 벤치마크 소개만으로 이 커밋의 모든 계측이 켜져 있다고 설명하면 안 됩니다. 실습 아이디어: 첫 응답 시간과 이후 생성 속도가 각각 어떤 사용자 경험을 설명하는지, 수치 없이 측정 계획부터 작성해 보세요.

7하드웨어 / 시스템 요구사항

7-1. 앱을 설치할 수 있다는 것과 모델을 돌릴 수 있다는 것

Android/src/app/build.gradle.kts의 minSdk=31은 Android 12 이상을 뜻합니다. README 기준으로 iOS는 17 이상이며, iOS 앱 빌드 프로젝트는 이 저장소에 포함되어 있지 않습니다.

Android 최소 버전을 만족해도, 선택한 모델의 메모리와 가속기 요구를 만족한다는 뜻은 아닙니다. 모델 파일 크기는 디스크 사용량이고, 실행 중 메모리에는 가중치·캐시·입력 처리·앱 화면 비용이 함께 들어갑니다.

7-2. 버전별 모델 목록에서 읽는 구체적인 기준

아래는 model_allowlists/1_0_20.json의 일부입니다. 파일 크기는 sizeInBytes를 십진 GB·MB로 반올림했습니다. 메모리는 목록의 minDeviceMemoryInGb 값이며 실측 최대 사용량이나 모든 기기에서의 성공 보장이 아닙니다.

EmbeddingGemma-2 항목에 메모리 수치가 없다는 것은 무제한 지원이라는 뜻이 아닙니다. 사진 샘플 부가 파일만 약 15.3MB이며, 사용자 영상 복사본·썸네일·벡터 DB·내보낸 클립은 모델 파일과 별도로 저장 공간을 사용합니다.

Android/src/app/src/main/java/com/google/ai/edge/gallery/ui/common/MemoryWarning.kt의 isMemoryLow()는 이 기준과 기기 총 메모리를 비교하고, API 34 이상에서는 advertisedMem을 사용합니다. 경고 창에는 계속 진행하는 선택지도 있습니다. 이 검사는 현재 남은 여유 메모리를 실시간으로 보장하는 검사나 강제 실행 차단과는 다릅니다.

7-3. CPU·GPU·NPU는 이름만 보고 고르지 않는다

Android/src/app/src/main/java/com/google/ai/edge/gallery/data/BackendSpec.kt는 가속기 목록의 첫 항목을 기본값으로 봅니다. 실제 LiteRT-LM 초기화에서는 주 계산·비전·오디오 백엔드를 따로 정하며, 오디오는 해당 경로에서 Backend.CPU()를 사용합니다. “GPU 모델”이라고 모든 입력 처리가 GPU로만 실행되는 것은 아닙니다.

Android/src/app/src/main/java/com/google/ai/edge/gallery/common/HardwareUtils.kt에는 isOldMaliGpu(), isTensorG3OrHigher()처럼 기기 문자열과 코드네임을 판별하는 함수가 있습니다. 모델·SoC·드라이버 조합을 다뤄야 한다는 흔적이지, 이 함수만으로 모든 성능이나 호환성이 증명되는 것은 아닙니다.

AndroidManifest.xml의 NPU와 카메라 기능은 required=false입니다. 반면 AICore 경로는 시스템 서비스와 지원 기기 조건을 별도로 검사합니다. 파일 기반 모델의 지원 범위와 AICore 지원 범위를 하나로 합치지 마세요.

7-4. 개발 PC·인증·첫 사용의 조건

• 개발 도구: Android Studio와 프로젝트의 AGP·Gradle·SDK 조합을 맞춰야 합니다. CI의 JDK 21을 기준으로 참고하되 JVM 11 타깃과 구분합니다.
• 다운로드 인증: DEVELOPMENT.md는 Hugging Face 개발 앱 설정을 안내합니다. Android/src/app/src/main/java/com/google/ai/edge/gallery/common/ProjectConfig.kt의 client ID·redirect URI와 Gradle의 redirect scheme이 아직 자리표시자입니다.
• 연결: 모델 목록과 가중치를 처음 확보할 때 네트워크가 필요합니다. 모델별 약관 동의나 접근 권한이 필요한 경우도 모델 배포 페이지에서 확인해야 합니다.
• 권한: 사진·동영상·카메라·마이크·알림 등의 요청은 선택한 기능과 관련됩니다. 저장소의 Manifest 선언과 실행 시 허용 여부를 구분해서 이해합니다.

8직접 해볼 수 있는 실습 과제

처음 두 과제는 소스를 읽기만 해도 진행할 수 있습니다. 구현 과제는 별도 학습용 사본에서 진행하고, 모델·기기 준비가 필요한 검증과 순수 로직 검증을 구분하세요. 각 과제는 정답 코드보다 설계 판단을 설명하는 데 목적이 있습니다.

실습의 완료 기준을 눈에 보이는 결과와 실패 조건으로 적으면, 코드를 따라 치는 공부가 설계를 검증하는 공부로 바뀝니다.

9관련 기술 심화 학습 로드맵

주당 4~6시간을 가정한 제안입니다. Kotlin 문법이 낯설면 첫 주를 두 주로 늘려도 됩니다. 매주 “무엇을 읽었다”보다 무엇을 설명하거나 검증할 수 있게 되었는지를 결과물로 남기세요.

9-1. 매주 반복할 읽기 순서

1. 입구 찾기: 사용자의 어떤 동작으로 이 코드가 시작되는지 적습니다.
2. 타입 확인: 함수 이름만 보지 말고 입력·출력·상태 타입을 읽습니다.
3. 정상 경로 추적: 한 가지 성공 사례를 끝까지 따라갑니다.
4. 실패 경로 추가: 오류·취소·미지원·빈 결과를 각각 확인합니다.
5. 다른 예제에 적용: 모델 대신 가짜 응답이나 가상의 벡터를 넣어 같은 구조를 설명합니다.

기능 하나의 입력·상태·실패·자원 회수까지 설명하는 경험이, 라이브러리 이름을 많이 아는 것보다 오래 남는 학습이 됩니다.

9-2. 그다음에는 관심 분야에 맞춰 갈라지자

10핵심 키워드 사전

용어를 외운 뒤에는 다시 함수로 돌아오세요. 예를 들어 “문맥 압축”을 이해했다면 SummarizationContextCompactor.compactContextIfNeeded()에서 현재 토큰 수 확인, 요약 생성, 대화 재설정, 실패 후 재시도 간격 처리를 차례로 찾아보는 식입니다.

11참고 링크

11-1. 프로젝트 공식 자료

• google-ai-edge/gallery 공식 저장소 — 제품 소개·이슈·배포 경로의 출발점.
• 커밋 8f5f2a0의 README — 기능 소개와 실험적 베타 안내.
• 릴리스 1.0.20 — 2026-10-06 배포 버전.
• 프로젝트 Wiki — 설치와 사용 안내.
• DEVELOPMENT.md — Hugging Face 개발 앱 설정.
• 함수 호출 확장 안내 — 도구·Action·Android 처리의 연결 예제.
• 스킬 개발 문서 — 지침·WebView·네이티브 스킬의 구성.
• MCP 연결 문서 — 원격 도구 연결과 실험 단계의 제약.

11-2. 소스 근거를 다시 읽는 바로가기

아래 링크는 분석 기준 커밋에 고정되어 있습니다. 기본 브랜치의 같은 경로는 이후 구현이 달라질 수 있습니다.

11-3. 관련 기술의 공식 문서

• LiteRT-LM 개요 — 런타임과 앱 예제의 관계, 가속기·입력 방식의 큰 그림.
• LiteRT-LM 공식 저장소 — 앱 외부에서 제공되는 추론 계층의 코드·문서.
• Compose UI 아키텍처 — 상태·이벤트·ViewModel 연결 원칙.
• WorkManager 작업 예약 — 지속 작업·고유 작업·포그라운드 작업.
• Hugging Face OAuth — 개발 앱과 권한 위임 설정.
• llama.cpp 공식 저장소 — 다른 로컬 추론 접근을 비교하는 출발점.

현재 상태 (2026-10-23 확인)

최근 push 날짜, 릴리스 날짜, 소스 분석 기준 커밋 날짜는 서로 다른 정보를 나타냅니다. 이 글의 코드 설명은 8f5f2a0에 고정하고, 인기 지표와 릴리스 상태는 분석일 기준으로 읽으면 됩니다.