Ejecuta secuencias de comandos personalizadas del servidor antes y después de las solicitudes

Versión preliminar: Activadores de Firebase AI Logic es una función en versión preliminar, lo que significa que no está sujeta a ningún ANS ni política de baja y podría cambiar de manera que deje de ser compatible con versiones anteriores.

Puedes ejecutar tus propios secuencias de comandos personalizadas del servidor antes y después de cada solicitud que tu app envía a Gemini API a través de Firebase AI Logic, sin cambiar el código del cliente. Implementarás estas secuencias de comandos como funciones de estilo de devolución de llamada implementadas en Cloud Functions for Firebase.

Con esta capacidad, puedes hacer cosas como moderar instrucciones, limitar el uso de tokens, registrar las generaciones para el análisis o redactar el contenido de las respuestas.

Existen dos tipos de eventos disponibles:

• beforeGenerateContent: Se ejecuta antes de que una solicitud llegue a Gemini API. La función puede inspeccionar o modificar la solicitud, o bien bloquearla por completo si arroja un error.

• afterGenerateContent: Se ejecuta después de que el Gemini API envía la respuesta y antes de que se muestre en la app cliente. La función puede inspeccionar o modificar la respuesta, bloquearla por completo o solo observarla (por ejemplo, para el registro o la auditoría).

Una vez que tus secuencias de comandos se implementan como funciones en Cloud Functions for Firebase, se registran como activadores de Firebase AI Logic, lo que significa que se ejecutarán para cada solicitud de generateContent en tu proyecto a Gemini API a través de Firebase AI Logic (incluidas las solicitudes realizadas con plantillas de instrucciones del servidor).

Estas funciones no se activan con solicitudes realizadas a Gemini API que no se realicen a través de Firebase AI Logic.

Requisitos previos

• Configura Firebase AI Logic: Si aún no lo hiciste, completa la guía de introducción de Firebase AI Logic, en la que se describe cómo configurar tu proyecto de Firebase, conectar tu app a Firebase, agregar el SDK, inicializar el servicio de backend para el proveedor de Gemini API que elijas y crear una instancia de GenerativeModel.

• Permisos necesarios: Asegúrate de tener los permisos de IAM necesarios para realizar la implementación en Cloud Functions for Firebase.

Paso 1: Configura tu proyecto para Cloud Functions for Firebase

Si nunca usaste Cloud Functions for Firebase en tu proyecto de Firebase, completa la siguiente configuración.

1. Asegúrate de que tu proyecto de Firebase tenga el plan de precios Blaze de pago por uso (obligatorio para usar Cloud Functions for Firebase).

   Te recomendamos que configures alertas de presupuesto y límites de inversión del presupuesto en Cloud Run Functions.

2. Instala las interfaces de línea de comandos (CLI): gcloud CLI y CLI de Firebase

   Nota: Puedes ejecutar comandos de gcloud CLI y Firebase CLI en Cloud Shell. Cloud Shell es un entorno de línea de comandos preautenticado basado en el navegador, al que se puede acceder desde la consola de Firebase y que incluye las CLIs de gcloud CLI y Firebase preinstaladas. Esto la convierte en una opción conveniente para comenzar rápidamente, siempre y cuando agregues los archivos de tu proyecto al entorno de Cloud Shell.

3. Otorga a la cuenta de servicio de Compute predeterminada el rol de cuenta de servicio de Cloud Build (roles/cloudbuild.builds.builder) que necesita para compilar tu función. Ejecuta el siguiente comando gcloud CLI:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:[e-mail]" \
     --role="roles/cloudbuild.builds.builder"
   

   Advertencia: Omitir este paso es el motivo más común por el que falla la primera implementación de tu función. Es posible que el error mencione políticas de la organización, pero la causa raíz suele ser este rol de IAM faltante.

4. Inicializa Cloud Functions for Firebase en tu proyecto de Firebase:

   1. Ejecuta el siguiente comando de la CLI de Firebase:

      firebase init functions
      

   2. Cuando se te solicite, elige TypeScript.

   3. Asegúrate de que firebase-functions en tu functions/package.json sea de la versión 6.3.0 o posterior. Sigue estos pasos para verificar tu versión:

      npm --prefix functions list firebase-functions
      

Paso 2: Escribe tus funciones

Escribe una función previa a la solicitud (beforeGenerateContent) Escribe una función posterior a la solicitud (afterGenerateContent)

Escribe una función previa a la solicitud (beforeGenerateContent)

Con el tipo de evento beforeGenerateContent, la función se activa cuando el proxy Firebase AI Logic recibe una solicitud generateContent. La función se ejecuta en la solicitud antes de que se envíe al Gemini API. La función puede modificar o bloquear la solicitud por completo.

