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. Sono necessarie tecniche di osservabilità speciali per l'IA generativa?

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

Cosa imparerai a fare

  • Scrivere un'applicazione che utilizza Vertex AI con l'editor di Cloud Shell
  • Memorizza il codice dell'applicazione su GitHub
  • Utilizza gcloud CLI 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 Open Telemetry
  • Ottieni informazioni sulla gestione dei dati dell'IA responsabile

2. Prerequisiti

Se non hai già 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 riutilizzare un progetto esistente. Prendi nota dell'ID progetto che hai appena creato o selezionato.
  3. Attiva la fatturazione per il progetto.
    • Il completamento di questo lab dovrebbe costare meno di 5 $in costi di fatturazione.
    • Per eliminare le risorse ed evitare ulteriori addebiti, puoi seguire i passaggi alla fine di questo lab.
    • I nuovi utenti sono idonei per la prova senza costi di 300$.
  4. Verifica che la fatturazione sia attivata in I miei progetti in Fatturazione Cloud.
    • Se nel nuovo progetto è presente 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, l'account probabilmente si chiamerà Account di fatturazione di prova della piattaforma Google Cloud

4. Prepara l'editor di Cloud Shell

  1. Vai a Cloud Shell Editor. 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
      Aprire 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 il tuo 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 richiede le tue credenziali per l'API GCPI, fai clic su Autorizza per continuare.
    Fai clic per autorizzare Cloud Shell
    Al termine dell'esecuzione, dovresti visualizzare il seguente messaggio:
    Updated property [core/project].
    Se vedi un WARNING e ti viene chiesto Do you want to continue (Y/N)?, è probabile che tu abbia 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 il seguente comando per visualizzare l'ID di tutti i tuoi progetti ordinati in ordine decrescente in base alla data di creazione:
    gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime

5. Attivare le API di Google

Nel terminale, abilita le API 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. Dovrebbe essere 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 quelli riportati di seguito, riprova a eseguire il comando dopo 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 di una semplice applicazione basata su richiesta che utilizza il modello Gemini per mostrare 10 curiosità su un animale a tua scelta. Procedi nel seguente modo per creare il codice dell'applicazione.

  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 NodeJS:
    npm init -y
  4. Installa il pacchetto fastify:
    npm install fastify
  5. Installa i pacchetti Cloud SDK per l'autenticazione e il lavoro 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 nella finestra dell'editor sopra il terminale dovrebbe apparire un file vuoto. La schermata sarà simile alla seguente:
    Mostrare 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, l'editor di Cloud Shell salverà automaticamente il codice.

Esegui il deployment del codice dell'applicazione di IA 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 viene visualizzato il prompt come quello riportato di seguito, ti viene comunicato 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, visualizzerai 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 il seguente comando nel terminale per stampare l'URL del servizio e fai clic sull'URL visualizzato tenendo premuto il tasto Ctrl per aprirlo:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando l'URL viene aperto, potresti ricevere un errore 500 o visualizzare il messaggio:
    Sorry, this is just a placeholder...
    Significa che il deployment dei servizi non è stato completato. 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 chiamate all'API Vertex

Il controllo delle chiamate alle API Google fornisce risposte a domande come "Chi chiama una determinata API, dove e quando?". Il controllo è importante per risolvere i problemi dell'applicazione, esaminare il consumo di risorse o eseguire analisi forensi del software.

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

  1. Fai clic sul pulsante di seguito 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, proprio nel menu a tre linee:
    Menu a discesa del progetto nella console Google Cloud
    Se necessario, seleziona il progetto corretto dalla casella combinata.
  3. Nella tabella Configurazione degli audit log di accesso ai dati, nella colonna Servizio, individua il servizio Vertex AI API 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 controllo "Lettura dei dati".
    Controllare i log di lettura dei dati
  5. Fai clic su Salva.

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

Esplorare i log di controllo

  1. Fai clic sul pulsante di seguito 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 situato nella parte superiore della pagina Esplora log:
    Esegui query sui log di controllo
  3. Fai clic su Esegui query.
  4. Seleziona una delle voci del log di controllo ed espandi i campi per ispezionare le informazioni acquisite nel log.
    Puoi visualizzare i dettagli della chiamata all'API Vertex, inclusi il metodo e il modello utilizzati. Puoi anche vedere l'identità dell'autore dell'invocazione e le autorizzazioni che hanno autorizzato la chiamata.

8. Registrare le interazioni con l'IA generativa

Non trovi i parametri di richiesta API o i dati di risposta nei log di controllo. 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 il logging delle applicazioni. Il logging utilizza il metodo di logging standard di NodeJS console.log per scrivere log strutturati nell'output standard. Questo metodo utilizza la funzionalità di Cloud Run per acquisire le informazioni stampate nell'output standard e 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 alla scheda) "Cloud Shell" nel browser.
  2. Nel terminale, riapri index.js:
    cloudshell edit ~/codelab-o11y/index.js
  3. Per registrare la risposta del modello:
    1. Trova la chiamata a await generativeModel.generateContent() (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 gestore 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 animale della richiesta e 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 IA 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 viene visualizzato il prompt come quello riportato di seguito, ti viene comunicato 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, visualizzerai 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 il seguente comando nel terminale per stampare l'URL del servizio e fai clic sull'URL visualizzato tenendo premuto il tasto Ctrl per aprirlo:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando l'URL viene aperto, potresti ricevere un errore 500 o visualizzare il messaggio:
    Sorry, this is just a placeholder...
    Significa che il deployment dei servizi non è stato completato. 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 modificando il valore del parametro ?animal= per ottenere risultati diversi.
Per visualizzare i log dell'applicazione:

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

  2. Incolla il seguente filtro nel riquadro Query (#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. Contare le interazioni con l'IA 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 dell'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 su log. Le metriche basate su log ti consentono di generare metriche di monitoraggio dalle voci di log scritte dall'applicazione in Cloud Logging. Utilizzeremo i log dell'applicazione che abbiamo implementato nel passaggio precedente per definire una metrica basata su log del contatore di tipo. La metrica conteggia il numero di chiamate riuscite all'API Vertex.

  1. Esamina 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. Guarda lo screenshot di seguito per trovare il menu:
    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 contatore 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. Sono previste alcune limitazioni per i nomi. Per informazioni dettagliate, consulta la sezione Risoluzione dei problemi relativa alle limitazioni per i nomi.
      • Descrizione: inserisci una descrizione per la metrica. Ad esempio, Number of log entries capturing successful call to model inference.
      • Unità: lascia vuoto o inserisci la cifra 1.
    3. Lascia i valori nella sezione Selezione filtro. Tieni presente che il campo Filtro di compilazione ha lo stesso filtro utilizzato per visualizzare i log dell'applicazione.
    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: digita 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 di seguito per aprire la pagina Esplora metriche nella console Cloud:

  2. Nella barra degli strumenti del riquadro Query Builder, seleziona il pulsante il cui nome è < > MQL o < > PromQL. Guarda l'immagine di seguito per vedere la posizione del pulsante.
    Posizione del pulsante MQL in Esplora metriche
  3. Verifica che PromQL sia selezionato nell'opzione 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. Viene visualizzato 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 il monitoraggio

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

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

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

Configura i componenti OTel per il monitoraggio delle metriche e del monitoraggio

  1. Torna alla finestra (o alla 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 codice riportato di seguito nell'editor per configurare il monitoraggio e il monitoraggio 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 delle metriche e il monitoraggio di 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}`);
});

Ora l'applicazione utilizza l'SDK OpenTelemetry per instrumentare l'esecuzione del codice con il monitoraggio e per implementare il conteggio di un numero di esecuzioni riuscite come metrica. Il metodo main() viene modificato per configurare gli esportatori OpenTelemetry in modo che le tracce e le metriche vengano scritte direttamente in Monitoraggio e Tracing di Google Cloud. Esegue anche configurazioni aggiuntive per compilare le metriche e le tracce 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 IA 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 viene visualizzato il prompt come quello riportato di seguito, ti viene comunicato 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, visualizzerai 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 il seguente comando nel terminale per stampare l'URL del servizio e fai clic sull'URL visualizzato tenendo premuto il tasto Ctrl per aprirlo:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando l'URL viene aperto, potresti ricevere un errore 500 o visualizzare il messaggio:
    Sorry, this is just a placeholder...
    Significa che il deployment dei servizi non è stato completato. 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 dati di telemetria, apri l'URL del servizio. Aggiorna la pagina modificando il valore del parametro ?animal= per ottenere risultati diversi.

Esplora le tracce dell'applicazione

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

  2. Seleziona una delle tracce più recenti. Dovresti vedere 5 o 6 span simili a quelli nello screenshot di seguito.
    Visualizzazione dell&#39;intervallo dell&#39;app in Esplora traccia
  3. Trova lo spazio che traccia la chiamata al gestore dell'evento (il metodo fun_facts). Sarà l'ultimo span con il nome /.
  4. Nel riquadro Dettagli traccia, seleziona Log ed eventi. Vedrai i log delle applicazioni correlati a questo determinato intervallo. La correlazione viene rilevata utilizzando gli ID traccia e intervallo nella traccia e nel log. Dovresti vedere 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 di seguito per aprire la pagina Esplora metriche nella console Cloud:

  2. Nella barra degli strumenti del riquadro Query Builder, seleziona il pulsante il cui nome è < > MQL o < > PromQL. Guarda l'immagine di seguito per vedere la posizione del pulsante.
    Posizione del pulsante MQL in Esplora metriche
  3. Verifica che PromQL sia selezionato nell'opzione 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 dovrebbe essere sicura, non è necessariamente così per molti altri scenari. La richiesta potrebbe includere alcune informazioni personali o comunque 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, è consigliata la seguente soluzione.

  1. Crea un argomento Pub/Sub per archiviare le voci di log in entrata
  2. Crea un sink di log che reindirizzi 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. Leggere una voce di log dall'argomento PubSub
    2. Controlla il payload della voce per individuare informazioni sensibili utilizzando l'API di ispezione DLP
    3. Oscura le informazioni sensibili nel payload utilizzando uno dei metodi di oscuramento di 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 addebiti per le risorse e le API utilizzate nel codelab, ti consigliamo di eseguire la pulizia al termine del lab. Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai 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à l'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 messaggio di 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 il tuo 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 IA generativa che utilizza il modello Gemini per fare previsioni. e ha strumentato l'applicazione con funzionalità di monitoraggio e logging essenziali. 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 assicurarti della sua affidabilità.

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

Ecco alcune opzioni per continuare a imparare: