온디바이스 및 클라우드 호스팅 모델로 Android 앱에서 하이브리드 환경 빌드


하이브리드 추론을 사용하여 AI 기반 Android 앱과 기능을 빌드할 수 있습니다. Firebase AI Logic 하이브리드 추론을 사용하면 기기별 모델을 사용할 수 있는 경우 이를 사용하여 추론을 실행하고, 그렇지 않은 경우 클라우드 호스팅 모델로 원활하게 대체할 수 있습니다 (그 반대의 경우도 마찬가지).

이 페이지에서는 클라이언트 SDK를 시작하는 방법과 온도와 같은 추가 구성 옵션 및 기능 을 보여줍니다.

Firebase AI Logic을 통한 기기별 추론은 Firebase AI Logic SDK v17.10.0 이상 (BoM v34.10.0 이상)을 사용하고 특정 기기에서 실행되는 Android 앱에서 지원됩니다. ML Kit 약관과 ML Kit의 생성형 AI 측면과 관련된 약관이 적용됩니다.

권장 사용 사례 및 지원되는 기능

권장 사용 사례

  • 추론에 기기별 모델 을 사용하면 다음과 같은 이점이 있습니다.

    • 향상된 개인 정보 보호
    • 로컬 컨텍스트
    • 무료 추론
    • 오프라인 기능

  • 하이브리드 기능을 사용하면 다음과 같은 이점이 있습니다.

    • 기기별 모델 사용 가능 여부와 인터넷 연결을 수용하여 더 많은 잠재고객에게 도달

기기별 추론을 위해 지원되는 기능

기기별 추론은 스트리밍 또는 비스트리밍 출력을 사용하여 단일 턴 텍스트 생성 (채팅 아님) 만 지원합니다. 다음과 같은 텍스트 생성 기능을 지원합니다.

이 페이지 하단에서 기기별 추론에 아직 사용할 수 없는 기능 목록을 검토하세요.

시작하기 전에

다음 사항에 유의합니다.

지원되는 Android 기기 및 기기별 모델

기기별 추론 (ML Kit의 Prompt API 사용)의 경우 ML Kit 문서에서 지원되는 기기 및 기기별 모델 목록을 확인할 수 있습니다.

시작하기

이 시작 단계에서는 전송하려는 지원되는 프롬프트 요청에 필요한 일반적인 설정을 설명합니다.

1단계: Firebase 프로젝트 설정 및 앱을 Firebase에 연결

  1. Firebase Console에 로그인한 후 Firebase 프로젝트를 선택합니다.

  2. Firebase Console에서 AI 서비스 > AI Logic으로 이동합니다.

  3. 시작하기 를 클릭하여 프로젝트에 필요한 API 와 리소스를 설정하는 데 도움이 되는 안내 워크플로를 실행합니다.

  4. 메시지가 표시되면 화면 안내에 따라 앱을 등록하고 Firebase 구성을 앱에 추가합니다.

  5. "Gemini API 제공업체"를 선택하라는 메시지가 표시되면 Gemini Developer API를 선택하는 것이 좋습니다. 이 API를 사용하면 무료로 빠르게 시작할 수 있습니다.

    나중에 언제든지 Vertex AI Gemini API (및 결제 요구사항)를 설정할 수 있습니다.

  6. 워크플로를 계속 진행하여 필요한 API와 연결된 서비스를 설정합니다. Firebase AI Logic

    2026년 7월 초부터 이 워크플로 단계에서는 앱에서 직접 액세스할 때 Gemini API를 보호하는 데 도움이 되는 중요한 서비스인 Firebase App Check가 AI Logic에 자동으로 적용됩니다. 시작하기의 일부로 (이 가이드의 뒷부분에 나오는 단계 참고) App Check가 적용될 때 로컬 개발을 위해 App Check 디버그 제공자 를 구성해야 합니다.

    App Check

  7. 이 가이드의 다음 단계로 계속 진행하여 앱에 필요한 SDK를 추가합니다.

2단계: 필요한 SDK 추가

Firebase AI Logic SDK for Android (firebase-ai)와 Firebase AI Logic On-Device SDK (firebase-ai-ondevice) 는 생성형 모델과 상호작용하기 위한 API에 대한 액세스를 제공합니다.

모듈 (앱 수준) Gradle 파일 (예: <project>/<app-module>/build.gradle.kts)에서 Android용 Firebase AI Logic 및 App Check 라이브러리의 종속 항목을 추가합니다.

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.13.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.2.0")
}

Java

Java의 경우 두 개의 추가 라이브러리를 추가해야 합니다.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.13.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.2.0")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

3단계: 로컬 개발을 위해 App Check 디버그 제공자 구성