Asegúrate de revisar la siguiente información antes de escribir tu función:

• Datos de eventos que puedes usar en tu función
• Consideraciones clave para las funciones previas a la solicitud
• Limitaciones y comportamientos de las funciones

Ejemplo

A continuación, se muestra una función de pre-solicitud de ejemplo que hace lo siguiente:

• Especifica que la función solo debe ejecutarse cuando la solicitud es para un proveedor de Gemini API específico.

• Inspecciona la instrucción en busca de temas bloqueados y rechaza la solicitud con un error.

• Limita la cantidad máxima de tokens de salida para los modelos de generación de texto.

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

Consideraciones clave para las funciones previas a la solicitud

• Especifica el proveedor Gemini API: event.data.request puede ser para Gemini Developer API o Agent Platform Gemini API (formerly Vertex AI). Los objetos de solicitud de estas diferentes APIs tienen formas diferentes. Para trabajar de forma segura con el objeto de solicitud, debes verificar event.data.api (por ejemplo, compararlo con geminiV1Beta o vertexV1Beta1, respectivamente).

• Lanzar bloquea la solicitud: Si lanzas un HttpsError, se rechazará la solicitud.

• Devuelve la solicitud completa: Si tu función modifica la solicitud, debes devolver el objeto de solicitud completo y modificado. Si no se devuelve nada (o undefined), la solicitud no se modifica.

• Prueba la latencia: Según lo que haga tu función, podría agregar latencia y afectar la experiencia del usuario.

Escribe una función posterior a la solicitud (afterGenerateContent)

Con el tipo de evento afterGenerateContent, la función se activa cuando el proxy Firebase AI Logic recibe una respuesta de una solicitud generateContent. La función se ejecuta en la respuesta antes de que se muestre al cliente. La función puede registrar el uso, modificar la respuesta o bloquearla por completo.

Asegúrate de revisar la siguiente información antes de escribir tu función:

• Datos de eventos que puedes usar en tu función
• Consideraciones clave para las funciones posteriores a la solicitud
• Limitaciones y comportamientos de las funciones

Ejemplo

Esta es una función de post-request de ejemplo que registra el uso del token y el motivo de finalización:

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

Consideraciones clave para las funciones posteriores a la solicitud

• Especifica el proveedor Gemini API: event.data.response puede ser para Gemini Developer API o Agent Platform Gemini API (formerly Vertex AI). Para convertir y trabajar de forma segura con el objeto de solicitud, debes verificar event.data.api (por ejemplo, compararlo con geminiV1Beta o vertexV1Beta1, respectivamente).

• Prueba la latencia: Según lo que haga tu función, podría agregar latencia y afectar la experiencia del usuario.

Paso 3: Implementa tus funciones

Implementar tus funciones en Firebase otorga permiso al agente de servicio de Firebase AI Logic para invocar estas funciones y registra cada función como un activador de Firebase AI Logic.

1. Implementa tus funciones con Firebase CLI:

   firebase deploy --only functions
   

2. Después de la implementación, confirma que tus funciones se hayan implementado en Firebase:

   firebase functions:list
   

3. Si necesitas iterar tu función, haz lo siguiente:

   Actualiza la función en el directorio del proyecto y, luego, vuelve a ejecutar firebase deploy --only functions.

Cómo detener la ejecución de una función

Para detener la ejecución de una de estas funciones, se debe borrar de nuestros servidores y anular su registro como un activador de Firebase AI Logic. Puedes hacerlo con la CLI de Firebase con cualquiera de las siguientes opciones:

• Opción 1: Borra la función de forma implícita

  1. Quita la función de la base de código del directorio del proyecto.

  2. Ejecuta el siguiente comando de la CLI de Firebase:

     firebase deploy --only functions
     

• Opción 2: Borra la función de forma explícita

  1. Quita la función de la base de código del directorio del proyecto.

  2. Ejecuta el siguiente comando de la CLI de Firebase:

     firebase functions:delete FUNCTION_NAME
     

Importante: Recuerda quitar la función de tu código. Si no lo haces, la próxima vez que ejecutes firebase deploy, la función se volverá a implementar en nuestros servidores y se volverá a registrar como un activador Firebase AI Logic (lo que significa que la función comenzará a activarse para las solicitudes generateContent nuevamente).

Ten en cuenta que, si actualizas la función y, luego, la vuelves a implementar, Firebase publicará la versión actualizada.

