Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Utilizza Remote Config lato server con Cloud Functions e Agent Platform

Questa guida descrive come iniziare a utilizzare Cloud Functions di 2ª gen. con Remote Config lato server per effettuare chiamate lato server all'Agent Platform Gemini API (formerly Vertex AI).

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

Prerequisiti

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

Configura un progetto Firebase

Se non hai ancora un progetto Firebase:

Accedi alla consoleFirebase.
Fai clic su Crea progetto, quindi utilizza una delle seguenti opzioni:
- Opzione 1: crea un nuovo progetto Firebase (e automaticamente il progetto Google Cloud sottostante) inserendo un nuovo nome del progetto nel primo passaggio del workflow "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 workflow "Crea progetto".
Quando richiesto, non è necessario configurare Google Analytics per utilizzare questa soluzione.
Continua a seguire le istruzioni sullo schermo per creare il progetto.

Se hai già un progetto Firebase:

Vai a Configura 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 nel runtime Cloud Functions.

Installa Node.js e npm.

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

Importante: ti consigliamo di utilizzare Node.js v20 o versioni successive. Consulta Imposta le opzioni di runtime per informazioni importanti sul supporto continuo delle versioni di Node.js.
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, potrebbe essere necessario modificare le autorizzazioni npm.

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

Nota: puoi anche eseguire i comandi dell'interfaccia a riga di comando Firebase in Cloud Shell. Cloud Shell è un ambiente a riga di comando pre-autenticato basato su browser, accessibile dalla console Firebase e dotato dell'interfaccia a riga di comando Firebase preinstallata. Questo lo rende un'opzione pratica per iniziare rapidamente, a condizione che tu aggiunga i file di progetto all'ambiente Cloud Shell.
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

Segui questi passaggi per creare, testare ed eseguire il deployment della tua Cloud Functions di 2ª gen. con Remote Config e Agent Platform:

Abilita Agent Platform API Recommender consigliate nella console Google Cloud.
Inizializza il progetto e installa le dipendenze Node.
Configura le autorizzazioni IAM per il tuo service account Admin SDK e salva la chiave.
Crea la funzione.
Crea un modello Remote Config specifico per il server.
Esegui il deployment della funzione e testala in Firebase Local Emulator Suite.
Esegui il deployment della funzione in Google Cloud.

Passaggio 1: abilita le API consigliate per Agent Platform nella console Google Cloud

Apri la console Google Cloud e, quando richiesto, seleziona il tuo progetto.
Nel campo Cerca nella parte superiore della console, inserisci Agent Platform e attendi che Agent Platform venga visualizzato come risultato.
Seleziona Agent Platform. Viene visualizzata la dashboard Agent Platform.
Fai clic su Abilita tutte le API Recommender consigliate.

L'abilitazione dell'API potrebbe richiedere qualche istante. Tieni la pagina attiva e aperta fino al termine dell'attivazione.
Se la fatturazione non è abilitata, ti verrà chiesto di aggiungere o collegare un account Cloud Billing. Dopo aver attivato un account di fatturazione, torna alla dashboard di Agent Platform e verifica che tutte le API consigliate siano abilitate.

Passaggio 2: inizializza il progetto e installa le dipendenze Node

Apri un terminale sul computer e vai alla directory in cui prevedi di creare la funzione.
Accedi a Firebase:
```
firebase login
```
Esegui questo comando per inizializzare Cloud Functions for Firebase:
```
firebase init functions
```
Seleziona Utilizza un progetto esistente e specifica l'ID progetto.
Quando ti viene chiesto di selezionare il linguaggio da utilizzare, scegli JavaScript e premi Invio.
Per tutte le altre opzioni, seleziona i valori predefiniti.

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 per la funzione e un file package.json che contiene le dipendenze del pacchetto.
Aggiungi i pacchetti Admin SDK e Agent Platform 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 ultime versioni 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. Inoltre, assicurati che la versione del motore del nodo corrisponda alla versione installata di Node.js e alla versione che esegui su Google Cloud. Ad esempio, se la sezione engines nel tuo package.json è configurata come Node versione 18 e utilizzi Node.js 20, aggiorna il file in modo che utilizzi 20:

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

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

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

Nella console Google Cloud, apri la pagina IAM e amministrazione e individua il service account Admin SDK (denominato firebase-adminsdk).
Seleziona l'account e fai clic su Modifica entità. Viene visualizzata la pagina Accesso in modifica.
Fai clic su Aggiungi un altro ruolo e seleziona Visualizzatore Remote Config.
Fai clic su Aggiungi un altro ruolo e seleziona sviluppatore di piattaforma AI.
Fai clic su Aggiungi un altro ruolo e seleziona Utente Agent Platform.
Fai clic su Aggiungi un altro ruolo e seleziona Cloud Run Invoker.
Fai clic su Salva.

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

Nella console Google Cloud, apri la pagina Credenziali.
Fai clic sul service account Admin SDK per aprire la pagina Dettagli.
Fai clic su Chiavi.
Fai clic su Aggiungi chiave > Crea nuova chiave.
Assicurati che sia selezionato JSON come Tipo di chiave, quindi fai clic su Crea.
Scarica la chiave in un luogo sicuro sul tuo computer.

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 Agent Platform Gemini API (formerly Vertex AI), configura i parametri predefiniti utilizzando Remote Config, recupera gli ultimi parametri Remote Config, elabora l'input dell'utente e trasmette una risposta all'utente.

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

Elimina i contenuti esistenti, quindi aggiungi l'SDK Admin SDK, Remote Config e Agent Platform e inizializza l'app incollando il seguente codice nel file:

