Tecniche di osservabilità pratiche per l'applicazione dell'IA generativa in JavaScript

1. Panoramica

Le applicazioni di AI generativa richiedono l'osservabilità come qualsiasi altra. Esistono tecniche di osservabilità speciali richieste per l'IA generativa?

In questo lab creerai una semplice applicazione di IA generativa. Esegui il deployment in Cloud Run. e strumentalo con funzionalità essenziali di monitoraggio e logging utilizzando i servizi e i prodotti di osservabilità di Google Cloud.

Cosa imparerai a fare

  • Scrivi un'applicazione che utilizza Vertex AI con l'editor di Cloud Shell
  • Archivia il codice dell'applicazione in GitHub
  • Utilizza la CLI gcloud per eseguire il deployment del codice sorgente dell'applicazione in Cloud Run
  • Aggiungere funzionalità di monitoraggio e logging all'applicazione di AI generativa
  • Utilizzo delle metriche basate su log
  • Implementazione di logging e monitoraggio con l'SDK OpenTelemetry
  • Ottenere approfondimenti sulla gestione dei dati dell'AI responsabile

2. Prerequisiti

Se non hai ancora un Account Google, devi crearne uno nuovo.

3. Configurazione del progetto

  1. Accedi alla console Google Cloud con il tuo Account Google.
  2. Crea un nuovo progetto o scegli di riutilizzarne uno esistente. Annota l'ID progetto del progetto che hai appena creato o selezionato.
  3. Abilita la fatturazione per il progetto.
    • Il completamento di questo lab dovrebbe costare meno di 5 $in costi di fatturazione.
    • Per evitare ulteriori addebiti, puoi seguire i passaggi alla fine di questo lab per eliminare le risorse.
    • I nuovi utenti hanno diritto alla prova senza costi di 300$.
  4. Verifica che la fatturazione sia abilitata in I miei progetti nella fatturazione Cloud
    • Se nel nuovo progetto viene visualizzato Billing is disabled nella colonna Billing account:
      1. Fai clic sui tre puntini nella colonna Actions.
      2. Fai clic su Modifica fatturazione.
      3. Seleziona l'account di fatturazione che vuoi utilizzare.
    • Se partecipi a un evento dal vivo, è probabile che l'account si chiami Account di fatturazione di prova di Google Cloud Platform.

4. Prepara l'editor di Cloud Shell

  1. Vai all'editor di Cloud Shell. Se viene visualizzato il seguente messaggio, che richiede di autorizzare Cloud Shell a chiamare gcloud con le tue credenziali, fai clic su Autorizza per continuare.
    Fai clic per autorizzare Cloud Shell
  2. Apri la finestra del terminale
    1. Fai clic sul menu a tre linee Icona del menu di navigazione.
    2. Fai clic su Terminale.
    3. Fai clic su Nuovo terminale
      Apri un nuovo terminale nell'editor di Cloud Shell.
  3. Nel terminale, configura l'ID progetto:
    gcloud config set project [PROJECT_ID]
    Sostituisci [PROJECT_ID] con l'ID del tuo progetto. Ad esempio, se l'ID progetto è lab-example-project, il comando sarà:
    gcloud config set project lab-project-id-example
    Se viene visualizzato il seguente messaggio, che indica che gcloud sta richiedendo le tue credenziali per l'API Google Cloud, fai clic su Autorizza per continuare.
    Fai clic per autorizzare Cloud Shell
    Se l'esecuzione va a buon fine, viene visualizzato il seguente messaggio:
    Updated property [core/project].
    Se visualizzi un WARNING e ti viene chiesto Do you want to continue (Y/N)?, probabilmente hai inserito l'ID progetto in modo errato. Premi N, premi Enter e prova a eseguire di nuovo il comando gcloud config set project dopo aver trovato l'ID progetto corretto.
  4. (Facoltativo) Se hai difficoltà a trovare l'ID progetto, esegui questo comando per visualizzare l'ID progetto di tutti i tuoi progetti ordinati in base all'ora di creazione in ordine decrescente:
    gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime

5. Abilita le API di Google

Nel terminale, abilita le API di Google richieste per questo lab:

gcloud services enable \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     aiplatform.googleapis.com \
     logging.googleapis.com \
     monitoring.googleapis.com \
     cloudtrace.googleapis.com

Il completamento di questo comando richiederà del tempo. Alla fine, viene visualizzato un messaggio di operazione riuscita simile a questo:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

Se ricevi un messaggio di errore che inizia con ERROR: (gcloud.services.enable) HttpError accessing e contiene dettagli dell'errore come di seguito, riprova a eseguire il comando dopo un ritardo di 1-2 minuti.

"error": {
  "code": 429,
  "message": "Quota exceeded for quota metric 'Mutate requests' and limit 'Mutate requests per minute' of service 'serviceusage.googleapis.com' ...",
  "status": "RESOURCE_EXHAUSTED",
  ...
}

6. Crea un'applicazione Node.js di AI generativa

In questo passaggio scriverai il codice della semplice applicazione basata su richieste che utilizza il modello Gemini per mostrare 10 curiosità su un animale a tua scelta. Per creare il codice dell'applicazione, segui questi passaggi.

  1. Nel terminale, crea la directory codelab-o11y:
    mkdir ~/codelab-o11y
  2. Cambia la directory corrente in codelab-o11y:
    cd ~/codelab-o11y
  3. Inizializza package.json dell'applicazione Node.js:
    npm init -y
  4. Installa il pacchetto fastify:
    npm install fastify
  5. Installa i pacchetti Cloud SDK per l'autenticazione e per lavorare con Vertex AI:
    npm install google-auth-library @google-cloud/vertexai
  6. Crea un file index.js e aprilo nell'editor di Cloud Shell:
    cloudshell edit index.js
    Ora dovrebbe essere visualizzato un file vuoto nella finestra dell'editor sopra il terminale. La schermata sarà simile alla seguente:
    Mostra l'editor di Cloud Shell dopo aver iniziato a modificare main.go
  7. Copia il seguente codice e incollalo nel file index.js aperto:
    const { VertexAI } = require('@google-cloud/vertexai');
const { GoogleAuth } = require('google-auth-library');

let generativeModel;
const auth = new GoogleAuth();
auth.getProjectId().then(result => {
  const vertex = new VertexAI({ project: result });
  generativeModel = vertex.getGenerativeModel({
      model: 'gemini-1.5-flash'
  });
});

const fastify = require('fastify')();
const PORT = parseInt(process.env.PORT || '8080');

fastify.get('/', async function (request, reply) {
  const animal = request.query.animal || 'dog';
  const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
  const resp = await generativeModel.generateContent(prompt);
  const html = resp.response.candidates[0].content.parts[0].text;
  reply.type('text/html').send(html);
})

fastify.listen({ host: '0.0.0.0', port: PORT }, function (err, address) {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`codelab-genai: listening on ${address}`);
})
    Dopo alcuni secondi, Cloud Shell Editor salverà automaticamente il codice.

Esegui il deployment del codice dell'applicazione di AI generativa in Cloud Run

  1. Nella finestra del terminale, esegui il comando per eseguire il deployment del codice sorgente dell'applicazione su Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se vedi il prompt come di seguito, che ti informa che il comando creerà un nuovo repository. Fai clic su Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    Il processo di deployment potrebbe richiedere alcuni minuti. Al termine del processo di deployment, vedrai un output simile al seguente:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. Copia l'URL del servizio Cloud Run visualizzato in una scheda o finestra separata del browser. In alternativa, esegui questo comando nel terminale per stampare l'URL del servizio e fai clic sull'URL visualizzato tenendo premuto il tasto Ctrl per aprire l'URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando viene aperto l'URL, potresti ricevere l'errore 500 o visualizzare il messaggio:
    Sorry, this is just a placeholder...
    Significa che i servizi non hanno completato il deployment. Attendi qualche istante e aggiorna la pagina. Alla fine vedrai un testo che inizia con Curiosità sui cani e contiene 10 curiosità sui cani.

Prova a interagire con l'applicazione per scoprire curiosità su diversi animali. Per farlo, aggiungi il parametro animal all'URL, ad esempio ?animal=[ANIMAL], dove [ANIMAL] è il nome di un animale. Ad esempio, aggiungi ?animal=cat per ricevere 10 curiosità sui gatti o ?animal=sea turtle per ricevere 10 curiosità sulle tartarughe marine.

7. Controlla le tue chiamate all'API Vertex

Il controllo delle chiamate API di Google fornisce risposte a domande come "Chi ha chiamato una determinata API, dove e quando?". L'audit è importante quando risolvi i problemi dell'applicazione, esamini il consumo di risorse o esegui l'analisi forense del software.

Gli audit log ti consentono di monitorare le attività amministrative e di sistema, nonché di registrare le chiamate alle operazioni API "lettura dati" e "scrittura dati". Per controllare le richieste di Vertex AI per generare contenuti, devi abilitare gli audit log "Lettura dati" nella console Google Cloud.

  1. Fai clic sul pulsante qui sotto per aprire la pagina Log di controllo nella console Cloud

  2. Assicurati che nella pagina sia selezionato il progetto che hai creato per questo lab. Il progetto selezionato viene visualizzato nell'angolo in alto a sinistra della pagina, subito dopo il menu hamburger:
    Menu a discesa del progetto della console Google Cloud
    Se necessario, seleziona il progetto corretto dalla casella combinata.
  3. Nella tabella Configurazione degli audit log di accesso ai dati, individua il servizio Vertex AI API nella colonna Servizio e selezionalo selezionando la casella di controllo a sinistra del nome del servizio.
    Seleziona l'API Vertex AI
  4. Nel riquadro delle informazioni a destra, seleziona il tipo di audit "Lettura dati".
    Controllare i log di lettura dei dati
  5. Fai clic su Salva.

Per generare audit log, apri l'URL del servizio. Aggiorna la pagina mentre modifichi il valore del parametro ?animal= per ottenere risultati diversi.

Esplora gli audit log

  1. Fai clic sul pulsante qui sotto per aprire la pagina Esplora log nella console Cloud:

  2. Incolla il seguente filtro nel riquadro Query.
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
    Il riquadro Query è un editor che si trova nella parte superiore della pagina Esplora log:
    Eseguire query sugli audit log
  3. Fai clic su Esegui query.
  4. Seleziona una delle voci del log di controllo ed espandi i campi per esaminare le informazioni acquisite nel log.
    Puoi visualizzare i dettagli della chiamata API Vertex, inclusi il metodo e il modello utilizzati. Puoi anche vedere l'identità del chiamante e quali autorizzazioni hanno autorizzato la chiamata.

8. Registrare le interazioni con l'AI generativa

Nei log di controllo non trovi i parametri della richiesta API o i dati di risposta. Tuttavia, queste informazioni possono essere importanti per la risoluzione dei problemi relativi all'analisi di applicazioni e flussi di lavoro. In questo passaggio colmiamo questa lacuna aggiungendo la registrazione delle applicazioni. Il logging utilizza il metodo di logging standard di NodeJS console.log per scrivere log strutturati nell'output standard. Questo metodo include la capacità di Cloud Run di acquisire le informazioni stampate nell'output standard e di importarle automaticamente in Cloud Logging. Per acquisire correttamente i log strutturati, il log stampato deve essere formattato di conseguenza. Segui le istruzioni riportate di seguito per aggiungere funzionalità di logging strutturato alla nostra applicazione NodeJS.

  1. Torna alla finestra (o scheda) "Cloud Shell" nel browser.
  2. Nel terminale, riapri index.js:
    cloudshell edit ~/codelab-o11y/index.js
  3. Per registrare la risposta del modello, segui questi passaggi:
    1. Trova la chiamata a await generativeModel.generateContent() (alla riga 20).
    2. Copia e incolla il codice riportato di seguito all'inizio della riga successiva.
        console.log(JSON.stringify({
      severity: 'DEBUG',
      message: 'Content is generated',
      animal: animal,
      prompt: prompt,
      response: resp.response,
  }));

