Praktische Methoden zur Beobachtbarkeit von Anwendungen mit generativer KI in Python

1. Übersicht

Für Anwendungen mit generativer KI ist wie für alle anderen Anwendungen eine Beobachtbarkeitslösung erforderlich. Sind für generative KI spezielle Observability-Techniken erforderlich?

In diesem Lab erstellen Sie eine einfache Gen AI-Anwendung. Stellen Sie sie in Cloud Run bereit. Außerdem müssen Sie sie mit wichtigen Monitoring- und Logging-Funktionen ausstatten, indem Sie die Observability-Dienste und -Produkte von Google Cloud verwenden.

Lerninhalte

  • Anwendung schreiben, die Vertex AI mit dem Cloud Shell-Editor verwendet
  • Anwendungscode in GitHub speichern
  • gcloud CLI verwenden, um den Quellcode Ihrer Anwendung in Cloud Run bereitzustellen
  • Monitoring- und Logging-Funktionen in Ihre Anwendung mit generativer KI einbinden
  • Logbasierte Messwerte verwenden
  • Logging und Monitoring mit dem OpenTelemetry SDK implementieren
  • Informationen zum verantwortungsbewussten Umgang mit KI-Daten

2. Vorbereitung

Wenn Sie noch kein Google-Konto haben, müssen Sie ein neues Konto erstellen.

3. Projekt einrichten

  1. Melden Sie sich mit Ihrem Google-Konto in der Google Cloud Console an.
  2. Erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes Projekt wieder. Notieren Sie sich die Projekt-ID des Projekts, das Sie gerade erstellt oder ausgewählt haben.
  3. Aktivieren Sie die Abrechnung für das Projekt.
    • Die Kosten für dieses Lab sollten weniger als 5 $betragen.
    • Sie können die Schritte am Ende dieses Labs ausführen, um Ressourcen zu löschen und so weitere Kosten zu vermeiden.
    • Neue Nutzer haben Anspruch auf die kostenlose Testversion mit einem Guthaben von 300$.
  4. Prüfen Sie in der Cloud-Abrechnung unter Meine Projekte
      , ob die Abrechnung aktiviert ist.
    • Wenn in Ihrem neuen Projekt in der Spalte Billing account der Wert Billing is disabled angezeigt wird:
      1. Klicken Sie in der Spalte Actions auf das Dreipunkt-Menü.
      2. Klicken Sie auf Abrechnung ändern.
      3. Wählen Sie das gewünschte Rechnungskonto aus.
    • Wenn Sie an einer Live-Veranstaltung teilnehmen, heißt das Konto wahrscheinlich Google Cloud Platform-Testrechnungskonto.

4. Cloud Shell-Editor vorbereiten

  1. Rufen Sie den Cloud Shell-Editor auf. Wenn Sie die folgende Meldung erhalten, in der Sie aufgefordert werden, Cloud Shell zu autorisieren, gcloud mit Ihren Anmeldedaten aufzurufen, klicken Sie auf Autorisieren, um fortzufahren.
    Klicken Sie, um Cloud Shell zu autorisieren.
  2. Terminalfenster öffnen
    1. Klicken Sie auf das Dreistrich-Menü Symbol für das Dreistrich-Menü.
    2. Klicken Sie auf Terminal.
    3. Klicken Sie auf Neues Terminal
      Neues Terminal im Cloud Shell-Editor öffnen.
  3. Konfigurieren Sie im Terminal Ihre Projekt-ID:
    gcloud config set project [PROJECT_ID]
    Ersetzen Sie [PROJECT_ID] durch die ID Ihres Projekts. Wenn Ihre Projekt-ID beispielsweise lab-example-project lautet, sieht der Befehl so aus:
    gcloud config set project lab-project-id-example
    Wenn Sie die folgende Meldung erhalten, in der Sie aufgefordert werden, Ihre Anmeldedaten für die GCPI API anzugeben, klicken Sie auf Autorisieren, um fortzufahren.
    Klicken Sie, um Cloud Shell zu autorisieren.
    Bei erfolgreicher Ausführung wird die folgende Meldung angezeigt:
    Updated property [core/project].
    Wenn Sie WARNING sehen und Do you want to continue (Y/N)? gefragt werden, haben Sie die Projekt-ID wahrscheinlich falsch eingegeben. Drücken Sie N, dann Enter und versuchen Sie, den Befehl gcloud config set project noch einmal auszuführen, nachdem Sie die richtige Projekt-ID gefunden haben.
  4. (Optional) Wenn Sie Probleme haben, die Projekt-ID zu finden, führen Sie den folgenden Befehl aus, um die Projekt-ID aller Ihrer Projekte nach Erstellungszeit in absteigender Reihenfolge zu sehen:
    gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime

5. Google APIs aktivieren

Aktivieren Sie im Terminal die für dieses Lab erforderlichen Google APIs:

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

Die Ausführung dieses Befehls kann einige Zeit in Anspruch nehmen. Wenn die Aktivierung erfolgreich war, erhalten Sie eine Meldung, die ungefähr so aussieht:

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

Wenn Sie eine Fehlermeldung erhalten, die mit ERROR: (gcloud.services.enable) HttpError accessing beginnt und Fehlerdetails wie unten enthält, wiederholen Sie den Befehl nach einer Verzögerung von 1 bis 2 Minuten.

"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. Gen AI-Python-Anwendung erstellen

In diesem Schritt schreiben Sie den Code für eine einfache anfragebasierte Anwendung, die das Gemini-Modell verwendet, um 10 interessante Fakten über ein Tier Ihrer Wahl anzuzeigen. So erstellen Sie den Anwendungscode:

  1. Erstellen Sie im Terminal das Verzeichnis codelab-o11y:
    mkdir ~/codelab-o11y
  2. Ändern Sie das aktuelle Verzeichnis in codelab-o11y:
    cd ~/codelab-o11y
  3. Erstellen Sie die requirements.txt mit der Liste der Abhängigkeiten:
    cat > requirements.txt << EOF
Flask==3.0.0
gunicorn==23.0.0
google-cloud-aiplatform==1.59.0
google-auth==2.32.0
EOF
  4. Erstellen Sie eine main.py-Datei und öffnen Sie sie im Cloud Shell-Editor:
    cloudshell edit main.py
    Im Editorfenster über dem Terminal sollte jetzt eine leere Datei angezeigt werden. Ihr Bildschirm sollte nun in etwa so aussehen:
    Cloud Shell-Editor nach dem Bearbeiten von „main.py“ anzeigen
  5. Kopieren Sie den folgenden Code und fügen Sie ihn in die geöffnete Datei main.py ein:
    import os
from flask import Flask, request
import google.auth
import vertexai
from vertexai.generative_models import GenerativeModel

_, project = google.auth.default()
app = Flask(__name__)

@app.route('/')
def fun_facts():
    vertexai.init(project=project, location='us-central1')
    model = GenerativeModel('gemini-1.5-flash')
    animal = request.args.get('animal', 'dog') 
    prompt = f'Give me 10 fun facts about {animal}. Return this as html without backticks.'
    response = model.generate_content(prompt)
    return response.text

if __name__ == '__main__':
    app.run(debug=True, host='0.0.0.0', port=int(os.environ.get('PORT', 8080)))
    Nach einigen Sekunden wird Ihr Code automatisch im Cloud Shell Editor gespeichert.

Code der GenAI-Anwendung in Cloud Run bereitstellen

  1. Führen Sie im Terminalfenster den Befehl aus, um den Quellcode der Anwendung in Cloud Run bereitzustellen.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Wenn Sie die folgende Aufforderung sehen, die Sie darüber informiert, dass mit dem Befehl ein neues Repository erstellt wird. Klicken Sie auf 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)?
    Die Bereitstellung kann einige Minuten dauern. Nach Abschluss der Bereitstellung wird in etwa folgende Ausgabe angezeigt:
    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. Kopieren Sie die angezeigte Cloud Run-Dienst-URL in einen separaten Tab oder ein separates Fenster in Ihrem Browser. Alternativ können Sie den folgenden Befehl im Terminal ausführen, um die Dienst-URL auszugeben, und dann bei gedrückter Ctrl auf die angezeigte URL klicken, um sie zu öffnen:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Wenn die URL geöffnet wird, erhalten Sie möglicherweise einen 500-Fehler oder die folgende Meldung:
    Sorry, this is just a placeholder...
    Das bedeutet, dass die Bereitstellung der Dienste nicht abgeschlossen wurde. Warten Sie einige Sekunden und aktualisieren Sie dann die Seite. Am Ende sehen Sie einen Text, der mit Fun Dog Facts beginnt und 10 Fun Facts über Hunde enthält.

Interagieren Sie mit der Anwendung, um interessante Fakten über verschiedene Tiere zu erhalten. Hängen Sie dazu den Parameter animal an die URL an, z. B. ?animal=[ANIMAL], wobei [ANIMAL] ein Tiername ist. Hängen Sie beispielsweise ?animal=cat an, um 10 Funfacts über Katzen zu erhalten, oder ?animal=sea turtle, um 10 Funfacts über Meeresschildkröten zu erhalten.

7. Vertex API-Aufrufe prüfen

Durch die Überprüfung von Google API-Aufrufen erhalten Sie Antworten auf Fragen wie „Wer hat eine bestimmte API wann und wo aufgerufen?“. Die Überwachung ist wichtig, wenn Sie Fehler in Ihrer Anwendung beheben, den Ressourcenverbrauch untersuchen oder eine Software-Forensik durchführen.

Mit Audit-Logs können Sie Administrator- und Systemaktivitäten nachverfolgen sowie Aufrufe von API-Vorgängen zum Lesen und Schreiben von Daten protokollieren. Wenn Sie Vertex AI-Anfragen zum Generieren von Inhalten prüfen möchten, müssen Sie Audit-Logs vom Typ „Daten lesen“ in der Cloud Console aktivieren.

  1. Klicken Sie auf die Schaltfläche unten, um die Seite „Audit-Logs“ in der Cloud Console zu öffnen.

  2. Achten Sie darauf, dass auf der Seite das Projekt ausgewählt ist, das Sie für dieses Lab erstellt haben. Das ausgewählte Projekt wird oben links auf der Seite direkt neben dem Dreistrich-Menü angezeigt:
    Google Cloud Console-Projekt-Dropdown-Menü
    Wählen Sie bei Bedarf das richtige Projekt aus der Kombinationsbox aus.
  3. Suchen Sie in der Tabelle Konfiguration für Audit-Logs zum Datenzugriff in der Spalte „Dienst“ nach dem Dienst Vertex AI API und wählen Sie den Dienst aus, indem Sie das Kästchen links neben dem Dienstnamen aktivieren.
    Vertex AI API auswählen
  4. Wählen Sie im Infobereich rechts den Audittyp „Daten lesen“ aus.
    Logs zum Lesen von Daten prüfen
  5. Klicken Sie auf Speichern.

Öffnen Sie die Dienst-URL, um Audit-Logs zu generieren. Aktualisieren Sie die Seite, während Sie den Wert des Parameters ?animal= ändern, um unterschiedliche Ergebnisse zu erhalten.

Audit-Logs ansehen

  1. Klicken Sie auf die Schaltfläche unten, um die Seite „Log-Explorer“ in der Cloud Console zu öffnen:

  2. Fügen Sie den folgenden Filter in den Bereich „Abfrage“ ein.
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
    Der Bereich „Abfrage“ ist ein Editor oben auf der Seite „Log-Explorer“:
    Audit-Logs abfragen
  3. Klicken Sie auf Abfrage ausführen.
  4. Wählen Sie einen der Audit-Log-Einträge aus. Die Felder werden maximiert, damit Sie die im Log erfassten Informationen sehen können.
     Sie können Details zum Vertex API-Aufruf sehen, einschließlich der verwendeten Methode und des verwendeten Modells. Außerdem können Sie die Identität des Aufrufers und die Berechtigungen sehen, die den Aufruf autorisiert haben.

8. Interaktionen mit generativer KI protokollieren

Sie finden keine API-Anfrageparameter oder Antwortdaten in Audit-Logs. Diese Informationen können jedoch für die Fehlerbehebung bei der Analyse von Anwendungen und Workflows wichtig sein. In diesem Schritt schließen wir diese Lücke, indem wir die Anwendungs-Logging-Funktion hinzufügen. Für das Logging wird das klassische Python-Paket logging verwendet. In Ihrer Produktionsumgebung verwenden Sie möglicherweise ein anderes Protokollierungs-Framework, die Prinzipien sind jedoch dieselben.

Das Python-Paket logging kann keine Logs in Google Cloud schreiben. Es wird das Schreiben in die Standardausgabe (standardmäßig stderr) oder in eine Datei unterstützt. Cloud Run bietet jedoch Funktionen, mit denen Informationen, die in der Standardausgabe ausgegeben werden, automatisch erfasst und in Cloud Logging aufgenommen werden. Folgen Sie der Anleitung unten, um Ihrer Gen AI-Anwendung Logging-Funktionen hinzuzufügen.

  1. Kehren Sie in Ihrem Browser zum Fenster (oder Tab) „Cloud Shell“ zurück.
  2. Öffnen Sie main.py im Terminal noch einmal:
    cloudshell edit ~/codelab-o11y/main.py
  3. Nehmen Sie die folgenden Änderungen am Code der Anwendung vor:
    1. Suchen Sie die letzte Importanweisung. Es sollte Zeile 5 sein:
      from vertexai.generative_models import GenerativeModel
      Setzen Sie den Cursor in die nächste Zeile (Zeile 6) und fügen Sie dort den folgenden Codeblock ein.
      import sys, json, logging
