Usa Remote Config del servidor con Cloud Functions y Vertex AI

En esta guía, se describe cómo comenzar a usar Cloud Functions de 2a gen. con Remote Config del servidor para realizar llamadas del servidor a la API de Vertex AI Gemini.

En este instructivo, agregarás Remote Config a una función similar a un chatbot que usa el modelo Gemini para responder las preguntas de los usuarios. Remote Config administrará las entradas de la API de Gemini (incluido un mensaje que deberás anteponer a las consultas entrantes de los usuarios) y puedes actualizar estas entradas a pedido desde Firebase console. También usarás Firebase Local Emulator Suite para probar y depurar la función y, luego, después de verificar que funcione, implementarla y probarla en Google Cloud.

Requisitos previos

En esta guía, se supone que estás familiarizado con el uso de JavaScript para desarrollar aplicaciones.

Configura un proyecto de Firebase

Si aún no tienes un proyecto de Firebase, haz lo siguiente:

  1. Accede a Firebase console.

  2. Haz clic en Crear proyecto y, luego, usa una de las siguientes opciones:

    • Opción 1: Ingresa el nombre de proyecto nuevo en el primer paso del flujo de trabajo “Crear proyecto” para crear un proyecto de Firebase nuevo (y su proyecto subyacente de Google Cloud automáticamente).
    • Opción 2: “Agrega Firebase” a un proyecto existente de Google Cloud. Para ello, selecciona el nombre de tu proyecto de Google Cloud en el menú desplegable del primer paso del flujo de trabajo “Crear proyecto”.

  3. Cuando se te solicite, no es necesario que configures Google Analytics para usar esta solución.

  4. Sigue las instrucciones en pantalla para crear tu proyecto.

Si ya tienes un proyecto de Firebase, haz lo siguiente:

Continúa con Configura tu entorno de desarrollo.

Cómo configurar tu entorno de desarrollo

Para escribir funciones, necesitarás un entorno de Node.js. Además, si quieres implementarlas en el entorno de ejecución de Cloud Functions, necesitarás Firebase CLI.

  1. Instala Node.js y npm.

    Para instalar Node.js y npm, te recomendamos que uses Node Version Manager.

  2. Instala Firebase CLI con el método que prefieras. Por ejemplo, para instalar la CLI con npm, ejecuta este comando:

    npm install -g firebase-tools@latest

    Este comando instala el comando firebase disponible de forma global. Si este comando falla, es posible que debas cambiar los permisos de npm.

    Para actualizar a la versión más reciente de firebase-tools, vuelve a ejecutar el mismo comando.

  3. Instala firebase-functions y firebase-admin, y usa --save para guardarlos en package.json:

    npm install firebase-functions@latest firebase-admin@latest --save

Ahora todo está listo para continuar con la implementación de esta solución.

Implementación

Sigue estos pasos para crear, probar e implementar tus Cloud Functions de 2a gen. con Remote Config y Vertex AI:

  1. Habilita las APIs recomendadas de Vertex AI en la consola de Google Cloud.
  2. Inicializa tu proyecto y, luego, instala las dependencias de Node.
  3. Configura permisos de IAM para tu cuenta de servicio del SDK de Admin y guarda tu clave.
  4. Crea la función.
  5. Crea una plantilla de Remote Config específica del servidor.
  6. Implementa tu función y pruébala en Firebase Local Emulator Suite.
  7. Implementa tu función en Google Cloud.

Paso 1: Habilita las APIs recomendadas de Vertex AI en la consola de Google Cloud

  1. Abre la consola de Google Cloud y selecciona tu proyecto cuando se te solicite.
  2. En el campo Buscar de la parte superior de la consola, ingresa Vertex AI y espera a que aparezca Vertex AI como resultado.
  3. Selecciona Vertex AI. Aparecerá el panel de Vertex AI.

  4. Haz clic en Habilitar todas las APIs recomendadas.

    La habilitación de la API puede tardar unos minutos en completarse. Mantén la página activa y abierta hasta que finalice la habilitación.

  5. Si la facturación no está habilitada, se te solicitará que agregues o vincules una cuenta de Facturación de Cloud. Después de habilitar una cuenta de facturación, regresa al panel de Vertex AI y verifica que todas las APIs recomendadas estén habilitadas.

Paso 2: Inicializa tu proyecto y, luego, instala las dependencias de Node

  1. Abre una terminal en tu computadora y navega al directorio en el que planeas crear la función.

  2. Accede a Firebase:

    firebase login

  3. Ejecuta el siguiente comando para inicializar Cloud Functions para Firebase:

    firebase init functions

  4. Selecciona Usar un proyecto existente y especifica el ID del proyecto.

  5. Cuando se te solicite que selecciones el lenguaje que quieres usar, elige JavaScript y presiona Intro.

  6. Para todas las demás opciones, selecciona los valores predeterminados.

    Se crea un directorio functions en el directorio actual. En él, encontrarás un archivo index.js que usarás para compilar tu función, un directorio node_modules que contiene las dependencias de tu función y un archivo package.json que contiene las dependencias del paquete.

  7. Para agregar el SDK de Admin y los paquetes de Vertex AI, ejecuta los siguientes comandos y usa --save para asegurarte de que se guarden en tu archivo package.json:

    cd functions
npm install firebase-admin@latest @google-cloud/vertexai --save

Tu archivo functions/package.json debería verse de la siguiente manera, con las versiones más recientes especificadas:

  {
    "name": "functions",
    "description": "Cloud Functions for Firebase",
    "scripts": {
      "serve": "firebase emulators:start --only functions",
      "shell": "firebase functions:shell",
      "start": "npm run shell",
      "deploy": "firebase deploy --only functions",
      "logs": "firebase functions:log"
    },
    "engines": {
      "node": "20"
    },
    "main": "index.js",
    "dependencies": {
      "@google-cloud/vertexai": "^1.1.0",
      "firebase-admin": "^12.1.0",
      "firebase-functions": "^5.0.0"
    },
    "devDependencies": {
      "firebase-functions-test": "^3.1.0"
    },
    "private": true
  }

Ten en cuenta que, si usas ESLint, verás una estrofa que lo incluye. Además, asegúrate de que la versión del motor de nodos coincida con la versión instalada de Node.js y la versión que ejecutas en Google Cloud en última instancia. Por ejemplo, si la estrofa engines en tu package.json está configurada como Node.js 18 y usas Node.js 20, actualiza el archivo para que use la versión 20:

  "engines": {
    "node": "20"
  },

Paso 3: Configura los permisos de IAM para tu cuenta de servicio del SDK de Admin y guarda tu clave

En esta solución, usarás la cuenta de servicio del SDK de Firebase Admin para ejecutar la función.

  1. En la consola de Google Cloud, abre la página IAM y administración y busca la cuenta de servicio del SDK de Admin (llamada firebase-adminsdk).
  2. Selecciona la cuenta y haz clic en Editar principal. Aparecerá la página de acceso de edición.
  3. Haz clic en Agregar otro rol y selecciona Visualizador de Remote Config.
  4. Haz clic en Agregar otro rol y selecciona Desarrollador de AI Platform.
  5. Haz clic en Agregar otro rol y selecciona Usuario de Vertex AI.
  6. Haz clic en Agregar otro rol y selecciona Invocador de Cloud Run.
  7. Haz clic en Guardar.

A continuación, exporta las credenciales de la cuenta de servicio del SDK de Admin y guárdalas en tu variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

  1. En la consola de Google Cloud, abre la página Credenciales.
  2. Haz clic en la cuenta de servicio del SDK de Admin para abrir la página Detalles.
  3. Haz clic en Claves (Keys).
  4. Haz clic en Agregar clave > Crear clave nueva.
  5. Asegúrate de que JSON esté seleccionado como el Tipo de clave y, luego, haz clic en Crear.
  6. Descarga la clave a un lugar seguro en tu computadora.

  7. Desde tu terminal, exporta la clave como una variable de entorno:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Paso 4: Crea la función

