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.

Über Cloud Trace und die Beobachtbarkeit von Agenten

Ein Trace stellt den Pfad einer Anfrage über alle Teile Ihrer verteilten Anwendung hinweg dar. Jeder Trace steht also für einen einzelnen End-to-End-Vorgang. Da Traces aus Spans bestehen, die Datensätze für eine einzelne Funktion oder einen einzelnen Vorgang sind, können Sie den Fluss 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 Cloud, und es bietet Funktionen zum Untersuchen von Traces oder zum Analysieren von Trace-Daten mit SQL. Viele Google Cloud Dienste wie Application Monitoring und Agent Registry können jedoch die von Cloud Trace verwalteten Daten anzeigen. Mit diesen Diensten können Sie Trace-Daten im Kontext des verwendeten Dienstes ansehen.

Hinweis

  1. Aktivieren Sie die APIs Cloud Trace, Cloud Logging, Telemetry und Model Armor.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere 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 einem Google Cloud MCP-Server.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen von Trace-Daten benötigen:

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.

Attribute des übergeordneten Spans

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

  • cloud.provider: der Cloud-Anbieter, der mit dem Vorgang verknüpft ist.
  • 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 Framework oder Protokoll für den Remote-Prozeduraufruf (RPC), das für den Vorgang verwendet wurde, z. B. grpc.
  • service.name: der Google Cloud Dienst, der mit dem Vorgang verknüpft ist. Bei Model Armor-Spans ist der Wert dieses Felds modelarmor.

Attribute des Anfragepfads

Der untergeordnete Span Request Path hat die folgenden Attribute:

  • gen_ai.security.target.type: der Typ des Inhalts oder der Aktion, auf die die Leitplanke angewendet wird. Im Span Request Path 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 gemäß der bereitgestellten Vorlage vertrauliche Daten aus dem Inhalt entfernt (anonymisiert) 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 als Detektoren bezeichnet) 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 gemäß der bereitgestellten Vorlage vertrauliche Daten aus dem Inhalt entfernt hat.
  • gcp.modelarmor.rai.violation: die Kategorien für verantwortungsbewusste Anwendung von KI, gegen die der Inhalt verstoßen hat. Weitere Informationen finden Sie unter Sicherheitsfilter für verantwortungsbewusste Anwendung von KI.
  • 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 die die Leitplanke angewendet wird. Im Span Response Path 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 gemäß der bereitgestellten Vorlage vertrauliche Daten aus dem Inhalt entfernt (anonymisiert) 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 als Detektoren bezeichnet) 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 gemäß der bereitgestellten Vorlage vertrauliche Daten aus dem Inhalt entfernt hat.
  • gcp.modelarmor.rai.violation: die Kategorien für verantwortungsbewusste Anwendung von KI, gegen die der Inhalt verstoßen hat. Weitere Informationen finden Sie unter Sicherheitsfilter für verantwortungsbewusste Anwendung von KI.
  • 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 seines DAG:

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

    Zu Agent Registry

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

  6. Trace untersuchen:

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

  7. Klicken Sie auf einen Span, um seine Attribute zu sehen.

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 apply_guardrail "Google Cloud Model Armor" Span zu suchen.

Nächste Schritte