class JsonFormatter(logging.Formatter):
    def format(self, record):
        json_log_object = {
            'severity': record.levelname,
            'message': record.getMessage(),
        }
        json_log_object.update(getattr(record, 'json_fields', {}))
        return json.dumps(json_log_object)
logger = logging.getLogger(__name__)
sh = logging.StreamHandler(sys.stdout)
sh.setFormatter(JsonFormatter())
logger.addHandler(sh)
logger.setLevel(logging.DEBUG)
    2. Suchen Sie den Code, der das Modell aufruft, um Inhalte zu generieren. Es sollte Zeile 30 sein:
      response = model.generate_content(prompt)
      Setzen Sie den Cursor an den Anfang der NÄCHSTEN Zeile (Zeile 31) und fügen Sie dort den folgenden Codeblock ein.
          json_fields = {
         'animal': animal,
         'prompt': prompt,
         'response': response.to_dict(),
    }
    logger.debug('content is generated', extra={'json_fields': json_fields})
    Mit diesen Änderungen wird die Python-Standardprotokollierung so konfiguriert, dass ein benutzerdefinierter Formatierer verwendet wird, um in Strings umgewandeltes JSON zu generieren, das den Richtlinien für die strukturierte Formatierung entspricht. Das Logging ist so konfiguriert, dass Logs in stdout ausgegeben werden. Dort werden sie vom Cloud Run-Logging-Agent erfasst und asynchron in Cloud Logging aufgenommen. In den Logs werden der Tierparameter der Anfrage sowie der Prompt und die Antwort des Modells erfasst.Nach einigen Sekunden werden Ihre Änderungen automatisch im Cloud Shell Editor gespeichert.

Code der GenAI-Anwendung in Cloud Run bereitstellen

  1. Führen Sie im Terminalfenster den Befehl aus, um den Quellcode der Anwendung in Cloud Run bereitzustellen.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Wenn Sie die folgende Aufforderung sehen, die Sie darüber informiert, dass mit dem Befehl ein neues Repository erstellt wird. Klicken Sie auf 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)?
    Die Bereitstellung kann einige Minuten dauern. Nach Abschluss der Bereitstellung wird in etwa folgende Ausgabe angezeigt:
    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. Kopieren Sie die angezeigte Cloud Run-Dienst-URL in einen separaten Tab oder ein separates Fenster in Ihrem Browser. Alternativ können Sie den folgenden Befehl im Terminal ausführen, um die Dienst-URL auszugeben, und dann bei gedrückter Ctrl auf die angezeigte URL klicken, um sie zu öffnen:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Wenn die URL geöffnet wird, erhalten Sie möglicherweise einen 500-Fehler oder die folgende Meldung:
    Sorry, this is just a placeholder...
    Das bedeutet, dass die Bereitstellung der Dienste nicht abgeschlossen wurde. Warten Sie einige Sekunden und aktualisieren Sie dann die Seite. Am Ende sehen Sie einen Text, der mit Fun Dog Facts beginnt und 10 Fun Facts über Hunde enthält.

