> [!WARNING] > **Experimental:** Using the Firebase AI Logic SDK to build hybrid experiences is an Experimental feature (and the Prompt API from ML Kit is in beta), which means that this feature isn't subject to any SLA or deprecation policy and could change in backwards-incompatible ways.
[Video](https://www.youtube.com/watch?v=UHYXjmWW0PQ) You can build AI-powered Android apps and features with hybrid inference using Firebase AI Logic. Hybrid inference enables running inference using on-device models when available and seamlessly falling back to cloud-hosted models otherwise (and vice versa). This page describes how to [get started using the client SDK](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#get-started). After completing this standard setup, check out the [additional configuration options and capabilities](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt). Note that on-device inference via Firebase AI Logic is supported for Android apps using Firebase AI Logic SDK v17.10.0+ (BoM v34.10.0+) and running on [specific devices](https://developers.google.com/ml-kit/genai#prompt-device). It's governed by the [ML Kit terms](https://developers.google.com/ml-kit/terms), as well as [terms specific to the Gen AI aspects of ML Kit](https://developers.google.com/ml-kit/genai-terms). [Jump to view code examples](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#initialize-service-and-model) ### Use cases and supported capabilities Depending on your app's use cases, you can take advantage of several benefits of on-device or hybrid experiences: - Benefits of using an **on-device model** for inference: - Enhanced privacy - Local context - Inference at no-cost - Offline functionality - Benefits of using a **hybrid** approach: - Provide a similar app experience, regardless of the end-user's device - Improve availability of generative AI features, regardless of internet connectivity, quota limitations, or device capabilities #### Supported on-device inference capabilities On-device inference only supports **single-turn text generation (*not* chat)** (with streaming or non-streaming output), specifically the following capabilities: - Generating [text from text-only input](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#text-in-text-out). - Generating [text from text-and-image input](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#image-in-text-out), specifically a single Bitmap image as input. - Generating [structured output](https://firebase.google.com/docs/ai-logic/hybrid/android/generate-structured-output.md.txt), including JSON and enums. Make sure to review the list of [not-yet-supported features for hybrid or on-device inference](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#features-not-yet-supported) at the bottom of this page. ### Supported APIs and devices The following sections describe the supported APIs, as well as the supported devices (and their on-device models). #### Supported APIs for in-cloud vs on-device inference - In-cloud inference uses your chosen Gemini API provider (either the Gemini Developer API or the Agent Platform Gemini API (formerly Vertex AI)). - On-device inference uses the [Prompt API from ML Kit](https://developers.google.com/ml-kit/genai/prompt/android), which is in beta and only available on [specific devices](https://developers.google.com/ml-kit/genai#prompt-device). > [!IMPORTANT] > **Important:** On-device models usage is governed by the [ML Kit terms](https://developers.google.com/ml-kit/terms), as well as [terms specific to the Gen AI aspects of ML Kit](https://developers.google.com/ml-kit/genai-terms). #### Supported Android devices and their on-device models For on-device inference (which uses the Prompt API from ML Kit), you can find a list of [supported devices and their on-device models](https://developers.google.com/ml-kit/genai#prompt-device) in the ML Kit documentation. ## Get started These get started steps describe the required general setup for any supported prompt request that you want to send. ### **Step 1**: Set up a Firebase project and connect your app to Firebase 1. Sign into the [Firebase console](https://console.firebase.google.com/), and then select your Firebase project.
Don't already have a Firebase project?
If you don't already have a Firebase project, click the button to create a new Firebase project, and then use either of the following options: - **Option 1** : Create a wholly new Firebase project (and its underlying Google Cloud project automatically) by entering a new project name in the first step of the workflow. - **Option 2** : "Add Firebase" to an existing Google Cloud project by clicking **Add Firebase to Google Cloud project** (at bottom of page). In the first step of the workflow, start entering the **project name** of the existing project, and then select the project from the displayed list. Complete the remaining steps of the on-screen workflow to create a Firebase project. Note that when prompted, you do ***not*** need to set up Google Analytics to use the Firebase AI Logic SDKs.

2. In the Firebase console, go to **AI Services** \> [**AI Logic**](https://console.firebase.google.com/project/_/ailogic/?useAutoProject=true). 3. Click **Get started** to launch a guided workflow that helps you set up the [required APIs](https://firebase.google.com/docs/ai-logic/faq-and-troubleshooting.md.txt#required-apis) and resources for your project. 4. If prompted, follow the on-screen instructions to register your app and add your Firebase configuration to your app. 5. When asked to choose a "Gemini API provider", we recommend selecting the **Gemini Developer API**, which lets you get started quickly at no cost. At any point later, you can always [set up the Agent Platform Gemini API (formerly Vertex AI)](https://console.firebase.google.com/project/_/ailogic?openVertexAiOnboarding=true&useAutoProject=true) (and its requirement for billing). 6. Continue in the workflow to set up the required APIs and associated services for Firebase AI Logic. This stage of the workflow automatically [enforces Firebase App Check for AI Logic](https://firebase.google.com/docs/ai-logic/app-check.md.txt), which is a *critical* service to help protect the Gemini API when it's directly accessed from your app. As part of getting started (see steps later in this guide), you'll need to configure the App Check *debug provider* for local development when App Check is enforced. > [!NOTE] > **Note:** To release your app's AI feature to end users, you need to [register your app with a production App Check attestation provider](https://firebase.google.com/docs/ai-logic/app-check.md.txt) so that they can use the feature when App Check is enforced. 7. Continue to the next step in this guide to add the required SDKs to your app. ### **Step 2**: Add the required SDKs The Firebase AI Logic SDK for Android (`firebase-ai`) along with the Firebase AI Logic On-Device SDK (`firebase-ai-ondevice`) provide access to the APIs for interacting with generative models. > [!IMPORTANT] > **Important:** The `firebase-ai-ondevice` library transitively includes the Prompt API from ML Kit and requires that your Android project target *at minimum* API level 26 (whereas the `firebase-ai` library only requires *at minimum* level 24). In your **module (app-level) Gradle file** (like `//build.gradle.kts`), add the dependencies for the Firebase AI Logic and App Check libraries for Android: ### Kotlin ```groovy 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:18.1.0") implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07") implementation("com.google.firebase:firebase-appcheck-debug:20.0.0") } ``` ### Java For Java, you need to add two additional libraries. ```groovy 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:18.1.0") implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07") implementation("com.google.firebase:firebase-appcheck-debug:20.0.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") } ``` ### **Step 3** : Configure the App Check debug provider for local development As part of the guided setup workflow for AI Logic in the console, Firebase App Check is automatically enforced to protect the Gemini API. For local development, you need to configure the App Check *debug provider* to bypass attestation while still maintaining the enforcement of App Check. > [!IMPORTANT] > **Important:** Make sure that App Check is enforced for AI Logic. In the Firebase console, go to the **Security** \> **App Check** \> [**APIs** tab](https://console.firebase.google.com/project/_/appcheck/apps/products/?useAutoProject=true), and then find the row for Firebase AI Logic. If it says `Unenforced`, then follow the [instructions to enforce App Check yourself](https://firebase.google.com/docs/ai-logic/app-check.md.txt#enforce-app-check-for-debug-provider-only). 1. In your debug build, configure App Check to use the debug provider factory: ### Kotlin ```kotlin Firebase.initialize(context = this) Firebase.appCheck.installAppCheckProviderFactory( DebugAppCheckProviderFactory.getInstance(), ) ``` ### Java ```java FirebaseApp.initializeApp(/*context=*/ this); FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance(); firebaseAppCheck.installAppCheckProviderFactory( DebugAppCheckProviderFactory.getInstance()); ``` 2. Obtain your debug token: 1. Run your app in the emulator or on your test device. 2. Look for the App Check debug token in your logs. For example: D DebugAppCheckProvider: Enter this debug secret into the allow list in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678 3. Copy the token (for example, `123a4567-b89c-12d3-e456-789012345678`). 3. Register your debug token with App Check: 1. In the Firebase console, go to the **Security** \> **App Check** \> [**Apps** tab](https://console.firebase.google.com/project/_/appcheck/apps/products/?useAutoProject=true). 2. Find your app, click the overflow menu (), and then select **Manage debug tokens**. 3. Follow the on-screen instructions to register your debug token. For details about the debug provider (including how to get a new debug token), check out the [official App Check docs](https://firebase.google.com/docs/app-check/android/debug-provider.md.txt). > [!CAUTION] > **Here are some critical points about the > App Check debug provider:** > > - **Keep your debug token and debug build private.** Don't commit your debug token to a public repository, and don't ship your debug token or debug build in production builds of your app. > - **Register your app with a production attestation provider before > releasing to end users.** You'll need to [register your app with a production App Check attestation provider](https://firebase.google.com/docs/ai-logic/app-check.md.txt) (for example, Play Integrity) so that your end-users can use your feature with App Check enforced. ### **Step 4**: Check if the on-device model is available Using [`FirebaseAIOnDevice`](https://firebase.google.com/docs/reference/android/com/google/firebase/ai/ondevice/FirebaseAIOnDevice.md.txt), check if the on-device model is available, and download the model if it's not available. Once downloaded, AICore will automatically keep the model updated. Check out the notes after the snippet for more details about AICore and managing the on-device model download. ### Kotlin ```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, downloading, and warming up the model is not yet available for Java. However, all other APIs and interactions in this guide are available for Java. Note the following about downloading the on-device model: - The time it takes to download the on-device model depends on many factors, including your network. - If your code uses an on-device model for its primary or fallback inference, make sure the model is downloaded early in your app's lifecycle so that the on-device model is available before your end-users encounter the code in your app. - If the on-device model is *not available* when an on-device inference request is made, the SDK will *not automatically* trigger the download of the on-device model. The SDK will either fall back to the cloud-hosted model or throw an exception (see details about the behavior of [inference modes](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#inference-modes)). - [AICore](https://android-developers.googleblog.com/2023/12/a-new-foundation-for-ai-on-android.html) (an Android system service) manages for you which model and version is downloaded, keeping the model updated, etc. Note that the device will only have one model downloaded, so if another app on the device has previously successfully downloaded the on-device model, then this check will return that the model is available. #### Latency optimization To optimize for the first inference call, you can have your app call [`onDeviceExtension?.warmUp()`](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/ai/OnDeviceExtension.md.txt#warmUp()) (currently available for Kotlin only). This loads the on-device model into memory and initializes runtime components. ### **Step 5**: Initialize the service and create a model instance |---| | *Click your Gemini API provider to view provider-specific content and code on this page.* | Set up the following before you send a prompt request to the model. 1. Initialize the service for your chosen API provider. 2. Create a `GenerativeModel` instance, and set the `mode` to one of the following. The descriptions here are very high-level, but you can learn details about the behavior of these modes in [Set an inference mode](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#inference-modes). - **`PREFER_ON_DEVICE`** : Attempt to use on-device model; otherwise, *fall back to the cloud-hosted model*. - **`ONLY_ON_DEVICE`** : Attempt to use on-device model; otherwise, *throw an exception*. - **`PREFER_IN_CLOUD`** : Attempt to use the cloud-hosted model; otherwise, *fall back to the on-device model*. - **`ONLY_IN_CLOUD`** : Attempt to use the cloud-hosted model; otherwise, *throw an exception*. ### Kotlin ```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 = "CLOUD_MODEL_NAME", onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE) ) ``` ### Java ```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( "CLOUD_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); ``` > [!NOTE] > **Note** : Keep the following in mind: > > - Before implementing hybrid or on-device inference, make sure to review the [list of not-yet-supported features](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#features-not-yet-supported). > - To use a cloud-hosted model, you must explicitly [specify a cloud-hosted model to use](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#specify-model). > - As part of the response, the SDK tells you [whether on-device or in-cloud inference was used](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#determine-inference-mode). ### **Step 6**: Send a prompt request to a model This section shows you how to send various types of input to generate different types of output, including: - [Generate text from text-only input](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#text-in-text-out) - [Generate text from text-and-image (multimodal) input](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#image-in-text-out) If you want to generate structured output (like JSON or enums), then use one of the following "generate text" examples and additionally [configure the model to respond according to a provided schema](https://firebase.google.com/docs/ai-logic/hybrid/android/generate-structured-output.md.txt). #### Generate text from text-only input |---| | *Before trying this sample, make sure that you've completed the [Get started](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#get-started) section of this guide.* | You can use [`generateContent()`](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/ai/GenerativeModel.md.txt#generateContent(kotlin.String)) to generate text from a prompt that contains text: ### Kotlin ```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 ```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 response = model.generateContent(prompt); Futures.addCallback(response, new FutureCallback() { @Override public void onSuccess(GenerateContentResponse result) { String resultText = result.getText(); System.out.println(resultText); } @Override public void onFailure(Throwable t) { t.printStackTrace(); } }, executor); ``` Note that Firebase AI Logic also supports streaming of text responses using [`generateContentStream`](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/ai/GenerativeModel.md.txt#generateContentStream(kotlin.String)) (instead of `generateContent`). #### Generate text from text-and-image (multimodal) input |---| | *Before trying this sample, make sure that you've completed the [Get started](https://firebase.google.com/docs/ai-logic/hybrid/android/get-started.md.txt#get-started) section of this guide.* | You can use [`generateContent()`](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/ai/GenerativeModel.md.txt#generateContent(kotlin.String)) to generate text from a prompt that contains text and *up to **one** image file (Bitmap only)* --- providing each input file's `mimeType` and the file itself. ### Kotlin ```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 ```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 response = model.generateContent(content); Futures.addCallback(response, new FutureCallback() { @Override public void onSuccess(GenerateContentResponse result) { String resultText = result.getText(); System.out.println(resultText); } @Override public void onFailure(Throwable t) { t.printStackTrace(); } }, executor); ``` Note that Firebase AI Logic also supports streaming of text responses using [`generateContentStream`](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/ai/GenerativeModel.md.txt#generateContentStream(kotlin.Array)) (instead of `generateContent`). ## What else can you do? You can use various additional configuration options and capabilities for your hybrid experiences: - [Set an inference mode.](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#inference-modes) - [Determine whether on-device or in-cloud inference was used.](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#determine-inference-mode) - [Specify a model to use.](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#specify-model) - [Use model configuration to control responses.](https://firebase.google.com/docs/ai-logic/hybrid/android/configuration-options.md.txt#model-config) - [Generate structured output (like JSON and enums).](https://firebase.google.com/docs/ai-logic/hybrid/android/generate-structured-output.md.txt) ## Features not yet supported As an experimental release, not all capabilities of cloud-hosted models or the Firebase AI Logic SDK are available for hybrid or on-device inference. ### Features not yet supported for **hybrid** implementations The following features cannot be used with hybrid implementations (neither on-device nor via cloud fallback): - **Gemini Live API**: Bi-directional real-time streaming is not supported. - **Server prompt templates**: Managed server prompt templates are not supported. - **Count tokens**: Count tokens shouldn't be relied upon because the count will differ between cloud-hosted and on-device models, so there's no intuitive fallback. ### Features not yet supported for **on-device** inference **The following features are *not yet supported for on-device inference*, but they are available for cloud-hosted models.** > [!NOTE] > **Note:** For many of these not-yet-supported features, if you set the mode to `PREFER_ON_DEVICE`, the SDK will automatically fall back to use the cloud-hosted model. However, to provide a more consistent experience for your users, consider directly using a cloud-hosted model. - Generating images - Can fall back to the cloud-hosted model; however, `ONLY_ON_DEVICE` mode will throw an exception. - Generating text from image file input types other than Bitmap (image loaded into memory) - Can fall back to the cloud-hosted model; however, `ONLY_ON_DEVICE` mode will throw an exception. - Generating text from image-only file input. For on-device inference, you must provide text as part of the multimodal request. - Can fall back to the cloud-hosted model; however, `ONLY_ON_DEVICE` mode will throw an exception. - Generating text from more than one image file input - Can fall back to the cloud-hosted model; however, `ONLY_ON_DEVICE` mode will throw an exception. - Generating text from multimodal inputs of audio, video, and documents (PDFs) - Can fall back to the cloud-hosted model; however, `ONLY_ON_DEVICE` mode will throw an exception. - Providing files using URLs in multimodal requests. For on-device inference, you must provide a single image as a Bitmap. - If you provide a file URL using `fileData` (`FileDataPart`), it can fall back to the cloud-hosted model (`ONLY_ON_DEVICE` mode will throw an exception). - If you embed a URL directly in a text prompt, it does *not* automatically fall back to the cloud-hosted model (embedded URLs are ignored by the on-device model). - Sending requests that exceed 4000 tokens (or approximately 3000 English words) - Can fall back to the cloud-hosted model; however, `ONLY_ON_DEVICE` mode will throw an exception. - Multi-turn chat - Does *not* automatically fall back to the cloud-hosted model (on-device inference concatenates the prompt history into a single text prompt; because the on-device model doesn't distinguish between roles and sees the history as a single message, it won't be as precise as a cloud-hosted model). - If you want to use multi-turn chat, we recommend using `ONLY_IN_CLOUD` mode. - Providing the model with *tools* to help it generate its response (like function calling, code execution, URL context, Grounding with Google Search, and Grounding with Google Maps) - Does *not* automatically fall back to the cloud-hosted model. If you want to use tools, we recommend using `ONLY_IN_CLOUD` mode. - AI monitoring in the Firebase console does ***not*** show any data for on-device inference (including on-device logs). However, any inference that uses a cloud-hosted model can be monitored just like other inference via Firebase AI Logic. ### Additional limitations In addition to the above, ***on-device* inference has the following limitations** (learn more in the [ML Kit documentation](https://developers.google.com/ml-kit/genai/prompt/android/get-started#supported-features)): - The end-user of your app must be using a [supported device](https://developers.google.com/ml-kit/genai#prompt-device) for on-device inference. - Your app can only run on-device inference when it's in the foreground. - Only English and Korean have been validated for on-device inference. - The maximum token limit for the entire on-device inference request is 4000 tokens. If your requests might exceed this limit, then make sure to configure an inference mode that can use a cloud-hosted model. - We recommend avoiding on-device inference use cases that require long output (more than 256 tokens). - [AICore](https://android-developers.googleblog.com/2023/12/a-new-foundation-for-ai-on-android.html) (an Android system service that manages the on-device models) enforces an inference quota *per app* . Making too many API requests in a short period will result in an `ErrorCode.BUSY` response. If you're receiving this error, consider using exponential backoff to retry the request. Also, `ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED` can be returned if an app exceeds a long-duration quota (for example, daily quota).
[Give feedback about your experience with Firebase AI Logic](https://firebase.google.com/docs/ai-logic/feedback)