Utilizzare Remote Config lato server con Cloud Functions e Vertex AI

Questa guida descrive come iniziare a utilizzare 2a generazione Cloud Functions con lato serverRemote Config per rendere lato server chiamate 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 dimestichezza 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 i relativi sottostanti Google Cloud automaticamente) inserendo un nuovo nome per il progetto il primo passaggio della procedura di creazione un flusso di lavoro di machine learning.
    • Opzione 2: "Aggiungi Firebase" a un progetto Google Cloud esistente selezionando il nome del progetto Google Cloud dal menu a discesa nella primo passaggio della procedura "Crea progetto" un flusso di lavoro di machine learning.

  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 ti servirà l'interfaccia a riga di comando Firebase per eseguire il deployment delle funzioni nell'Cloud Functions runtime.

  1. Installa Node.js e npm.

    Per installare Node.js e npm, consigliamo di utilizzare Gestore delle versioni dei nodi.

  2. Installa l'interfaccia a riga di comando Firebase utilizzando il tuo metodo preferito. 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 usa --save per risparmiare al tuo 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 Vertex AI API consigliate nella console Google Cloud.
  2. Inizializza il progetto e installa le dipendenze dei nodi.
  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 Vertex AI API consigliate nella console Google Cloud

  1. Apri l'app 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 compaia Vertex AI come risultato.
  3. Seleziona Vertex AI. Viene visualizzata la dashboard Vertex AI.

  4. Fai clic su Abilita tutte le API consigliate.

    Il completamento dell'abilitazione dell'API potrebbe richiedere qualche istante. 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 a Vertex AI e verifica che tutte le API consigliate siano abilitate.

Passaggio 2: inizializza il progetto e installa le dipendenze dei nodi

  1. Apri un terminale sul computer e vai alla directory in cui per creare la tua 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. All'interno trova un file index.js da utilizzare per creare la funzione, una directory node_modules che contiene le dipendenze per la funzione, e un file package.json che contiene le dipendenze del pacchetto.

  7. Aggiungi i pacchetti Admin SDK e Vertex AI eseguendo il comando seguenti comandi utilizzando --save per assicurarti che venga salvato package.json file:

    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 il IAM e pagina Amministrazione, e individua l'account di servizio 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, seleziona Remote Config Visualizzatore.
  4. Fai clic su Aggiungi un altro ruolo e seleziona AI Platform Developer.
  5. Fai clic su Aggiungi un altro ruolo, seleziona Utente Vertex AI.
  6. Fai clic su Aggiungi un altro ruolo e seleziona Invoker di 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 dell'utente e genera Risposte basate sull'IA. Combina più snippet di codice per creare un 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 invia una risposta in streaming all'utente.

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

  2. Elimina i contenuti esistenti e aggiungi Admin SDK, Remote Config e l'SDK Vertex AI e inizializzano l'app tramite incollando il codice seguente 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 verranno utilizzati dalla funzione se non può connettersi il server Remote Config. Questa soluzione configura textModel, generationConfig, safetySettings, textPrompt e location come Parametri Remote Config corrispondenti a Remote Config parametri che configurerai più avanti in questa guida. Per ulteriori informazioni su questi parametri, consulta il client Node.js di Vertex AI.

    Facoltativamente, puoi anche configurare un parametro per controllare se accedi all'Vertex AI Gemini API (in questo esempio, un parametro vertex_enabled). Questa configurazione può essere utile quando testi 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-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 funzione e imposta 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

A questo punto, 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 ed espandi dal menu di navigazione Esegui e seleziona Remote Config.

  2. Seleziona Server dal selettore Client/Server nella parte superiore della finestra Remote 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 modello
    Per elenchi aggiornati dei nomi dei modelli da utilizzare nel codice, vedi Modello versioni e cicli di vita o Disponibile dei modelli.     		Stringa gemini-1.5-pro-preview-0514
    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 il deployment e il test della funzione in locale con il Firebase Local Emulator Suite.

  1. Assicurati di aver impostato GOOGLE_APPLICATION_CREDENTIALS come ambiente come descritto in Passaggio 3: configura le autorizzazioni IAM per account di servizio Admin SDK e salva 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 il 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 input utente e ricorda che is_vertex_enabled sta configurato nel modello di server Remote Config, dovrebbe accedere Gemini tramite Vertex AI Gemini API e che questo potrebbe sono soggetti ad addebiti:

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

  6. Apporta le modifiche al tuo modello di server Remote Config nella 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 testa la funzione live.

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 fai clic su Salva.

Configura il tuo account utente per utilizzare 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 seguenti spiegano come configurare il tuo account utente e la funzione per l'esecuzione con i privilegi dell'account di servizio Admin SDK.

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

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

    Per informazioni più dettagliate sul furto d'identità degli account di servizio, consulta Account di servizio furto d'identità nella documentazione di Google Cloud.

  4. Apri la pagina Cloud Functions della console Google Cloud 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 impostandolo su Account SDK Admin.

  7. Fai clic su Avanti e poi su Esegui il deployment.

Configura gcloud CLI

Per eseguire e testare la funzione in modo sicuro dalla riga di comando, è necessario autenticarsi con il servizio Cloud Functions e ottenere una token di autenticazione.

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

  1. Se non è già installato sul computer, installa gcloud CLI come descritto in Installare lo strumento interfaccia a riga di comando.

  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