Öffnen Sie die Dienst-URL, um Anwendungslogs zu generieren. Aktualisieren Sie die Seite, während Sie den Wert des Parameters ?animal= ändern, um unterschiedliche Ergebnisse zu erhalten.
 So rufen Sie die Anwendungslogs auf:

  1. Klicken Sie auf die Schaltfläche unten, um die Seite „Log-Explorer“ in der Cloud Console zu öffnen:

  2. Fügen Sie den folgenden Filter in den Bereich „Abfrage“ (#2 in der Log-Explorer-Benutzeroberfläche) ein:
    LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
  3. Klicken Sie auf Abfrage ausführen.

Das Ergebnis der Abfrage enthält Protokolle mit dem Prompt und der Vertex AI-Antwort, einschließlich Sicherheitsbewertungen.

9. Interaktionen mit generativer KI zählen

Cloud Run schreibt verwaltete Messwerte, mit denen bereitgestellte Dienste überwacht werden können. Mit nutzerverwalteten Überwachungsstatistiken haben Sie mehr Kontrolle über Daten und Häufigkeit der Statistikaktualisierung. Um einen solchen Messwert zu implementieren, müssen Sie Code schreiben, der Daten erfasst und in Cloud Monitoring schreibt. Im nächsten (optionalen) Schritt erfahren Sie, wie Sie dies mit dem OpenTelemetry SDK implementieren.

In diesem Schritt wird eine Alternative zur Implementierung von Nutzermesswerten im Code gezeigt: logbasierte Messwerte. Mit logbasierten Messwerten können Sie Monitoring-Messwerte aus den Logeinträgen generieren, die Ihre Anwendung in Cloud Logging schreibt. Wir verwenden die Anwendungslogs, die wir im vorherigen Schritt implementiert haben, um einen logbasierten Messwert vom Typ „Zähler“ zu definieren. Mit diesem Messwert wird die Anzahl der erfolgreichen Aufrufe an die Vertex API gezählt.

  1. Sehen Sie sich das Fenster des Log-Explorers an, das wir im vorherigen Schritt verwendet haben. Suchen Sie im Bereich „Abfrage“ nach dem Drop-down-Menü Aktionen und klicken Sie darauf, um es zu öffnen. Im Screenshot unten sehen Sie, wo sich das Menü befindet:
    Symbolleiste für Abfrageergebnisse mit dem Drop-down-Menü „Aktionen“
  2. Wählen Sie im geöffneten Menü Messwert erstellen aus, um den Bereich Logbasierten Messwert erstellen zu öffnen.
  3. So konfigurieren Sie einen neuen Zählermesswert im Bereich Logbasierten Messwert erstellen:
    1. Legen Sie den Messwerttyp fest: Wählen Sie Zähler aus.
    2. Legen Sie im Abschnitt Details die folgenden Felder fest:
      • Name des Logmesswerts: Legen Sie den Namen auf model_interaction_count fest. Für die Benennung gelten einige Einschränkungen. Weitere Informationen dazu finden Sie unter Fehlerbehebung.
      • Beschreibung: Geben Sie eine Beschreibung für den Messwert ein. z. B. Number of log entries capturing successful call to model inference..
      • Einheiten: Lassen Sie dieses Feld leer oder geben Sie die Zahl 1 ein.
    3. Übernehmen Sie die Werte im Abschnitt Filterauswahl. Das Feld Build-Filter enthält denselben Filter, den wir zum Aufrufen von Anwendungslogs verwendet haben.
    4. Optional: Fügen Sie ein Label hinzu, mit dem Sie die Anzahl der Anrufe für jedes Tier zählen können. HINWEIS: Dieses Label kann die Kardinalität von Messwerten erheblich erhöhen und wird nicht für den Einsatz in der Produktion empfohlen:
      1. Klicken Sie auf Label hinzufügen.
      2. Legen Sie im Abschnitt Labels die folgenden Felder fest:
        • Labelname: Legen Sie als Namen animal fest.
        • Beschreibung: Geben Sie die Beschreibung des Labels ein. Beispiel: Animal parameter.
        • Labeltyp: Wählen Sie STRING aus.
        • Feldname: Geben Sie jsonPayload.animal ein.
        • Regulärer Ausdruck: Lassen Sie das Feld leer.
      3. Klicken Sie auf Fertig.
    5. Klicken Sie auf Messwert erstellen, um den Messwert zu erstellen.

Sie können auch einen logbasierten Messwert auf der Seite Logbasierte Messwerte mit dem gcloud logging metrics create CLI-Befehl oder mit der google_logging_metric Terraform-Ressource erstellen.

Öffnen Sie die Dienst-URL, um Messwertdaten zu generieren. Aktualisieren Sie die geöffnete Seite mehrmals, um mehrere Aufrufe des Modells zu generieren. Verwenden Sie wie zuvor verschiedene Tiere im Parameter.

Geben Sie die PromQL-Abfrage ein, mit der nach den logbasierten Messwertdaten gesucht werden soll. So geben Sie eine PromQL-Abfrage ein:

  1. Klicken Sie auf die Schaltfläche unten, um die Seite „Metrics Explorer“ in der Cloud Console zu öffnen:

  2. Klicken Sie in der Symbolleiste des Bereichs „Query Builder“ auf die Schaltfläche, deren Name entweder < > MQL oder < > PromQL ist. Die Position der Schaltfläche sehen Sie auf dem Bild unten.
    Position der MQL-Schaltfläche im Metrics Explorer
  3. Prüfen Sie, ob im Ein-/Aus-Button Sprache PromQL ausgewählt ist. Die Sprachschaltfläche befindet sich in derselben Symbolleiste, mit der Sie Ihre Abfrage formatieren können.
  4. Geben Sie Ihre Abfrage in den Editor Abfragen ein:
    sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
    Weitere Informationen zur Verwendung von PromQL finden Sie unter PromQL in Cloud Monitoring.
  5. Klicken Sie auf Abfrage ausführen. Es wird ein Liniendiagramm wie in diesem Screenshot angezeigt:
    Abgefragte Messwerte anzeigen

    Hinweis: Wenn der Ein/Aus-Schalter Automatisch ausführen aktiviert ist, wird der Button Abfrage ausführen nicht angezeigt.

10. Optional: OpenTelemetry für Monitoring und Tracing verwenden

Wie im vorherigen Schritt erwähnt, können Sie Messwerte mit dem OpenTelemetry (Otel) SDK implementieren. Die Verwendung von OTel in Mikrodienstarchitekturen wird empfohlen. In diesem Schritt wird Folgendes beschrieben:

  • OTel-Komponenten initialisieren, um Tracing und Monitoring der Anwendung zu unterstützen
  • OTel-Konfiguration mit Ressourcenmetadaten der Cloud Run-Umgebung füllen
  • Flask-Anwendung mit automatischen Tracing-Funktionen instrumentieren
  • Zählermesswert implementieren, um die Anzahl der erfolgreichen Modellaufrufe zu erfassen
  • Tracing mit Anwendungslogs korrelieren

Die empfohlene Architektur für Dienste auf Produktebene ist die Verwendung des OTel-Collectors zum Erfassen und Aufnehmen aller Observability-Daten für einen oder mehrere Dienste. Der Einfachheit halber wird im Code in diesem Schritt kein Collector verwendet. Stattdessen werden OTel-Exporte verwendet, mit denen Daten direkt in Google Cloud geschrieben werden.

OTel-Komponenten für Tracing und Messwert-Monitoring einrichten

  1. Kehren Sie in Ihrem Browser zum Fenster (oder Tab) „Cloud Shell“ zurück.
  2. Aktualisieren Sie im Terminal die Datei requirements.txt mit einer zusätzlichen Liste von Abhängigkeiten:
    cat >> ~/codelab-o11y/requirements.txt << EOF
opentelemetry-api==1.24.0
opentelemetry-sdk==1.24.0
opentelemetry-exporter-otlp-proto-http==1.24.0
opentelemetry-instrumentation-flask==0.45b0
opentelemetry-instrumentation-requests==0.45b0
opentelemetry-exporter-gcp-trace==1.7.0
opentelemetry-exporter-gcp-monitoring==1.7.0a0   
EOF
  3. Erstellen Sie eine neue Datei setup_opentelemetry.py:
    cloudshell edit ~/codelab-o11y/setup_opentelemetry.py
    Im Editorfenster über dem Terminal sollte jetzt eine leere Datei angezeigt werden.
  4. Kopieren Sie den folgenden Code und fügen Sie ihn in die geöffnete Datei setup_opentelemetry.py ein:
    import os

from opentelemetry import metrics
from opentelemetry import trace
from opentelemetry.exporter.cloud_monitoring import CloudMonitoringMetricsExporter
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.resourcedetector.gcp_resource_detector import GoogleCloudResourceDetector
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import get_aggregated_resources, Resource, CLOUD_ACCOUNT_ID, SERVICE_NAME
from opentelemetry.sdk.trace.export import BatchSpanProcessor

resource = get_aggregated_resources(
    [GoogleCloudResourceDetector(raise_on_error=True)]
)
resource = resource.merge(Resource.create(attributes={
    SERVICE_NAME: os.getenv("K_SERVICE"),
}))

meter_provider = MeterProvider(
    resource=resource,
    metric_readers=[
        PeriodicExportingMetricReader(
            CloudMonitoringMetricsExporter(), export_interval_millis=5000
        )
    ],
)
metrics.set_meter_provider(meter_provider)
meter = metrics.get_meter(__name__)

trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(CloudTraceSpanExporter(
    # send all resource attributes
    resource_regex=r".*"
))
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)