En este paso, crearás una función que maneje las entradas del usuario y genere respuestas potenciadas por IA. Combinarás varios fragmentos de código para compilar una función integral que inicialice el SDK de Admin y la API de Vertex AI Gemini, configure los parámetros predeterminados con Remote Config, recupere los parámetros más recientes de Remote Config, procese las entradas del usuario y transmita una respuesta al usuario.

  1. En tu base de código, abre functions/index.js en un editor de texto o IDE.

  2. Borra el contenido existente y, luego, agrega el SDK de Admin, Remote Config y el SDK de Vertex AI. Luego, pega el siguiente código en el archivo para inicializar la app:

    const { onRequest } = require("firebase-functions/v2/https");
const logger = require("firebase-functions/logger");

const { initializeApp } = require("firebase-admin/app");
const { VertexAI } = require('@google-cloud/vertexai');
const { getRemoteConfig } = require("firebase-admin/remote-config");

// Set and check environment variables.
const project = process.env.GCLOUD_PROJECT;

// Initialize Firebase.
const app = initializeApp();
    index.js

  3. Configura los valores predeterminados que usará tu función si no se puede conectar al servidor de Remote Config. Esta solución configura textModel, generationConfig, safetySettings, textPrompt y location como parámetros de Remote Config que corresponden a los parámetros de Remote Config que configurarás más adelante en esta guía. Para obtener más información sobre estos parámetros, consulta Cliente de Vertex AI para Node.js.

    De manera opcional, también puedes configurar un parámetro para controlar si accedes o no a la API de Vertex AI Gemini (en este ejemplo, un parámetro llamado vertex_enabled). Esta configuración puede ser útil cuando pruebas tu función. En los siguientes fragmentos de código, este valor se establece en false, por lo que se omitirá el uso de Vertex AI mientras pruebas la implementación de funciones básicas. Si se establece en true, se invocará la API de Vertex AI Gemini.

    // Define default (fallback) parameter values for Remote Config.
const defaultConfig = {

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-preview-0514",
  generation_config: [{
    "stopSequences": [], "temperature": 0.7,
    "maxOutputTokens": 64, "topP": 0.1, "topK": 20
  }],
  prompt: "I'm a developer who wants to learn about Firebase and you are a \
    helpful assistant who knows everything there is to know about Firebase!",
  safety_settings: [{
    "category":
      "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT",
    "threshold": "HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE"
  }],
  location: 'us-central1',

  // Disable Vertex AI Gemini API access for testing.
  vertex_enabled: false
};
    index.js

  4. Crea la función y configura Remote Config del servidor:

    // Export the function.
