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 Aktivitäten zur Verwaltung von Ressourcen und Administratoren aufzuzeichnen. Weitere Informationen finden Sie unter Audit-Logging für Model Armor.

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

Hinweis

Führen Sie diese Aufgaben aus, bevor Sie die restlichen Aufgaben in diesem Dokument erledigen.

Erforderliche Berechtigungen abrufen

Bitten Sie Ihren Administrator, Ihnen die Model Armor-Administrator (roles/modelarmor.admin) IAM-Rolle 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

Aktivieren Sie die Model Armor API.
Erforderliche Rollen zum Aktivieren von APIs
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, in dem Sie Model Armor aktivieren möchten.

gcloud

Führen Sie vor Beginn die folgenden Schritte mit der Google Cloud CLI und der Model Armor API aus:

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 von Google verwaltete MCP-Server (Model Context Protocol) die Traffic-Bereinigung über die Mindesteinstellungen ein. Weitere Informationen finden Sie unter Schutz für von Google und Google Cloud extern verwaltete MCP Server konfigurieren. (Vorschau)

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, der das Logging der Vorgänge zum Erstellen, Aktualisieren, Lesen und Löschen von Vorlagen aktiviert.
log_sanitize_operations: Ein boolescher Wert, der das Logging der Bereinigungsvorgänge aktiviert. Die Logs enthalten den Prompt und die Antwort, die Bewertungsergebnisse von Model Armor und zusätzliche Metadatenfelder.

Console

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

Zu Model Armor
Prüfen Sie, ob Sie das Projekt sehen, in dem 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

Mit den Mindesteinstellungen werden grundlegende Sicherheitsfilter für alle Gemini-Modelle in Vertex AI und von Google verwaltete Model Context Protocol (MCP)-Server (Vorschau) in Ihrem Projekt festgelegt. Wenn Sie die Mindesteinstellungen für Model Armor aktualisieren, können Sie angeben, ob Bereinigungsvorgänge von Model Armor protokolliert werden sollen.

Sie können das Logging von Bereinigungsvorgängen für Vertex AI und von Google verwaltete MCP-Server einzeln aktivieren. Wenn aktiviert, enthalten die Logs den Prompt und die Antwort (für Vertex AI) oder Tool-Aufrufe und Tool-Antworten (für MCP-Server), die Bewertungsergebnisse von Model Armor und zusätzliche Metadatenfelder.

Console

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

Zu Model Armor
Prüfen Sie, ob Sie das Projekt sehen, in dem Sie Model Armor aktiviert haben.
Rufen Sie den Tab Mindesteinstellungen auf.
Wählen Sie im Abschnitt Logs die Option Von Google verwalteter MCP aus.
Klicken Sie auf Speichern.

gcloud

Mit einem der folgenden Flags können Sie das Logging von Bereinigungsvorgängen in den Mindesteinstellungen verwalten.

Verwenden Sie eines der folgenden Flags, um das Logging zu aktivieren:

Verwenden Sie für Vertex AI das Flag --enable-vertex-ai-cloud-logging.
Verwenden Sie für von Google verwaltete MCP-Server das Flag --enable-google-mcp-server-cloud-logging.

Verwenden Sie eines der folgenden Flags, um das Logging zu deaktivieren:

Verwenden Sie für Vertex AI das Flag --no-enable-vertex-ai-cloud-logging.
Verwenden Sie für von Google verwaltete MCP-Server das Flag --no-enable-google-mcp-server-cloud-logging.

**Hinweis**: Sie können das Logging für einen oder beide Dienste mit einem einzigen Befehl aktivieren oder deaktivieren.

Mit dem folgenden Beispielbefehl wird das Logging von Bereinigungsvorgängen für Vertex AI und von Google verwaltete MCP-Server 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

Mit der Methode UpdateFloorSetting können Sie die Mindesteinstellungen aktualisieren, um das Logging von Bereinigungsvorgängen zu aktivieren. Wenn Sie diese Methode verwenden, müssen Sie den entsprechenden Parameter auf „true“ setzen, um das Logging zu aktivieren:

Setzen Sie für Vertex AI aiPlatformFloorSetting.enableCloudLogging auf true.
Setzen Sie für von Google verwaltete MCP-Server googleMcpServerFloorSetting.enableCloudLogging auf true.

Mit dem folgenden Beispielbefehl wird das Logging von Bereinigungsvorgängen für Vertex AI und von Google verwaltete MCP-Server 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.

Logs ansehen

So rufen Sie Model Armor-Logs mit dem Log-Explorer in Logging auf:

Rufen Sie in der Google Cloud Console den Log-Explorer auf. Weitere Informationen finden Sie unter Logs mit dem Log-Explorer aufrufen.
Filtern Sie die Logs nach dem Dienstnamen modelarmor.googleapis.com.
Suchen Sie nach Einträgen, die sich auf die Vorgänge beziehen, die Sie in Ihrer Vorlage aktiviert haben. Eine Liste aller Dienstnamen und überwachten Ressourcentypen, finden Sie unter Überwachte Ressourcen und Dienste.

Model Armor-Logs filtern

Sie können Loglabels verwenden, um die Model Armor-Logs nach den Bereinigungsvorgängen und dem Vorlagenlogging zu filtern. Führen Sie dazu folgende Schritte aus:

Führen Sie die folgende Abfrage im Log-Explorer aus, um die Logs der Bereinigungsvorgänge zu filtern.

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"

Um die Logs der Bereinigungsvorgänge weiter zu verfeinern, können Sie in der Abfrage einen Clientnamen oder eine Korrelations-ID angeben.

Clientname verwenden: Wenn Model Armor in Dienste wie Vertex AI 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:

labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"

Ersetzen Sie Folgendes:

CLIENT_NAME: der Name Ihres Clients, z. B. VERTEX_AI.
CORRELATION_ID: die eindeutige ID, 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 verwenden. Diese ID ist eine eindeutige Kennung, 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 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.

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

Logs ansehen

Model Armor-Logs filtern

Logs und zugehörige Ereignisse korrelieren

Logging konfigurieren