Model Armor in die Gemini Enterprise Agent Platform einbinden

In diesem Dokument wird beschrieben, wie Sie Model Armor konfigurieren, um Gemini-Modelle auf der Gemini Enterprise Agent Platform zu schützen, indem Sie Prompts und Antworten prüfen. Wenn Model Armor in die Gemini Enterprise Agent Platform eingebunden ist, werden Prompts abgefangen, bevor sie die Gemini-Modelle erreichen, und Antworten werden abgefangen, bevor sie von Ihrer Anwendung empfangen werden. Je nach Konfiguration ruft die Gemini Enterprise Agent Platform den Model Armor-Dienst auf, der Traffic prüft oder blockiert, der gegen Ihre definierten Richtlinien verstößt. Dabei werden Sicherheitsmaßnahmen wie Prompt Injection- und Jailbreak-Erkennung, verantwortungsbewusste Anwendung von KI-Filter und Sensitive Data Protection erzwungen. Sie können diese Einbindung entweder mit Mindesteinstellungen für den Schutz auf Projektebene oder mit Vorlagen für den Schutz pro Anfrage konfigurieren.

Model Armor bietet Prompt- und Antwortschutz in der Gemini API in Vertex AI für die Methode generateContent. Sie müssen Cloud Logging aktivieren, um die Ergebnisse der Bereinigung von Prompts und Antworten zu sehen.

Neben dem Schutz direkter REST-Aufrufe an den Gemini Enterprise Agent Platform-Dienst, können Sie Model Armor auch verwenden, um andere Schnittstellen zu schützen, die Zugriff auf die Gemini API in Vertex AI bieten, z. B. die Google Generative AI SDKs oder Firebase AI Logic SDKs.

Beschränkungen

Beachten Sie bei der Einbindung von Model Armor in die Gemini Enterprise Agent Platform die folgenden Einschränkungen:

• Wenn Model Armor eine Sensitive Data Protection-Vorlage zum Scannen von Prompts oder Antworten verwendet, wird geprüft, ob der Inhalt den in der Vorlage definierten Filterkriterien entspricht. Wenn eine Übereinstimmung gefunden wird, kennzeichnet Model Armor, dass der Inhalt den Sensitive Data Protection-Filter ausgelöst hat. Sensitive Data Protection de-identifiziert die Daten zwar anhand der Vorlagenkonfiguration, Model Armor gibt die de-identifizierten Daten (z. B. maskierte, geschwärzte oder gehashte Inhalte) aber nicht zur weiteren Verarbeitung an die Gemini Enterprise Agent Platform zurück. Wenn der Erzwingungstyp INSPECT_AND_BLOCK ist, gibt Model Armor stattdessen eine Blockierungsentscheidung aus, um zu verhindern, dass sensible Daten weiterverarbeitet werden.
• Das Bereinigen von Prompts und Antworten, die Dokumente enthalten, wird nicht unterstützt.
• Wenn die Gemini Enterprise Agent Platform eine Anfrage an eine Region weiterleitet, in der die angegebene Model Armor-Vorlage nicht vorhanden ist, schlägt die Anfrage mit dem Fehler Template not found fehl.

• Die Gemini Enterprise Agent Platform überspringt den Model Armor-Bereinigungsschritt und verarbeitet die Anfrage unter den folgenden Bedingungen weiter:

  • Model Armor ist in einer Region nicht verfügbar, in der die Gemini Enterprise Agent Platform vorhanden ist.
  • Model Armor ist vorübergehend nicht erreichbar.
  • In Model Armor ist ein Fehler aufgetreten.

  In all diesen Fällen können gelegentlich ungeprüfte Prompts oder Antworten angezeigt werden, da die Anfrage ohne Bereinigung von Prompts und Antworten fortgesetzt wird.

  Obwohl die Integration für Hochverfügbarkeit bei Verbindungsfehlern konzipiert ist, werden im Modus INSPECT_AND_BLOCK weiterhin Konfigurationsfehler wie Berechtigungs- oder Kontingentprobleme gemeldet.

Hinweis

• Weisen Sie dem Dienstkonto der Gemini Enterprise Agent Platform die Rolle Model Armor-Nutzer zu.

  gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:[e-mail]' --role='roles/modelarmor.user'

  Ersetzen Sie Folgendes:

  • PROJECT_ID durch Ihre Google Cloud Projekt-ID.
  • PROJECT_NUMBER durch Ihre Google Cloud Projektnummer.

