Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Logging konfigurieren

In diesem Dokument wird beschrieben, wie Sie Model Armor so konfigurieren, dass die folgenden Vorgänge protokolliert werden:

Vorgänge zum Erstellen, Aktualisieren oder Löschen einer Vorlage
Vorgänge, bei denen ein Nutzer-Prompt oder eine Modellantwort bereinigt wird

Model Armor verwendet Audit-Logs, um Verwaltungs- und Ressourcenverwaltungsaktivitäten aufzuzeichnen. Weitere Informationen finden Sie unter Audit-Logging für Model Armor.

Informationen zu den Preisen für Logs finden Sie unter Cloud Logging – Preise. Je nach Menge der verarbeiteten Daten können auch Gebühren für die Nutzung von Model Armor anfallen. Weitere Informationen finden Sie unter Model Armor-Preise.

Hinweis

Führen Sie zuerst die folgenden Schritte aus.

Erforderliche Berechtigungen erhalten

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Model Armor Admin (roles/modelarmor.admin) für die Model Armor-Vorlage zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren der Protokollierung für Model Armor 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.

APIs aktivieren

Sie müssen die Model Armor API aktivieren, bevor Sie Model Armor verwenden können.

Console

Aktivieren Sie die Model Armor API.
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
API aktivieren
Wählen Sie das Projekt aus, für das Sie Model Armor aktivieren möchten.

gcloud

Führen Sie die folgenden Schritte mit der Google Cloud CLI und der Model Armor API aus, bevor Sie beginnen:

Aktivieren Sie Cloud Shell in der Google Cloud Console.

Cloud Shell aktivieren

Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.
API-Endpunktüberschreibung mit der gcloud CLI festlegen

API-Endpunktüberschreibung mit der gcloud CLI festlegen

Dieser Schritt ist nur erforderlich, wenn Sie die gcloud CLI verwenden, um die Model Armor API zu aktivieren. Sie müssen die Überschreibung des API-Endpunkt manuell festlegen, damit die gcloud CLI Anfragen korrekt an den Model Armor-Dienst weiterleitet.

Führen Sie den folgenden Befehl aus, um den API-Endpunkt für den Model Armor-Dienst festzulegen.

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

Ersetzen Sie LOCATION durch die Region, in der Sie Model Armor verwenden möchten.

Traffic-Bereinigung einrichten

Für Google- und Google Cloud MCP-Server richten Sie die Traffic-Bereinigung über Mindesteinstellungen ein. Weitere Informationen finden Sie unter Schutz für Google- undGoogle Cloud MCP-Server konfigurieren.

Logging in Vorlagen konfigurieren

In Vorlagen werden die Filter und Grenzwerte für verschiedene Sicherheitskategorien definiert. Wenn Sie eine Model Armor-Vorlage erstellen oder aktualisieren, können Sie angeben, ob Model Armor bestimmte Vorgänge protokollieren soll. Verwenden Sie die folgenden Flags in den Vorlagenmetadaten:

log_template_operations: Ein boolescher Wert, mit dem Sie die Vorgänge zum Erstellen, Aktualisieren, Lesen und Löschen von Vorlagen protokollieren können.
log_sanitize_operations: Ein boolescher Wert, mit dem Sie den vollständigen Inhalt von Nutzer-Prompts und Modellantworten während der Bereinigungsvorgänge protokollieren können.

Console

Rufen Sie in der Google Cloud Console die Seite Model Armor auf.

Zu Model Armor
Prüfen Sie, ob Sie das Projekt aufrufen, für das Sie Model Armor aktiviert haben.
Klicken Sie auf der Seite Model Armor auf Vorlage erstellen. Weitere Informationen zum Erstellen von Vorlagen finden Sie unter Model Armor-Vorlage erstellen.
Wählen Sie im Abschnitt Logging konfigurieren die Vorgänge aus, für die Sie das Logging konfigurieren möchten.
Klicken Sie auf Erstellen.

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

Ersetzen Sie Folgendes:

PROJECT_ID: die ID des Projekts, zu dem die Vorlage gehört.
LOCATION: der Speicherort der Vorlage.
TEMPLATE_ID: die ID der Vorlage.

Python

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Model Armor Python SDK installieren.

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)

Ersetzen Sie Folgendes:

PROJECT_ID: die ID des Projekts, zu dem die Vorlage gehört.
LOCATION: der Speicherort der Vorlage.
TEMPLATE_ID: die ID der Vorlage.

Logging in den Mindesteinstellungen konfigurieren

Wenn Sie Mindesteinstellungen für Traffic von Gemini-Modellen in der Gemini Enterprise Agent Platform und auf den Google Cloud MCP-Servern in Ihrem Projekt erzwingen, definieren die Mindesteinstellungen die Sicherheitsfilter für Bereinigungen. Wenn Sie die Mindesteinstellungen für Model Armor aktualisieren, können Sie angeben, ob Model Armor Bereinigungsvorgänge protokollieren soll.

Sie können die Protokollierung von Bereinigungsoperationen für die Agent Platform sowie für Google- und Google Cloud MCP-Server einzeln aktivieren. Wenn aktiviert, enthalten die Protokolle den Prompt und die Antwort (für die Agent Platform) oder Tool-Aufrufe und Tool-Antworten (für MCP-Server), die Bewertungsergebnisse von Model Armor und zusätzliche Metadatenfelder.

Die folgenden Beispiele zeigen, wie Sie die Protokollierung von Bereinigungsoperationen für die Agent-Plattform und die Google Cloud -MCP-Server von Google aktivieren.

Console

Rufen Sie in der Google Cloud Console die Seite Model Armor auf.

Zu Model Armor
Prüfen Sie, ob Sie das Projekt aufrufen, für das Sie Model Armor aktiviert haben.
Rufen Sie den Tab Floor Settings (Etagenkonfiguration) auf.
Wählen Sie im Bereich Logs die Kästchen Vertex AI und Von Google verwalteter MCP aus, um das Logging für die einzelnen Dienste zu aktivieren.
Klicken Sie auf Speichern.

gcloud

Verwenden Sie das Flag --enable-vertex-ai-cloud-logging, um das Logging für die Agent Platform zu aktivieren, und das Flag --enable-google-mcp-server-cloud-logging, um das Logging für Google- und Google Cloud MCP-Server zu aktivieren. Verwenden Sie die Flags --no-enable-vertex-ai-cloud-logging und --no-enable-google-mcp-server-cloud-logging, um die Protokollierung zu deaktivieren.

Mit dem folgenden Beispielbefehl wird das Logging von Bereinigungsoperationen sowohl für die Agent-Plattform als auch für die Google Cloud MCP-Server von Google aktiviert:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

Ersetzen Sie PROJECT_ID durch die ID Ihres Projekts.

REST

Um das Logging zu aktivieren, legen Sie für Agent Platform aiPlatformFloorSetting.enableCloudLogging auf true und für Google- und Google Cloud MCP-Server in der Methode UpdateFloorSetting googleMcpServerFloorSetting.enableCloudLogging auf true fest.

Mit dem folgenden Beispielbefehl wird das Logging von Bereinigungsoperationen sowohl für die Agent-Plattform als auch für die Google Cloud MCP-Server von Google aktiviert:

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

Ersetzen Sie PROJECT_ID durch die ID Ihres Projekts.

Python

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Model Armor Python SDK installieren.

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

Ersetzen Sie PROJECT_ID durch die ID Ihres Projekts.

Model Armor-Logs ansehen und filtern

So rufen Sie Model Armor-Logs auf und filtern sie im Log-Explorer in Logging:

Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

Zum Log-Explorer

