Hybride Lösungen mit On-Device- und Cloud-gehosteten Modellen erstellen

Mit Firebase AI Logic KI-basierte Web-Apps und Funktionen mit hybrider Inferenz erstellen. Mit der hybriden Inferenz können Sie die Inferenz mit On-Device-Modellen ausführen, wenn sie verfügbar sind. Andernfalls wird nahtlos auf cloudbasierte Modelle zurückgegriffen (und umgekehrt).

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

Die Inferenz auf dem Gerät wird für Web-Apps unterstützt, die in Chrome auf dem Computer ausgeführt werden.

Zu den Codebeispielen springen

Empfohlene Anwendungsfälle und unterstützte Funktionen

Empfohlene Anwendungsfälle:

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

  • Besserer Datenschutz
  • Lokaler Kontext
  • Kostenlose Inferenz
  • Offlinefunktionen

• So nutzen Sie Hybridfunktionen:

  • 100% Ihrer Zielgruppe erreichen, unabhängig von der Verfügbarkeit des On-Device-Modells oder der Internetverbindung

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

• Inhaltsgenerierung in einem Durchgang, Streaming und Nicht-Streaming
• Text aus reinen Texteingaben generieren
• Text aus Text- und Bildeingaben generieren, insbesondere Eingabebildtypen JPEG und PNG
• Strukturierte Ausgaben generieren, einschließlich JSON und Enums

Hinweis

Beachten Sie Folgendes:

• Für die Inferenz mit einem On-Device-Modell wird die Prompt API von Chrome verwendet. Für die Inferenz mit einem in der Cloud gehosteten Modell wird der von Ihnen ausgewählte Gemini API-Anbieter (entweder Gemini Developer API oder Vertex AI Gemini API) verwendet.

• Auf dieser Seite wird beschrieben, wie Sie mit der Entwicklung mit localhost beginnen. Weitere Informationen zur Verwendung von APIs auf localhost finden Sie in der Chrome-Dokumentation. Zusätzliche Konfigurationsoptionen und Funktionen (z. B. strukturierte Ausgabe) finden Sie weiter unten auf dieser Seite.

• Nachdem Sie die Funktion implementiert haben, können Sie Endnutzern die Möglichkeit geben, sie in Ihrer tatsächlichen App auszuprobieren.

Erste Schritte mit Localhost

In dieser Anleitung werden die erforderlichen allgemeinen Einrichtungsschritte für alle unterstützten Prompts beschrieben, die Sie senden möchten.

Schritt 1: Chrome und die Prompt API für die On-Device-Inferenz einrichten

1. Vergewissern Sie sich, dass Sie eine aktuelle Version von Chrome verwenden. Aktualisieren Sie in chrome://settings/help.
   Die Inferenz auf dem Gerät ist ab Chrome 139 verfügbar.

2. Aktivieren Sie das multimodale On-Device-Modell, indem Sie das folgende Flag auf Aktiviert setzen:

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. Starten Sie Chrome neu.

4. (Optional) Laden Sie das On-Device-Modell vor der ersten Anfrage herunter.

   Die Prompt API ist in Chrome integriert. Das On-Device-Modell ist jedoch nicht standardmäßig verfügbar. Wenn Sie das Modell noch nicht vor Ihrer ersten Anfrage für die Inferenz auf dem Gerät heruntergeladen haben, wird der Download des Modells automatisch im Hintergrund gestartet.

   Anleitung zum Herunterladen des On-Device-Modells ansehen

   1. Öffnen Sie die Entwicklertools > Konsole.

   2. Führen Sie den folgenden Befehl aus:

      await LanguageModel.availability();
      

   3. Achten Sie darauf, dass die Ausgabe available, downloading oder downloadable ist.

   4. Wenn die Ausgabe downloadable ist, starten Sie den Modell-Download mit folgendem Befehl:

      await LanguageModel.create();
      

   5. Mit dem folgenden monitor-Callback können Sie den Downloadfortschritt verfolgen und dafür sorgen, dass das Modell available ist, bevor Sie Anfragen stellen:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