• Aktivieren Sie die Model Armor API.

• Legen Sie die Überschreibung des API-Endpunkt mit der gcloud CLI fest.

Konfigurieren, wie Model Armor die Gemini Enterprise Agent Platform schützt

Sie können auf zwei Arten konfigurieren, wie Model Armor die Gemini Enterprise Agent Platform schützt:

• Vorlagen für den Schutz pro Anfrage verwenden: Mit diesem Ansatz haben Sie eine detaillierte Kontrolle, da Sie auf jeden generateContent API-Aufruf an Gemini-Modelle auf der Gemini Enterprise Agent Platform eine bestimmte Vorlage anwenden können.
• Mindesteinstellungen für den Schutz auf Projektebene verwenden: Mit diesem Ansatz wird ein grundlegender Schutz erzwungen, indem Mindesteinstellungen auf alle generateContent API Aufrufe an Gemini-Modelle auf der Gemini Enterprise Agent Platform in Ihrem Projekt angewendet werden.

Definieren Sie den Erzwingungstyp, um festzulegen, ob Verstöße nur geprüft oder auch blockiert werden sollen.

Konfiguration pro Anfrage mit Vorlagen

Mit Vorlagen können Sie konfigurieren, wie Model Armor Prompts und Antworten prüft, und Konfigurationen für Sicherheitsfilter definieren. Sie müssen zuerst Vorlagen erstellen und diese dann mit der Methode generateContent von Gemini verwenden. Weitere Informationen zu Vorlagen finden Sie unter Model Armor-Vorlagen erstellen und verwalten.

Nachdem Sie die Model Armor-Vorlage konfiguriert haben, übergeben Sie die Vorlagen-ID als Parameter, wenn Sie mit der Methode generateContent einen Aufruf an die Gemini API senden. Die Gemini Enterprise Agent Platform leitet die Anfrage zur Verarbeitung an Model Armor weiter.

Wenn Sie bestimmte Vorlagen auf einen einzelnen generateContent-Aufruf anwenden möchten, fügen Sie das Objekt modelArmorConfig in Ihre Anfrage ein.

• promptTemplateName: Der Ressourcenname der Model Armor-Vorlage zum Bereinigen des Prompts.
• responseTemplateName: Der Ressourcenname der Model Armor-Vorlage zum Bereinigen der Antwort.

Das folgende Codebeispiel zeigt die Anfrage an die Methode generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "[YOUR PROMPT HERE]"
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
},
 "model_armor_config": {
        "prompt_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "response_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
        }
}'

Ersetzen Sie Folgendes:

• PROJECT_ID durch die Google Cloud Projekt-ID.
• LOCATION durch den Google Cloud Standort des Gemini-Endpunkts. Die unterstützten Standorte sind europe-west1, europe-west2, europe-west3, asia-southeast1 und asia-south1.
• TEMPLATE_ID durch die Model Armor-Vorlagen-ID.

Das folgende Codebeispiel zeigt die Antwort der Methode generateContent.

