Model Armor-Trace-Spans ansehen

In diesem Dokument werden die Model Armor-Spans in Traces und das Aufrufen ihrer Details beschrieben. Weitere Informationen zu Traces finden Sie unter Agent-Traces ansehen.

Cloud Trace und Beobachtbarkeit von KI-Agenten

Ein Trace stellt den Pfad einer Anfrage über alle Teile Ihrer verteilten Anwendung hinweg dar. Das bedeutet, dass jeder Trace einen einzelnen End-to-End-Vorgang darstellt. Da Traces aus Spans bestehen, die Datensätze für eine einzelne Funktion oder einen einzelnen Vorgang sind, können Sie den Ablauf von Anfragen verfolgen und Latenzdaten untersuchen. Anhand dieser Informationen können Sie die Ursache eines Problems ermitteln.

Cloud Trace ist das verteilte Tracing-System für Google Cloudund bietet Funktionen zum Erkunden von Traces oder zum Analysieren von Trace-Daten mit SQL. VieleGoogle Cloud -Dienste wie Anwendungsmonitoring und Agent Registry können jedoch die von Cloud Trace verwalteten Daten anzeigen. Mit diesen Diensten können Sie Trace-Daten im Kontext des von Ihnen verwendeten Dienstes ansehen.

Hinweis

  1. Aktivieren Sie die APIs Cloud Trace, Cloud Logging, Telemetry und Model Armor, falls sie noch nicht aktiviert sind.

    Erforderliche Rollen zum Aktivieren von APIs

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    APIs aktivieren

  2. Richten Sie das Tracing für Ihren Agenten ein.
  3. Konfigurieren Sie Model Armor auf einem Gateway oder auf einem Google Cloud-MCP-Server.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen zum Aufrufen von Trace-Daten haben:

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.

Informationen zu anderen Rollen, die Sie möglicherweise benötigen, finden Sie unter Zugriffssteuerung für Cloud Trace und Zugriffssteuerung für Cloud Logging.

Unterstützte Nutzlasten

Eine Liste der unterstützten Nutzlasten finden Sie unter Unterstützte und nicht unterstützte Nutzlasten.

Bei einer Anfrage mit einer nicht unterstützten Nutzlast generiert Model Armor einen Span mit einem Fehler.

Model Armor-Span-Namen und ‑Attribute

Die folgenden Model Armor-Spans sind verfügbar:

  • Übergeordneter Span: apply_guardrail "Google Cloud Model Armor"
  • Untergeordneter Span: Request Path
  • Untergeordneter Span: Response Path

In den folgenden Abschnitten sind alle möglichen Attribute eines Model Armor-Spans aufgeführt. Nicht alle Attribute sind in jedem Span vorhanden. Diese Attributnamen können sich ändern.

Übergeordnete Span-Attribute

Der übergeordnete Span apply_guardrail "Google Cloud Model Armor" hat die folgenden Attribute:

  • cloud.provider: der mit dem Vorgang verknüpfte Cloud-Anbieter.
  • cloud.region: die Google Cloud Region, in der der Vorgang ausgeführt wurde.
  • gcp.project_id: die ID des Projekts, in dem der Vorgang ausgeführt wurde.
  • rpc.system: das zugrunde liegende Remote-Prozeduraufruf (RPC)-Framework oder Protokoll, das für den Vorgang verwendet wurde, z. B. grpc.
  • service.name: der Google Cloud -Dienst, der dem Vorgang zugeordnet ist. Bei Model Armor-Spans ist der Wert dieses Felds modelarmor.

Attribute für Anfragepfad

Der untergeordnete Span Request Path hat die folgenden Attribute:

  • gen_ai.security.target.type: der Typ des Inhalts oder der Aktion, auf den die Schutzmaßnahme angewendet wird. Im Request Path-Span ist dies immer input.
  • gen_ai.security.decision.type: Das Ergebnis oder die Aktion, die von Model Armor angewendet wurde. Der Wert modify gibt an, dass Model Armor sensible Daten gemäß der bereitgestellten Vorlage aus dem Inhalt entfernt (de-identifiziert) hat.
  • gen_ai.security.decision.code: ein numerischer Code für die Sicherheitsentscheidung.
  • gen_ai.security.decision.reason: ein für Nutzer lesbarer Grund für die Entscheidung.
  • gen_ai.security.policy.id: der vollständige Ressourcenname der Model Armor-Vorlage im Format projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID.
  • gen_ai.security.policy.name: der Name der Model Armor-Vorlage, die für den Vorgang verwendet wurde.
  • gcp.modelarmor.filter.match.state: Gibt an, ob der Inhalt gegen einen der Model Armor-Filter (auch Detektoren genannt) verstoßen hat.
  • gcp.modelarmor.violations: die Model Armor-Filter, gegen die der Inhalt verstoßen hat. Der Wert deidentified gibt an, dass Model Armor vertrauliche Daten gemäß der bereitgestellten Vorlage aus dem Inhalt entfernt hat.
  • gcp.modelarmor.rai.violations: Die Kategorien für verantwortungsbewusste Anwendung von KI, gegen die der Inhalt verstoßen hat. Weitere Informationen finden Sie unter Sicherheitsfilter für Responsible AI.
  • gcp.modelarmor.sdp.info_types: die sensiblen Datentypen (z. B. EMAIL_ADDRESS oder PHONE_NUMBER), die von Sensitive Data Protection-Filtern identifiziert werden.
  • error.type: eine Kennung für den aufgetretenen Fehler.