Schritt 2: 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.

   Sie haben noch kein Firebase-Projekt?

   Wenn Sie noch kein Firebase-Projekt haben, klicken Sie auf die Schaltfläche, um ein neues Firebase-Projekt zu erstellen, und verwenden Sie dann eine der folgenden Optionen:

   • Option 1: Erstellen Sie ein völlig neues Firebase-Projekt (und das zugrunde liegende Google Cloud-Projekt automatisch), indem Sie im ersten Schritt des Workflows einen neuen Projektnamen eingeben.

   • Option 2: Firebase einem vorhandenen Google Cloud-Projekt hinzufügen, indem Sie unten auf der Seite auf Firebase dem Google Cloud-Projekt hinzufügen klicken. Geben Sie im ersten Schritt des Workflows den Projektnamen des vorhandenen Projekts ein und wählen Sie das Projekt aus der angezeigten Liste aus.

   Führen Sie die restlichen Schritte des Arbeitsablaufs auf dem Bildschirm aus, um ein Firebase-Projekt zu erstellen. Wenn Sie dazu aufgefordert werden, müssen Sie nicht Google Analytics einrichten, um die Firebase AI Logic-SDKs zu verwenden.

2. Rufen Sie in der Firebase Console die Seite Firebase 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. Richten Sie Ihr Projekt für die Verwendung eines „Gemini API“-Anbieters ein.

   Wir empfehlen, mit der Gemini Developer API zu beginnen. Sie können jederzeit Vertex AI Gemini API einrichten (und die zugehörigen Abrechnungsanforderungen erfüllen).

   Für die Gemini Developer API werden in der Konsole die erforderlichen APIs aktiviert und ein Gemini-API-Schlüssel in Ihrem Projekt erstellt.
   Fügen Sie diesen Gemini-API-Schlüssel nicht in den Code Ihrer App ein. Weitere Informationen

5. Folgen Sie der Anleitung auf dem Bildschirm, um Ihre App zu registrieren und mit Firebase zu verbinden.

6. Fahren Sie mit dem nächsten Schritt in dieser Anleitung fort, um das SDK Ihrer App hinzuzufügen.

Schritt 3: SDK hinzufügen

Die Firebase-Bibliothek bietet Zugriff auf die APIs für die Interaktion mit generativen Modellen. Die Bibliothek ist im Firebase JavaScript SDK für Web enthalten.

1. Installieren Sie das Firebase JS SDK für Web mit npm:

   npm install firebase
   

2. Initialisieren Sie Firebase in Ihrer App:

   import { initializeApp } from "firebase/app";
   
   // TODO(developer) Replace the following with your app's Firebase configuration
   // See: https://firebase.google.com/docs/web/learn-more#config-object
   const firebaseConfig = {
     // ...
   };
   
   // Initialize FirebaseApp
   const firebaseApp = initializeApp(firebaseConfig);
   

Schritt 4: Dienst initialisieren und Modellinstanz erstellen

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 API-Anbieter.

2. Erstellen Sie eine GenerativeModel-Instanz. Beachte Folgendes:

   1. Rufen Sie getGenerativeModel nach oder bei einer Endnutzerinteraktion (z. B. einem Klick auf eine Schaltfläche) auf. Dies ist eine Voraussetzung für inferenceMode.

   2. Legen Sie für mode einen der folgenden Werte fest:

      • PREFER_ON_DEVICE: Das On-Device-Modell wird verwendet, sofern verfügbar. Andernfalls wird auf das in der Cloud gehostete Modell zurückgegriffen.

      • ONLY_ON_DEVICE: Das On-Device-Modell wird verwendet, sofern verfügbar. Andernfalls wird eine Ausnahme ausgelöst.

      • PREFER_IN_CLOUD: Verwenden Sie das in der Cloud gehostete Modell, falls verfügbar. Andernfalls greifen Sie auf das On-Device-Modell zurück.

      • ONLY_IN_CLOUD: Verwenden Sie das in der Cloud gehostete Modell, falls verfügbar. Andernfalls wird eine Ausnahme ausgelöst.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Schritt 5: Prompt-Anfrage an ein Modell senden

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

• Text aus reinen Texteingaben generieren
• Text aus multimodalen Eingaben (Text und Bild) generieren

Wenn Sie eine strukturierte Ausgabe (z. B. JSON oder Enums) generieren möchten, verwenden Sie eines der folgenden Beispiele für „Text generieren“ und konfigurieren Sie das Modell zusätzlich so, dass es gemäß einem bereitgestellten Schema antwortet.