def google_trace_id_format(trace_id: int) -> str:
    project_id = resource.attributes[CLOUD_ACCOUNT_ID]
    return f'projects/{project_id}/traces/{trace.format_trace_id(trace_id)}'
    Nach einigen Sekunden wird Ihr Code automatisch im Cloud Shell Editor gespeichert.

Anwendungscode mit Tracing- und Monitoringfunktionen mit OTel instrumentieren

  1. Öffnen Sie main.py im Terminal noch einmal:
    cloudshell edit ~/codelab-o11y/main.py
  2. Nehmen Sie die folgenden Änderungen am Code der Anwendung vor:
    1. Fügen Sie vor der Zeile import os (Zeile 1) den folgenden Code ein (beachten Sie die leere Zeile am Ende):
      from setup_opentelemetry import google_trace_id_format
from opentelemetry import metrics, trace
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.instrumentation.flask import FlaskInstrumentor
    2. Fügen Sie nach der Deklaration der Methode format() (Zeile 9) den folgenden Code ein (Achtung: Einrückung):
              span = trace.get_current_span()
    3. Fügen Sie nach Zeile 13 (mit "message": record.getMessage()) den folgenden Code ein (Achtung: Einrückung beachten):
                  "logging.googleapis.com/trace": google_trace_id_format(span.get_span_context().trace_id),
            "logging.googleapis.com/spanId": trace.format_span_id(span.get_span_context().span_id),
      Mit diesen beiden zusätzlichen Attributen lassen sich Anwendungslogs und OTel-Tracing-Spans korrelieren.
    4. Fügen Sie nach der Zeile app = Flask(__name__) (Zeile 31) den folgenden Code ein:
      FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()
      Diese Zeile instrumentiert alle eingehenden und ausgehenden Anfragen unserer Flask-Anwendung mit Tracing.
    5. Fügen Sie direkt nach dem neu hinzugefügten Code (nach Zeile 33) den folgenden Code ein:
      meter = metrics.get_meter(__name__)
