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 2ª gen. con Remote Config del servidor para realizar llamadas del servidor a Vertex AI Gemini API.

En este instructivo, agregarás Remote Config a una función similar a un chatbot que usa el modelo Gemini para responder a las preguntas de los usuarios. Remote Config administrará las entradas de Gemini API (incluida una instrucción que antepondrás a las consultas entrantes de los usuarios), y puedes actualizar estas entradas según demanda desde Firebase console. También usarás Firebase Local Emulator Suite para probar y depurar la función y, luego de verificar que funcione, la implementarás y probarás en Google Cloud.

Requisitos previos

En esta guía, se da por sentado 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 Firebase console.

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

    • Opción 1: Crea un proyecto de Firebase nuevo (y su proyecto subyacente de Google Cloud automáticamente); para ello, ingresa un nuevo nombre de proyecto en el primer paso de la página "Crear proyecto" de Terraform.
    • Opción 2: "Agrega Firebase" a un proyecto de Google Cloud existente; para ello, selecciona el nombre de tu proyecto de Google Cloud del 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 usar el Administrador de versiones de Node.

  2. Instala Firebase CLI con tu método preferido. Por ejemplo, para instalar la CLI con npm, ejecuta el siguiente: comando:

    npm install -g firebase-tools@latest

    Este comando instala el comando firebase disponible de manera global. Si el comando falla, tal vez tengas que 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 tu package.json:

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

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

Implementación

Sigue estos pasos para crear, probar y, además, implementar tu Cloud Functions de 2ª 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 los permisos de IAM para tu cuenta de servicio de Admin SDK 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 cuando se te solicite, selecciona tu proyecto.
  2. En el campo Buscar en 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 Vertex AI.

  4. Haz clic en Habilitar todas las APIs recomendadas.

    La habilitación de la API puede tardar unos minutos en completarse. Conservar 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 Cloud Billing. Después de habilitar una cuenta de facturación, regresa al panel de Vertex AI y verifica que estén habilitadas todas las APIs recomendadas.

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 tu función.

  2. Accede a Firebase:

    firebase login

  3. Ejecuta el siguiente comando para inicializar Cloud Functions for 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 su interior, verá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. Agrega los paquetes Admin SDK y Vertex AI; para ello, 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 últimas versiones 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. También 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 finalmente ejecutarás en Google Cloud. Por ejemplo, si la estrofa engines de tu package.json se configura 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 de Admin SDK y guarda tu clave

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

  1. En la consola de Google Cloud, abre la página IAM y administración, y busca la cuenta de servicio de Admin SDK (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.

Luego, exporta las credenciales de la cuenta de servicio del Admin SDK y guárdalas en la 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 de Admin SDK para abrir la página Detalles.
  3. Haga clic en Claves.
  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 y colócala en 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 las respuestas potenciadas por IA. Combinarás varios fragmentos de código para crear una función completa que inicialice Admin SDK y Vertex AI Gemini API, configure los parámetros predeterminados con Remote Config, recupere los parámetros de Remote Config más recientes, procese la entrada del usuario y envíe 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, a continuación, agrega el Admin SDK, Remote Config y el SDK de Vertex AI. Luego, inicializa la app; para ello, pega el siguiente código en el archivo:

    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 el servidor de Remote Config. Esta solución configura textModel, generationConfig, safetySettings, textPrompt y location como parámetros de Remote Config que se corresponden con los parámetros de Remote Config que configurarás más adelante en esta guía. Para obtener más información acerca de estos parámetros, consulta Cliente de Vertex AI Node.js.

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

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

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-002",
  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 tu función. Para crear una plantilla de Remote Config específica del servidor, sigue estos pasos:

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

  2. Selecciona Servidor en el selector Cliente/Servidor que se encuentra en la parte superior de la página 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 lado 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
    Para obtener listas actualizadas de los nombres de modelos que puedes usar en tu código, consulta Versiones y ciclos de vida de los modelos o Nombres de los modelos disponibles.     		String gemini-1.5-flash-002
    prompt Indica que se debe anteponer a la pregunta 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 modelo y servicio de Vertex AI. String us-central1
    is_vertex_enabled Parámetro opcional que controla si se envían las consultas a Vertex AI. Booleano true

  4. Cuando termines de agregar los parámetros, revisa que sus tipos de datos sean correctos y, 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 de forma local con Firebase Local Emulator Suite.

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

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

  2. Abre los 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 regresa a la página de registros del emulador de Firebase o a tu consola y comprueba si hay errores o advertencias.

  5. Intenta enviar alguna entrada del usuario; para ello, ten en cuenta que, como is_vertex_enabled se configuró en tu plantilla del servidor de Remote Config, esto debería acceder a Gemini a través de Vertex AI Gemini API y que esto podría generar cargos:

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

  6. Realiza cambios en tu plantilla del servidor de Remote Config en Firebase console y vuelve a acceder a tu función para observar los cambios.

Paso 7: Implementa tu función en Google Cloud

Después de probar y verificar tu función, podrás comenzar a implementar Google Cloud y probar la función en vivo.

Implemente su función

Implementa tu función con Firebase CLI:

firebase deploy --only functions

Bloquea el acceso no autenticado a la función

Cuando se implementan funciones con Firebase, las invocaciones no autenticadas se permiten de forma predeterminada si la política de tu organización no lo restringe. Durante las pruebas y antes de brindar seguridad con App Check, recomendamos bloquear 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 Admin SDK

Debido a que la cuenta de servicio del Admin SDK tiene todos los roles y permisos necesarios para ejecutar la función y, además, interactuar con Remote Config y Vertex AI Gemini API, te recomendamos usarla para ejecutar tu función. Para hacer esto, 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 que se ejecute con los privilegios de la cuenta de servicio de Admin SDK.

  1. En la consola de Google Cloud, habilita la API de Service Account Credentials de IAM.
  2. Otórgale a tu cuenta de usuario el rol de creador de tokens de cuenta de servicio: Desde la consola de Google Cloud, abre IAM y Administrador > IAM, selecciona tu cuenta de usuario y, luego, haz clic en Editar cuenta principal > Agrega otro rol.

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

    Para obtener información más detallada acerca de la identidad temporal como cuenta de servicio, consulta Identidad temporal como cuenta 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, la compilación, las conexiones y la 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 autenticar 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 está instalado en tu computadora, instala gcloud CLI como se describe en Instala la configuración de 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