Benutzerdefinierte serverseitige Skripts vor und nach Anfragen ausführen


Sie können vor und nach jeder Anfrage, die Ihre Anwendung über Firebase AI Logic an Gemini API sendet, eigene benutzerdefinierte serverseitige Skripts ausführen – ohne Ihren Clientcode zu ändern. Sie implementieren diese Skripts als Callback-Funktionen, die in Cloud Functions for Firebase bereitgestellt werden.

Mit dieser Funktion können Sie beispielsweise Prompts moderieren, die Tokennutzung begrenzen, Generierungen für Analysen protokollieren oder Antwortinhalte entfernen.

Es sind zwei Ereignistypen verfügbar:

  • beforeGenerateContent: Wird ausgeführt, bevor eine Anfrage den Gemini API erreicht. Die Funktion kann die Anfrage prüfen oder ändern oder die Anfrage vollständig blockieren, indem sie einen Fehler ausgibt.

  • afterGenerateContent: Wird ausgeführt, nachdem die Antwort vom Gemini API zurückgesendet wurde und bevor sie an die Client-App zurückgegeben wird. Die Funktion kann die Antwort prüfen oder ändern, die Antwort vollständig blockieren oder sie nur beobachten (z. B. für Logging oder Auditing).

Sobald Ihre Skripts als Funktionen in Cloud Functions for Firebase bereitgestellt wurden, werden sie als Firebase AI Logic-Trigger registriert. Das bedeutet, dass sie für jede generateContent-Anfrage in Ihrem Projekt an die Gemini API über Firebase AI Logic ausgeführt werden (einschließlich Anfragen, die mit Server-Prompt-Vorlagen gestellt wurden).

Diese Funktionen werden nicht durch Anfragen an Gemini API ausgelöst, die nicht über Firebase AI Logic erfolgen.

Vorbereitung

Schritt 1: Projekt für Cloud Functions for Firebase einrichten

Wenn Sie Cloud Functions for Firebase noch nie in Ihrem Firebase-Projekt verwendet haben, führen Sie die folgende Einrichtung durch.

  1. Achten Sie darauf, dass für Ihr Firebase-Projekt das Blaze-Preismodell (Pay as you go) gilt (erforderlich für die Verwendung von Cloud Functions for Firebase).

  2. Installieren Sie die Befehlszeilen (CLIs): gcloud CLI und Firebase-CLI

  3. Weisen Sie dem Compute-Standarddienstkonto die Rolle Cloud Build-Dienstkonto (roles/cloudbuild.builds.builder) zu, die zum Erstellen der Funktion erforderlich ist. Führen Sie den folgenden gcloud CLI-Befehl aus:

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/cloudbuild.builds.builder"

  4. Initialisieren Sie Cloud Functions for Firebase in Ihrem Firebase-Projekt:

    1. Führen Sie den folgenden Firebase-Befehlszeilenbefehl aus:

      firebase init functions

    2. Wählen Sie bei Aufforderung TypeScript aus.

    3. Prüfen Sie, ob firebase-functions in Ihrer functions/package.json Version 6.3.0 oder höher ist. So findest du heraus, welche Version du hast:

      npm --prefix functions list firebase-functions

Schritt 2: Funktionen schreiben

Funktion für Voranfragen schreiben (beforeGenerateContent) Funktion für Nachanfragen schreiben (afterGenerateContent)

Funktion vor der Anfrage schreiben (beforeGenerateContent)

Beim Ereignistyp beforeGenerateContent wird die Funktion ausgelöst, wenn der Proxy Firebase AI Logic eine generateContent-Anfrage empfängt. Die Funktion wird für die Anfrage ausgeführt, bevor die Anfrage an den Gemini API gesendet wird. Die Funktion kann die Anfrage ändern oder vollständig blockieren.

Lesen Sie die folgenden Informationen, bevor Sie Ihre Funktion schreiben:

Beispiel

Hier ist ein Beispiel für eine Pre-Request-Funktion, die Folgendes tut:

  • Gibt an, dass die Funktion nur ausgeführt werden soll, wenn die Anfrage für einen bestimmten Gemini API-Anbieter gilt.

  • Prüft den Prompt auf blockierte Themen und lehnt die Anfrage ab, indem ein Fehler ausgegeben wird.

  • Begrenzt die maximale Anzahl von Ausgabetokens für textgenerierende Modelle.

import { logger } from "firebase-functions";
import {
  beforeGenerateContent,
  HttpsError,
  vertexV1Beta1,
  type VertexV1Beta1GenerateContentRequest,
} from "firebase-functions/v2/ai";

const BLOCKED_TOPICS = ["weapon", "explosive", "self-harm"];
const MAX_OUTPUT_TOKENS = 4000;

