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 e mostra ulteriori opzioni e funzionalità di configurazione.

Tieni presente che l'inferenza on-device tramite Firebase AI Logic è supportata per le app per Android che utilizzano l'SDK Firebase AI Logic v17.10.0+ (BoM v34.10.0+) e sono in esecuzione 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:

    • Maggiore privacy
    • 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 consultare l'elenco delle funzionalità non ancora disponibili per l'inferenza on-device 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 per iniziare 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 AI Services > AI Logic.

  3. Fai clic su Inizia per avviare un flusso di lavoro guidato che ti aiuta a configurare le API e le risorse richieste per il tuo progetto.

  4. Se richiesto, segui le istruzioni sullo schermo per registrare la tua app e aggiungere la configurazione Firebase all'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 nel workflow 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 proteggere Gemini API quando l'accesso avviene direttamente dalla tua app. Come parte della procedura iniziale (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. Vai al passaggio successivo di questa guida per aggiungere gli SDK richiesti 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.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  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.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")
}

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 nella console, Firebase App Check viene applicato automaticamente per proteggere Gemini API. Per lo sviluppo locale, devi configurare il App Check provider di debug per bypassare 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. Per maggiori dettagli su AICore e sulla gestione del download del modello on-device, consulta le note dopo lo snippet.

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 dell'app, in modo che sia disponibile prima che gli utenti finali incontrino il codice nell'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 i componenti di runtime vengono inizializzati.

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 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: Tentativo di utilizzare il modello on-device; altrimenti, tornare al modello basato su cloud.

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

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

    • 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 Per iniziare 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 di 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 Per iniziare 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 sai fare?

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

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

Trattandosi di una 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 fallback al modello ospitato nel 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ò eseguire il fallback 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ò eseguire il fallback al modello ospitato nel cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Generazione di testo da più file immagine di input

    • Può eseguire il fallback 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 fallback al modello ospitato nel cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà un'eccezione.

  • Fornire file utilizzando gli 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ò eseguire il fallback 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 fallback al modello ospitato nel 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 nel cloud può essere monitorata come qualsiasi altra inferenza 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 on-device è 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, riceverai una risposta ErrorCode.BUSY. Se ricevi questo errore, valuta la possibilità di utilizzare il backoff esponenziale per riprovare 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