Text aus reinen Texteingaben generieren

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

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

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

Text aus multimodalen Eingaben (Text und Bild) generieren

Mit generateContent() können Sie Text aus einem Prompt generieren, der Text- und Bilddateien enthält. Geben Sie dazu für jede Eingabedatei den mimeType und die Datei selbst an.

Die unterstützten Eingabebildtypen für die Inferenz auf dem Gerät sind PNG und JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

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

Endnutzern die Möglichkeit geben, Ihre Funktion auszuprobieren

Damit Endnutzer Ihre Funktion in Ihrer App testen können, müssen Sie sich für Chrome-Origin-Trials registrieren. Beachten Sie, dass diese Testzeiträume zeitlich und hinsichtlich der Nutzung begrenzt sind.

1. Registrieren Sie sich für den Prompt API Chrome-Ursprungstest. Sie erhalten ein Token.

2. Geben Sie das Token auf jeder Webseite an, für die die Testfunktion aktiviert werden soll. Verwenden Sie eine der folgenden Optionen:

   • Geben Sie das Token als Meta-Tag im <head>-Tag an: <meta http-equiv="origin-trial" content="TOKEN">

   • Geben Sie das Token als HTTP-Header an: Origin-Trial: TOKEN

   • Stellen Sie das Token programmatisch zur Verfügung.

Was kannst du sonst noch tun?

In diesem Abschnitt erfahren Sie, wie Sie einen Inferenzmodus festlegen, das standardmäßige cloudbasierte Fallback-Modell überschreiben und die Modellkonfiguration verwenden, um Antworten zu steuern (z. B. strukturierte Ausgaben zu generieren).

Inferenzmodus festlegen

In den Beispielen im allgemeinen Setup wird der Modus PREFER_ON_DEVICE verwendet. Dies ist jedoch nur einer der vier verfügbaren Inferenzmodi.

• PREFER_ON_DEVICE: Das On-Device-Modell wird verwendet, sofern verfügbar. Andernfalls wird auf das in der Cloud gehostete Modell zurückgegriffen.

  const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });
  

• ONLY_ON_DEVICE: Das On-Device-Modell wird verwendet, sofern verfügbar. Andernfalls wird eine Ausnahme ausgelöst.

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });
  

• PREFER_IN_CLOUD: Verwenden Sie das in der Cloud gehostete Modell, falls verfügbar. Andernfalls greifen Sie auf das On-Device-Modell zurück.

  const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });
  

• ONLY_IN_CLOUD: Verwenden Sie das in der Cloud gehostete Modell, falls verfügbar. Andernfalls wird eine Ausnahme ausgelöst.

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });
  

Ermitteln, ob die Inferenz auf dem Gerät oder in der Cloud verwendet wurde

Wenn Sie die Inferenzmodi PREFER_ON_DEVICE oder PREFER_IN_CLOUD verwenden, kann es hilfreich sein, zu wissen, welcher Modus für bestimmte Anfragen verwendet wurde. Diese Informationen werden durch das Attribut inferenceSource jeder Antwort bereitgestellt (verfügbar ab JS SDK v12.5.0).

Wenn Sie auf diese Eigenschaft zugreifen, ist der zurückgegebene Wert entweder ON_DEVICE oder IN_CLOUD.

// ...

console.log('You used: ' + result.response.inferenceSource);

console.log(result.response.text());

Standard-Fallbackmodell überschreiben

Das standardmäßige cloudbasierte Modell ist gemini-2.5-flash-lite (ab JS SDK v12.8.0).

Dieses Modell ist das Fallback-Modell, das in der Cloud gehostet wird, wenn Sie den Modus PREFER_ON_DEVICE verwenden. Es ist auch das Standardmodell, wenn Sie den Modus ONLY_IN_CLOUD oder PREFER_IN_CLOUD verwenden.

Mit der Konfigurationsoption inCloudParams können Sie ein alternatives standardmäßiges cloudbasiertes Modell angeben.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
  }
});

Hier finden Sie die Modellnamen für alle unterstützten Gemini-Modelle.

Antworten mit der Modellkonfiguration steuern