La funzione di gestione viene modificata per chiamare console.log() per stampare la struttura JSON il cui schema segue le linee guida per la formattazione strutturata. Il log acquisisce il parametro dell'animale della richiesta, il prompt e la risposta del modello.

Dopo alcuni secondi, Cloud Shell Editor salva automaticamente le modifiche.

Esegui il deployment del codice dell'applicazione di AI generativa in Cloud Run

  1. Nella finestra del terminale, esegui il comando per eseguire il deployment del codice sorgente dell'applicazione su Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se vedi il prompt come di seguito, che ti informa che il comando creerà un nuovo repository. Fai clic su Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    Il processo di deployment potrebbe richiedere alcuni minuti. Al termine del processo di deployment, vedrai un output simile al seguente:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. Copia l'URL del servizio Cloud Run visualizzato in una scheda o finestra separata del browser. In alternativa, esegui questo comando nel terminale per stampare l'URL del servizio e fai clic sull'URL visualizzato tenendo premuto il tasto Ctrl per aprire l'URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando viene aperto l'URL, potresti ricevere l'errore 500 o visualizzare il messaggio:
    Sorry, this is just a placeholder...
    Significa che i servizi non hanno completato il deployment. Attendi qualche istante e aggiorna la pagina. Alla fine vedrai un testo che inizia con Curiosità sui cani e contiene 10 curiosità sui cani.

