Hybride Funktionen in Android-Apps mit On-Device- und Cloud-basierten Modellen entwickeln


Mit Firebase AI Logic können Sie KI-gestützte Android-Apps und ‑Funktionen mit hybrider Inferenz erstellen. Die Hybrid-Inferenz ermöglicht die Ausführung von Inferenzen mit On-Device-Modellen, sofern verfügbar, und den nahtlosen Wechsel zu in der Cloud gehosteten Modellen (und umgekehrt).

Auf dieser Seite wird beschrieben, wie Sie mit dem Client SDK beginnen. Außerdem werden zusätzliche Konfigurationsoptionen und Funktionen vorgestellt.

Die On-Device-Inferenz über Firebase AI Logic wird für Android-Apps unterstützt, die das Firebase AI Logic SDK ab Version 17.10.0 (BoM ab Version 34.10.0) verwenden und auf bestimmten Geräten ausgeführt werden. Sie unterliegt den Nutzungsbedingungen für ML Kit sowie den Nutzungsbedingungen für die generativen KI-Aspekte von ML Kit.

Empfohlene Anwendungsfälle und unterstützte Funktionen

Empfohlene Anwendungsfälle

  • Die Verwendung eines On-Device-Modells für die Inferenz bietet folgende Vorteile:

    • Erweiterter Datenschutz
    • Lokaler Kontext
    • Kostenlose Inferenz
    • Offline-Funktionen
  • Die Verwendung der Hybrid-Funktion bietet:

    • Erreichen Sie mehr Nutzer, indem Sie die Verfügbarkeit von On-Device-Modellen und die Internetverbindung berücksichtigen.

Unterstützte Funktionen und Features für die On-Device-Inferenz

Die On-Device-Inferenz unterstützt nur die Single-Turn-Textgenerierung (keinen Chat) mit Streaming- oder Nicht-Streaming-Ausgabe. Es unterstützt die folgenden Funktionen zur Textgenerierung:

Sehen Sie sich die Liste der noch nicht verfügbaren Funktionen für die On-Device-Inferenz unten auf dieser Seite an.

Hinweis

Beachten Sie Folgendes:

Unterstützte Android-Geräte und ihre On-Device-Modelle

Für die On-Device-Inferenz (die die Prompt API von ML Kit verwendet) finden Sie in der ML Kit-Dokumentation eine Liste der unterstützten Geräte und ihrer On-Device-Modelle.

Jetzt starten

In diesen Schritten wird die erforderliche allgemeine Einrichtung für alle unterstützten Prompt-Anfragen beschrieben, die Sie senden möchten.

Schritt 1: Firebase-Projekt einrichten und App mit Firebase verbinden

  1. Melden Sie sich in der Firebase-Konsole an und wählen Sie Ihr Firebase-Projekt aus.

  2. Rufen Sie in der Firebase-Konsole KI-Dienste > AI Logic auf.

  3. Klicken Sie auf Jetzt starten, um einen geführten Workflow zu starten, mit dem Sie die erforderlichen APIs und Ressourcen für Ihr Projekt einrichten können.

  4. Folgen Sie bei Aufforderung der Anleitung auf dem Bildschirm, um Ihre App zu registrieren und die Firebase-Konfiguration hinzuzufügen.

  5. Wenn Sie aufgefordert werden, einen „Gemini API-Anbieter“ auszuwählen, empfehlen wir die Gemini Developer API. Damit können Sie schnell und kostenlos loslegen.

    Sie können die Agent Platform Gemini API (formerly Vertex AI) (und die Abrechnungsanforderung) jederzeit später einrichten.

  6. Fahren Sie im Workflow fort, um die erforderlichen APIs und zugehörigen Dienste für Firebase AI Logic einzurichten.

    Ab Anfang Juli 2026 wird in dieser Phase des Workflows automatisch Firebase App Check für AI Logic erzwungen. Dies ist ein wichtiger Dienst, der zum Schutz von Gemini API beiträgt, wenn direkt über Ihre App darauf zugegriffen wird. Im Rahmen der ersten Schritte (siehe Schritte weiter unten in diesem Leitfaden) müssen Sie den Debug-Anbieter für App Check für die lokale Entwicklung konfigurieren, wenn App Check erzwungen wird.

  7. Fahren Sie mit dem nächsten Schritt in dieser Anleitung fort, um die erforderlichen SDKs zu Ihrer App hinzuzufügen.