In jeder Anfrage an ein Modell können Sie eine Modellkonfiguration senden, um zu steuern, wie das Modell eine Antwort generiert. Cloudbasierte und geräteinterne Modelle bieten unterschiedliche Konfigurationsoptionen.

Die Konfiguration wird für die gesamte Lebensdauer der Instanz beibehalten. Wenn Sie eine andere Konfiguration verwenden möchten, erstellen Sie eine neue GenerativeModel-Instanz mit dieser Konfiguration.

Konfiguration für ein in der Cloud gehostetes Modell festlegen

Verwenden Sie die Option inCloudParams, um ein in der Cloud gehostetes Gemini-Modell zu konfigurieren. Verfügbare Parameter

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
    temperature: 0.8,
    topK: 10
  }
});

Konfiguration für ein On-Device-Modell festlegen

Für die Inferenz mit einem On-Device-Modell wird die Prompt API von Chrome verwendet.

Verwenden Sie die Option onDeviceParams, um ein On-Device-Modell zu konfigurieren. Verfügbare Parameter

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

Konfiguration für strukturierte Ausgaben (z. B. JSON) festlegen

Das Generieren strukturierter Ausgaben (wie JSON und Enums) wird für die Inferenz sowohl mit cloudbasierten als auch mit On-Device-Modellen unterstützt.

Verwenden Sie für die hybride Inferenz sowohl inCloudParams als auch onDeviceParams, um das Modell so zu konfigurieren, dass es mit strukturierter Ausgabe antwortet. Verwenden Sie für die anderen Modi nur die entsprechende Konfiguration.

• Für inCloudParams: Geben Sie die entsprechende responseMimeType (in diesem Beispiel application/json) sowie die responseSchema an, die das Modell verwenden soll.

• Für onDeviceParams: Geben Sie die responseConstraint an, die das Modell verwenden soll.

JSON-Ausgabe

Im folgenden Beispiel wird das allgemeine Beispiel für die JSON-Ausgabe für die hybride Inferenz angepasst:

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

Enum-Ausgabe

Wie oben, aber die Dokumentation zur Enum-Ausgabe für Hybrid-Inferenz anpassen:

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...
});

// ...

Funktionen, die noch nicht für die Inferenz auf dem Gerät verfügbar sind

Da es sich um eine experimentelle Version handelt, sind nicht alle Funktionen des Web-SDK für die Geräteinferenz verfügbar. Die folgenden Funktionen werden noch nicht für die Inferenz auf dem Gerät unterstützt (sind aber in der Regel für die cloudbasierte Inferenz verfügbar).

• Text aus anderen Bilddateitypen als JPEG und PNG generieren

  • Kann auf das in der Cloud gehostete Modell zurückgreifen. Im ONLY_ON_DEVICE-Modus wird jedoch ein Fehler ausgegeben.

• 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 ein Fehler ausgegeben.

• Bilder mit Gemini- oder Imagen-Modellen generieren

  • Kann auf das in der Cloud gehostete Modell zurückgreifen. Im ONLY_ON_DEVICE-Modus wird jedoch ein Fehler ausgegeben.

• Dateien über URLs in multimodalen Anfragen bereitstellen Sie müssen Dateien als Inline-Daten für On-Device-Modelle bereitstellen.

• Wechselseitiger Chat

  • Kann auf das in der Cloud gehostete Modell zurückgreifen. Im ONLY_ON_DEVICE-Modus wird jedoch ein Fehler ausgegeben.

• Bidirektionales Streaming mit dem Gemini Live API

• Das Modell mit Tools ausstatten, die ihm helfen, seine Antwort zu generieren (z. B. Funktionsaufrufe, Codeausführung, URL-Kontext und Fundierung mit der Google Suche)

• Tokens zählen

  • Gibt immer einen Fehler aus. Die Anzahl unterscheidet sich zwischen cloudbasierten und On-Device-Modellen, sodass es keinen intuitiven Fallback gibt.

• KI-Monitoring in der Firebase Console für die Inferenz auf dem Gerät.

  • Hinweis: Alle Inferenzen, die mit den in der Cloud gehosteten Modellen durchgeführt werden, können wie andere Inferenzen mit dem Firebase AI Logic-Client-SDK für Web überwacht werden.

Feedback zu Firebase AI Logic geben