Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Logging konfigurieren

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

Vorgänge, die eine Vorlage erstellen, aktualisieren oder löschen
Vorgänge, die einen Nutzer-Prompt oder eine Modellantwort bereinigen

Model Armor verwendet Audit-Logs, um administrative Aktivitäten und Aktivitäten zur Ressourcenverwaltung aufzuzeichnen. Weitere Informationen finden Sie unter Audit-Logging für Model Armor.

Informationen zu den Logpreisen finden Sie unter Cloud Logging Preise. Abhängig vom Volumen der verarbeiteten Daten können auch Nutzungsgebühren für Model Armor anfallen. Weitere Informationen finden Sie unter Model Armor Preise .

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen.

Erforderliche Berechtigungen abrufen

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

Die Model Armor API aktivieren
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 Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen.
API aktivieren
Wählen Sie das Projekt aus, in dem Sie Model Armor aktivieren möchten.

gcloud

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

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.
Legen Sie die API-Endpunktüberschreibung mit der gcloud CLI fest.

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 API-Endpunktüberschreibung 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

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

Logging in Vorlagen konfigurieren

In Vorlagen werden die Filter und Schwellenwerte 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 sehen, 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 Mindesteinstellungen konfigurieren

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

Sie können das Logging von Bereinigungsvorgängen für die Agent Platform und für Google- und Google Cloud MCP-Server einzeln aktivieren. Wenn aktiviert, enthalten die Logs 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.

In den folgenden Beispielen wird gezeigt, wie Sie das Logging von Bereinigungsvorgängen sowohl für die Agent Platform als auch für Google und Google Cloud MCP-Server aktivieren.

Console

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

Zu Model Armor
Prüfen Sie, ob Sie das Projekt sehen, für das Sie Model Armor aktiviert haben.
Rufen Sie den Tab Mindesteinstellungen auf.
Wählen Sie im Abschnitt 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 --enable-google-mcp-server-cloud-logging Flag, 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 das Logging zu deaktivieren.

Der folgende Beispielbefehl aktiviert das Logging von Bereinigungsvorgängen für sowohl die Agent Platform als auch Google und Google Cloud MCP-Server:

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

Legen Sie für die Aktivierung des Loggings in der UpdateFloorSetting Methode für die Agent Platform aiPlatformFloorSetting.enableCloudLogging auf true und für Google- und Google Cloud MCP-Server googleMcpServerFloorSetting.enableCloudLogging auf true fest.

Der folgende Beispielbefehl aktiviert das Logging von Bereinigungsvorgängen sowohl für die Agent Platform als auch für Google und Google Cloud MCP-Server:

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

Verwenden Sie den Log-Explorer in Logging, um Model Armor-Logs anzusehen und zu filtern:

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 zu Bereinigungsvorgängen:
```
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"
```
  Um die Logs zu Bereinigungsvorgängen weiter zu verfeinern, 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 ist, können Sie den Clientnamen verwenden, um Logs für eine bestimmte Einbindung 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 Client name nicht angegeben ist.
    - VERTEX_AI: für die Einbindung in die Gemini Enterprise Agent Platform.
    - LOAD_BALANCER: für die Einbindung mit Load Balancer als Diensterweiterung.
    - LANGCHAIN: für die Einbindung in LangChain.
    - GEMINI_ENTERPRISE_BUSINESS: für die Einbindung in Gemini Enterprise – Business-Version.
    - GOOGLE_MCP_SERVER: für die Einbindung in Google- und von Google verwaltete MCP-Server.
    - AGENT_GATEWAY: für die Einbindung in Agent Gateway.
    - GEMINI_ENTERPRISE_NON_BUSINESS : für die Einbindung in andere Gemini Enterprise-Versionen als Business (Standard, Plus, Frontline).
    - SECURE_WEB_PROXY : für die Einbindung in Secure Web Proxy.
  - CORRELATION_ID: die eindeutige ID, die Sie für eine bestimmte Anfrage generieren.

Logs und zugehörige Ereignisse korrelieren

Um Logs und Ereignisse für eine bestimmte Interaktion zu korrelieren, können Sie eine Model Armor-Client-Korrelations-ID verwenden. Diese ID ist eine eindeutige ID, die Sie generieren (z. B. eine UUID), mit der eine bestimmte Anfrage in Ihrem System verfolgt wird. 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 bereitgestellt wurde.
MODEL_RESPONSE: die Antwort, die vom Modell empfangen wurde.