exports.generateWithVertex = onRequest(async (request, response) => {

  try {

    // Set up Remote Config.
    const rc = getRemoteConfig(app);

    // Get the Remote Config template and assign default values.
    const template = await rc.getServerTemplate({
      defaultConfig: defaultConfig
    });

    // Add the template evaluation to a constant.
    const config = template.evaluate();

    // Obtain values from Remote Config.
    const textModel = config.getString("model_name") ||
        defaultConfig.model_name;
    const textPrompt = config.getString("prompt") || defaultConfig.prompt;
    const generationConfig = config.getString("generation_config") ||
        defaultConfig.generation_config;
    const safetySettings = config.getString("safety_settings") ||
        defaultConfig.safety_settings;
    const location = config.getString("location") ||
        defaultConfig.location;
    const vertexEnabled = config.getBoolean("is_vertex_enabled") ||
        defaultConfig.vertex_enabled;
    index.js

  5. Configura Vertex AI y agrega la lógica de chat y respuesta:

      // Allow user input.
  const userInput = request.query.prompt || '';

  // Instantiate Vertex AI.
    const vertex_ai = new VertexAI({ project: project, location: location });
    const generativeModel = vertex_ai.getGenerativeModel({
      model: textModel,
      safety_settings: safetySettings,
      generation_config: generationConfig,
    });

    // Combine prompt from Remote Config with optional user input.
    const chatInput = textPrompt + " " + userInput;

    if (!chatInput) {
      return res.status(400).send('Missing text prompt');
    }
    // If vertexEnabled isn't true, do not send queries to Vertex AI.
    if (vertexEnabled !== true) {
      response.status(200).send({
        message: "Vertex AI call skipped. Vertex is not enabled."
      });
      return;
    }

    logger.log("\nRunning with model ", textModel, ", prompt: ", textPrompt,
      ", generationConfig: ", generationConfig, ", safetySettings: ",
      safetySettings, " in ", location, "\n");

    const result = await generativeModel.generateContentStream(chatInput); 
    response.writeHead(200, { 'Content-Type': 'text/plain' });

    for await (const item of result.stream) {
      const chunk = item.candidates[0].content.parts[0].text;
      logger.log("Received chunk:", chunk);
      response.write(chunk);
    }

    response.end();

  } catch (error) {
    logger.error(error);
    response.status(500).send('Internal server error');
  }
});
    index.js

  6. Guarde y cierre el archivo.

Paso 5: Crea una plantilla de Remote Config específica del servidor

A continuación, crea una plantilla de Remote Config del servidor y configura los parámetros y valores para usar en la función. Para crear una plantilla de Remote Config específica del servidor, sigue estos pasos:

  1. Abre Firebase console y, en el menú de navegación, expande Ejecutar y selecciona Remote Config.

  2. Selecciona Servidor en el selector Cliente/Servidor en la parte superior de la página de Remote Config.

    • Si es la primera vez que usas Remote Config o plantillas de servidor, haz clic en Crear configuración. Aparecerá el panel Crea tu primer parámetro del servidor.
    • Si no es la primera vez que usas plantillas de servidor de Remote Config, haz clic en Agregar parámetro.

  3. Define los siguientes parámetros de Remote Config:

    Nombre del parámetro Descripción Tipo Valor predeterminado
    model_name Nombre del modelo
    Si deseas ver listas actualizadas de nombres de modelos para usar en tu código, consulta Versiones y ciclos de vida de los modelos o Nombres de modelos disponibles.     		String gemini-1.5-pro-preview-0514
    prompt Indica que se debe anteponer a la consulta del usuario. String I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!
    generation_config Parámetros para enviar al modelo. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Configuración de seguridad para Vertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Ubicación para ejecutar el servicio y el modelo de Vertex AI. String us-central1
    is_vertex_enabled Parámetro opcional que controla si las consultas se envían a Vertex AI. Booleano true

  4. Cuando termines de agregar los parámetros, vuelve a verificarlos y que sus tipos de datos sean correctos. Luego, haz clic en Publicar cambios.

Paso 6: Implementa tu función y pruébala en Firebase Local Emulator Suite

Ya está todo listo para implementar y probar tu función localmente con Firebase Local Emulator Suite.

  1. Asegúrate de haber configurado GOOGLE_APPLICATION_CREDENTIALS como una variable de entorno como se describe en el Paso 3: Configura los permisos de IAM para la cuenta de servicio del SDK de Admin y guarda tu clave. Luego, desde el directorio superior de tu directorio functions, implementa tu función en el emulador de Firebase:

    firebase emulators:start --project PROJECT_ID --only functions

  2. Abre la página de registros del emulador. Esto debería mostrar que se cargó tu función.

  3. Accede a tu función ejecutando el siguiente comando, en el que PROJECT_ID es el ID del proyecto y LOCATION es la región en la que implementaste la función (por ejemplo, us-central1):

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. Espera una respuesta y, luego, regresa a la página de registros del emulador de Firebase o a tu consola y revisa si hay errores o advertencias.

  5. Intenta enviar alguna entrada del usuario. Ten en cuenta que, como is_vertex_enabled está configurado en tu plantilla de servidor de Remote Config, esto debería acceder a Gemini a través de la API de Vertex AI Gemini y que esto podría generar cargos:

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. Haz cambios en la plantilla del servidor de Remote Config en Firebase console y, luego, vuelve a acceder a la función para observar los cambios.

