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

Firebase AI Logic


Mit Firebase AI Logic können Sie KI-gestützte Android-Apps und ‑Funktionen mit Hybrid-Inferenz erstellen. Firebase AI Logic Die Hybrid-Inferenz ermöglicht die Ausführung von Inferenz mit Modellen auf dem Gerät, wenn verfügbar, und die nahtlose Umstellung auf in der Cloud gehostete Modelle, wenn nicht (und umgekehrt).

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

Die Inferenz auf dem Gerät über Firebase AI Logic wird für Android-Apps mit Firebase AI Logic SDK ab Version 17.10.0 (BoM ab Version 34.10.0) und auf bestimmten Geräten unterstützt. Sie unterliegt den ML Kit-Nutzungsbedingungen, sowie den Nutzungsbedingungen, die speziell für die generativen KI-Aspekte von ML Kit gelten.

Empfohlene Anwendungsfälle und unterstützte Funktionen

Empfohlene Anwendungsfälle

  • Die Verwendung eines Modells auf dem Gerät für die Inferenz bietet folgende Vorteile:

    • Besserer Schutz für die Daten einzelner Nutzer
    • Lokaler Kontext
    • Kostenlose Inferenz
    • Offline-Funktionen

  • Die Verwendung der Hybrid -Funktionalität bietet folgende Vorteile:

    • Sie erreichen mehr Nutzer, da die Verfügbarkeit von Modellen auf dem Gerät und die Internetverbindung berücksichtigt werden.

Unterstützte Funktionen für die Inferenz auf dem Gerät

Die Inferenz auf dem Gerät unterstützt nur die Textgenerierung in einem Durchgang (kein Chat) mit Streaming- oder Nicht-Streaming-Ausgabe. Die folgenden Funktionen zur Textgenerierung werden unterstützt:

Sehen Sie sich die Liste der noch nicht verfügbaren Funktionen für die Inferenz auf dem Gerät unten auf dieser Seite an.

Hinweis

Beachten Sie Folgendes:

Unterstützte Android-Geräte und ihre Modelle auf dem Gerät

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

Jetzt starten

In diesen Schritten wird die erforderliche allgemeine Einrichtung für jede unterstützte Prompt-Anfrage 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 Console AI Services > AI Logic auf.

  3. Klicken Sie auf Jetzt starten , um einen geführten Workflow zu starten, der Sie bei der Einrichtung der erforderlichen APIs und Ressourcen für Ihr Projekt unterstützt.

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

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

    Sie können die jederzeit später einrichten Agent Platform Gemini API (formerly Vertex AI) (und die dafür erforderliche Abrechnung).

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

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

    App CheckApp Check

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

Schritt 2: Erforderliche SDKs hinzufügen

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

firebase-ai-ondevicefirebase-ai

Fügen Sie in der Gradle-Datei des Moduls (auf Anwendungsebene) (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:17.14.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.3.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:17.14.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.3.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 konfigurieren, um die Attestierung zu umgehen und gleichzeitig die Erzwingung von App Check beizubehalten.

  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 den Logs nach dem App Check Debug-Token. 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 Console den Sicherheit > App Check > Apps Tab auf.

    2. Suchen Sie Ihre App, klicken Sie auf das Dreipunkt-Menü () und wählen Sie dann 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 der Anleitung zum Abrufen eines neuen Debug-Tokens) finden Sie in der offiziellen Dokumentation.App Check

Schritt 4: Verfügbarkeit des Modells auf dem Gerät prüfen

Prüfen Sie mit FirebaseAIOnDevice, ob das Modell auf dem Gerät verfügbar ist, und laden Sie es herunter, falls nicht verfügbar.

Nach dem Download wird AICore das Modell automatisch auf dem neuesten Stand halten. Weitere Informationen zu AICore und zum Verwalten des Downloads von Modellen auf dem Gerät 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 and downloading 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 Modells auf dem Gerät Folgendes:

  • Die Zeit, die für das Herunterladen des Modells auf dem Gerät benötigt wird, hängt von vielen Faktoren ab, einschließlich Ihres Netzwerks.

  • Wenn Ihr Code ein Modell auf dem Gerät für die primäre oder Fallback-Inferenz verwendet, muss das Modell frühzeitig im Lebenszyklus Ihrer App heruntergeladen werden, damit es verfügbar ist, bevor Ihre Endnutzer auf den Code in Ihrer App stoßen.

  • Wenn das Modell auf dem Gerät nicht verfügbar ist, wenn eine Anfrage für die Inferenz auf dem Gerät gestellt wird, wird das SDK den Download des Modells auf dem Gerät nicht automatisch auslösen. Das SDK greift entweder auf das in der Cloud gehostete Modell zurück oder löst eine Ausnahme aus (siehe Details zum Verhalten von Inferenzmodi).

  • AICore (ein Android-Systemdienst) verwaltet für Sie, welches Modell und welche Version heruntergeladen werden, 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 Modell auf dem Gerät bereits erfolgreich heruntergeladen hat, wird bei dieser Prüfung zurückgegeben, dass das Modell verfügbar ist.

Latenzoptimierung

Um den ersten Inferenzaufruf zu optimieren, kann Ihre App aufrufen warmup(). Dadurch wird das Modell auf dem Gerät in den Arbeitsspeicher geladen und 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 von Ihnen ausgewählten API-Anbieter.

  2. Erstellen Sie eine GenerativeModel-Instanz und legen Sie den mode auf 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: Versuchen Sie, das Modell auf dem Gerät zu verwenden. Andernfalls greifen Sie auf das in der Cloud gehostete Modell zurück.

    • ONLY_ON_DEVICE: Versuchen Sie, das Modell auf dem Gerät zu verwenden. Andernfalls lösen Sie eine Ausnahme aus.

    • PREFER_IN_CLOUD: Versuchen Sie, das in der Cloud gehostete Modell zu verwenden. Andernfalls greifen Sie auf das Modell auf dem Gerät zurück.

    • 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 = "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);

Schritt 6: Prompt-Anfrage an ein Modell senden

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

Text aus reinen Texteingaben generieren

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

Mit generateContent() können Sie Text aus einem Prompt 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 unterstützt (anstelle von generateContent).

Text aus Text- und Bildeingaben (multimodal) generieren

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

Mit generateContent() können Sie Text aus einem Prompt generieren, der Text und bis zu einer Bilddatei (nur Bitmap) enthält. Geben Sie dazu den mimeType und die Datei selbst für jede Eingabedatei 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 unterstützt (anstelle von generateContent).

Was können Sie sonst noch tun?

Sie können verschiedene zusätzliche Konfigurationsoptionen und Funktionen für Ihre Hybrid-Anwendungen verwenden:

Noch nicht für die Inferenz auf dem Gerät 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 in diesem Abschnitt aufgeführten Funktionen sind noch nicht für die Inferenz auf dem Gerät verfügbar. Wenn Sie eine dieser Funktionen verwenden möchten, empfehlen wir den Inferenzmodus ONLY_IN_CLOUD, um eine konsistentere Nutzererfahrung zu erzielen.

  • Strukturierte Ausgabe generieren (z. B. JSON oder Enums)

  • Text aus anderen Bilddateieingabetypen als Bitmap generieren (Bild in den Arbeitsspeicher geladen)

  • Text aus mehr als einer Bilddatei generieren

  • Text aus Audio-, Video- und Dokumenteingaben (z. B. PDFs) generieren

  • Bilder mit Gemini oder Imagen Modellen generieren

  • Dateien über URLs in multimodalen Anfragen bereitstellen Sie müssen Dateien als Inline-Daten für Modelle auf dem Gerät bereitstellen

  • Anfragen senden, die 4.000 Tokens (oder etwa 3.000 englische Wörter) überschreiten

  • Multi-Turn-Unterhaltung

  • Dem Modell Tools zur Verfügung stellen, mit denen es seine Antwort generieren kann (z. B. Funktionsaufrufe, Code-Ausführung, URL-Kontext, Grounding mit Google Search, und Grounding mit Google Maps)

Beim KI-Monitoring in der Firebase Console werden keine Daten für die Inferenz auf dem Gerät angezeigt (einschließlich Logs auf dem Gerät). Jede Inferenz, bei der ein in der Cloud gehostetes Modell verwendet wird, kann jedoch wie andere Inferenz über Firebase AI Logic überwacht werden.

Zusätzliche Einschränkungen

Zusätzlich zu den oben genannten Einschränkungen unterliegt die Inferenz auf dem Gerät den 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 Inferenz auf dem Gerät verwenden.

  • Ihre App kann die Inferenz auf dem Gerät nur ausführen, wenn sie im Vordergrund ist.

  • Nur Englisch und Koreanisch wurden für die Inferenz auf dem Gerät validiert.

  • Das maximale Tokenlimit für die gesamte Anfrage für die Inferenz auf dem Gerät beträgt 4.000 Tokens. Wenn Ihre Anfragen dieses Limit überschreiten könnten, müssen Sie einen Inferenzmodus konfigurieren, der ein in der Cloud gehostetes Modell verwenden kann.

  • Wir empfehlen, Anwendungsfälle für die Inferenz auf dem Gerät zu vermeiden, die eine lange Ausgabe erfordern (mehr als 256 Tokens).

  • AICore (ein Android-Systemdienst, der die Modelle auf dem Gerät verwaltet) erzwingt ein Inferenzkontingent pro App. Zu viele API-Anfragen in kurzer Zeit führen zu einer 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 App ein Kontingent für lange Zeiträume (z. B. ein Tageskontingent) überschreitet.


Feedback geben zu Firebase AI Logic