ADK-Anwendungen mit OpenTelemetry instrumentieren

Vorschau

Diese Funktion unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

In diesem Dokument wird beschrieben, wie Sie einen KI-Agenten instrumentieren, der mit dem Agent Development Kit (ADK) erstellt wurde. Das ADK-Framework umfasst OpenTelemetry-Instrumentierung, mit der Telemetriedaten von den wichtigsten Aktionen des Agents erfasst werden. Wenn Sie die integrierte Instrumentierung aktivieren, werden Informationen wie Text-Prompts und Agent-Antworten an Ihr Google Cloud -Projekt gesendet. In diesem Dokument werden die erforderlichen Änderungen beschrieben und ein Link zu einer Beispielanwendung bereitgestellt.

Anwendungen, die das ADK verwenden, können auch multimodale Prompts und Antworten erfassen. In diesem Dokument wird beschrieben, wie Sie Text-Prompts und ‑Antworten erfassen. Wenn Sie multimodale Daten erfassen möchten, ist eine zusätzliche Konfiguration erforderlich. Weitere Informationen finden Sie unter Multimodale Prompts und Antworten erfassen und ansehen.

Die standardmäßige Observability, die vom ADK bereitgestellt wird, reicht möglicherweise nicht für den Anwendungsfall Ihrer Anwendung aus. Sie können zusätzliche Instrumentierungsbibliotheken mit OpenTelemetry hinzufügen, um Telemetriedaten aus anderen Teilen Ihrer App oder Ihrer eigenen benutzerdefinierten Instrumentierung zu erfassen, um detailliertere Informationen zu erhalten. In Ihrer Anwendung können Sie beispielsweise Instrumentierungscode schreiben, um:

• Ressourcenverbrauch von Agent-aufgerufenen Tools verfolgen.
• Anwendungsspezifische Validierungsfehler, Verstöße gegen Geschäftsregeln oder benutzerdefinierte Mechanismen zur Fehlerbehebung lassen sich nachverfolgen.
• Sie können Qualitätsfaktoren für Agentenantworten anhand Ihrer domainspezifischen Kriterien erfassen.

Hinweis: In diesem Dokument wird davon ausgegangen, dass Sie ein ADK-Framework mit Version 1.17.0 oder höher verwenden.

Anwendung mit generativer KI für die Erfassung von Telemetriedaten instrumentieren

So instrumentieren Sie Ihren KI-Agenten, um Log-, Messwert- und Trace-Daten zu erfassen:

1. OpenTelemetry-Pakete installieren
2. ADK-Umgebung konfigurieren

Im Rest dieses Abschnitts werden die vorherigen Schritte beschrieben.

OpenTelemetry-Pakete installieren

Fügen Sie die folgenden OpenTelemetry-Instrumentierungs- und -Exporterpakete hinzu:

pip install 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Log- und Messwertdaten werden mithilfe der Cloud Logging API oder der Cloud Monitoring API an Ihr Google Cloud -Projekt gesendet. Die Bibliotheken opentelemetry-exporter-gcp-logging und opentelemetry-exporter-gcp-monitoring rufen Endpunkte in diesen APIs auf.

Tracedaten werden mit der Telemetry (OTLP) API an Google Cloud gesendet. Diese API implementiert das OpenTelemetry OTLP-Protokoll. Die Bibliothek opentelemetry-exporter-otlp-proto-grpc ruft den Telemetry-API-Endpunkt (OTLP) auf.

Ihre Tracedaten werden in einem Format gespeichert, das im Allgemeinen mit den Protobuf-Dateien übereinstimmt, die vom OpenTelemetry OTLP Protocol definiert werden. Felder können jedoch vor dem Speichern von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert werden. Weitere Informationen zum Speicherformat finden Sie unter Schema für Tracedaten.

ADK-Umgebung konfigurieren

ADK-Framework-Versionen 1.17.0 und höher bieten integrierte Unterstützung für OpenTelemetry und das Senden von OpenTelemetry-Telemetriedaten anGoogle Cloud Observability. Dazu konfigurieren Sie Ihre ADK-Umgebung:

• Wenn Sie Ihre Anwendung mit dem adk web-CLI-Befehl ausführen, fügen Sie das Flag --otel_to_cloud ein.

• Legen Sie in der Datei opentelemetry.env die folgenden Umgebungsvariablen fest:

  OTEL_SERVICE_NAME=adk-sql-agent
  OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
  

• Wir empfehlen, der Datei opentelemetry.env auch die folgende Umgebungsvariable hinzuzufügen:

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false
  

  Diese Umgebungsvariable hat folgende Funktion:

  • Verhindert, dass mit der ADK-Instrumentierung Spannenattribute angehängt werden, die das Attributgrößenlimit überschreiten.
  • Verhindert, dass personenidentifizierbare Informationen als Attribute an Spans angehängt werden.

Beispielanwendung herunterladen und ausführen

In diesem Beispielcode wird ein Agent für generative KI implementiert, der mit dem ADK erstellt wurde. Der Agent ist mit OpenTelemetry instrumentiert und so konfiguriert, dass Messwerte, Traces und Logs an Ihr Google Cloud -Projekt gesendet werden. Die an Ihr Projekt gesendeten Telemetriedaten umfassen Prompts und Antworten für generative KI.

ADK-Agenten-Persona

Der GenAI-Agent ist als SQL-Experte definiert, der vollen Zugriff auf eine temporäre SQLite-Datenbank hat. Der Agent wird mit dem Agent Development Kit erstellt und greift über das SQLDatabaseToolkit auf eine Datenbank zu. Die Datenbank ist anfangs leer.

