Creare esperienze ibride nelle app per Android con modelli ospitati sul dispositivo e nel cloud


Puoi creare app e funzionalità Android basate sull'AI con l'inferenza ibrida utilizzando Firebase AI Logic. L'inferenza ibrida consente di eseguire l'inferenza utilizzando modelli on-device, se disponibili, e di passare senza problemi ai modelli ospitati nel cloud in caso contrario (e viceversa).

Questa pagina descrive come iniziare a utilizzare l'SDK client, oltre a mostrare opzioni e funzionalità di configurazione aggiuntive.

Tieni presente che l'inferenza on-device tramite Firebase AI Logic è supportata per le app per Android che utilizzano l'Firebase AI Logic SDK v17.10.0+ (BoM v34.10.0+) e che vengono eseguite su dispositivi specifici. È regolato dai termini di ML Kit, nonché dai termini specifici per gli aspetti di AI generativa di ML Kit.

Casi d'uso consigliati e funzionalità supportate

Casi d'uso consigliati

  • L'utilizzo di un modello on-device per l'inferenza offre:

    • Privacy avanzata
    • Local Context
    • Inferenza senza costi
    • Funzionalità offline

  • L'utilizzo della funzionalità ibrida offre:

    • Raggiungi un pubblico più ampio adattandoti alla disponibilità dei modelli on-device e alla connessione a internet

Funzionalità supportate per l'inferenza on-device

L'inferenza on-device supporta solo la generazione di testo a turno singolo (non chat), con output in streaming o non in streaming. Supporta le seguenti funzionalità di generazione di testo:

Assicurati di esaminare l'elenco delle funzionalità non ancora disponibili per l'inferenza sul dispositivo in fondo a questa pagina.

Prima di iniziare

Tieni presente quanto segue:

Dispositivi Android supportati e relativi modelli on-device

Per l'inferenza on-device (che utilizza l'API Prompt di ML Kit), puoi trovare un elenco di dispositivi supportati e dei relativi modelli on-device nella documentazione di ML Kit.

Inizia

Questi passaggi iniziali descrivono la configurazione generale richiesta per qualsiasi richiesta di prompt supportata che vuoi inviare.

Passaggio 1: configura un progetto Firebase e connetti la tua app a Firebase

  1. Accedi alla console Firebase, quindi seleziona il tuo progetto Firebase.

  2. Nella console Firebase, vai a Servizi AI > AI Logic.

  3. Fai clic su Inizia per avviare un workflow guidato che ti aiuti a configurare le API richieste e le risorse per il tuo progetto.

  4. Se richiesto, segui le istruzioni sullo schermo per registrare la tua app e aggiungere la configurazione Firebase alla tua app.

  5. Quando ti viene chiesto di scegliere un "provider dell'API Gemini", ti consigliamo di selezionare l'API Gemini Developer, che ti consente di iniziare rapidamente senza costi.

    In qualsiasi momento successivo, puoi sempre configurare Agent Platform Gemini API (formerly Vertex AI) (e il relativo requisito per la fatturazione).

  6. Continua il flusso di lavoro per configurare le API richieste e i servizi associati per Firebase AI Logic.

    A partire dall'inizio di luglio 2026, questa fase del workflow applica automaticamente Firebase App Check per AI Logic, che è un servizio critico per contribuire a proteggere Gemini API quando l'accesso avviene direttamente dalla tua app. Come parte dei primi passi (vedi i passaggi più avanti in questa guida), dovrai configurare il provider di debug di App Check per lo sviluppo locale quando App Check viene applicato.

  7. Continua con il passaggio successivo di questa guida per aggiungere gli SDK necessari alla tua app.

Passaggio 2: aggiungi gli SDK necessari

L'SDK Firebase AI Logic per Android (firebase-ai) insieme all'SDK Firebase AI Logic On-Device (firebase-ai-ondevice) forniscono l'accesso alle API per interagire con i modelli generativi.

Nel file Gradle (a livello di app) del modulo (ad esempio <project>/<app-module>/build.gradle.kts), aggiungi le dipendenze per le librerie Firebase AI Logic e App Check per Android:

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:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")
}

Java

Per Java, devi aggiungere due librerie aggiuntive.

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.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  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")
}

Passaggio 3: configura il provider di debug App Check per lo sviluppo locale