Advertencia: No uses la consola de Google Cloud para borrar la función. Debes usar una de las opciones de la CLI de Firebase descritas anteriormente. Si borras la función con la consola de Google Cloud, no se anulará el registro de la función como un activador de Firebase AI Logic. Esto hace que Firebase AI Logic siga intentando invocar la función en cada solicitud de generateContent, pero, como la función ya no existe, la solicitud fallará.

---

Referencia de datos de eventos

Tanto beforeGenerateContent como afterGenerateContent reciben un objeto AIBlockingEvent que contiene contexto y metadatos sobre la solicitud.

Metadatos de la solicitud de nivel superior (AIBlockingEvent)

El objeto AIBlockingEvent de nivel superior proporciona información sobre la persona que llama y el entorno de activación:

• event.authType: Estado de autenticación de la persona que llama: "app_user", "unauthenticated" o "unknown".
• event.authId: Es el UID de Firebase Authentication del llamador, si accedió.
• event.authClaims: Son las reivindicaciones de autenticación personalizadas del llamador, si existen.
• event.appId: Es el ID de la app de Firebase que realizó la solicitud.
• event.androidPackageName o event.iosBundleId: Es el nombre del paquete o el ID del paquete de la app que realiza la llamada (aplicable para las plataformas de Android o Apple, respectivamente).
• event.data: Es la carga útil del evento, que difiere entre las funciones previas a la solicitud y las posteriores a la solicitud:
  • Para beforeGenerateContent, este es un objeto BeforeGenerateContentData.
  • Para afterGenerateContent, este es un objeto AfterGenerateContentData.

Datos del evento previo a la solicitud (beforeGenerateContent)

En una función beforeGenerateContent, event.data se propaga con un objeto BeforeGenerateContentData:

• event.data.api: El proveedor de Gemini API: geminiV1Beta (Gemini Developer API) o vertexV1Beta1 (Agent Platform Gemini API (formerly Vertex AI)).
• event.data.model: Es la ruta completa del recurso del modelo (por ejemplo, projects/{PROJECT_ID}/locations/global/publishers/google/models/gemini-3.8-flash).
• event.data.template: Metadatos sobre la plantilla de instrucciones del servidor que se usó (PromptTemplateInfo), si corresponde.
• event.data.request: Es la carga útil de la solicitud saliente. El tipo de objeto y las propiedades dependen del proveedor Gemini API:
  • Gemini Developer API (geminiV1Beta): GeminiV1BetaGenerateContentRequest
  • Agent Platform Gemini API (formerly Vertex AI) (vertexV1Beta1): VertexV1Beta1GenerateContentRequest

Datos de eventos posteriores a la solicitud (afterGenerateContent)

En una función afterGenerateContent, event.data se propaga con un objeto AfterGenerateContentData. Este objeto extiende BeforeGenerateContentData (proporcionando api, model, template y request) y agrega la respuesta del modelo:

• event.data.response: Es la carga útil de la respuesta del modelo. El tipo de objeto y las propiedades dependen del proveedor de Gemini API:
  • Gemini Developer API (geminiV1Beta): GeminiV1BetaGenerateContentResponse
  • Agent Platform Gemini API (formerly Vertex AI) (vertexV1Beta1): VertexV1Beta1GenerateContentResponse

---

Limitaciones y comportamientos

Cuando implementes estas funciones, ten en cuenta los siguientes comportamientos y limitaciones:

• Solo solicitudes generateContent: Estas funciones solo se pueden activar con solicitudes generateContent a Gemini API a través de Firebase AI Logic.

  Las siguientes acciones no activarán estas funciones, y las funciones se omitirán de forma silenciosa para esa solicitud:

  • Las solicitudes a generateContentStream no activarán estas funciones.

  • Las solicitudes a Gemini Live API no activarán estas funciones.

• No se requieren cambios en el código del cliente: Además de asegurarte de usar solicitudes generateContent cuando quieras ejecutar estas funciones, no se requieren cambios en tu base de código del cliente.

  Estas funciones se implementan en nuestros servidores y se registran como activadores de Firebase AI Logic para que el proxy de Firebase AI Logic pueda interceptar solicitudes y respuestas del servidor.

• Alcance a nivel del proyecto: Puedes implementar como máximo una función de beforeGenerateContent y una función de afterGenerateContent por proyecto de Firebase.

• Ubicaciones predeterminadas: Estas funciones se implementarán en us-central1 de forma predeterminada (obtén información sobre las ubicaciones de las funciones). Sin embargo, la función se registrará como un activador de Firebase AI Logic en la región global, independientemente de dónde implementes la función.

Advertencia: Si necesitas detener la ejecución de una función, debes usar la CLI de Firebase para que la función se borre de nuestros servidores y se anule su registro como un activador de Firebase AI Logic.