requests_counter = meter.create_counter(
    name="model_call_counter",
    description="number of model invocations",
    unit="1"
)
      Mit diesen Zeilen wird ein neuer Messwert vom Typ „Zähler“ mit dem Namen model_call_counter erstellt und für den Export registriert.
    6. Fügen Sie nach dem Aufruf von logger.debug() (Zeile 49) den folgenden Code ein:
          requests_counter.add(1, {'animal': animal})
      Durch diese Änderung wird der Zähler jedes Mal um 1 erhöht, wenn die Anwendung die Vertex API erfolgreich aufruft, um mit dem Gemini-Modell zu interagieren.

Code der GenAI-Anwendung in Cloud Run bereitstellen

  1. Führen Sie im Terminalfenster den Befehl aus, um den Quellcode der Anwendung in Cloud Run bereitzustellen.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Wenn Sie die folgende Aufforderung sehen, die Sie darüber informiert, dass mit dem Befehl ein neues Repository erstellt wird. Klicken Sie auf 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)?
    Die Bereitstellung kann einige Minuten dauern. Nach Abschluss der Bereitstellung wird in etwa folgende Ausgabe angezeigt:
    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. Kopieren Sie die angezeigte Cloud Run-Dienst-URL in einen separaten Tab oder ein separates Fenster in Ihrem Browser. Alternativ können Sie den folgenden Befehl im Terminal ausführen, um die Dienst-URL auszugeben, und dann bei gedrückter Ctrl auf die angezeigte URL klicken, um sie zu öffnen:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Wenn die URL geöffnet wird, erhalten Sie möglicherweise einen 500-Fehler oder die folgende Meldung:
    Sorry, this is just a placeholder...
    Das bedeutet, dass die Bereitstellung der Dienste nicht abgeschlossen wurde. Warten Sie einige Sekunden und aktualisieren Sie dann die Seite. Am Ende sehen Sie einen Text, der mit Fun Dog Facts beginnt und 10 Fun Facts über Hunde enthält.

Öffnen Sie die Dienst-URL, um Telemetriedaten zu generieren. Aktualisieren Sie die Seite, während Sie den Wert des Parameters ?animal= ändern, um unterschiedliche Ergebnisse zu erhalten.

Anwendungs-Traces ansehen

  1. Klicken Sie auf die Schaltfläche unten, um die Seite „Trace Explorer“ in der Cloud Console zu öffnen:

  2. Wählen Sie einen der letzten Traces aus. Sie sollten 5 oder 6 Spannen sehen, die wie im Screenshot unten aussehen.
    Ansicht des App-Spans im Trace-Explorer
  3. Suchen Sie nach dem Span, der den Aufruf des Event-Handlers (die Methode fun_facts) nachverfolgt. Das ist der letzte Bereich mit dem Namen /.
  4. Wählen Sie im Bereich Trace-Details die Option Logs und Ereignisse aus. Sie sehen Anwendungslogs, die mit diesem bestimmten Span korrelieren. Die Korrelation wird anhand der Trace- und Span-IDs im Trace und im Log erkannt. Sie sollten das Anwendungsprotokoll sehen, in dem der Prompt und die Antwort der Vertex API aufgezeichnet wurden.