2026년 7월 초부터 Console의 AI Logic 안내 설정 워크플로의 일부로 Firebase App Check가(이) Gemini API를(을) 보호하기 위해 자동으로 적용됩니다. 로컬 개발의 경우 App Check 디버그 제공자를 구성하여 적용을 유지하면서 증명을 우회해야 합니다.App Check

  1. 디버그 빌드에서 App Check 디버그 제공자 팩토리를 사용하도록 구성합니다.

    Kotlin

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

    자바

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. 디버그 토큰을 가져옵니다.

    1. 에뮬레이터 또는 테스트 기기에서 앱을 실행합니다.

    2. 로그에서 App Check 디버그 토큰을 찾습니다. 예를 들면 다음과 같습니다.

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. 토큰을 복사합니다 (예: 123a4567-b89c-12d3-e456-789012345678).

  3. App Check에 디버그 토큰을 등록합니다.

    1. Firebase Console에서 보안 > 앱 체크 > 앱 탭으로 이동합니다.

    2. 앱을 찾고 더보기 메뉴 ()를 클릭한 후 디버그 토큰 관리를 선택합니다.

    3. 화면에 표시된 안내에 따라 디버그 토큰을 등록합니다.

새 디버그 토큰을 가져오는 방법을 비롯한 디버그 제공자에 관한 자세한 내용은 다음 공식 App Check 문서를 참고하세요.

4단계: 기기별 모델을 사용할 수 있는지 확인

FirebaseAIOnDevice를 사용하여 기기별 모델을 사용할 수 있는지 확인하고, 사용할 수 없는 경우 모델을 다운로드합니다.

다운로드되면 AICore가 모델을 자동으로 업데이트합니다. AICore 및 기기별 모델 다운로드 관리에 관한 자세한 내용은 스니펫 뒤의 메모를 참고하세요.

Kotlin 

val status = FirebaseAIOnDevice.checkStatus()
when (status) {
  OnDeviceModelStatus.UNAVAILABLE -> {
    Log.w(TAG, "On-device model is unavailable")
  }

  OnDeviceModelStatus.DOWNLOADABLE -> {
    FirebaseAIOnDevice.download().collect { status ->
      when (status) {
        is DownloadStatus.DownloadStarted ->
          Log.w(TAG, "Starting download - ${status.bytesToDownload}")

        is DownloadStatus.DownloadInProgress ->
          Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")

        is DownloadStatus.DownloadCompleted ->
          Log.w(TAG, "On-device model download complete")

        is DownloadStatus.DownloadFailed ->
          Log.e(TAG, "Download failed ${status}")
      }
    }
  }
  OnDeviceModelStatus.DOWNLOADING -> {
    Log.w(TAG, "On-device model is being downloaded")
  }

  OnDeviceModelStatus.AVAILABLE -> {
    Log.w(TAG, "On-device model is available")
  }
}

Java 

Checking for and downloading the model is not yet available for Java.

However, all other APIs and interactions in this guide are available for Java.

기기별 모델 다운로드와 관련하여 다음 사항을 참고하세요.

  • 기기별 모델을 다운로드하는 데 걸리는 시간은 네트워크를 비롯한 여러 요인에 따라 달라집니다.

  • 코드가 기본 또는 대체 추론에 기기별 모델을 사용하는 경우 최종 사용자가 앱에서 코드를 발견하기 전에 기기별 모델을 사용할 수 있도록 앱의 수명 주기 초기에 모델이 다운로드되었는지 확인합니다.

  • 기기별 추론 요청이 이루어질 때 기기별 모델을 사용할 수 없는 경우 SDK는 기기별 모델의 다운로드를 자동으로 트리거하지 않습니다. SDK는 클라우드 호스팅 모델로 대체되거나 예외를 발생시킵니다 (추론 모드의 동작에 관한 세부정보 참고).

  • AICore (Android 시스템 서비스)는 다운로드되는 모델과 버전을 관리하고 모델을 업데이트하는 등의 작업을 수행합니다. 기기에는 하나의 모델만 다운로드되므로 기기의 다른 앱에서 이전에 기기별 모델을 다운로드한 경우 이 검사에서는 모델을 사용할 수 있다고 반환합니다.

지연 시간 최적화

첫 번째 추론 호출을 최적화하려면 앱에서 warmup()을 호출하도록 할 수 있습니다. 이렇게 하면 기기별 모델이 메모리에 로드되고 런타임 구성요소가 초기화됩니다.

5단계: 서비스 초기화 및 모델 인스턴스 만들기

Gemini API 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠 및 코드를 확인합니다.

모델에 프롬프트 요청을 보내기 전에 다음을 설정합니다.

  1. 선택한 API 제공업체의 서비스를 초기화합니다.

  2. GenerativeModel 인스턴스를 만들고 mode를 다음 중 하나로 설정합니다. 여기에 있는 설명은 매우 개략적이지만 추론 모드 설정에서 이러한 모드의 동작에 관한 세부정보를 확인할 수 있습니다.

    • PREFER_ON_DEVICE: 기기별 모델을 사용해 봅니다. 그렇지 않은 경우 클라우드 호스팅 모델로 대체 합니다.

    • ONLY_ON_DEVICE: 기기별 모델을 사용해 봅니다. 그렇지 않은 경우 예외를 발생 시킵니다.

    • PREFER_IN_CLOUD: 클라우드 호스팅 모델을 사용해 봅니다. 그렇지 않은 경우 기기별 모델로 대체 합니다.

    • ONLY_IN_CLOUD: 클라우드 호스팅 모델을 사용해 봅니다. 그렇지 않은 경우 예외를 발생 시킵니다.