{
  "promptFeedback": {
    "blockReason": "MODEL_ARMOR",
    "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
  },
  "usageMetadata": {
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Erzwingungstyp für Vorlagen definieren

Legen Sie den Erzwingungstyp fest, um zu konfigurieren, wie Model Armor Erkennungen verarbeitet.

Das folgende Beispiel zeigt die Model Armor-Vorlagenkonfiguration mit dem Erzwingungstyp Inspect only.

export TEMPLATE_CONFIG='{
   "filter_config": {
    "rai_settings": {
     "rai_filters": [{
       "filter_type": "HATE_SPEECH",
       "confidence_level": "MEDIUM_AND_ABOVE"
      }, {
      "filter_type": "HARASSMENT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }, {
      "filter_type": "DANGEROUS",
      "confidence_level": "MEDIUM_AND_ABOVE"
    },{
      "filter_type": "SEXUALLY_EXPLICIT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }]
  },
  "pi_and_jailbreak_filter_settings": {
    "filter_enforcement": "ENABLED",
    "confidence_level": "LOW_AND_ABOVE"
  },
  "malicious_uri_filter_settings": {
    "filter_enforcement": "ENABLED"
  }
 },
 "template_metadata": {
    "enforcement_type": "INSPECT_ONLY",
    "multi_language_detection": {
      "enable_multi_language_detection": true
    }
  }
}'

curl -X POST \
    -d "$TEMPLATE_CONFIG"  \
    -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 durch die ID des Projekts, zu dem die Vorlage gehört.
• TEMPLATE_ID durch die ID der zu erstellenden Vorlage.
• LOCATION durch den Standort der Vorlage.

Konfiguration auf Projektebene mit Mindesteinstellungen

Mindesteinstellungen definieren einen Mindestschutz, der auf alle generateContent-Aufrufe der Gemini Enterprise Agent Platform in einem Projekt angewendet wird, auch wenn der Parameter modelArmorConfig in der API-Anfrage nicht angegeben ist. Informationen zum Einrichten von Mindesteinstellungen finden Sie unter Mindesteinstellungen konfigurieren.

Wenn Sie die Einbindung von Model Armor und der Gemini Enterprise Agent Platform aktivieren möchten, legen Sie Mindesteinstellungen nur auf Projektebene mit der API oder der Google Cloud Console fest.

Führen Sie den folgenden Befehl aus, um Mindesteinstellungen mit der Einbindung der Gemini Enterprise Agent Platform zu konfigurieren:

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --add-integrated-services=VERTEX_AI

Mit diesem Befehl wird standardmäßig der Erzwingungsmodus INSPECT_ONLY aktiviert. Wenn Sie den Modus in INSPECT_AND_BLOCK ändern möchten, führen Sie den folgenden Befehl aus:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

Führen Sie den folgenden Befehl aus, um die Gemini Enterprise Agent Platform aus den eingebundenen Diensten zu entfernen:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --remove-integrated-services=VERTEX_AI

Führen Sie den folgenden Befehl aus, um alle konfigurierten eingebundenen Dienste aus den Mindesteinstellungen zu entfernen:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --clear-integrated-services

Ersetzen Sie PROJECT_ID durch die ID des Projekts für die Mindesteinstellungen.

REST

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{"filterConfig" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Ersetzen Sie PROJECT_ID durch die ID des Projekts, das die Mindesteinstellungen enthält.

Nachdem Sie die Mindesteinstellungen so konfiguriert haben, dass die Gemini Enterprise Agent Platform bereinigt wird, bereinigt Model Armor alle generateContent-API-Aufrufe an die Gemini-Endpunkte des Projekts mit den angegebenen Filtereinstellungen.

Das folgende Codebeispiel zeigt, wie die Methode generateContent verwendet wird.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

Ersetzen Sie Folgendes:

• PROJECT_ID durch Ihre Google Cloud Projekt-ID.
• LOCATION durch den Google Cloud Standort des Gemini Endpunkts. Unterstützte Standorte finden Sie unter Standorte für die Model Armor API.

Das folgende Codebeispiel zeigt die Antwort der Methode generateContent.

{
"promptFeedback": {
  "blockReason": "MODEL_ARMOR",
  "blockReasonMessage": "Blocked by Floor Setting. The prompt violated
  Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection
  and Jailbreak filters."
},
"usageMetadata": {
  "trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Erzwingungstyp für Mindesteinstellungen definieren

Legen Sie den Erzwingungstyp auf entweder INSPECT oder INSPECT_AND_BLOCK fest, um zu konfigurieren, wie Model Armor Erkennungen verarbeitet. Das folgende Beispiel zeigt die Konfiguration der Mindesteinstellungen mit dem Erzwingungstyp INSPECT_AND_BLOCK.

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/modelarmor-api-test/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

REST

export FLOOR_SETTING='{
  "filterConfig": {
    "raiSettings": {
      "raiFilters": [
        { "filterType": "HATE_SPEECH", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "DANGEROUS", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "HARASSMENT", "confidenceLevel": "LOW_AND_ABOVE" }
      ]
    },
    "sdpSettings": {
      "basicConfig": { "filterEnforcement": "ENABLED" }
    },
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED",
      "confidenceLevel": "LOW_AND_ABOVE"
    },
    "maliciousUriFilterSettings": { "filterEnforcement": "ENABLED" }
  },
  "integratedServices": ["AI_PLATFORM"],
  "aiPlatformFloorSetting": {
    "inspectAndBlock": true,
    "enableCloudLogging": true
  },
  "enableFloorSettingEnforcement": true
}'

curl -X PATCH \
    -d "$FLOOR_SETTING" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Ersetzen Sie Folgendes:

• PROJECT_ID durch die ID des Projekts für die Mindesteinstellungen.
• LOCATION durch den Standort der Mindesteinstellungen.

Inline-Erzwingung mit einem API-Aufruf testen

Testen Sie die Einbindung, um die Methode generateContent der Gemini Enterprise Agent Platform API aufzurufen. Verwenden Sie einen Prompt, der so konzipiert ist, dass er gegen die konfigurierten Mindesteinstellungen verstößt.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://${VERTEX_AI_LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION}/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": ""
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
}
}'

Wenn die Einbindung wie erwartet funktioniert, gibt die API eine Antwort zurück, in der das Feld blockReason auf MODEL_ARMOR gesetzt ist, wenn Model Armor den Prompt als Verstoß identifiziert.

Hier ist eine Beispielantwort:

    {
    "promptFeedback": {
      "blockReason": "MODEL_ARMOR",
      "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings..."
    },
    "usageMetadata": { "trafficType": "ON_DEMAND" },
    "modelVersion": "gemini-2.5-flash"
    }

Interaktions- und Vorrangregeln

Wenn Sie Model Armor mit der Gemini Enterprise Agent Platform verwenden, können Sie Sicherheitskonfigurationen auf mehreren Ebenen definieren. In solchen Fällen folgen Model Armor und die Gemini Enterprise Agent Platform einer bestimmten Vorrangreihenfolge:

1. Model Armor-Vorlagen: Jede Konfiguration, die explizit in der Konfiguration der API-Anfrage angegeben wird, hat die höchste Priorität. Diese Einstellungen überschreiben alle anderen in Konflikt stehenden Konfigurationen für diese bestimmte Anfrage.

2. Model Armor-Mindesteinstellungen: Wenn in der API-Anfrage keine überschreibende Konfiguration angegeben ist, werden die Model Armor-Mindesteinstellungen angewendet.

3. Sicherheitsfilter der Gemini Enterprise Agent Platform: Die standardmäßigen Sicherheitsfilter, die in die Gemini Enterprise Agent Platform integriert sind , haben die niedrigste Priorität. Sie werden nur angewendet, wenn Sie keine bestimmten Model Armor-Vorlagen oder Mindesteinstellungen definieren.

Dieser hierarchische Ansatz bietet eine Kombination aus umfassenden, organisationsweiten Mindeststandards (mit Mindesteinstellungen) und Kontrolle pro Anfrage (mit Vorlagen), wobei die integrierten Sicherheitsfunktionen der Gemini Enterprise Agent Platform als Grundlage verwendet werden.

Das Verhalten von Model Armor und den Sicherheitsfunktionen der Gemini Enterprise Agent Platform hängt davon ab, wie Sie die Konfiguration bereitstellen.

Vorlage konfiguriert?	Sicherheitsfilter der Gemini Enterprise Agent Platform konfiguriert?	Mindesteinstellungen konfiguriert?	Verhalten
Ja	Ja	Beliebig	Sie erhalten eine Fehlermeldung. Sie können nicht gleichzeitig eine Vorlagenkonfiguration und Sicherheitsfilter der Gemini Enterprise Agent Platform in derselben Anfrage angeben.
Ja	Nein	Beliebig	Model Armor wird ausgeführt und verwendet die in modelArmorConfig angegebenen Vorlagen. Die Sicherheitsfilter der Gemini Enterprise Agent Platform werden ignoriert. Anfragevorlagen überschreiben Mindesteinstellungen.
Nein	Ja	Ja	Beide werden ausgeführt. Model Armor scannt mit der Richtlinie für Mindesteinstellungen und die Gemini Enterprise Agent Platform wertet ihre Sicherheitsfilter aus. Das restriktivste Ergebnis wird angewendet.
Nein	Nein	Ja	Model Armor wird ausgeführt und verwendet die aktive Richtlinie für Mindesteinstellungen.
Nein	Ja	Nein	Nur die Sicherheitsfilter der Gemini Enterprise Agent Platform werden ausgewertet. Model Armor wird nicht aufgerufen.
Nein	Nein	Nein	Weder Model Armor pro Anfrage noch die Sicherheitsfilter der Gemini Enterprise Agent Platform werden angewendet. Nur die grundlegenden Modellverhaltensweisen sind aktiv.