Per generare i log dell'applicazione, apri l'URL del servizio. Aggiorna la pagina mentre modifichi il valore del parametro ?animal= per ottenere risultati diversi.
Per visualizzare i log dell'applicazione:

  1. Fai clic sul pulsante qui sotto per aprire la pagina Esplora log nella console Cloud:

  2. Incolla il seguente filtro nel riquadro Query (n. 2 nell'interfaccia di Esplora log):
    LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
  3. Fai clic su Esegui query.

Il risultato della query mostra i log con il prompt e la risposta di Vertex AI, incluse le valutazioni di sicurezza.

9. Conteggio delle interazioni con l'AI generativa

Cloud Run scrive metriche gestite che possono essere utilizzate per monitorare i servizi di cui è stato eseguito il deployment. Le metriche di monitoraggio gestite dall'utente offrono un maggiore controllo sui dati e sulla frequenza di aggiornamento delle metriche. Per implementare questa metrica è necessario scrivere un codice che raccolga i dati e li scriva in Cloud Monitoring. Consulta il passaggio successivo (facoltativo) per scoprire come implementarlo utilizzando l'SDK OpenTelemetry.

Questo passaggio mostra un'alternativa all'implementazione della metrica utente nel codice: le metriche basate sui log. Le metriche basate su log ti consentono di generare metriche di monitoraggio dalle voci di log che la tua applicazione scrive in Cloud Logging. Utilizzeremo i log dell'applicazione implementati nel passaggio precedente per definire una metrica basata sui log del tipo counter. La metrica conteggerà il numero di chiamate riuscite all'API Vertex.

  1. Guarda la finestra di Esplora log che abbiamo utilizzato nel passaggio precedente. Nel riquadro Query, individua il menu a discesa Azioni e fai clic per aprirlo. Per trovare il menu, consulta lo screenshot riportato di seguito:
    Barra degli strumenti dei risultati della query con il menu a discesa Azioni
  2. Nel menu aperto, seleziona Crea metrica per aprire il riquadro Crea metrica basata su log.
  3. Per configurare una nuova metrica di conteggio nel riquadro Crea metrica basata su log:
    1. Imposta il Tipo di metrica: seleziona Contatore.
    2. Imposta i seguenti campi nella sezione Dettagli:
      • Nome metrica di log: imposta il nome su model_interaction_count. Si applicano alcune limitazioni alla denominazione. Per maggiori dettagli, consulta la sezione Risoluzione dei problemi.
      • Descrizione: inserisci una descrizione per la metrica. Ad esempio, Number of log entries capturing successful call to model inference.
      • Unità: lascia vuoto questo campo o inserisci la cifra 1.
    3. Lascia i valori nella sezione Selezione filtri. Tieni presente che il campo Crea filtro contiene lo stesso filtro che abbiamo utilizzato per visualizzare i log delle applicazioni.
    4. (Facoltativo) Aggiungi un'etichetta che ti aiuti a conteggiare il numero di chiamate per ogni animale. NOTA: questa etichetta ha il potenziale di aumentare notevolmente la cardinalità della metrica e non è consigliata per l'utilizzo in produzione:
      1. Fai clic su Aggiungi etichetta.
      2. Imposta i seguenti campi nella sezione Etichette:
        • Nome etichetta: imposta il nome su animal.
        • Descrizione: inserisci la descrizione dell'etichetta. Ad esempio, Animal parameter.
        • Tipo di etichetta: seleziona STRING.
        • Nome campo: tipo jsonPayload.animal.
        • Espressione regolare: lascia vuoto.
      3. Fai clic su Fine.
    5. Fai clic su Crea metrica per creare la metrica.

Puoi anche creare una metrica basata su log dalla pagina Metriche basate su log utilizzando il comando CLI gcloud logging metrics create o la risorsa Terraform google_logging_metric.

Per generare i dati delle metriche, apri l'URL del servizio. Aggiorna la pagina aperta più volte per effettuare più chiamate al modello. Come prima, prova a utilizzare animali diversi nel parametro.

Inserisci la query PromQL per cercare i dati delle metriche basate su log. Per inserire una query PromQL:

  1. Fai clic sul pulsante qui sotto per aprire la pagina Esplora metriche nella console Cloud:

  2. Nella barra degli strumenti del riquadro del generatore di query, seleziona il pulsante il cui nome è < > MQL o < > PromQL. Per la posizione del pulsante, vedi l'immagine di seguito.
    Posizione del pulsante MQL in Esplora metriche
  3. Verifica che PromQL sia selezionato nel pulsante di attivazione/disattivazione Lingua. Il pulsante di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che ti consente di formattare la query.
  4. Inserisci la query nell'editor Query:
    sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
    Per ulteriori informazioni sull'utilizzo di PromQL, consulta PromQL in Cloud Monitoring.
  5. Fai clic su Esegui query. Vedrai un grafico a linee simile a questo screenshot:
    Mostra le metriche sottoposte a query

    Tieni presente che quando l'opzione di attivazione/disattivazione Esecuzione automatica è attiva, il pulsante Esegui query non viene visualizzato.

10. (Facoltativo) Utilizza OpenTelemetry per il monitoraggio e la tracciabilità

Come indicato nel passaggio precedente, è possibile implementare le metriche utilizzando l'SDK OpenTelemetry (Otel). L'utilizzo di OTel nelle architetture basate su microservizi è una pratica consigliata. Questo passaggio descrive quanto segue:

  • Inizializzazione dei componenti OTel per supportare il tracciamento e il monitoraggio dell'applicazione
  • Compilazione della configurazione OTel con i metadati delle risorse dell'ambiente Cloud Run
  • Instrumentazione dell'applicazione Flask con funzionalità di tracciamento automatico
  • Implementazione di una metrica di conteggio per monitorare il numero di chiamate al modello riuscite
  • Correlare la tracciabilità con i log delle applicazioni

L'architettura consigliata per i servizi a livello di prodotto prevede l'utilizzo del raccoglitore OTel per raccogliere e importare tutti i dati di osservabilità per uno o più servizi. Il codice in questo passaggio non utilizza il raccoglitore per semplicità. Utilizza invece le esportazioni OTel che scrivono i dati direttamente su Google Cloud.

Configura i componenti OTel per il monitoraggio di tracciamento e metriche

  1. Torna alla finestra (o scheda) "Cloud Shell" nel browser.
  2. Installa i pacchetti necessari per utilizzare la strumentazione automatica OpenTelemetry:
    npm install @opentelemetry/sdk-node \
  @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/instrumentation-express \
  @opentelemetry/instrumentation-http \
  @opentelemetry/sdk-metrics \
  @opentelemetry/sdk-trace-node \
  @google-cloud/opentelemetry-cloud-trace-exporter \
  @google-cloud/opentelemetry-cloud-monitoring-exporter \
  @google-cloud/opentelemetry-resource-util
  3. Nel terminale, crea un nuovo file setup.js:
    cloudshell edit ~/codelab-o11y/setup.js
  4. Copia e incolla il seguente codice nell'editor per configurare il monitoraggio e la tracciabilità di OpenTelemetry.
    const opentelemetry = require("@opentelemetry/api");
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { MeterProvider, PeriodicExportingMetricReader } = require("@opentelemetry/sdk-metrics");
const { AlwaysOnSampler, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { Resource } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');
const { FastifyInstrumentation } = require('@opentelemetry/instrumentation-fastify');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { TraceExporter } = require("@google-cloud/opentelemetry-cloud-trace-exporter");
const { MetricExporter } = require("@google-cloud/opentelemetry-cloud-monitoring-exporter");
const { GcpDetectorSync } = require("@google-cloud/opentelemetry-resource-util");

module.exports = { setupTelemetry };

function setupTelemetry() {
  const gcpResource = new Resource({
    [ATTR_SERVICE_NAME]: process.env.K_SERVICE,
  }).merge(new GcpDetectorSync().detect())

  const tracerProvider = new NodeTracerProvider({
    resource: gcpResource,
    sampler: new AlwaysOnSampler(),
    spanProcessors: [new SimpleSpanProcessor(new TraceExporter({
      // will export all resource attributes that start with "service."
      resourceFilter: /^service\./
    }))],
  });
  registerInstrumentations({
    tracerProvider: tracerProvider,
    instrumentations: [
      // Express instrumentation expects HTTP layer to be instrumented
      new HttpInstrumentation(),
      new FastifyInstrumentation(),
    ],
  });
  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
  tracerProvider.register();

  const meterProvider = new MeterProvider({
    resource: gcpResource,
    readers: [new PeriodicExportingMetricReader({
      // Export metrics every second (default quota is 30,000 time series ingestion requests per minute)
      exportIntervalMillis: 1_000,
      exporter: new MetricExporter(),
    })],
  });
  opentelemetry.metrics.setGlobalMeterProvider(meterProvider);
}
  5. Torna al terminale e riapri index.js:
    cloudshell edit ~/codelab-o11y/index.js
  6. Sostituisci il codice con la versione che inizializza la raccolta di tracce e metriche OpenTelemetry e aggiorna anche il contatore delle prestazioni a ogni esecuzione riuscita. Per aggiornare il codice, elimina i contenuti del file, quindi copia e incolla il codice riportato di seguito:
    const { VertexAI } = require('@google-cloud/vertexai');
const { GoogleAuth } = require('google-auth-library');

let generativeModel, traceIdPrefix;
const auth = new GoogleAuth();
auth.getProjectId().then(result => {
  const vertex = new VertexAI({ project: result });
  generativeModel = vertex.getGenerativeModel({
        model: 'gemini-1.5-flash'
  });
  traceIdPrefix = `projects/${result}/traces/`;
});

// setup tracing and monitoring OTel providers
const { setupTelemetry }= require('./setup');
setupTelemetry();

const { trace, context } = require('@opentelemetry/api');
function getCurrentSpan() {
  const current_span = trace.getSpan(context.active());
  return {
      trace_id: current_span.spanContext().traceId,
      span_id: current_span.spanContext().spanId,
      flags: current_span.spanContext().traceFlags
  };
};

const opentelemetry = require("@opentelemetry/api");
const meter = opentelemetry.metrics.getMeter("genai-o11y/nodejs/workshop/example");
const counter = meter.createCounter("model_call_counter");

const fastify = require('fastify')();
const PORT = parseInt(process.env.PORT || '8080');

fastify.get('/', async function (request, reply) {
  const animal = request.query.animal || 'dog';
  const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
  const resp = await generativeModel.generateContent(prompt)
  const span = getCurrentSpan();
  console.log(JSON.stringify({
      severity: 'DEBUG',
      message: 'Content is generated',
      animal: animal,
      prompt: prompt,
      response: resp.response,
      "logging.googleapis.com/trace": traceIdPrefix + span.trace_id,
      "logging.googleapis.com/spanId": span.span_id,
  }));
  counter.add(1, { animal: animal });
  const html = resp.response.candidates[0].content.parts[0].text;
  reply.type('text/html').send(html);
});

fastify.listen({ host: '0.0.0.0', port: PORT }, function (err, address) {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`codelab-genai: listening on ${address}`);
});

L'applicazione ora utilizza l'SDK OpenTelemetry per instrumentare l'esecuzione del codice con la tracciabilità e per implementare il conteggio di un numero di esecuzioni riuscite come metrica. Il metodo main() viene modificato per configurare gli esportatori OpenTelemetry per tracce e metriche da scrivere direttamente in Google Cloud Tracing e Monitoring. Esegue anche configurazioni aggiuntive per popolare le tracce e le metriche raccolte con i metadati relativi all'ambiente Cloud Run. La funzione Handler() viene aggiornata per incrementare il contatore delle metriche ogni volta che la chiamata all'API Vertex AI restituisce risultati validi.

Dopo alcuni secondi, Cloud Shell Editor salva automaticamente le modifiche.

Esegui il deployment del codice dell'applicazione di AI generativa in Cloud Run

  1. Nella finestra del terminale, esegui il comando per eseguire il deployment del codice sorgente dell'applicazione su Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se vedi il prompt come di seguito, che ti informa che il comando creerà un nuovo repository. Fai clic su Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    Il processo di deployment potrebbe richiedere alcuni minuti. Al termine del processo di deployment, vedrai un output simile al seguente:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. Copia l'URL del servizio Cloud Run visualizzato in una scheda o finestra separata del browser. In alternativa, esegui questo comando nel terminale per stampare l'URL del servizio e fai clic sull'URL visualizzato tenendo premuto il tasto Ctrl per aprire l'URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando viene aperto l'URL, potresti ricevere l'errore 500 o visualizzare il messaggio:
    Sorry, this is just a placeholder...
    Significa che i servizi non hanno completato il deployment. Attendi qualche istante e aggiorna la pagina. Alla fine vedrai un testo che inizia con Curiosità sui cani e contiene 10 curiosità sui cani.

Per generare dati di telemetria, apri l'URL del servizio. Aggiorna la pagina mentre modifichi il valore del parametro ?animal= per ottenere risultati diversi.

Esplora le tracce dell'applicazione

  1. Fai clic sul pulsante qui sotto per aprire la pagina Esplora tracce nella console Cloud:

  2. Seleziona una delle tracce più recenti. Dovresti vedere 5 o 6 intervalli simili a quelli dello screenshot riportato di seguito.
    Visualizzazione dell&#39;intervallo dell&#39;app in Esplora tracce
  3. Trova lo span che traccia la chiamata al gestore eventi (il metodo fun_facts). Sarà l'ultimo intervallo con il nome /.
  4. Nel riquadro Dettagli traccia, seleziona Log ed eventi. Verranno visualizzati i log delle applicazioni correlati a questo intervallo specifico. La correlazione viene rilevata utilizzando gli ID traccia e span nella traccia e nel log. Dovresti visualizzare il log dell'applicazione che ha scritto il prompt e la risposta dell'API Vertex.

Esplora la metrica del contatore

  1. Fai clic sul pulsante qui sotto per aprire la pagina Esplora metriche nella console Cloud:

  2. Nella barra degli strumenti del riquadro del generatore di query, seleziona il pulsante il cui nome è < > MQL o < > PromQL. Per la posizione del pulsante, vedi l'immagine di seguito.
    Posizione del pulsante MQL in Esplora metriche
  3. Verifica che PromQL sia selezionato nel pulsante di attivazione/disattivazione Lingua. Il pulsante di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che ti consente di formattare la query.
  4. Inserisci la query nell'editor Query:
    sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
  5. Fai clic su Esegui query.Quando l'opzione di attivazione/disattivazione Esecuzione automatica è attiva, il pulsante Esegui query non viene visualizzato.

11. (Facoltativo) Informazioni sensibili offuscate dai log

Nel passaggio 10 abbiamo registrato informazioni sull'interazione dell'applicazione con il modello Gemini. Queste informazioni includevano il nome dell'animale, il prompt effettivo e la risposta del modello. Sebbene la memorizzazione di queste informazioni nel log sia sicura, non è necessariamente vero per molti altri scenari. Il prompt potrebbe includere alcune informazioni personali o sensibili che un utente non vuole che vengano memorizzate. Per risolvere il problema, puoi offuscare i dati sensibili scritti in Cloud Logging. Per ridurre al minimo le modifiche al codice, ti consigliamo la seguente soluzione.

  1. Crea un argomento Pub/Sub per archiviare le voci di log in entrata
  2. Crea un sink di log che reindirizza i log importati all'argomento Pub/Sub.
  3. Crea una pipeline Dataflow che modifichi i log reindirizzati all'argomento Pub/Sub seguendo questi passaggi:
    1. Leggi una voce di log dall'argomento Pub/Sub
    2. Ispeziona il payload della voce per individuare informazioni sensibili utilizzando l'API DLP Inspection
    3. Oscura le informazioni sensibili nel payload utilizzando uno dei metodi di oscuramento DLP.
    4. Scrivi la voce di log offuscata in Cloud Logging
  4. Esegui il deployment della pipeline

12. (Facoltativo) Pulizia

Per evitare il rischio di incorrere in addebiti per le risorse e le API utilizzate nel codelab, è consigliabile eseguire la pulizia al termine del lab. Il modo più semplice per eliminare la fatturazione è eliminare il progetto creato per il codelab.

  1. Per eliminare il progetto, esegui il comando di eliminazione del progetto nel terminale:
    PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet
    L'eliminazione del progetto Cloud interrompe la fatturazione per tutte le risorse e le API utilizzate al suo interno. Dovresti vedere questo messaggio, dove PROJECT_ID sarà il tuo ID progetto:
    Deleted [https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID].

You can undo this operation for a limited period by running the command below.
    $ gcloud projects undelete PROJECT_ID

See https://cloud.google.com/resource-manager/docs/creating-managing-projects for information on shutting down projects.
  2. (Facoltativo) Se ricevi un errore, consulta il passaggio 5 per trovare l'ID progetto che hai utilizzato durante il lab. Sostituiscilo al comando nella prima istruzione. Ad esempio, se l'ID progetto è lab-example-project, il comando sarà:
    gcloud projects delete lab-project-id-example --quiet

13. Complimenti

In questo lab hai creato un'applicazione di AI generativa che utilizza il modello Gemini per fare previsioni. e ha instrumentato l'applicazione con funzionalità essenziali di monitoraggio e logging. Hai eseguito il deployment dell'applicazione e delle modifiche dal codice sorgente a Cloud Run. Poi, utilizza i prodotti Google Cloud Observability per monitorare le prestazioni dell'applicazione, in modo da garantirne l'affidabilità.

Se ti interessa partecipare a uno studio di ricerca sull'esperienza utente (UX) per migliorare i prodotti che hai utilizzato oggi, registrati qui.

Ecco alcune opzioni per continuare a imparare: