Hybride Funktionen in Apple-Apps mit On-Device- und Cloud-gehosteten Modellen entwickeln

Mit Firebase AI Logic können Sie KI‑basierte Apple-Apps und ‑Funktionen mit hybrider Inferenz erstellen. Die hybride Inferenz ermöglicht die Ausführung von Inferenz mit On-Device-Modellen (insbesondere dem Foundation Models-Framework von Apple), sofern verfügbar, und die nahtlose Rückkehr zu in der Cloud gehosteten Google-Modellen, falls 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 erläutert.

Die On-Device-Inferenz über Firebase AI Logic wird für Apple-Apps unterstützt, die das Firebase AI Logic SDK ab Version 12.13.0 verwenden und auf Geräten mit aktivierter Apple Intelligence ausgeführt werden. Es unterliegt den Anforderungen für die zulässige Nutzung des Foundation Models-Frameworks von Apple.

Empfohlene Anwendungsfälle

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

    • Besserer Datenschutz
    • Kostenlose Inferenz
    • Offline-Funktionen

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

    • Allen Kunden eine ähnliche App-Erfahrung bieten, unabhängig vom Gerät des Endnutzers
    • Verfügbarkeit von auf generativer KI basierenden Funktionen verbessern, unabhängig von Internetverbindung, Kontingentbeschränkungen oder Gerätefunktionen

Unterstützte Funktionen, APIs und Geräte

Bevor Sie die hybride und On-Device-Inferenz mit Firebase AI Logic implementieren, sollten Sie sich diesen Abschnitt ansehen, um zu erfahren, was für Apple-Apps unterstützt wird.

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

Die Inferenz auf dem Gerät unterstützt nur die Textgenerierung, insbesondere die folgenden Funktionen zur Textgenerierung:

Eine detaillierte Liste der noch nicht unterstützten Hybrid- oder On-Device-Inferenz finden Sie unten auf dieser Seite.

Unterstützte APIs und Geräte

Jetzt starten

Prüfen Sie, ob Sie den Abschnitt oben mit den unterstützten Funktionen, APIs und Geräten gelesen haben.

In dieser Anleitung wird die allgemeine Einrichtung beschrieben, die für jede unterstützte Prompts-Anfrage erforderlich ist, die Sie senden möchten.

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

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

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

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

  4. Folgen Sie bei Bedarf 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, mit der Sie schnell und kostenlos loslegen können.

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

  6. Fahren Sie mit dem 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. Das 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 Anleitung weiter unten) müssen Sie den App Check-Debug-Anbieter 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

Verwenden Sie Swift Package Manager (SPM), um Xcode-Abhängigkeiten zu installieren und zu verwalten. Die Hybrid-Unterstützung ist nur bei Verwendung von SPM verfügbar.

Die Bibliothek Firebase AI Logic bietet Zugriff auf die APIs für die Interaktion mit generativen Modellen. Die Bibliothek ist Teil des Firebase SDK für Apple-Plattformen (firebase-ios-sdk).

Wenn Sie Firebase bereits verwenden, muss Ihr Firebase-Paket Version 12.13.0 oder höher haben.

  1. Öffnen Sie Ihr App-Projekt und gehen Sie in Xcode zu File > Add Package Dependencies (Datei > Paketabhängigkeiten hinzufügen).

  2. Fügen Sie bei entsprechender Aufforderung das Firebase Apple Platforms SDK-Repository hinzu:

    https://github.com/firebase/firebase-ios-sdk

  3. Wählen Sie die aktuelle SDK-Version aus.

  4. Wählen Sie die Bibliotheken FirebaseAILogic und FirebaseAppCheck aus.

Anschließend löst Xcode die Abhängigkeiten automatisch auf und lädt sie im Hintergrund herunter.

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

Ab Anfang Juli 2026 wird im Rahmen des geführten Einrichtungsprozesses 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 Durchsetzung von App Check beizubehalten.

So verwenden Sie den Debug-Anbieter, während Sie Ihre App interaktiv in einem Simulator ausführen (z. B. während der lokalen Entwicklung):

  1. Importieren Sie in Ihrem Xcode-Projekt FirebaseAppCheck und initialisieren Sie App Check mit der Debug-Anbieter-Factory bevor Sie Firebase konfigurieren.

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. Fehlerbehebungstoken abrufen:

    1. Starten Sie Ihre App im Simulator oder auf Ihrem Testgerät.

    2. Öffnen Sie die Xcode-Konsole und suchen Sie nach dem App Check-Debug-Token. Beispiel:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Kopieren Sie das Token (z. B. 123a4567-b89c-12d3-e456-789012345678).

  3. Registrieren Sie Ihr Fehlerbehebungstoken bei App Check:

    1. Rufen Sie in der Firebase-Konsole den Tab Apps unter Sicherheit > App Check > 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 Debugging-Anbieter (einschließlich Informationen zum Abrufen eines neuen Debugging-Tokens) finden Sie in der offiziellen App Check-Dokumentation.

Schritt 4: Dienst initialisieren und eine Modell-Sitzungsinstanz erstellen

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

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

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

  2. Erstellen Sie eine GenerativeModelSession-Instanz mit einem HybridModel.

  3. Legen Sie die Modelle primary und secondary nach Ihren Wünschen fest. Sie können die Reihenfolge der versuchten Inferenzen festlegen:

    • Zuerst Inferenz auf dem Gerät versuchen, aber Fallback auf die Cloud zulassen: Setzen Sie primary auf ein „System“-Modell und secondary auf ein Cloud-Modell.

    • Zuerst Inferenz in der Cloud versuchen, aber Fallback auf das Gerät zulassen: Setzen Sie primary auf ein Cloud-Modell und secondary auf ein „System“-Modell.

    Das SDK unterstützt nur die Festlegung eines einzelnen model. Das bedeutet, dass das SDK nur entweder die Inferenz auf dem Gerät oder in der Cloud versucht. Für eine hybride Lösung müssen Sie jedoch eine HybridModel erstellen und sowohl das primary- als auch das secondary-Modell festlegen.

    Weitere Informationen zum Verhalten von „Inferenzmodi“ (die Reihenfolge der versuchten Inferenz) finden Sie unter Konfigurationsoptionen.

Das folgende Beispiel zeigt, wie zuerst versucht wird, die Inferenz auf dem Gerät auszuführen, aber ein Fallback auf das in der Cloud gehostete Modell zugelassen wird:

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Initialize a cloud model that supports your use case.
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")
// Initialize an on-device model that supports your use case.
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a Hybrid Model.
// Provide your preferred model as `primary` and your fallback model as `secondary`.
// In this example, attempt to use on-device model; otherwise, fall back to cloud.
let hybridModel = HybridModel(
  primary: systemModel,
  secondary: cloudModel
)

// Create a GenerativeModelSession with the HybridModel created earlier.
let session = firebaseAI.generativeModelSession(
  model: hybridModel,
)

Schritt 5: Prompt-Anfrage an ein Modell senden

In diesem Abschnitt erfahren Sie, wie Sie Folgendes tun:

Text aus reinen Texteingaben generieren

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

Wenn Sie Text aus einem Prompt generieren möchten, der Text enthält, verwenden Sie respond(to:) so:

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To generate text output, call `respond(to:)` with the text input
let response = try await session.respond(to: prompt)
print(response.content)

Text aus reinen Texteingaben streamen

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

Sie können schnellere Interaktionen erzielen, indem Sie nicht auf das gesamte Ergebnis der Modellgenerierung warten, sondern stattdessen Streaming verwenden, um Teilergebnisse zu verarbeiten. Wenn Sie generierten Text aus einem Prompt mit Text streamen möchten, verwenden Sie streamResponse(to:) so:

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To stream generated text output, call `streamResponse(to:)` with the text input
let stream = session.streamResponse(to: prompt)
for try await snapshot in stream {
  print(snapshot.content)
}

Was kannst du sonst noch tun?

Für Ihre hybriden Anwendungen stehen verschiedene zusätzliche Konfigurationsoptionen und Funktionen zur Verfügung:

Funktionen, die für Hybrid- oder On-Device-Inferenz noch nicht unterstützt werden

Da es sich um eine experimentelle Version handelt, werden nicht alle Funktionen von Firebase AI Logic oder cloudbasierten Modellen unterstützt.

  • Die folgenden Elemente werden nicht für Hybrid- oder On-Device-Implementierungen unterstützt: die Gemini Live API- und Server-Promptvorlagen. Außerdem sollte man sich nicht auf die Anzahl der Tokens verlassen, da sie sich zwischen cloudbasierten und geräteinternen Modellen unterscheidet. Es gibt also keine intuitive Fallback-Lösung.

  • Die folgenden Funktionen werden für die Inferenz auf dem Gerät noch nicht unterstützt: Wenn Sie eine dieser Funktionen verwenden möchten, empfehlen wir Ihnen, nur ein in der Cloud gehostetes Modell zu verwenden, um eine konsistentere Nutzung zu ermöglichen.

    • Text aus multimodalen Eingaben wie Bildern, Audio, Videos und Dokumenten (PDFs) generieren

    • Beim Generieren von Medien wie Bildern, Audio oder Videos

    • Anfragen mit mehr als 4.096 Tokens (oder etwa 3.000 Wörtern auf Englisch) werden gesendet.

    • Das On-Device-Modell wird mit integrierten Tools ausgestattet, die ihm helfen, seine Antwort zu generieren (z. B. Code-Ausführung, URL-Kontext und Fundierung mit der Google Suche).

  • Das KI-Monitoring in der Firebase Console zeigt keine Daten für die Inferenz auf dem Gerät an, einschließlich der Logs auf dem Gerät. Alle Inferenzen, für die ein in der Cloud gehostetes Modell verwendet wird, können jedoch wie andere Inferenzen über Firebase AI Logic überwacht werden.

Zusätzliche Einschränkungen

Zusätzlich zu den oben genannten Einschränkungen gelten für die On-Device-Inferenz die folgenden Einschränkungen:


Feedback zu Firebase AI Logic geben