Weitere Informationen finden Sie unter Logs mit dem Log-Explorer aufrufen.
Geben Sie im Bereich „Abfrage“ eine der folgenden Abfragen ein, um Model Armor-Logs zu filtern:
- So rufen Sie alle Model Armor-Logs auf, einschließlich Audit-Logs und Logs für Bereinigungsoperationen:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- So rufen Sie nur Model Armor-Audit-Logs auf:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  Eine Liste aller Dienstnamen und überwachten Ressourcentypen finden Sie unter Überwachte Ressourcen und Dienste.
- So rufen Sie nur Model Armor-Logs für Bereinigungsvorgänge auf:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  Wenn Sie die Protokolle des Bereinigungsvorgangs weiter eingrenzen möchten, können Sie in der Abfrage einen Clientnamen oder eine Korrelations-ID angeben.
  - Clientname verwenden: Wenn Model Armor in Dienste wie die Gemini Enterprise Agent Platform oder Gemini Enterprise eingebunden wird, können Sie den Clientnamen verwenden, um Protokolle für eine bestimmte Integration zu filtern.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - Korrelations-ID verwenden:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
  Ersetzen Sie Folgendes:
  - CLIENT_NAME: Der Name Ihres Clients. Verwenden Sie einen der folgenden Werte:
    - CLIENT_NAME_UNSPECIFIED: Standardwert, der verwendet wird, wenn der Clientname nicht angegeben ist.
    - VERTEX_AI: Zur Integration in die Gemini Enterprise Agent Platform.
    - LOAD_BALANCER: Für die Integration mit Load Balancer as a Service Extension.
    - LANGCHAIN: Für die Integration mit LangChain.
    - GEMINI_ENTERPRISE_BUSINESS: Für die Integration mit Gemini Enterprise – Business-Version.
    - GOOGLE_MCP_SERVER: Für die Integration mit Google und von Google verwalteten MCP-Servern.
    - AGENT_GATEWAY: Für die Integration mit Agent Gateway.
    - GEMINI_ENTERPRISE_NON_BUSINESS Für die Integration mit anderen Gemini Enterprise-Versionen als Business (Standard, Plus, Frontline).
    - SECURE_WEB_PROXY Zur Integration in Secure Web Proxy.
  - CORRELATION_ID: Die eindeutige Kennung, die Sie für eine bestimmte Anfrage generieren.

Logs und zugehörige Ereignisse korrelieren

Wenn Sie Logs und Ereignisse für eine bestimmte Interaktion korrelieren möchten, können Sie eine Client-Korrelations-ID von Model Armor verwenden. Diese ID ist eine eindeutige Kennung, die Sie generieren (z. B. eine UUID), um eine bestimmte Anfrage in Ihrem System nachzuverfolgen. Wenn Sie eine Client-Korrelations-ID in einem cURL-Header festlegen möchten, verwenden Sie die Option -H, um einen benutzerdefinierten Header MA-Client-Correlation-Id in Ihre Anfrage einzufügen.

Hier ist das Beispielformat:

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

Ersetzen Sie Folgendes:

PROJECT_ID: die ID des Projekts, zu dem die Vorlage gehört.
LOCATION: der Speicherort der Vorlage.
TEMPLATE_ID: die ID der Vorlage.
USER_PROMPT: Der Prompt, der dem Modell zur Verfügung gestellt wurde.
MODEL_RESPONSE: Die vom Modell empfangene Antwort.

Plattformlogs im Vergleich zu Cloud-Audit-Logs

Es ist wichtig, zwischen den Logs, die Sie in einer Model Armor-Vorlage oder in den Mindesteinstellungen aktivieren können, und Cloud-Audit-Logs zu unterscheiden.

Funktion	Cloud-Audit-Logs	Plattform-Logs
Hauptzweck	Sicherheits-Auditing von API-Aufrufen (wer hat was wann getan) und Compliance-Monitoring.	Operatives Monitoring, Debugging und detaillierte Analyse von Bereinigungsereignissen.
Erfasste API-Vorgänge	Vorgänge zum Erstellen, Lesen, Aktualisieren, Löschen und Auflisten von Vorlagen und Etagenkonfigurationen. Bereinigungsoperationen (`SanitizeUserPrompt`, `SanitizeModelResponse`) werden als Metadaten protokolliert.	Erfasst alle Anfragen wie `SanitizeUserPrompt` und `SanitizeModelResponse`.
Nutzlast-Inhalte	Enthält nicht den tatsächlichen Nutzer-Prompt oder den Antworttext des Modells für Bereinigungsoperationen. Enthält Metadaten wie Aufrufer, Methode, Ressource, Zeitstempel und Status.	Enthält die vollständige Nutzlast, z. B. den Prompt- oder Antworttext, Filterergebnisse und andere Details der Bereinigung.
Aktivierungsmechanismus	Standard Google Cloud IAM-Audit-Log-Einstellungen für die Model Armor API. Für Datenzugriffslogs ist häufig eine explizite Aktivierung erforderlich. Audit-Logs für Vorlagenvorgänge werden automatisch generiert.	Wird aktiviert, indem das boolesche Flag `log_sanitize_operations` in den Vorlagenmetadaten oder Mindesteinstellungen festgelegt wird.
Bedingungen für die Protokollierung	Protokolliert automatisch Vorgänge zum Erstellen, Lesen, Aktualisieren, Löschen und Auflisten von Vorlagen und Etagenkonfigurationen.	Protokolliert Daten (Nutzer-Prompts und Modellantworten) für alle Datenebenenanfragen, unabhängig davon, ob Sensitive Data Protection aktiviert ist oder ob eine Filtereinstellung übereinstimmt.
Logvolumen und Kosten	Sie sind in der Regel kleiner und besser vorhersagbar und es gelten die standardmäßigen Cloud Logging-Preise.	Kann sehr groß und umfangreich sein, was aufgrund großer Nutzlasten und häufiger Nutzung zu erheblichen Cloud Logging-Kosten führen kann. Große Nutzlasten können in mehrere Logeinträge aufgeteilt werden.
Sicherheitsaspekte	Relativ sicher, da Nutzlastdaten nicht protokolliert werden. Für den Zugriff sind spezielle IAM-Berechtigungen erforderlich, z. B. bestimmte IAM-Rollen zum Aufrufen von Audit-Logs.	Enthält potenziell vertrauliche Nutzerdaten (personenidentifizierbare Informationen, vertrauliche Informationen). Für alle Nutzer mit Berechtigungen zum Ansehen von Logs zugänglich (z. B. `roles/logging.privateLogViewer`).
Empfehlung	Aktivieren Sie die Funktion für allgemeines Sicherheits- und Compliance-Monitoring.	Nicht für Produktions- oder sensible Daten empfohlen, sofern sie nicht sicher an ein zugriffsgesteuertes Ziel weitergeleitet werden (z. B. BigQuery mit strengem IAM).

Wenn Sie das Logging in einer Vorlage aktivieren, werden Roh-Prompts und ‑Antworten in Logging geschrieben. Diese Daten können vertrauliche Nutzerdaten, personenidentifizierbare Informationen (PII) oder vertrauliche Informationen enthalten. Hohes Traffic-Aufkommen und große Nutzlasten können zu erheblichen Logging-Kosten und potenziell großen Logvolumen führen, die Grenzwerte überschreiten und eine sorgfältige Verwaltung erfordern.

Aufruferidentität in Audit-Logs

Wenn Sie Audit-Logs aufrufen, wird die Identität des Aufrufers in Cloud-Audit-Logs im Feld protoPayload.authenticationInfo.principalEmail erfasst. Die aufgezeichnete Identität hängt davon ab, wie die Model Armor API aufgerufen wird:

Direkter API-Aufruf: Wenn ein Nutzer oder Dienstkonto die Model Armor API direkt aufruft (z. B. über gcloud, Clientbibliotheken oder REST APIs), enthält principalEmail die E-Mail-Adresse dieses Nutzers oder Dienstkontos.
Aufruf über einen integrierten Google Cloud Dienst: principalEmailWenn Model Armor in einen anderenGoogle Cloud Dienst wie die Gemini Enterprise Agent Platform eingebunden ist, enthält principalEmaildie Identität dieses Dienstes, die in der Regel ein von Google verwaltetes Dienstkonto ist. Dienst-Agents haben das Format service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. Wenn ein Aufruf beispielsweise von einer Funktion der Gemini Enterprise Agent Platform stammt, wird ein Dienst-Agent der Gemini Enterprise Agent Platform verwendet.

Wenn Sie zwischen Anrufern unterscheiden möchten, prüfen Sie das Feld principalEmail im Audit-Logeintrag. Bei Anrufen von Endnutzern oder von Nutzern verwalteten Dienstkonten werden deren E‑Mail-Adressen angezeigt. Bei Anrufen über andere Google Cloud Dienste werden E‑Mail-Adressen von von Google verwalteten Dienstkonten angezeigt.

Logging konfigurieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Erforderliche Berechtigungen erhalten

APIs aktivieren

Console

gcloud

API-Endpunktüberschreibung mit der gcloud CLI festlegen

Traffic-Bereinigung einrichten

Logging in Vorlagen konfigurieren

Console

REST

Python

Logging in den Mindesteinstellungen konfigurieren

Console

gcloud

REST

Python

Model Armor-Logs ansehen und filtern

Logs und zugehörige Ereignisse korrelieren

Plattformlogs im Vergleich zu Cloud-Audit-Logs

Aufruferidentität in Audit-Logs

Logging konfigurieren