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


Puoi creare app e funzionalità per Android basate sull'AI con l'inferenza ibrida utilizzando Firebase AI Logic. L'inferenza ibrida consente di eseguire l'inferenza utilizzando modelli sul dispositivo quando disponibili e di passare senza problemi a modelli ospitati sul 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, come la temperatura.

Tieni presente che l'inferenza on-device tramite Firebase AI Logic è supportata per le app Android in esecuzione su dispositivi specifici ed è regolata dai termini di ML Kit, nonché dai termini specifici per gli aspetti di IA 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
    • Contesto locale
    • Inferenza senza costi
    • Funzionalità offline

  • L'utilizzo delle offerte con funzionalità ibrida:

    • Raggiungere una parte più ampia del tuo pubblico tenendo conto della disponibilità del modello sul dispositivo e della connettività a internet

Funzionalità e capacità supportate per l'inferenza sul dispositivo

L'inferenza sul dispositivo supporta solo la generazione di testo a un solo turno (non chat), con output di streaming o non 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 sul dispositivo

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 alla pagina Firebase 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. Configura il progetto in modo che utilizzi un provider "Gemini API".

    Ti consigliamo di iniziare a utilizzare Gemini Developer API. In qualsiasi momento, puoi sempre configurare Vertex AI Gemini API (e il relativo requisito di fatturazione).

    Per Gemini Developer API, la console abiliterà le API richieste e creerà una chiave API Gemini nel tuo progetto.
    Non aggiungere questa chiave API Gemini al codebase della tua app. Scopri di più.

  5. Se richiesto nel flusso di lavoro della console, segui le istruzioni sullo schermo per registrare la tua app e connetterla a Firebase.

  6. Continua con il passaggio successivo di questa guida per aggiungere l'SDK alla tua app.

Passaggio 2: aggiungi gli SDK richiesti

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 per Android:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.10.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")
}

Java

Per Java, devi aggiungere due librerie aggiuntive.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.10.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")

  // 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: controlla se il modello sul dispositivo è disponibile

Utilizzando FirebaseAIOnDevice, controlla se il modello sul dispositivo è disponibile e scaricalo in caso contrario.

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

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.

Tieni presente quanto segue in merito al download del modello sul dispositivo:

  • Il tempo necessario per scaricare il modello sul dispositivo dipende da molti fattori, inclusa 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 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 attiva automaticamente il download del modello on-device. L'SDK eseguirà il fallback al modello ospitato sul cloud o genererà un'eccezione (vedi i dettagli sul comportamento delle modalità di inferenza).

  • AICore (un servizio di sistema Android) gestisce il modello e la versione scaricati, 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 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 warmup(). In questo modo, il modello sul dispositivo viene caricato in memoria e vengono inizializzati i componenti di runtime.

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

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

Configura quanto segue prima di inviare una richiesta di prompt al modello.

  1. Inizializza il servizio per il provider API scelto.

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

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

    • ONLY_ON_DEVICE: tenta di utilizzare il modello sul dispositivo; 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 sul cloud; in caso contrario, 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 = "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);

Passaggio 5: 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:

Generare testo da 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).

Generare 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 delle risposte di testo utilizzando generateContentStream (anziché generateContent).

Cos'altro puoi fare?

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

Funzionalità non ancora disponibili per l'inferenza sul dispositivo

In quanto release sperimentale, non tutte le funzionalità dei modelli cloud sono disponibili per l'inferenza on-device.

Le funzionalità elencate in questa sezione non sono ancora disponibili per l'inferenza sul dispositivo. Se vuoi utilizzare una di queste funzionalità, ti consigliamo di utilizzare la modalità di inferenza ONLY_IN_CLOUD per un'esperienza più coerente.

  • Generazione di output strutturato (come JSON o enumerazioni)

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

  • Generare testo da più file immagine

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

  • Generare immagini utilizzando i modelli Gemini o Imagen

  • Fornire file utilizzando URL nelle richieste multimodali. Devi fornire i file come dati incorporati ai modelli sul dispositivo

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

  • Chat multi-turno

  • Fornire al modello strumenti per aiutarlo a generare la risposta (come chiamate di funzioni, esecuzione di codice, contesto URL e fondatezza con la Ricerca Google)

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

Limitazioni aggiuntive

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 sul dispositivo.

  • L'app può eseguire l'inferenza sul dispositivo solo quando è in primo piano.

  • Solo l'inglese e il coreano sono stati convalidati per l'inferenza sul dispositivo.

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

  • Ti consigliamo di evitare casi d'uso dell'inferenza sul dispositivo che richiedono un output lungo (più di 256 token).

  • AICore (un servizio di sistema Android che gestisce i modelli sul dispositivo) applica una quota di inferenza per app. L'invio di un numero eccessivo di richieste API in un breve periodo comporterà 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).


Fornisci un feedback sulla tua esperienza con Firebase AI Logic