Schritt 2: Erforderliche SDKs hinzufügen

Das Firebase AI Logic SDK für Android (firebase-ai) und das Firebase AI Logic On-Device SDK (firebase-ai-ondevice) bieten Zugriff auf die APIs für die Interaktion mit generativen Modellen.

Fügen Sie in der Gradle-Datei Ihres Moduls (auf App-Ebene) (z. B. <project>/<app-module>/build.gradle.kts) die Abhängigkeiten für die Firebase AI Logic- und App Check-Bibliotheken für Android hinzu:

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

Für Java müssen Sie zwei zusätzliche Bibliotheken hinzufügen.

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")
}

Schritt 3: App Check-Debug-Anbieter für die lokale Entwicklung konfigurieren

Ab Anfang Juli 2026 wird im Rahmen des geführten Einrichtungsworkflows für AI Logic in der Console automatisch Firebase App Check erzwungen, um die Gemini API zu schützen. Für die lokale Entwicklung müssen Sie den App Check-Debug-Anbieter so konfigurieren, dass die Attestierung umgangen wird, während die Erzwingung von App Check beibehalten wird.

  1. Konfigurieren Sie in Ihrem Debug-Build App Check so, dass die Debug-Anbieter-Factory verwendet wird:

    Kotlin

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

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
    FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
    firebaseAppCheck.installAppCheckProviderFactory(
            DebugAppCheckProviderFactory.getInstance());
    
  2. Rufen Sie Ihr Debug-Token ab:

    1. Führen Sie Ihre App im Emulator oder auf Ihrem Testgerät aus.

    2. Suchen Sie in Ihren Logs nach dem Debug-Token App Check. Beispiel:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
      in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678
      
    3. Kopieren Sie das Token (z. B. 123a4567-b89c-12d3-e456-789012345678).

  3. Registrieren Sie Ihr Debug-Token bei App Check:

    1. Rufen Sie in der Firebase-Konsole den Tab Sicherheit > App Check > Apps auf.

    2. Suchen Sie Ihre App, klicken Sie auf das Dreipunkt-Menü () und wählen Sie Debug-Tokens verwalten aus.

    3. Folgen Sie der Anleitung auf dem Bildschirm, um Ihr Debug-Token zu registrieren.

Weitere Informationen zum Debug-Anbieter (einschließlich des Abrufs eines neuen Debug-Tokens) finden Sie in der offiziellen App Check-Dokumentation.

Schritt 4: Prüfen, ob das On-Device-Modell verfügbar ist

Prüfen Sie mit FirebaseAIOnDevice, ob das On-Device-Modell verfügbar ist, und laden Sie es herunter, wenn es nicht verfügbar ist.

Nach dem Herunterladen wird das Modell von AICore automatisch auf dem neuesten Stand gehalten. Weitere Informationen zu AICore und zur Verwaltung des Downloads des On-Device-Modells finden Sie in den Hinweisen nach dem 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.

Beachten Sie beim Herunterladen des On-Device-Modells Folgendes:

  • Wie lange es dauert, das On-Device-Modell herunterzuladen, hängt von vielen Faktoren ab, einschließlich Ihres Netzwerks.

  • Wenn Ihr Code ein On-Device-Modell für die primäre oder Fallback-Inferenz verwendet, achten Sie darauf, dass das Modell früh im Lebenszyklus Ihrer App heruntergeladen wird, damit es verfügbar ist, bevor Endnutzer den Code in Ihrer App sehen.

  • Wenn das On-Device-Modell nicht verfügbar ist, wenn eine On-Device-Inferenzanfrage gestellt wird, löst das SDK den Download des On-Device-Modells nicht automatisch aus. Das SDK greift entweder auf das in der Cloud gehostete Modell zurück oder löst eine Ausnahme aus (weitere Informationen zum Verhalten von Inferenzmodi).

  • AICore (ein Android-Systemdienst) verwaltet für Sie, welches Modell und welche Version heruntergeladen wird, hält das Modell auf dem neuesten Stand usw. Beachten Sie, dass auf dem Gerät nur ein Modell heruntergeladen wird. Wenn also eine andere App auf dem Gerät das On-Device-Modell zuvor erfolgreich heruntergeladen hat, wird bei dieser Prüfung zurückgegeben, dass das Modell verfügbar ist.

Latenzoptimierung

Wenn Sie den ersten Inferenzaufruf optimieren möchten, können Sie in Ihrer App onDeviceExtension?.warmUp() aufrufen (derzeit nur für Kotlin verfügbar). Dadurch wird das On-Device-Modell in den Arbeitsspeicher geladen und die Laufzeitkomponenten werden initialisiert.

Schritt 5: Dienst initialisieren und Modellinstanz erstellen

Klicken Sie auf Ihren Gemini API-Anbieter, um anbieterspezifische Inhalte und Code auf dieser Seite aufzurufen.

Richten Sie Folgendes ein, bevor Sie eine Prompt-Anfrage an das Modell senden.

  1. Initialisieren Sie den Dienst für den ausgewählten API-Anbieter.

  2. Erstellen Sie eine GenerativeModel-Instanz und legen Sie für mode einen der folgenden Werte fest. Die Beschreibungen hier sind sehr allgemein gehalten. Details zum Verhalten dieser Modi finden Sie unter Inferenzmodus festlegen.

    • PREFER_ON_DEVICE: Versucht, das On-Device-Modell zu verwenden. Wenn das nicht möglich ist, wird auf das cloudgehostete Modell zurückgegriffen.

    • ONLY_ON_DEVICE: Versucht, das On-Device-Modell zu verwenden. Andernfalls wird eine Ausnahme ausgelöst.

    • PREFER_IN_CLOUD: Versucht, das in der Cloud gehostete Modell zu verwenden. Andernfalls wird auf das On-Device-Modell zurückgegriffen.

    • ONLY_IN_CLOUD: Versuchen Sie, das in der Cloud gehostete Modell zu verwenden. Andernfalls lösen Sie eine Ausnahme aus.

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

Schritt 6: Prompt-Anfrage an ein Modell senden

In diesem Abschnitt erfahren Sie, wie Sie verschiedene Arten von Eingaben senden, um verschiedene Arten von Ausgaben zu generieren, darunter:

Text aus Nur-Text-Eingabe generieren

Bevor Sie dieses Beispiel ausprobieren, müssen Sie den Abschnitt Erste Schritte dieses Leitfadens abgeschlossen haben.

Sie können generateContent() verwenden, um Text aus einem Prompt zu generieren, der Text enthält:

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

Beachten Sie, dass Firebase AI Logic auch das Streaming von Textantworten mit generateContentStream (anstelle von generateContent) unterstützt.

Text aus Text- und Bild-Eingaben (multimodal) generieren

Bevor Sie dieses Beispiel ausprobieren, müssen Sie den Abschnitt Erste Schritte dieses Leitfadens abgeschlossen haben.

Mit generateContent() können Sie Text aus einem Prompt generieren, der Text und bis zu eine Bilddatei (nur Bitmap) enthält. Geben Sie dazu den mimeType jeder Eingabedatei und die Datei selbst an.

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

Beachten Sie, dass Firebase AI Logic auch das Streaming von Textantworten mit generateContentStream (anstelle von generateContent) unterstützt.

Was kannst du sonst noch alles für mich tun?

Für Ihre Hybridumgebungen können Sie verschiedene zusätzliche Konfigurationsoptionen und Funktionen verwenden:

Noch nicht für die On-Device-Inferenz verfügbare Funktionen

Da es sich um eine experimentelle Version handelt, sind nicht alle Funktionen von Cloud-Modellen für die Inferenz auf dem Gerät verfügbar. Die folgenden Funktionen sind noch nicht für die On-Device-Inferenz verfügbar (sie sind aber in der Regel für die cloudbasierte Inferenz verfügbar).

  • Bilder werden generiert

    • Kann auf das in der Cloud gehostete Modell zurückgreifen. Im ONLY_ON_DEVICE-Modus wird jedoch eine Ausnahme ausgelöst.
  • Text aus anderen Bilddateieingabetypen als Bitmap generieren (Bild in den Arbeitsspeicher geladen)

    • Kann auf das in der Cloud gehostete Modell zurückgreifen. Der ONLY_ON_DEVICE-Modus löst jedoch eine Ausnahme aus.
  • Text aus einer reinen Bilddatei generieren. Für die On-Device-Inferenz müssen Sie Text als Teil der multimodalen Anfrage bereitstellen.

    • Kann auf das in der Cloud gehostete Modell zurückgreifen. Der ONLY_ON_DEVICE-Modus löst jedoch eine Ausnahme aus.
  • Text aus mehreren Bilddateieingaben generieren

    • Kann auf das in der Cloud gehostete Modell zurückgreifen. Im ONLY_ON_DEVICE-Modus wird jedoch eine Ausnahme ausgelöst.
  • Text aus Audio-, Video- und Dokumenteingaben (z. B. PDFs) generieren

    • Kann auf das in der Cloud gehostete Modell zurückgreifen. Im ONLY_ON_DEVICE-Modus wird jedoch eine Ausnahme ausgelöst.
  • Dateien mithilfe von URLs in multimodalen Anfragen bereitstellen. Für die On-Device-Inferenz müssen Sie ein einzelnes Bild als Bitmap bereitstellen.

    • Wenn Sie eine Datei-URL mit fileData (FileDataPart) angeben, kann auf das in der Cloud gehostete Modell zurückgegriffen werden. Im ONLY_ON_DEVICE-Modus wird eine Ausnahme ausgelöst.
    • Wenn Sie eine URL direkt in einen Text-Prompt einbetten, wird nicht automatisch auf das in der Cloud gehostete Modell zurückgegriffen. Eingebettete URLs werden vom On-Device-Modell ignoriert.
  • Anfragen mit mehr als 4.000 Tokens (oder etwa 3.000 englischen Wörtern) senden

    • Kann auf das in der Cloud gehostete Modell zurückgreifen. Der ONLY_ON_DEVICE-Modus löst jedoch eine Ausnahme aus.
  • Multi-Turn-Unterhaltung

    • Es wird nicht automatisch auf das in der Cloud gehostete Modell zurückgegriffen. Bei der On-Device-Inferenz wird der Prompt-Verlauf zu einem einzigen Text-Prompt verkettet. Da das On-Device-Modell nicht zwischen Rollen unterscheidet und den Verlauf als eine einzige Nachricht sieht, ist es nicht so präzise wie ein in der Cloud gehostetes Modell.
    • Wenn Sie Multi-Turn-Unterhaltungen verwenden möchten, empfehlen wir den ONLY_IN_CLOUD-Modus.
  • Dem Modell Tools zur Verfügung stellen, die es beim Generieren der Antwort unterstützen (z. B. Funktionsaufrufe, Code-Ausführung, URL-Kontext, Fundierung mit Google Search und Fundierung mit Google Maps)

    • Es wird nicht automatisch auf das in der Cloud gehostete Modell zurückgegriffen. Wenn Sie Tools verwenden möchten, empfehlen wir den ONLY_IN_CLOUD-Modus.

Beim KI-Monitoring in der Firebase-Konsole werden keine Daten für die On-Device-Inferenz (einschließlich Geräteprotokolle) angezeigt. Inferenz, die ein in der Cloud gehostetes Modell verwendet, kann jedoch wie andere Inferenz über Firebase AI Logic überwacht werden.

Zusätzliche Einschränkungen

Zusätzlich zu den oben genannten Einschränkungen gelten für die Inferenz auf dem Gerät die folgenden Einschränkungen (weitere Informationen finden Sie in der ML Kit-Dokumentation):

  • Der Endnutzer Ihrer App muss ein unterstütztes Gerät für die On-Device-Inferenz verwenden.

  • Ihre App kann die On-Device-Inferenz nur ausführen, wenn sie sich im Vordergrund befindet.

  • Nur Englisch und Koreanisch wurden für die On-Device-Inferenz validiert.

  • Das maximale Tokenlimit für die gesamte On-Device-Inferenzanfrage beträgt 4.000 Tokens. Wenn Ihre Anfragen dieses Limit überschreiten könnten, sollten Sie einen Inferenzmodus konfigurieren, der ein in der Cloud gehostetes Modell verwenden kann.

  • Wir empfehlen, Anwendungsfälle für die On-Device-Inferenz zu vermeiden, die eine lange Ausgabe (mehr als 256 Tokens) erfordern.

  • AICore (ein Android-Systemdienst, der die On-Device-Modelle verwaltet) erzwingt ein Inferenzkontingent pro App. Wenn Sie in kurzer Zeit zu viele API-Anfragen stellen, erhalten Sie eine ErrorCode.BUSY-Antwort. Wenn Sie diesen Fehler erhalten, sollten Sie den exponentiellen Backoff verwenden, um die Anfrage noch einmal zu senden. Außerdem kann ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED zurückgegeben werden, wenn eine Anwendung ein langfristiges Kontingent (z. B. ein Tageskontingent) überschreitet.


Feedback zu Ihren Erfahrungen mit Firebase AI Logic geben