Utilizzare Remote Config lato server con Cloud Functions e Vertex AI

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

In questo tutorial, aggiungerai Remote Config a una funzione simile a un chatbot che utilizza un Gemini modello per rispondere alle domande degli utenti. Remote Config gestirà gli input Gemini API (incluso un prompt che anteporrai alle query utente in entrata) e potrai aggiornare questi input on demand dalla console Firebase. Utilizzerai anche Firebase Local Emulator Suite per testare ed eseguire il debug della funzione, quindi, dopo aver verificato che funzioni, la eseguirai 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 già un progetto Firebase:

  1. Accedi alla Firebase console.

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

    • Opzione 1: crea un nuovo progetto Firebase (e il relativo progetto sottostante Google Cloud automaticamente) inserendo un nuovo nome del progetto 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 ti viene 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:

Procedi alla sezione Configurare l'ambiente di sviluppo.

Configurare l'ambiente di sviluppo

Per scrivere le funzioni, avrai bisogno di un ambiente Node.js e di Firebase CLI per eseguire il deployment delle funzioni nel Cloud Functions runtime.

  1. Installa Node.js e npm.

    Per l'installazione di Node.js e npm, ti consigliamo di utilizzare Node Version Manager.

    consulta Impostare le opzioni di runtime.

  2. Installa la Firebase CLI 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 riesce, potresti dover modificare le autorizzazioni npm.

    Per eseguire l'aggiornamento all'ultima versione di firebase-tools, esegui di nuovo lo stesso comando.

  3. Installa firebase-functions e firebase-admin e utilizza --save per salvarli in 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 (2ª gen.) Cloud Functions con Remote Config e Vertex AI:

  1. Abilita le API consigliate nella console.Vertex AIGoogle Cloud
  2. Inizializza il progetto e installa le dipendenze Node.
  3. Configura le autorizzazioni IAM per il service account 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 in Firebase Local Emulator Suite.
  7. Esegui il deployment della funzione su Google Cloud.

Passaggio 1: abilita le API consigliate in Google Cloud consoleVertex AI

  1. Apri la Google Cloud console e, quando ti viene richiesto, seleziona il 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.

    L'abilitazione dell'API potrebbe richiedere alcuni istanti. Mantieni la pagina attiva e aperta fino al termine dell'abilitazione.

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

Passaggio 2: inizializza il progetto e installa le dipendenze Node

  1. Apri un terminale sul computer e vai alla directory in cui prevedi 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 Usa 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 le impostazioni predefinite.

    Nella directory attuale viene creata una directory functions. All'interno troverai un file index.js che utilizzerai per creare la funzione, una directory node_modules che contiene le dipendenze della funzione e un file package.json che contiene 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 dovrebbe ora 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 sezione che lo include. In oltre, assicurati che la versione del motore Node corrisponda alla versione installata di Node.js e alla versione che alla fine verrà eseguita su Google Cloud. Ad esempio, se la sezione engines in package.json è configurata come versione 18 di Node e utilizzi Node.js 20, aggiorna il file in modo che utilizzi la versione 20:

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

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

In questa soluzione, utilizzerai il service account di Firebase Admin SDK per eseguire la funzione.

  1. Nella console Google Cloud, apri la pagina IAM e amministrazione e individua il service account Admin SDK (denominato firebase-adminsdk).
  2. Seleziona l'account e fai clic su Modifica entità. Viene visualizzata la pagina Accesso in modifica.
  3. Fai clic su Aggiungi un altro ruolo e seleziona Remote Config Visualizzatore.
  4. Fai clic su Aggiungi un altro ruolo e seleziona Sviluppatore della piattaforma AI.
  5. Fai clic su Aggiungi un altro ruolo e seleziona Vertex AI utente.
  6. Fai clic su Aggiungi un altro ruolo e seleziona Invoker Cloud Run.
  7. Fai clic su Salva.