A partire dall'inizio di luglio 2026, nell'ambito del workflow di configurazione guidata per AI Logic in Play Console, Firebase App Check viene applicato automaticamente per proteggere Gemini API. Per lo sviluppo locale, devi configurare il provider di debug App Check per ignorare l'attestazione mantenendo comunque l'applicazione di App Check.

  1. Nella build di debug, configura App Check in modo che utilizzi la factory del provider di debug:

    Kotlin

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

    Java

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

  2. Ottieni il token di debug:

    1. Esegui l'app nell'emulatore o sul dispositivo di test.

    2. Cerca il token di debug App Check nei log. Ad esempio:

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

    3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (tra cui come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Passaggio 4: controlla se il modello on-device è disponibile

Utilizzando FirebaseAIOnDevice, controlla se il modello on-device è disponibile e scaricalo se non lo è.

Una volta scaricato, AICore manterrà automaticamente aggiornato il modello. Consulta le note dopo lo snippet per maggiori dettagli su AICore e sulla gestione del download del modello on-device.

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.

Tieni presente quanto segue per il download del modello on-device:

  • Il tempo necessario per scaricare il modello on-device dipende da molti fattori, tra cui la rete.

  • Se il tuo codice utilizza un modello on-device per l'inferenza principale o di riserva, assicurati che il modello venga scaricato all'inizio del ciclo di vita della tua app in modo che il modello on-device sia disponibile prima che gli utenti finali incontrino il codice nella tua app.

  • Se il modello on-device non è disponibile quando viene effettuata una richiesta di inferenza on-device, l'SDK non attiverà automaticamente il download del modello on-device. L'SDK utilizzerà il modello ospitato nel cloud o genererà un'eccezione (consulta i dettagli sul comportamento delle modalità di inferenza).

  • AICore (un servizio di sistema Android) gestisce per te il download del modello e della versione, mantenendo il modello aggiornato e così via. Tieni presente che sul dispositivo verrà scaricato un solo modello, quindi se un'altra app sul dispositivo ha già scaricato correttamente il modello on-device, questo controllo restituirà che il modello è disponibile.

Ottimizzazione della latenza

Per ottimizzare la prima chiamata di inferenza, puoi fare in modo che la tua app chiami onDeviceExtension?.warmUp() (attualmente disponibile solo per Kotlin). In questo modo, il modello on-device viene caricato in memoria e vengono inizializzati i componenti di runtime.

Passaggio 5: inizializza il servizio e crea un'istanza del modello

Fai clic sul tuo provider Gemini API per visualizzare i contenuti e il codice specifici del provider in questa pagina.

Prima di inviare una richiesta di prompt al modello, configura quanto segue.

  1. Inizializza il servizio per il provider API che hai scelto.

  2. Crea un'istanza GenerativeModel e imposta mode su uno dei seguenti valori. Le descrizioni qui sono molto generali, ma puoi scoprire i dettagli sul comportamento di queste modalità in Imposta una modalità di inferenza.

    • PREFER_ON_DEVICE: tenta di utilizzare il modello on-device; altrimenti, utilizza il modello ospitato nel cloud.

    • ONLY_ON_DEVICE: tenta di utilizzare il modello on-device; altrimenti, genera un'eccezione.

    • PREFER_IN_CLOUD: tenta di utilizzare il modello ospitato sul cloud; in caso contrario, torna al modello sul dispositivo.

    • ONLY_IN_CLOUD: tenta di utilizzare il modello ospitato nel cloud; altrimenti, genera un'eccezione.

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 

// 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);

Passaggio 6: invia una richiesta di prompt a un modello

Questa sezione mostra come inviare vari tipi di input per generare diversi tipi di output, tra cui:

Genera testo da un input di solo testo

Prima di provare questo esempio, assicurati di aver completato la sezione Inizia di questa guida.

Puoi utilizzare generateContent() per generare testo da un prompt che contiene testo:

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

Tieni presente che Firebase AI Logic supporta anche lo streaming delle risposte di testo utilizzando generateContentStream (anziché generateContent).

Genera testo da input di testo e immagini (multimodale)

Prima di provare questo esempio, assicurati di aver completato la sezione Inizia di questa guida.

Puoi utilizzare generateContent() per generare testo da un prompt che contiene testo e fino a un file immagine (solo bitmap), fornendo il mimeType di ogni file di input e il file stesso.

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

Tieni presente che Firebase AI Logic supporta anche lo streaming di risposte di testo utilizzando generateContentStream (anziché generateContent).

Cos'altro puoi fare?

Puoi utilizzare varie opzioni e funzionalità di configurazione aggiuntiva per le tue esperienze ibride:

Funzionalità non ancora disponibili per l'inferenza on-device

In quanto release sperimentale, non tutte le funzionalità dei modelli cloud sono disponibili per l'inferenza on-device. Le seguenti funzionalità non sono ancora disponibili per l'inferenza on-device (ma sono generalmente disponibili per l'inferenza basata su cloud).

  • Generazione delle immagini in corso…

    • Può eseguire il failover sul modello ospitato sul cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Generazione di testo da tipi di input di file immagine diversi da Bitmap (immagine caricata in memoria)

    • Può tornare al modello ospitato nel cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Generazione di testo da un file di input di sola immagine. Per l'inferenza on-device, devi fornire il testo come parte della richiesta multimodale.

    • Può tornare al modello ospitato nel cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Generazione di testo da più file immagine di input

    • Può tornare al modello ospitato nel cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Generazione di testo da input di audio, video e documenti (come i PDF)

    • Può eseguire il failover sul modello ospitato sul cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Fornire file utilizzando URL nelle richieste multimodali. Per l'inferenza on-device, devi fornire una singola immagine come bitmap.

    • Se fornisci un URL file utilizzando fileData (FileDataPart), può essere utilizzato il modello ospitato nel cloud (la modalità ONLY_ON_DEVICE genererà un'eccezione).
    • Se incorpori un URL direttamente in un prompt testuale, non viene eseguito automaticamente il fallback al modello ospitato nel cloud (gli URL incorporati vengono ignorati dal modello on-device).

  • Invio di richieste che superano i 4000 token (o circa 3000 parole in inglese)

    • Può tornare al modello ospitato nel cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Chat a più turni

    • Non esegue automaticamente il fallback al modello ospitato nel cloud (l'inferenza on-device concatena la cronologia dei prompt in un unico prompt testuale; poiché il modello on-device non distingue tra i ruoli e vede la cronologia come un singolo messaggio, non sarà preciso come un modello ospitato nel cloud).
    • Se vuoi utilizzare la chat a più turni, ti consigliamo di utilizzare la modalità ONLY_IN_CLOUD.

  • Fornire al modello strumenti per aiutarlo a generare la risposta (come chiamata di funzione, esecuzione di codice, contesto dell'URL, grounding con Google Search e grounding con Google Maps)

    • Non esegue automaticamente il failover sul modello ospitato sul cloud. Se vuoi utilizzare gli strumenti, ti consigliamo di utilizzare la modalità ONLY_IN_CLOUD.

Il monitoraggio AI nella console Firebase non mostra dati per l'inferenza on-device (inclusi i log del dispositivo on-device). Tuttavia, qualsiasi inferenza che utilizza un modello ospitato sul cloud può essere monitorata come altre inferenze tramite Firebase AI Logic.

Ulteriori limitazioni

Oltre a quanto sopra, l'inferenza on-device presenta le seguenti limitazioni (scopri di più nella documentazione di ML Kit):

  • L'utente finale della tua app deve utilizzare un dispositivo supportato per l'inferenza on-device.

  • La tua app può eseguire l'inferenza on-device solo quando è in primo piano.

  • Solo l'inglese e il coreano sono stati convalidati per l'inferenza on-device.

  • Il limite massimo di token per l'intera richiesta di inferenza sul dispositivo è di 4000 token. Se le tue richieste potrebbero superare questo limite, assicurati di configurare una modalità di inferenza che possa utilizzare un modello ospitato nel cloud.

  • Ti consigliamo di evitare i casi d'uso di inferenza on-device che richiedono un output lungo (più di 256 token).

  • AICore (un servizio di sistema Android che gestisce i modelli on-device) applica una quota di inferenza per app. Se effettui troppe richieste API in un breve periodo di tempo, riceverai una risposta ErrorCode.BUSY. Se ricevi questo errore, valuta la possibilità di utilizzare il backoff esponenziale per riprovare a inviare la richiesta. Inoltre, ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED può essere restituito se un'app supera una quota di lunga durata (ad esempio, la quota giornaliera).


Invia un feedback sulla tua esperienza con Firebase AI Logic