Usa Remote Config lato server con Cloud Functions e Vertex AI

Questa guida descrive come iniziare a utilizzare Cloud Functions di 2ª gen. con Remote Config lato server per effettuare chiamate lato server al Vertex AI Gemini API.

In questo tutorial aggiungerai Remote Config a una funzione simile a un chatbot che utilizza il modello Gemini per rispondere alle domande degli utenti. Remote Config gestirà gli input di Gemini API (incluso un prompt da anteporre alle query degli utenti in arrivo) e potrai aggiornarli on demand dalla console Firebase. Utilizzerai Firebase Local Emulator Suite anche per testare e eseguire il debug della funzione e, dopo aver verificato che funziona, la eseguirai il deployment e la testerai su Google Cloud.

Prerequisiti

Questa guida presuppone che tu abbia familiarità con l'utilizzo di JavaScript per sviluppare applicazioni.

Configurare un progetto Firebase

Se non hai ancora un progetto Firebase:

  1. Accedi alla console Firebase.

  2. Fai clic su Crea progetto e utilizza una delle seguenti opzioni:

    • Opzione 1: crea un nuovo progetto Firebase (e automaticamente il relativo progettoGoogle Cloud di base) inserendo un nuovo nome nel primo passaggio del flusso di lavoro "Crea progetto".
    • Opzione 2: "Aggiungi Firebase" a un progetto Google Cloud esistente selezionando il nome del progetto Google Cloud dal menu a discesa nel primo passaggio del flusso di lavoro "Crea progetto".

  3. Quando richiesto, non devi configurare Google Analytics per utilizzare questa soluzione.

  4. Continua a seguire le istruzioni sullo schermo per creare il progetto.

Se hai già un progetto Firebase:

Vai a Configurare l'ambiente di sviluppo.

Configura l'ambiente di sviluppo

Per scrivere le funzioni, avrai bisogno di un ambiente Node.js e dell'interfaccia a riga di comando Firebase per eseguire il deployment delle funzioni nell'ambiente di runtime Cloud Functions.

  1. Installa Node.js e npm.

    Per installare Node.js e npm, ti consigliamo di utilizzare Node Version Manager.

  2. Installa l'interfaccia a riga di comando Firebase utilizzando il metodo che preferisci. Ad esempio, per installare l'interfaccia a riga di comando utilizzando npm, esegui questo comando:

    npm install -g firebase-tools@latest

    Questo comando installa il comando firebase disponibile a livello globale. Se questo comando non va a buon fine, potresti dover modificare le autorizzazioni npm.

    Per eseguire l'aggiornamento alla versione più recente di firebase-tools, esegui di nuovo lo stesso comando.

  3. Installa firebase-functions e firebase-admin e utilizza --save per salvarli su package.json:

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

Ora puoi procedere all'implementazione di questa soluzione.

Implementazione

Per creare, testare ed eseguire il deployment di Cloud Functions di 2ª gen. con Remote Config e Vertex AI:

  1. Abilita le API consigliate di Vertex AI nella console Google Cloud.
  2. Inizializza il progetto e installa le dipendenze Node.
  3. Configura le autorizzazioni IAM per il tuo account di servizio Admin SDK e salva la chiave.
  4. Crea la funzione.
  5. Crea un modello Remote Config specifico per il server.
  6. Esegui il deployment della funzione e testala inFirebase Local Emulator Suite.
  7. Esegui il deployment della funzione in Google Cloud.

Passaggio 1: abilita le API consigliate di Vertex AI nella console Google Cloud

  1. Apri la console Google Cloud e, quando richiesto, seleziona il tuo progetto.
  2. Nel campo Cerca nella parte superiore della console, inserisci Vertex AI e attendi che Vertex AI venga visualizzato come risultato.
  3. Seleziona Vertex AI. Viene visualizzata la dashboard Vertex AI.

  4. Fai clic su Abilita tutte le API consigliate.

    Il completamento dell'attivazione dell'API potrebbe richiedere alcuni istanti. Mantieni la pagina attiva e aperta fino al completamento dell'attivazione.

  5. Se la fatturazione non è attivata, ti verrà chiesto di aggiungere o collegare un account Cloud Billing. Dopo aver attivato un account di fatturazione, torna alla dashboard di Vertex AI e verifica che tutte le API consigliate siano attive.

Passaggio 2: inizializza il progetto e installa le dipendenze Node

  1. Apri un terminale sul computer e vai alla directory in cui hai intenzione di creare la funzione.

  2. Accedi a Firebase:

    firebase login

  3. Esegui il comando seguente per inizializzare Cloud Functions for Firebase:

    firebase init functions

  4. Seleziona Utilizza un progetto esistente e specifica l'ID progetto.

  5. Quando ti viene chiesto di selezionare la lingua da utilizzare, scegli Javascript e premi Invio.

  6. Per tutte le altre opzioni, seleziona i valori predefiniti.

    Nella directory corrente viene creata una directory functions. Al suo interno troverai un file index.js che utilizzerai per creare la funzione, una directory node_modules contenente le dipendenze per la funzione e un file package.json contenente le dipendenze del pacchetto.

  7. Aggiungi i pacchetti Admin SDK e Vertex AI eseguendo i seguenti comandi, utilizzando --save per assicurarti che vengano salvati nel file package.json:

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

Il file functions/package.json ora dovrebbe avere il seguente aspetto, con le versioni più recenti specificate:

  {
    "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
  }

Tieni presente che se utilizzi ESLint, vedrai una stanza che lo include. Inoltre, assicurati che la versione del motore Node corrisponda alla versione di Node.js installata e alla versione che esegui su Google Cloud. Ad esempio, se la stanza engines in package.json è configurata come versione Node 18 e utilizzi Node.js 20, aggiorna il file in modo da utilizzare la versione 20:

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

Passaggio 3: configura le autorizzazioni IAM per il tuo account di servizio Admin SDK e salva la chiave

In questa soluzione, utilizzerai l'account di servizio Admin SDK Firebase per eseguire la funzione.

  1. Nella console Google Cloud, apri la pagina IAM e amministrazione e individua l'account di servizio Admin SDK (chiamato firebase-adminsdk).
  2. Seleziona l'account e fai clic su Modifica utente principale. Viene visualizzata la pagina Accesso in modifica.
  3. Fai clic su Aggiungi un altro ruolo, seleziona Remote Config Visualizzatore.
  4. Fai clic su Aggiungi un altro ruolo e seleziona Sviluppatore di piattaforme di IA.
  5. Fai clic su Aggiungi un altro ruolo, seleziona Utente Vertex AI.
  6. Fai clic su Aggiungi un altro ruolo, seleziona Richiedente Cloud Run.
  7. Fai clic su Salva.

Successivamente, esporta le credenziali per l'account di servizio Admin SDK e salvale nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. Nella console Google Cloud, apri la pagina Credenziali.
  2. Fai clic sull'account di servizio Admin SDK per aprire la pagina Dettagli.
  3. Fai clic su Chiavi.
  4. Fai clic su Aggiungi chiave > Crea nuova chiave.
  5. Assicurati che JSON sia selezionato come Tipo di chiave, quindi fai clic su Crea.
  6. Scarica la chiave in un luogo sicuro sul computer.

  7. Dal terminale, esporta la chiave come variabile di ambiente:

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

Passaggio 4: crea la funzione

In questo passaggio, creerai una funzione che gestisce l'input utente e genera risposte basate sull'IA. Combinerai più snippet di codice per creare una funzione completa che inizializza Admin SDK e Vertex AI Gemini API, configura i parametri predefiniti utilizzando Remote Config, recupera i parametri Remote Config più recenti, elabora l'input dell'utente e restituisce una risposta in streaming all'utente.

  1. Nella base di codice, apri functions/index.js in un editor di testo o in un IDE.

  2. Elimina i contenuti esistenti, quindi aggiungi gli SDK Admin SDK, Remote Config e Vertex AI e inizializza l'app incollando il seguente codice nel file:

    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 i valori predefiniti che la funzione utilizzerà se non riesce a connettersi al server Remote Config. Questa soluzione configura textModel, generationConfig, safetySettings, textPrompt e location come parametri Remote Config che corrispondono ai parametri Remote Config che configurerai più avanti in questa guida. Per ulteriori informazioni su questi parametri, consulta il client Node.js di Vertex AI.

    Se vuoi, puoi anche configurare un parametro per controllare se accedere o meno a Vertex AI Gemini API (in questo esempio, un parametro chiamato vertex_enabled). Questa configurazione può essere utile per testare la funzione. Nei seguenti snippet di codice, questo valore è impostato su false, il che consente di saltare l'utilizzo di Vertex AI durante il test del deployment delle funzioni di base. Impostando il valore su true verrà richiamato 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 funzione e configura Remote Config lato server:

    // 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 e aggiungi la logica di chat e risposta:

      // 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. Salva e chiudi il file.

Passaggio 5: crea un modello Remote Config specifico per il server

Poi, crea un modello Remote Config lato server e configura i parametri e i valori da utilizzare nella funzione. Per creare un modelloRemote Config specifico per il server:

  1. Apri la console Firebase e, dal menu di navigazione, espandi Esegui e seleziona Remote Config.

  2. Seleziona Server dal selettore Client/server nella parte superiore della paginaRemote Config.

    • Se è la prima volta che utilizzi Remote Config o i modelli di server, fai clic su Crea configurazione. Viene visualizzato il riquadro Crea il tuo primo parametro lato server.
    • Se non è la prima volta che utilizzi i modelli di server Remote Config, fai clic su Aggiungi parametro.

  3. Definisci i seguenti parametri Remote Config:

    Nome parametro Descrizione Tipo Valore predefinito
    model_name Nome del modello
    Per elenchi aggiornati dei nomi dei modelli da utilizzare nel codice, consulta Versioni e cicli di vita dei modelli o Nomi dei modelli disponibili.     		Stringa gemini-1.5-flash-002
    prompt Prompt da anteporre alla query dell'utente. Stringa 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 Parametri da inviare al modello. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Impostazioni di sicurezza per Vertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Località per eseguire il servizio e il modello Vertex AI. Stringa us-central1
    is_vertex_enabled Parametro facoltativo che controlla se le query vengono inviate a Vertex AI. Booleano true

  4. Quando hai finito di aggiungere i parametri, ricontrolla che siano corretti e che i relativi tipi di dati siano corretti, poi fai clic su Pubblica modifiche.

Passaggio 6: esegui il deployment della funzione e testala in Firebase Local Emulator Suite

Ora è tutto pronto per eseguire il deployment e testare la funzione localmente con Firebase Local Emulator Suite.

  1. Assicurati di aver impostato GOOGLE_APPLICATION_CREDENTIALS come variabile di ambiente come descritto nel passaggio 3: configura le autorizzazioni IAM per il tuo account di servizio Admin SDK e salva la chiave. Quindi, dalla directory principale della directory functions, esegui il deployment della funzione nell'emulatore Firebase:

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

  2. Apri la pagina dei log dell'emulatore. Dovresti vedere che la funzione è stata caricata.

  3. Accedi alla funzione eseguendo il seguente comando, dove PROJECT_ID è l'ID progetto e LOCATION è la regione in cui hai eseguito il deployment della funzione (ad esempio us-central1):

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

  4. Attendi una risposta, quindi torna alla pagina dei log di Firebase Emulator o alla console e controlla se sono presenti errori o avvisi.

  5. Prova a inviare un input utente, tenendo presente che, poiché is_vertex_enabled è configurato nel modello di server Remote Config, dovrebbe accedere a Gemini tramite Vertex AI Gemini API e che potrebbero essere addebitati costi:

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

  6. Apporta modifiche al modello di server Remote Config nella console Firebase, quindi accedi di nuovo alla funzione per osservare le modifiche.

Passaggio 7: esegui il deployment della funzione in Google Cloud

Dopo aver testato e verificato la funzione, puoi eseguire il deployment in Google Cloud e testare la funzione in produzione.

esegui il deployment della funzione

Esegui il deployment della funzione utilizzando l'interfaccia a riga di comando Firebase:

firebase deploy --only functions

Bloccare l'accesso non autenticato alla funzione

Quando le funzioni vengono di cui vengono eseguiti il deployment utilizzando Firebase, le chiamate non autenticate sono consentite per impostazione predefinita se i criteri della tua organizzazione non lo limitano. Durante i test e prima di eseguire la protezione con App Check, consigliamo di bloccare l'accesso non autenticato.

Per bloccare l'accesso non autenticato alla funzione:

  1. Nella console Google Cloud, apri Cloud Run.

  2. Fai clic su generateWithVertex, quindi sulla scheda Sicurezza.

  3. Attiva Richiedi autenticazione e poi fai clic su Salva.

Configura il tuo account utente in modo che utilizzi le credenziali dell'account di servizio Admin SDK

Poiché l'account di servizio Admin SDK dispone di tutti i ruoli e le autorizzazioni necessari per eseguire la funzione e interagire con Remote Config e Vertex AI Gemini API, ti consigliamo di utilizzarlo per eseguire la funzione. Per farlo, devi essere in grado di creare token per l'account dal tuo account utente.

I passaggi riportati di seguito descrivono come configurare l'account utente e la funzione da eseguire con i privilegi dell'account di servizio Admin SDK.

  1. Nella console Google Cloud, abilita l'API IAM Service Account Credentials.
  2. Concedi al tuo account utente il ruolo Creatore di token account di servizio: dalla console Google Cloud, apri IAM e amministrazione > IAM, seleziona il tuo account utente e poi fai clic su Modifica entità principale > Aggiungi un altro ruolo.

  3. Seleziona Creatore token account di servizio, quindi fai clic su Salva.

    Per informazioni più dettagliate sull'impersonificazione degli account di servizio, consulta Impersonificazione degli account di servizio nella documentazione di Google Cloud.

  4. Apri la pagina Google Cloud della console Cloud Functions e fai clic sulla funzione generateWithVertex nell'elenco Funzioni.

  5. Seleziona Attivati > Modifica ed espandi Impostazioni di runtime, build, connessioni e sicurezza.

  6. Nella scheda Runtime, modifica l'account di servizio di runtime in Account SDK Admin.

  7. Fai clic su Avanti, quindi su Esegui il deployment.

Configurare l'interfaccia a riga di comando gcloud

Per eseguire e testare in sicurezza la funzione dalla riga di comando, devi eseguire l'autenticazione con il servizio Cloud Functions e ottenere un token di autenticazione valido.

Per attivare la generazione di token, installa e configura gcloud CLI:

  1. Se non è già installata sul computer, installa l'interfaccia a riga di comando gcloud come descritto in Installare l'interfaccia a riga di comando gcloud.

  2. Ottieni le credenziali di accesso per il tuo account Google Cloud:

    gcloud auth login

  3. Imposta l'ID progetto in gcloud:

    gcloud config set project PROJECT_ID

Testa la funzione

Ora è tutto pronto per testare la funzione in Google Cloud. Per testare la funzione, esegui il seguente comando:

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

Riprova con i dati forniti dall'utente:

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"

Ora puoi apportare modifiche al modello di server Remote Config, pubblicarle e testare diverse opzioni.

Passaggi successivi