Successivamente, esporta le credenziali per il Admin SDK service account e salvale nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. Nella console Google Cloud, apri la pagina Credenziali.
  2. Fai clic sul Admin SDK service account per aprire la pagina Dettagli.
  3. Fai clic su Chiavi.
  4. Fai clic su Aggiungi chiave > Crea nuova chiave.
  5. Assicurati che sia selezionato JSON 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 dell'utente e genera risposte basate sull'AI. 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 gli ultimi parametri Remote Config, elabora l'input dell'utente e trasmette una risposta all'utente.

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

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

    const { onRequest } = require("firebase-functions/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 a l Remote Config server. Questa soluzione configura textModel, generationConfig, safetySettings, textPrompt, e location come Remote Config parametri che corrispondono ai Remote Config parametri che configurerai più avanti in questa guida. Per saperne di più su questi parametri, consulta Client Node.js di Vertex AI.

    Facoltativamente, puoi anche configurare un parametro per controllare se accedere o meno a Vertex AI Gemini API (in questo esempio, un parametro denominato vertex_enabled). Questa configurazione può essere utile per testare la funzione. Negli snippet di codice seguenti, questo valore è impostato su false, il che significa che l'utilizzo di Vertex AI verrà ignorato durante il test del deployment di base della funzione. Se lo imposti su true, verrà richiamata la 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 lato server Remote Config:

    // 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 specifico per il server Remote Config

Successivamente, crea un modello Remote Config lato server e configura i parametri e i valori da utilizzare nella funzione. Per creare un modello Remote 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 Remote Config pagina.

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

  3. Definisci i seguenti Remote Config parametri:

    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-2.0-flash
    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à in cui 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. Al termine dell'aggiunta dei parametri, ricontrolla i parametri e verifica che i tipi di dati siano corretti, quindi fai clic su Pubblica modifiche.

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

Ora puoi eseguire il deployment e testare la funzione localmente con il Firebase Local Emulator Suite.

  1. Assicurati di aver impostato GOOGLE_APPLICATION_CREDENTIALS come variabile di ambiente, come descritto in Passaggio 3: configura le autorizzazioni IAM per il service account Admin SDKe 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. Dovrebbe indicare che la funzione è stata caricata.

  3. Accedi alla funzione eseguendo il comando seguente, 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 dell'emulatore Firebase o alla console e verifica la presenza di errori o avvisi.

  5. Prova a inviare alcuni input utente, tenendo presente che, poiché is_vertex_enabled è configurato nel modello server Remote Config, dovrebbe accedere al modello Gemini tramite l'Vertex AI Gemini API e che ciò potrebbe comportare addebiti:

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

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

Passaggio 7: esegui il deployment della funzione su Google Cloud

Dopo aver testato e verificato la funzione, puoi eseguirne il deployment su Google Cloud e testare la funzione live.

Esegui il deployment della funzione

Esegui il deployment della funzione utilizzando la Firebase CLI:

firebase deploy --only functions

Blocca l'accesso non autenticato alla funzione

Quando le funzioni vengono eseguite utilizzando Firebase, le chiamate non autenticate sono consentite per impostazione predefinita se la policy della tua organizzazione non le limita. Durante i test e prima di proteggere con App Check, ti consigliamo di bloccare l'accesso non autenticato.

Per bloccare l'accesso non autenticato alla funzione:

  1. Nella Google Cloud console, apri Cloud Run.

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

  3. Attiva Richiedi autenticazione e fai clic su Salva.

Configura l'account utente in modo che utilizzi le credenziali del service account Admin SDK

Poiché il Admin SDK service account dispone di tutti i ruoli e le autorizzazioni necessari per eseguire la funzione e interagire con il Remote Config e il 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 seguenti descrivono come configurare l'account utente e la funzione in modo che vengano eseguiti con i privilegi del service account Admin SDK.

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

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

    Per informazioni più dettagliate sulla simulazione dell'identità dei service account, consulta Simulazione dell'identità dei service account nella documentazione Google Cloud.

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

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

  6. Nella scheda Runtime, modifica il Service account di runtime in Account SDK Admin.

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

Configura gcloud CLI

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

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

  1. Se non è già installato sul computer, installa gcloud CLI come descritto in Installa gcloud CLI.

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

    gcloud auth login

  3. Imposta l'ID progetto in gcloud:

    gcloud config set project PROJECT_ID

Testa la funzione

Ora puoi testare la funzione in Google Cloud. Per testare la funzione, esegui questo 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 server di Remote Config, pubblicare tali modifiche e testare diverse opzioni.

Passaggi successivi