Kotlin 

// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)

// ...

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

Java 

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
    .generativeModel(
        "MODEL_NAME",
        new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
    );

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

6단계: 모델에 프롬프트 요청 보내기

이 섹션에서는 다음과 같은 다양한 유형의 출력을 생성하기 위해 다양한 유형의 입력을 보내는 방법을 보여줍니다.

텍스트 전용 입력에서 텍스트 생성

이 샘플을 시도하기 전에 이 가이드의 시작하기 섹션을 완료했는지 확인하세요.

generateContent() 를 사용하여 텍스트가 포함된 프롬프트에서 텍스트를 생성할 수 있습니다.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."

// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Firebase AI Logic은 generateContentStream (대신 generateContent)를 사용하여 텍스트 응답 스트리밍도 지원합니다.

텍스트 및 이미지 (멀티모달) 입력에서 텍스트 생성

이 샘플을 시도하기 전에 이 가이드의 시작하기 섹션을 완료했는지 확인하세요.

generateContent() 를 사용하여 텍스트와 최대 하나 의 이미지 파일 (Bitmap만 해당) 이 포함된 프롬프트에서 텍스트를 생성할 수 있습니다. 각 입력 파일의 mimeType과 파일 자체를 제공합니다.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)

// Provide a prompt that includes the image specified above and text
val prompt = content {
  image(bitmap)
  text("What developer tool is this mascot from?")
}

// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);

// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("What developer tool is this mascot from?")
        .build();

// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Firebase AI Logic은 generateContentStream (대신 generateContent)를 사용하여 텍스트 응답 스트리밍도 지원합니다.

또 뭘 할 수 있니?

하이브리드 환경에 다양한 추가 구성 옵션과 기능을 사용할 수 있습니다.

기기별 추론에 아직 사용할 수 없는 기능

실험용 출시 버전이므로 클라우드 모델의 모든 기능을 기기별 추론에 사용할 수 있는 것은 아닙니다.

이 섹션에 나열된 기능은 기기별 추론에 아직 사용할 수 없습니다. 이러한 기능을 사용하려면 ONLY_IN_CLOUD 추론 모드를 사용하여 환경을 더 일관되게 만드는 것이 좋습니다.

  • 구조화된 출력 생성 (예: JSON 또는 enum)

  • Bitmap(메모리에 로드된 이미지) 이외의 이미지 파일 입력 유형에서 텍스트 생성

  • 두 개 이상의 이미지 파일에서 텍스트 생성

  • 오디오, 동영상, 문서 (예: PDF) 입력에서 텍스트 생성

  • Gemini 또는 Imagen 모델을 사용하여 이미지 생성

  • 멀티모달 요청에서 URL을 사용하여 파일 제공 파일을 인라인 데이터로 기기별 모델에 제공해야 합니다.

  • 4,000개 토큰(또는 약 3,000개의 영어 단어)을 초과하는 요청 전송

  • 멀티턴 채팅

  • 모델이 응답을 생성하는 데 도움이 되는 도구 제공 (예: 함수 호출, 코드 실행, URL 컨텍스트, Google Search를 통한 그라운딩, Google Maps를 통한 그라운딩)

Firebase Console의 AI 모니터링은 기기별 추론 (기기별 로그 포함)에 관한 데이터를 표시하지 않습니다. 하지만 클라우드 호스팅 모델을 사용하는 모든 추론은 Firebase AI Logic을 통한 다른 추론과 마찬가지로 모니터링할 수 있습니다. Firebase AI Logic

추가 제한사항

위의 내용 외에도 기기별 추론에는 다음과 같은 제한사항이 있습니다 (자세한 내용은 ML Kit 문서 참고).

  • 앱의 최종 사용자는 기기별 추론에 지원되는 기기를 사용해야 합니다.

  • 앱은 포그라운드에 있을 때만 기기별 추론을 실행할 수 있습니다.

  • 기기별 추론은 영어와 한국어만 검증되었습니다.

  • 전체 기기별 추론 요청의 최대 토큰 한도는 4,000개 토큰입니다. 요청이 이 한도를 초과할 수 있는 경우 클라우드 호스팅 모델을 사용할 수 있는 추론 모드를 구성해야 합니다.

  • 출력이 긴 (256개 토큰 초과) 기기별 추론 사용 사례는 피하는 것이 좋습니다.

  • AICore (기기별 모델을 관리하는 Android 시스템 서비스)는 추론 할당량을 적용합니다. 짧은 기간에 너무 많은 API 요청을 하면 앱별 ErrorCode.BUSY 응답이 발생합니다. 이 오류가 발생하면 지수 백오프를 사용하여 요청을 다시 시도해 보세요. 또한 앱이 장기 할당량 (예: 일일 할당량)을 초과하면 ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED가 반환될 수 있습니다.


의견 보내기 Firebase AI Logic 사용 경험에 관한