Plattform-Logs 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	Sicherheitsaudit von API-Aufrufen (wer hat was wann getan) und Compliance-Monitoring.	Betriebsmonitoring, Debugging und detaillierte Analyse von Bereinigungsereignissen.
Erfasste API-Vorgänge	Vorgänge zum Erstellen, Lesen, Aktualisieren, Löschen und Auflisten von Vorlagen und Mindesteinstellungen. Bereinigungsvorgänge (`SanitizeUserPrompt`, `SanitizeModelResponse`) werden als Metadaten protokolliert.	Erfasst alle Anfragen wie `SanitizeUserPrompt` und `SanitizeModelResponse`.
Nutzlastinhalt	Enthält nicht den tatsächlichen Text des Nutzer-Prompts oder der Modellantwort für Bereinigungsvorgänge. 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 mäßige IAM-Audit-Log-Einstellungen für die Model Armor API. Für Logs zum Datenzugriff ist oft eine explizite Aktivierung erforderlich. Audit-Logs für Vorlagenvorgänge werden automatisch generiert.	Aktiviert durch Festlegen des booleschen Flags `log_sanitize_operations` in den Vorlagenmetadaten oder Mindesteinstellungen.
Logging-Bedingungen	Protokolliert automatisch Vorgänge zum Erstellen, Lesen, Aktualisieren, Löschen und Auflisten von Vorlagen und Mindesteinstellungen.	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	In der Regel kleiner und besser vorhersehbar, es fallen die Standardpreise für Cloud Logging an.	Kann sehr groß und umfangreich sein, was aufgrund großer Nutzlasten und häufiger Verwendung zu erheblichen Cloud Logging-Kosten führen kann. Große Nutzlasten können in mehrere Logeinträge aufgeteilt werden.
Sicherheitsaspekte	Relativ sicher, da keine Nutzlastdaten protokolliert werden. Für den Zugriff sind spezielle IAM-Berechtigungen erforderlich (z. B. bestimmte IAM-Rollen zum Aufrufen von Audit-Logs).	Enthält potenziell sensible Nutzerdaten (PII, vertrauliche Informationen). Für alle Nutzer mit Berechtigungen zum Aufrufen von Logs zugänglich (z. B. `roles/logging.privateLogViewer`).
Empfehlung	Für allgemeines Sicherheits- und Compliance-Monitoring aktivieren.	Nicht für Produktions- oder sensible Daten empfohlen, es sei denn, sie werden sicher an eine zugriffsgeschützte Senke weitergeleitet (z. B. BigQuery mit strengen IAM-Einstellungen).

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

Aufruferidentität in Audit-Logs

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

Direkter API-Aufruf: Wenn ein Nutzer oder ein Dienstkonto die Model Armor API direkt aufruft (z. B. mit gcloud, Client Bibliotheken oder REST APIs), enthält principalEmail die E‑Mail-Adresse dieses Nutzers oder Dienstkontos.
Aufruf über einen eingebundenen Google Cloud Dienst: Wenn Model Armor in einen anderen Google Cloud Dienst wie die Gemini Enterprise Agent Platform eingebunden ist, enthält principalEmail die Identität dieses Dienstes, die in der Regel ein von Google verwaltetes Dienst konto ist. Das Format für Dienst-Agents ist service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. Bei einem Aufruf, der von einer Funktion der Gemini Enterprise Agent Platform stammt, wird beispielsweise ein Dienst-Agent der Gemini Enterprise Agent Platform verwendet.

Um zwischen Aufrufern zu unterscheiden, prüfen Sie das Feld principalEmail im Audit-Logeintrag. Bei Aufrufen von Endnutzern oder von Nutzern verwalteten Dienstkonten werden deren E‑Mail-Adressen angezeigt, während bei Aufrufen über andere Google Cloud Dienste die E‑Mail-Adressen von von Google verwalteten Dienstkonten angezeigt werden.

Nächste Schritte

Model Armor-Logs mit Gemini Enterprise-Logs korrelieren

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

Hinweis

Erforderliche Berechtigungen abrufen

APIs aktivieren

Console

gcloud

API-Endpunktüberschreibung mit der gcloud CLI festlegen

Traffic-Bereinigung einrichten

Logging in Vorlagen konfigurieren

Console

REST

Python

Logging in Mindesteinstellungen konfigurieren

Console

gcloud

REST

Python

Model Armor-Logs ansehen und filtern

Logs und zugehörige Ereignisse korrelieren

Plattform-Logs im Vergleich zu Cloud-Audit-Logs

Aufruferidentität in Audit-Logs

Nächste Schritte

Logging konfigurieren