Paso 7: Implementa tu función en Google Cloud

Después de probar y verificar tu función, estarás listo para implementarla en Google Cloud y probar la función activa.

Implementa tu función

Implementa tu función con Firebase CLI:

firebase deploy --only functions

Bloquea el acceso no autenticado a la función

Cuando las funciones se implementan con Firebase, las invocaciones no autenticadas se permiten de forma predeterminada si la política de tu organización no las restringe. Durante las pruebas y antes de protegerte con la Verificación de aplicaciones, te recomendamos que bloquees el acceso sin autenticación.

Sigue estos pasos para bloquear el acceso no autenticado a la función:

  1. En la consola de Google Cloud, abre Cloud Run.

  2. Haz clic en generateWithVertex y, luego, en la pestaña Seguridad.

  3. Habilita Solicitar autenticación y, luego, haz clic en Guardar.

Configura tu cuenta de usuario para usar las credenciales de la cuenta de servicio del SDK de Admin.

Debido a que la cuenta de servicio del SDK de Admin tiene todos los roles y permisos necesarios para ejecutar la función y, además, interactuar con Remote Config y la API de Vertex AI Gemini, te recomendamos usarla para ejecutar la función. Para ello, debes poder crear tokens para la cuenta desde tu cuenta de usuario.

En los siguientes pasos, se describe cómo configurar tu cuenta de usuario y la función para ejecutarse con los privilegios de la cuenta de servicio del SDK de Admin.

  1. En la consola de Google Cloud, habilita la API de credenciales de la cuenta de servicio de IAM.
  2. Otorga a tu cuenta de usuario la función de Creador de tokens de cuenta de servicio. Desde la consola de Google Cloud, abre IAM y administración > IAM, selecciona tu cuenta de usuario y, luego, haz clic en Editar principal > Agregar otro rol.

  3. Selecciona Creador de tokens de cuenta de servicio y, luego, haz clic en Guardar.

    Para obtener información más detallada sobre la suplantación de cuentas de servicio, consulta Robo de identidad de cuentas de servicio en la documentación de Google Cloud.

  4. Abre la página Cloud Functions de la consola de Google Cloud y haz clic en la función generateWithVertex en la lista Funciones.

  5. Selecciona Activador > Editar y expande Configuración del entorno de ejecución, compilación, conexiones y seguridad.

  6. En la pestaña Entorno de ejecución, cambia la cuenta de servicio del entorno de ejecución a la cuenta del SDK de Admin.

  7. Haz clic en Siguiente y, luego, en Implementar.

Configura la CLI de gcloud

Para ejecutar y probar tu función de forma segura desde la línea de comandos, deberás autenticarte con el servicio de Cloud Functions y obtener un token de autenticación válido.

Para habilitar la generación de tokens, instala y configura gcloud CLI:

  1. Si aún no lo has hecho, instala gcloud CLI como se describe en Instala la gcloud CLI.

  2. Obtén credenciales de acceso para tu cuenta de Google Cloud:

    gcloud auth login

  3. Configura tu ID del proyecto en gcloud:

    gcloud config set project PROJECT_ID

Prueba la función

Ya está todo listo para probar tu función en Google Cloud. Para probar la función, ejecuta el siguiente comando:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json"

Vuelve a intentarlo con datos proporcionados por el usuario:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20dogs \
 -H "Authorization: bearer $(gcloud auth print-identity-token)" \
 -H "Content-Type: application/json"

Ahora puedes realizar cambios en tu plantilla del servidor de Remote Config, publicar esos cambios y probar diferentes opciones.

Próximos pasos