const { onRequest } = require("firebase-functions/https");
const { requiresRole, requiresAPI } = require("firebase-functions");
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");

requiresRole("roles/aiplatform.user");
requiresRole("roles/cloudconfig.viewer");
requiresAPI("aiplatform.googleapis.com", "Needed to query Vertex AI Gemini models");
requiresAPI("firebaseremoteconfig.googleapis.com", "Needed to fetch server-side Remote Config templates");

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

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

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 Client Node.js di Vertex AI.

Facoltativamente, puoi anche configurare un parametro per controllare se accedi o meno a Agent Platform Gemini API (formerly Vertex AI) (in questo esempio, un parametro denominato vertex_enabled). Questa configurazione può essere utile durante il test della funzione. Negli snippet di codice seguenti, questo valore è impostato su false, il che eviterà l'utilizzo di Agent Platform durante il test del deployment della funzione di base. Se lo imposti su true, verrà richiamato Agent Platform Gemini API (formerly Vertex AI).
```
// 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
```

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

Configura Agent Platform 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

Salva e chiudi il file.

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

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:

Nella console Firebase, vai a DevOps e coinvolgimento > Remote Config.
Dal selettore Client/Server nella parte superiore della pagina, seleziona Server.
- Se è la prima volta che utilizzi Remote Config o i modelli di 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 di server Remote Config, fai clic su Aggiungi parametro.

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-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 Agent Platform	JSON	`[{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]`
`location`	Località in cui eseguire il servizio e il modello Agent Platform	Stringa	`global`
`is_vertex_enabled`	Parametro facoltativo che controlla se le query vengono inviate a Agent Platform.	Booleano	`true`

Dopo aver aggiunto i parametri, controllali e verifica 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.

Assicurati di aver impostato GOOGLE_APPLICATION_CREDENTIALS come variabile di ambiente, come descritto in Passaggio 3: configura le autorizzazioni IAM per il tuo service account 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
```
Suggerimento: puoi anche eseguire le funzioni nell'emulatore eseguendo npm run serve dalla directory functions.
Apri la pagina dei log dell'emulatore. Dovresti vedere che la funzione è stata caricata.
Accedi alla funzione eseguendo questo 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
```
Suggerimento: questo link verrà visualizzato anche nell'output della console dopo l'avvio dell'emulatore. Puoi anche tagliarlo e incollarlo in un browser.
Attendi una risposta, quindi torna alla pagina dei log di Firebase Emulator o alla console e controlla se sono presenti errori o avvisi.
Prova a inviare un input utente, tenendo presente che, poiché is_vertex_enabled è configurato nel tuo modello di server Remote Config, questo dovrebbe accedere al modello Gemini tramite Agent Platform Gemini API (formerly Vertex AI) e che ciò potrebbe comportare addebiti:
```
curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
```
Apporta modifiche al modello di server Remote Config nella console Firebase, quindi accedi nuovamente alla funzione per osservare le modifiche.

Passaggio 7: esegui il deployment della funzione in Google Cloud

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

esegui il deployment della funzione

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

firebase deploy --only functions

Blocca l'accesso non autenticato alla funzione

Quando viene eseguito il deployment delle funzioni utilizzando Firebase, le chiamate non autenticate sono consentite per impostazione predefinita se la policy della tua organizzazione non lo 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:

Nella console Google Cloud, apri Cloud Run.
Fai clic su generateWithVertex, quindi sulla scheda Sicurezza.
Attiva Richiedi autenticazione e poi fai clic su Salva.

Configura il tuo account utente in modo che utilizzi le credenziali del service account Admin SDK

Poiché il service account Admin SDK dispone di tutti i ruoli e le autorizzazioni necessari per eseguire la funzione e interagire con Remote Config e Agent Platform Gemini API (formerly Vertex AI), 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 per l'esecuzione con i privilegi del service account Admin SDK.

Nella console Google Cloud, abilita l'API Service Account Credentials IAM.
Concedi al tuo account utente il ruolo Creatore token account di servizio: dalla console Google Cloud, apri IAM e amministrazione > IAM, seleziona il tuo account utente, quindi fai clic su Modifica entità > Aggiungi un altro ruolo.
Seleziona Creatore token account di servizio, 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 di Google Cloud.
Apri la pagina della console Google Cloud Cloud Functions e fai clic sulla funzione generateWithVertex nell'elenco Functions.
Seleziona Trigger > Modifica ed espandi Impostazioni di runtime, build, connessioni e sicurezza.
Nella scheda Runtime, cambia il Service account di runtime in Account SDK Admin.
Fai clic su Avanti, quindi su Esegui il deployment.

Configura gcloud CLI

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

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

Se non è già installata sul tuo computer, installa gcloud CLI come descritto in Installa gcloud CLI.
Ottieni le credenziali di accesso per il tuo account Google Cloud:
```
gcloud auth login
```
Imposta l'ID progetto in gcloud:
```
gcloud config set project PROJECT_ID
```

Testa la funzione

Ora puoi testare la tua 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 di server Remote Config, pubblicarle e testare diverse opzioni.

Passaggi successivi

Firebase consiglia di utilizzare App Check per proteggere Cloud Functions. Per saperne di più su come proteggere la tua funzione con App Check, consulta Abilita l'applicazione di App Check per Cloud Functions
Prova una funzione richiamabile di esempio con Remote Config e App Check lato server in Chiama Agent Platform Gemini API (formerly Vertex AI) con Remote Config e App Check.
Scopri di più su Cloud Functions per Firebase.
Scopri di più sull'utilizzo di Remote Config negli ambienti server.