Hinweise

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable aiplatform.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Install the Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable aiplatform.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

1. Wenn Sie das Beispiel in Cloud Shell, auf Google Cloud-Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen, reichen die in diesem Abschnitt aufgeführten Berechtigungen aus. Für Produktionsanwendungen werden die Anmeldedaten zum Schreiben von Log-, Messwert- und Tracedaten in der Regel von einem Dienstkonto bereitgestellt.

   Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, damit die Beispielanwendung Log-, Messwert- und Tracedaten schreiben kann:

   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
   • Log-Autor (roles/logging.logWriter)
   • Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
   • Vertex AI-Nutzer (roles/aiplatform.user)

App starten

So starten Sie die Beispielanwendung:

1. Geben Sie in Cloud Shell den folgenden Befehl ein:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git
   

2. Gehen Sie zum Beispielverzeichnis:

   cd opentelemetry-operations-python/samples/adk-sql-agent
   

3. Erstellen Sie eine virtuelle Umgebung und führen Sie das Beispiel aus:

   python -m venv venv/
   source venv/bin/activate
   pip install -r requirements.txt
   env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud
   

   In der Anwendung wird eine Meldung ähnlich der folgenden angezeigt:

   Appplication startup complete
   Uvicorn running on http://0.0.0.0:8080
   

4. Wenn Sie mit dem Agent interagieren möchten, wählen Sie die URL aus, die in der Ausgabe des vorherigen Schritts angezeigt wird.

5. Maximieren Sie Select an agent (Agent auswählen) und wählen Sie sql_agent aus der Liste der Agents aus.

Mit dem Agent interagieren

Wenn Sie mit dem Agent interagieren möchten, stellen Sie ihm eine Frage oder geben Sie ihm einen Befehl. Sie könnten beispielsweise folgende Frage stellen:

What can you do for me ?

Da sql_agent die Rolle eines SQL-Experten hat, können Sie es beispielsweise bitten, Tabellen für Ihre Anwendungen zu erstellen und Abfragen zu schreiben, um die erstellten Tabellen zu bearbeiten. Der Agent kann nur eine temporäre Datenbank erstellen, die auf einer .db-Datei basiert, die auf dem Computer erstellt wird, auf dem die Anwendung ausgeführt wird.

Im Folgenden wird eine Beispielinteraktion zwischen dem sql_agent und dem Nutzer veranschaulicht:



Die von generativen KI-Agents ausgeführten Aktionen sind nicht deterministisch. Sie erhalten also möglicherweise unterschiedliche Antworten auf denselben Prompt.

App schließen

Geben Sie zum Beenden der Anwendung Ctrl-C in der Shell ein, die zum Starten der Anwendung verwendet wurde.

Traces, Messwerte und Logs ansehen

In diesem Abschnitt wird beschrieben, wie Sie Ereignisse im Zusammenhang mit generativer KI aufrufen können.

Hinweise

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen zum Aufrufen Ihrer Log-, Messwert- und Tracedaten haben:

• Logbetrachter (roles/logging.viewer)
• Monitoring Viewer (roles/monitoring.viewer)
• Cloud Trace User (roles/cloudtrace.user)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Telemetrie ansehen

So rufen Sie die von der Anwendung erstellten Ereignisse für generative KI auf:

1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

   Zum Trace Explorer

   Sie können diese Seite auch über die Suchleiste finden.

2. Wählen Sie in der Symbolleiste Filter hinzufügen aus, dann Span-Name und schließlich call_llm.

   Das folgende Bild zeigt die Seite Trace Explorer nach dem Filtern der Daten:

   

   Wenn Sie Cloud Trace noch nie verwendet haben, muss Google Cloud Observability eine Datenbank zum Speichern Ihrer Trace-Daten erstellen. Das Erstellen der Datenbank kann einige Minuten dauern. In dieser Zeit sind keine Tracedaten verfügbar.

3. Wenn Sie Ihre Spannen- und Logdaten ansehen möchten, wählen Sie in der Tabelle Spannen eine Spanne aus.

   Die Seite Details wird geöffnet. Auf dieser Seite werden der zugehörige Trace und seine Spans angezeigt. In der Tabelle auf der Seite werden detaillierte Informationen für den ausgewählten Zeitraum angezeigt. Zu diesen Informationen gehören:

   • Auf dem Tab Ein-/Ausgaben werden Ereignisse für generative KI-Agents angezeigt. Weitere Informationen zu diesen Ereignissen

     Der folgende Screenshot zeigt einen Trace, in dem ein Span den Namen call_llm hat. Dieser Bereich ruft das LLM (Large Language Model) auf, das diesen Agenten unterstützt. In diesem Beispiel ist es Gemini. Der Gemini-Span enthält Ereignisse der generativen KI:

     

   • Auf dem Tab Logs und Ereignisse werden Logeinträge und Ereignisse aufgeführt, die mit dem Bereich verknüpft sind. Wenn Sie die Logdaten im Log-Explorer aufrufen möchten, wählen Sie in der Symbolleiste dieses Tabs Logs ansehen aus.

     Die Protokolldaten enthalten die Antwort von sql_agent. Für den Beispiel-Lauf enthält die JSON-Nutzlast beispielsweise den folgenden Inhalt:

     {
       "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
       "jsonPayload": {
         "content": {
           "parts": [
             0: {
               "text": "Now I can create the table."
             }
             1: {1}
             ],
           "role": "model"
         }
       },
       ...
     }
     

Das Beispiel ist so instrumentiert, dass Messwertdaten an Ihr Google Cloud -Projekt gesendet werden, es werden jedoch keine Messwerte generiert.