export const guardPrompts = beforeGenerateContent((event) => {
  // 1. Optional: If you want the function to only run for a specific Gemini API provider, specify it here.
  if (event.data.api !== vertexV1Beta1) return;
  const request = event.data.request as VertexV1Beta1GenerateContentRequest;

  // 2. Read the prompt: contents[] -> parts[] -> text
  const prompt = (request.contents ?? [])
    .flatMap((c) => c.parts ?? [])
    .map((p) => ("text" in p ? p.text : "") ?? "")
    .join(" ")
    .toLowerCase();

  // 3. Throwing rejects the request. The request is never sent to the Gemini API.
  const blocked = BLOCKED_TOPICS.find((t) => prompt.includes(t));
  if (blocked) {
    logger.warn("Blocked a prompt", { topic: blocked });
    throw new HttpsError("invalid-argument", `We don't return content about ${blocked}.`);
  }

  logger.info("Allowing generation", {
    model: event.data.model,
    authType: event.authType,
    authId: event.authId,
    appId: event.appId,
  });

  // 4. The next step truncates the response, but that will break images.
  if (event.data.model.includes("image")) return;

  // 5. Return the WHOLE request, edited. Returning nothing leaves it untouched.
  return {
    ...request,
    generationConfig: {
      ...request.generationConfig,
      maxOutputTokens: Math.min(
        request.generationConfig?.maxOutputTokens ?? MAX_OUTPUT_TOKENS,
        MAX_OUTPUT_TOKENS,
      ),
    },
  };
});

Wichtige Überlegungen zu Pre-Request-Funktionen

  • Geben Sie den Gemini API-Anbieter an: event.data.request kann entweder für Gemini Developer API oder Agent Platform Gemini API (formerly Vertex AI) sein. Die Anfrageobjekte für diese verschiedenen APIs haben unterschiedliche Formen. Um sicher mit dem Anfrageobjekt zu arbeiten, müssen Sie event.data.api prüfen (z. B. mit geminiV1Beta bzw. vertexV1Beta1 vergleichen).

  • Das Auslösen blockiert die Anfrage: Wenn Sie einen HttpsError auslösen, wird die Anfrage abgelehnt.

  • Vollständige Anfrage zurückgeben: Wenn Ihre Funktion die Anfrage ändert, müssen Sie das vollständige, geänderte Anfrageobjekt zurückgeben. Wenn nichts (oder undefined) zurückgegeben wird, bleibt die Anfrage unverändert.

  • Auf Latenz testen: Je nachdem, was Ihre Funktion tut, kann sie die Latenz erhöhen und die Nutzererfahrung beeinträchtigen.

Funktion für die Zeit nach der Anfrage schreiben (afterGenerateContent)

Beim Ereignistyp afterGenerateContent wird die Funktion ausgelöst, wenn der Firebase AI Logic-Proxy eine Antwort auf eine generateContent-Anfrage empfängt. Die Funktion wird für die Antwort ausgeführt, bevor die Antwort an die Client-App zurückgegeben wird. Die Funktion kann die Nutzung protokollieren, die Antwort ändern oder die Antwort vollständig blockieren.

Lesen Sie die folgenden Informationen, bevor Sie Ihre Funktion schreiben:

Beispiel

Hier ist eine Beispielfunktion für eine POST-Anfrage, die die Tokennutzung und den Grund für das Beenden protokolliert:

import { logger } from "firebase-functions";
import {
  afterGenerateContent,
  vertexV1Beta1,
  type VertexV1Beta1GenerateContentResponse,
} from "firebase-functions/v2/ai";

export const recordGenerationUsage = afterGenerateContent((event) => {
  // Optional: If you want the function to only run for a specific Gemini API provider, specify it here.
  if (event.data.api !== vertexV1Beta1) return;
  const response = event.data.response as VertexV1Beta1GenerateContentResponse;

  logger.info("Generation finished", {
    model: event.data.model,
    promptTokens: response.usageMetadata?.promptTokenCount,
    totalTokens: response.usageMetadata?.totalTokenCount,
    finishReason: response.candidates?.[0]?.finishReason,
  });

  // To leave the response untouched, return nothing.
  // To modify the response, return a modified response object here.
});

Wichtige Überlegungen zu Funktionen nach der Anfrage

  • Geben Sie den Gemini API-Anbieter an: event.data.response kann entweder für Gemini Developer API oder Agent Platform Gemini API (formerly Vertex AI) sein. Um das Anfrageobjekt sicher umzuwandeln und damit zu arbeiten, müssen Sie event.data.api prüfen (z. B. mit geminiV1Beta bzw. vertexV1Beta1 vergleichen).

  • Auf Latenz testen: Je nachdem, was Ihre Funktion tut, kann sie die Latenz erhöhen und die Nutzererfahrung beeinträchtigen.

Schritt 3: Funktionen bereitstellen

Wenn Sie Ihre Funktionen in Firebase bereitstellen, erhält der Dienst-Agent Firebase AI Logic die Berechtigung, diese Funktionen aufzurufen. Außerdem wird jede Funktion als Firebase AI Logic-Trigger registriert.

  1. Stellen Sie Ihre Funktionen mit der Firebase-Befehlszeile bereit:

    firebase deploy --only functions

  2. Prüfen Sie nach der Bereitstellung, ob Ihre Funktionen in Firebase bereitgestellt wurden:

    firebase functions:list

  3. Wenn Sie Ihre Funktion iterieren müssen:

    Aktualisieren Sie die Funktion in Ihrem Projektverzeichnis und führen Sie firebase deploy --only functions noch einmal aus.

Ausführung einer Funktion beenden

Wenn Sie eine dieser Funktionen beenden möchten, müssen Sie sie von unseren Servern löschen und als Firebase AI Logic-Trigger abmelden. Dazu können Sie die Firebase-Befehlszeile mit einer der folgenden Optionen verwenden:

  • Option 1: Funktion implizit löschen

    1. Entfernen Sie die Funktion aus der Codebasis Ihres Projektverzeichnisses.

    2. Führen Sie den folgenden Firebase-Befehlszeilenbefehl aus:

      firebase deploy --only functions

  • Option 2: Funktion explizit löschen

    1. Entfernen Sie die Funktion aus der Codebasis Ihres Projektverzeichnisses.

    2. Führen Sie den folgenden Firebase-Befehlszeilenbefehl aus:

      firebase functions:delete FUNCTION_NAME


Referenz für Ereignisdaten

Sowohl beforeGenerateContent als auch afterGenerateContent erhalten ein AIBlockingEvent-Objekt mit Kontext und Metadaten zur Anfrage.

Anfragemetadaten auf oberster Ebene (AIBlockingEvent)

Das Objekt AIBlockingEvent der obersten Ebene enthält Informationen zum Aufrufer und zur auslösenden Umgebung:

  • event.authType: Authentifizierungsstatus für den Aufrufer: "app_user", "unauthenticated" oder "unknown".
  • event.authId: Die Firebase Authentication-UID des Aufrufers, falls angemeldet.
  • event.authClaims: Die benutzerdefinierten Authentifizierungsansprüche des Aufrufers, falls vorhanden.
  • event.appId: Die Firebase-App-ID, die die Anfrage gestellt hat.
  • event.androidPackageName / event.iosBundleId: Der Paketname oder die Paket-ID der aufrufenden App (gilt für Android- bzw. Apple-Plattformen).
  • event.data: Die Ereignisnutzlast, die sich zwischen Funktionen vor und nach der Anfrage unterscheidet:

Ereignisdaten vor der Anfrage (beforeGenerateContent)

In einer beforeGenerateContent-Funktion wird event.data mit einem BeforeGenerateContentData-Objekt gefüllt:

  • event.data.api: Der Gemini API-Anbieter: geminiV1Beta (Gemini Developer API) oder vertexV1Beta1 (Agent Platform Gemini API (formerly Vertex AI)).
  • event.data.model: Der vollständige Modellressourcenpfad (z. B. projects/{PROJECT_ID}/locations/global/publishers/google/models/gemini-3.8-flash).
  • event.data.template: Metadaten zur verwendeten Server-Prompt-Vorlage (PromptTemplateInfo), falls zutreffend.
  • event.data.request: Die Nutzlast der ausgehenden Anfrage. Der Objekttyp und die Attribute hängen vom Gemini API-Anbieter ab:

Ereignisdaten nach der Anfrage (afterGenerateContent)

In einer afterGenerateContent-Funktion wird event.data mit einem AfterGenerateContentData-Objekt gefüllt. Dieses Objekt erweitert BeforeGenerateContentData (mit api, model, template und request) und fügt die Antwort des Modells hinzu:


Einschränkungen und Verhalten

Beachten Sie bei der Implementierung dieser Funktionen die folgenden Verhaltensweisen und Einschränkungen:

  • Nur generateContent-Anfragen: Diese Funktionen können nur durch generateContent-Anfragen an die Gemini API über Firebase AI Logic ausgelöst werden.

    In den folgenden Fällen werden diese Funktionen nicht ausgelöst und die Funktionen werden für diese Anfrage unbemerkt umgangen:

    • Anfragen an generateContentStream lösen diese Funktionen nicht aus.

    • Anfragen an Gemini Live API lösen diese Funktionen nicht aus.

  • Keine clientseitigen Codeänderungen: Abgesehen davon, dass Sie generateContent-Anfragen verwenden müssen, wenn Sie diese Funktionen ausführen möchten, sind keine Änderungen an Ihrer clientseitigen Codebasis erforderlich.

    Diese Funktionen werden auf unseren Servern bereitgestellt und als Firebase AI Logic-Trigger registriert, damit der Firebase AI Logic-Proxy Anfragen und Antworten serverseitig abfangen kann.

  • Bereich auf Projektebene: Sie können pro Firebase-Projekt maximal eine beforeGenerateContent-Funktion und eine afterGenerateContent-Funktion bereitstellen.

  • Standardstandorte: Diese Funktionen werden standardmäßig in us-central1 bereitgestellt (Informationen zu Standorten für Funktionen). Die Funktion wird jedoch unabhängig davon, wo Sie sie bereitstellen, als Firebase AI Logic-Trigger in der Region global registriert.