In diesem Dokument wird beschrieben, wie Sie Model Armor so konfigurieren, dass die folgenden Vorgänge protokolliert werden:
- Vorgänge, bei denen eine Vorlage erstellt, aktualisiert oder gelöscht wird
- Vorgänge, die einen Nutzer-Prompt oder eine Modellantwort bereinigen
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 verarbeitetem Datenvolumen können auch Nutzungsgebühren für Model Armor anfallen. Weitere Informationen finden Sie unter Model Armor – Preise.
Hinweis
Führen Sie zuerst die folgenden Aufgaben aus.
Erforderliche Berechtigungen einholen
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 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, falls sie noch nicht aktiviert ist.
Rollen, die zum Aktivieren von APIs erforderlich sind
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 RollenWählen Sie das Projekt aus, in dem 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:
Installieren Sie die Google Cloud CLI und melden Sie sich dann mit Ihrer föderierten Identität in der gcloud CLI an. Nach der Anmeldung initialisieren Sie die Google Cloud CLI mit dem folgenden Befehl:
gcloud initAktivieren Sie die Model Armor API, falls sie noch nicht aktiviert ist:
Rollen, die zum Aktivieren von APIs erforderlich sind
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 Rollengcloud services enable modelarmor.googleapis.com
API-Endpunktüberschreibung mit der gcloud CLI festlegen
Dieser Schritt ist nur erforderlich, wenn Sie die gcloud CLI verwenden. Legen Sie die API-Endpunktüberschreibung fest, 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 oder Multiregion, 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 die Mindesteinstellungen ein. Weitere Informationen finden Sie unter Schutz für Google- undGoogle Cloud MCP-Server konfigurieren.
Logging in Vorlagen konfigurieren
Vorlagen definieren die Filter und Schwellenwerte für verschiedene Sicherheitskategorien. 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 Vorlagenvorgänge zum Erstellen, Aktualisieren, Lesen und Löschen 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.
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 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 Standort der Vorlage.TEMPLATE_ID: die ID der Vorlage.
Python
Wenn Sie diesen Code ausführen möchten, 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 Standort der Vorlage.TEMPLATE_ID: die ID der Vorlage.
Logging in den Mindesteinstellungen konfigurieren
Wenn Sie Mindesteinstellungen für den 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 Armor aktualisieren, können Sie angeben, ob Model Armor Bereinigungsvorgänge protokollieren soll.
Sie können das Logging von Bereinigungsvorgängen für die Agent-Plattform und für MCP-Server von Google und Google Cloud einzeln aktivieren. Wenn aktiviert, enthalten die Logs den Prompt und die Antwort (für die Agent Platform) oder Toolaufrufe und Toolantworten (für MCP-Server), die Bewertungsergebnisse von Model Armor und zusätzliche Metadatenfelder.
In den folgenden Beispielen wird gezeigt, wie Sie die Protokollierung von Bereinigungsvorgängen sowohl für die Agent-Plattform als auch für die MCP-Server von Google und Google Cloud aktivieren.
Console
Rufen Sie in der Google Cloud Console die Seite Model Armor auf.
Prüfen Sie, ob Sie das Projekt aufrufen, für das Sie Model Armor aktiviert haben.
Rufen Sie den Tab Floor Settings (Mindestpreiseinstellungen) 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 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 das Logging zu deaktivieren.
Mit dem folgenden Beispielbefehl wird das Logging von Bereinigungsvorgängen sowohl für die Agent Platform als auch für Google- und Google Cloud 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
Wenn Sie das Logging aktivieren möchten, setzen Sie in der Methode UpdateFloorSetting für die Agent Platform aiPlatformFloorSetting.enableCloudLogging auf true und für Google- und Google Cloud -MCP-Server googleMcpServerFloorSetting.enableCloudLogging auf true.
Mit dem folgenden Beispielbefehl wird das Logging von Bereinigungsvorgängen sowohl für die Agent Platform als auch für Google- und Google Cloud 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
Wenn Sie diesen Code ausführen möchten, 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 aufzurufen und zu filtern:
Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.
Weitere Informationen finden Sie unter Logs mit dem Log-Explorer aufrufen.
Geben Sie im Abfragebereich 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"Wenn Sie die Logs für Bereinigungsvorgänge weiter eingrenzen möchten, können Sie in der Abfrage einen Clientnamen, eine Korrelations-ID oder ein Auswertungslabel für eine Ausschlussregel (Vorabversion) angeben:
Clientname: 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 Integration zu filtern.
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"Mit einer Korrelations-ID:
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: Für die Einbindung in die Gemini Enterprise Agent Platform.LOAD_BALANCER: Für die Integration mit einem Load Balancer als Diensterweiterung.LANGCHAIN: Für die Integration in LangChain.GEMINI_ENTERPRISE_BUSINESS: Für die Einbindung in Gemini Enterprise – Business-Version.GOOGLE_MCP_SERVER: Für die Integration 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 und Frontline).SECURE_WEB_PROXY: Für die Integration in Secure Web Proxy.
CORRELATION_ID: die eindeutige Kennung, die Sie für eine bestimmte Anfrage generieren.
Mit Ausschlussregel-Labels (Vorschau): Wenn eine Ausschlussregel ein Filterergebnis überschreibt oder Model Armor die Auswertung der Ausschlussregel überspringt, füllt Model Armor die folgenden optionalen
labels-Felder auf oberster Ebene inmodelarmor.googleapis.com/SanitizeOperation-Logeinträgen aus:modelarmor.googleapis.com/exclusion_rule_overridden_filters: Eine durch Kommas getrennte Liste von Filtern, derenMATCH_FOUND- oderEXECUTION_SKIPPED-Ergebnisse mitNO_MATCH_FOUNDüberschrieben wurden, weil eine Ausschlussregel zutraf.modelarmor.googleapis.com/exclusion_rule_skipped_filters: eine durch Kommas getrennte Liste von Filtern, deren Ausschlussregel-Auswertung übersprungen wurde (z. B. wenn eine Eingabe das Limit für die Ausschluss-Nutzlast von 130.000 Tokens (0,5 MB) überschreitet).
Verwenden Sie die folgenden Beispielabfragen, um Bereinigungslogs nach Ausschlussregellabels zu filtern:
- So finden Sie Anfragen, bei denen ein Filterergebnis durch eine Ausschlussregel überschrieben wurde:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters":"FILTER_NAME"- So finden Sie Anfragen, bei denen die Erkennung von Prompt Injection und Jailbreaking durch eine Ausschlussregel überschrieben wurde:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters"="PROMPT_INJECTION_AND_JAILBREAK"- So finden Sie Anfragen, bei denen die Auswertung der Ausschlussregel übersprungen wurde:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"Ersetzen Sie
FILTER_NAMEdurch den Namen des Filters (PROMPT_INJECTION_AND_JAILBREAKoderRESPONSIBLE_AI).
Logs und zugehörige Ereignisse korrelieren
Wenn Sie Logs und Ereignisse für eine bestimmte Interaktion korrelieren möchten, können Sie eine Model Armor-Client-Korrelations-ID verwenden. Diese ID ist eine eindeutige Kennung, die Sie generieren (z. B. eine UUID), um eine bestimmte Anfrage in Ihrem System zu verfolgen. Wenn Sie eine Client-Korrelations-ID in einem curl-Header festlegen möchten, verwenden Sie die Option -H, um einen benutzerdefinierten MA-Client-Correlation-Id-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 Standort der Vorlage.TEMPLATE_ID: die ID der Vorlage.USER_PROMPT: der Prompt, der dem Modell bereitgestellt wird.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 grundlegenden Einstellungen aktivieren können, und Cloud-Audit-Logs zu unterscheiden.
| Funktion | Cloud-Audit-Logs | Plattform-Logs |
|---|---|---|
| Hauptzweck | Sicherheitsaudits von API-Aufrufen (wer hat was wann getan) und Compliance-Monitoring. | Betriebsmonitoring, Fehlerbehebung und detaillierte Analyse von Bereinigungsereignissen. |
| Erfasste API-Vorgänge | Vorgänge zum Erstellen, Lesen, Aktualisieren, Löschen und Auflisten von Vorlagen und Mindestpreiseinstellungen. Bereinigungsvorgänge (SanitizeUserPrompt, SanitizeModelResponse) werden als Metadaten protokolliert. |
Erfasst alle Anfragen wie SanitizeUserPrompt und SanitizeModelResponse. |
| Payload-Inhalt | Enthält nicht den tatsächlichen Nutzerprompt oder Modellantworttext 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 | Standardmäßige Google Cloud IAM-Audit-Log-Einstellungen für die Model Armor API. Datenzugriffslogs müssen oft explizit aktiviert werden. Audit-Logs für Vorlagenvorgänge werden automatisch generiert. | Wird aktiviert, indem das boolesche Flag log_sanitize_operations in den Vorlagenmetadaten oder den Mindesteinstellungen festgelegt wird. |
| Logging-Bedingungen | Protokolliert automatisch Vorgänge zum Erstellen, Lesen, Aktualisieren, Löschen und Auflisten von Vorlagen und Mindestpreiseinstellungen. | 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, wobei die standardmäßigen Cloud Logging-Preise anfallen. | 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. Erfordert spezielle IAM-Berechtigungen für den Zugriff (z. B. bestimmte IAM-Rollen zum Aufrufen von Audit-Logs). | Enthält potenziell vertrauliche Nutzerdaten (personenidentifizierbare Informationen, vertrauliche Informationen). Zugänglich für alle Nutzer mit Berechtigungen zum Aufrufen von Logs (z. B. roles/logging.privateLogViewer). |
| Empfehlung | Aktivieren Sie diese Option für allgemeines Sicherheits- und Compliance-Monitoring. | Nicht für Produktions- oder sensible Daten empfohlen, es sei denn, sie werden sicher an eine zugriffsgesteuerte Senke weitergeleitet (z. B. BigQuery mit striktem 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 oder vertrauliche Informationen enthalten. Hoher Traffic und große Nutzlasten können zu erheblichen Logging-Kosten führen und dazu, dass große Logvolumen die Limits überschreiten und sorgfältig verwaltet werden müssen.
Anruferidentitä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 Dienstkonto die Model Armor API direkt aufruft (z. B. über
gcloud, Clientbibliotheken oder REST APIs), enthältprincipalEmaildie E-Mail-Adresse dieses Nutzers oder Dienstkontos. - Aufruf über einen integrierten Google Cloud -Dienst: Wenn 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. Das Format für Dienst-Agents istservice-PROJECT_NUMBER@SERVICE_NAME.. Ein Aufruf, der von einer Gemini Enterprise Agent Platform-Funktion stammt, verwendet beispielsweise einen Gemini Enterprise Agent Platform-Dienst-Agenten.
Wenn Sie zwischen Aufrufern unterscheiden möchten, prüfen Sie das Feld principalEmail im Audit-Logeintrag. Bei Aufrufen von Endnutzern oder nutzerverwalteten 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.