Attribute des Antwortpfads

Der untergeordnete Span Response Path hat die folgenden Attribute:

  • gen_ai.security.target.type: der Typ des Inhalts oder der Aktion, auf den die Guardrail angewendet wird. Im Response Path-Span ist dies immer output.
  • gen_ai.security.decision.type: Das Ergebnis oder die Aktion, die von Model Armor angewendet wurde. Der Wert modify gibt an, dass Model Armor sensible Daten gemäß der bereitgestellten Vorlage aus dem Inhalt entfernt (de-identifiziert) hat.
  • gen_ai.security.decision.code: ein numerischer Code für die Sicherheitsentscheidung.
  • gen_ai.security.decision.reason: ein für Nutzer lesbarer Grund für die Entscheidung.
  • gen_ai.security.policy.id: der vollständige Ressourcenname der Model Armor-Vorlage im Format projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID.
  • gen_ai.security.policy.name: der Name der Model Armor-Vorlage, die für den Vorgang verwendet wurde.
  • gcp.modelarmor.filter.match.state: Gibt an, ob der Inhalt gegen einen der Model Armor-Filter (auch Detektoren genannt) verstoßen hat.
  • gcp.modelarmor.violations: die Model Armor-Filter, gegen die der Inhalt verstoßen hat. Der Wert deidentified gibt an, dass Model Armor vertrauliche Daten gemäß der bereitgestellten Vorlage aus dem Inhalt entfernt hat.
  • gcp.modelarmor.rai.violations: Die Kategorien für verantwortungsbewusste Anwendung von KI, gegen die der Inhalt verstoßen hat. Weitere Informationen finden Sie unter Sicherheitsfilter für Responsible AI.
  • gcp.modelarmor.sdp.info_types: die sensiblen Datentypen (z. B. EMAIL_ADDRESS oder PHONE_NUMBER), die von Sensitive Data Protection-Filtern identifiziert werden.
  • error.type: eine Kennung für den aufgetretenen Fehler.

Details eines Model Armor-Spans ansehen

So rufen Sie einen Model Armor-Span und seine Details auf, einschließlich seiner Attribute und des DAG:

  1. Rufen Sie in der Google Cloud Console die Agent Registry auf.

    Zur Agent Registry

  2. Wählen Sie Ihr Projekt aus.
  3. Klicken Sie auf den Namen des KI-Agenten.
  4. Klicken Sie auf den Tab Traces.
  5. Klicken Sie auf die ID eines Trace, den Sie sich ansehen möchten. Wenn der Trace einen Model Armor-Span enthält, enthält der Trace den Span apply_guardrail "Google Cloud Model Armor".

  6. Trace untersuchen:

    • Wenn Sie den Trace als gerichteten azyklischen Graphen (Directed Acyclic Graph, DAG) ansehen möchten, klicken Sie auf die Ansicht Graph. In dieser Ansicht wird der Ausführungs-Trace eines KI-Agenten als Knoten-Link-Diagramm dargestellt. DAGs betonen die kausalen Beziehungen und Abhängigkeiten zwischen verschiedenen Trace-Spans und zeigen, wie ein Vorgang den nächsten auslöst. Jeder Knoten im Diagramm ist ein Span.
    • Wenn Sie den Trace als Zeitachse ansehen möchten, klicken Sie auf die Ansicht Zeitachse. Jeder Balken in der Zeitachse stellt einen Span dar.

  7. Klicken Sie auf einen Span, um die zugehörigen Attribute aufzurufen.

Alternativ können Sie auf In Cloud Trace ansehen klicken, um alle Spans in Ihrem Projekt über den Trace Explorer aufzurufen. Wenden Sie Span-Filter an, um nach dem Span apply_guardrail "Google Cloud Model Armor" zu suchen.

Nächste Schritte