Zählermesswert ansehen

  1. Klicken Sie auf die Schaltfläche unten, um die Seite „Metrics Explorer“ in der Cloud Console zu öffnen:

  2. Klicken Sie in der Symbolleiste des Bereichs „Query Builder“ auf die Schaltfläche, deren Name entweder < > MQL oder < > PromQL ist. Die Position der Schaltfläche sehen Sie auf dem Bild unten.
    Position der MQL-Schaltfläche im Metrics Explorer
  3. Prüfen Sie, ob im Ein-/Aus-Button Sprache PromQL ausgewählt ist. Die Sprachschaltfläche befindet sich in derselben Symbolleiste, mit der Sie Ihre Abfrage formatieren können.
  4. Geben Sie Ihre Abfrage in den Editor Abfragen ein:
    sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
  5. Klicken Sie auf Abfrage ausführen.Wenn der Ein/Aus-Button Automatisch ausführen aktiviert ist, wird der Button Abfrage ausführen nicht angezeigt.

11. (Optional) Vertrauliche Informationen aus Logs verschleiern

In Schritt 10 haben wir Informationen zur Interaktion der Anwendung mit dem Gemini-Modell protokolliert. Diese Informationen umfassten den Namen des Tieres, den eigentlichen Prompt und die Antwort des Modells. Das Speichern dieser Informationen im Log sollte sicher sein, das gilt jedoch nicht für viele andere Szenarien. Der Prompt kann personenbezogene oder anderweitig vertrauliche Informationen enthalten, die ein Nutzer nicht speichern möchte. Um dieses Problem zu beheben, können Sie die sensiblen Daten, die in Cloud Logging geschrieben werden, verschleiern. Um Codeänderungen zu minimieren, empfehlen wir die folgende Lösung.

  1. Pub/Sub-Thema zum Speichern eingehender Logeinträge erstellen
  2. Erstellen Sie eine Logs-Senke, die aufgenommene Logs an ein Pub/Sub-Thema weiterleitet.
  3. Erstellen Sie eine Dataflow-Pipeline, die Logs ändert, die an ein Pub/Sub-Thema weitergeleitet werden. Gehen Sie dazu so vor:
    1. Logeintrag aus dem Pub/Sub-Thema lesen
    2. Die Nutzlast des Eintrags mit der DLP Inspection API auf vertrauliche Informationen prüfen
    3. Entfernen Sie die vertraulichen Informationen in der Nutzlast mit einer der DLP-Methoden zum Entfernen.
    4. Den verschleierten Logeintrag in Cloud Logging schreiben
  4. Stellen Sie die Pipeline bereit.

12. Optional: Bereinigen

Um das Risiko zu vermeiden, dass für die im Codelab verwendeten Ressourcen und APIs Gebühren anfallen, empfiehlt es sich, nach Abschluss des Codelabs die Ressourcen zu bereinigen. Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das für das Codelab erstellte Projekt löschen.

  1. Führen Sie den Befehl zum Löschen des Projekts im Terminal aus, um das Projekt zu löschen:
    PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet
    Wenn Sie Ihr Cloud-Projekt löschen, wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen und APIs beendet. Es sollte folgende Meldung angezeigt werden, wobei PROJECT_ID Ihre Projekt-ID ist:
    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. (Optional) Wenn Sie eine Fehlermeldung erhalten, sehen Sie in Schritt 5 nach, welche Projekt-ID Sie während des Labs verwendet haben. Ersetzen Sie den Befehl in der ersten Anleitung damit. Wenn Ihre Projekt-ID beispielsweise lab-example-project lautet, sieht der Befehl so aus:
    gcloud projects delete lab-project-id-example --quiet

13. Glückwunsch

In diesem Lab haben Sie eine Anwendung mit generativer KI erstellt, die mit dem Gemini-Modell Vorhersagen trifft. Außerdem wurde die Anwendung mit wichtigen Monitoring- und Logging-Funktionen ausgestattet. Sie haben die Anwendung und Änderungen aus dem Quellcode in Cloud Run bereitgestellt. Anschließend können Sie die Leistung der Anwendung mit Google Cloud Observability-Produkten verfolgen, um die Zuverlässigkeit der Anwendung zu gewährleisten.

Wenn Sie an einer Studie zur Nutzerfreundlichkeit teilnehmen möchten, um die Produkte zu verbessern, mit denen Sie heute gearbeitet haben, registrieren Sie sich hier.

Hier sind einige Optionen, um weiterzulernen: