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

Filterversion festlegen

In diesem Dokument wird beschrieben, wie Model Armor-Filterversionen funktionieren und wie Sie Model Armor anweisen, eine bestimmte Filterversion oder einen bestimmten Filterversionsalias in Vorgängen zu verwenden.

Model Armor verwendet Filter, um schädliche Inhalte, sensible Daten, schädliche URLs und Prompt Injection-Angriffe in LLM-Prompts und -Antworten zu erkennen und zu blockieren. Weitere Informationen finden Sie unter Model Armor-Filter.

Model Armor-Filterversionen bieten Stabilität für Produktionsarbeitslasten und Zugriff auf die neuesten Modelle zur Erkennung von Bedrohungen. Sie konfigurieren eine einzelne Filterversion auf Vorlagenebene. Sie können keine unterschiedlichen Versionen für einzelne Filter angeben.

Wann Filterversionen und ‑aliase konfiguriert werden sollten

Im Folgenden sind einige gängige Anwendungsfälle aufgeführt:

Deterministisches Filterverhalten sperren: Legen Sie für Vorlagen eine bestimmte Filterversion fest, um Änderungen an der Logik zur Erkennung von Bedrohungen in unternehmenskritischen Systemen zu verhindern.
Automatische Sicherheitsupdates erhalten: Verwenden Sie den Alias Stable, um aktualisierte Modelle zur Erkennung von Bedrohungen automatisch zu übernehmen, sobald sie die Validierung bestehen.
Künftige Erkennungsfunktionen testen: Verwenden Sie den Alias Latest in Vorproduktionsumgebungen, um neue Filterregeln anhand von realen Traffic-Mustern zu testen.
Vorhersehbare Roll-out-Zyklen aktivieren: Arbeitslasten anhand neu veröffentlichter Filterversionen validieren, bevor Produktionsvorlagen manuell aktualisiert werden.

Versionsaliasse

In einer Model Armor-Vorlage können Sie einen Alias verwenden, um die bevorzugte Filterversion anzugeben. Ein Alias steht für eine Phase im Versionslebenszyklus. Jeder Alias wird im Laufe des Lebenszyklus auf die entsprechende Version festgelegt.

Wenn Sie einen Alias auswählen, wird die Version verwendet, auf die der Alias festgelegt ist. Wenn die zugrunde liegende Version für diesen Alias aktualisiert wird (z. B. wenn eine neue Version auf Stable hochgestuft wird), verwenden Vorlagen, die den Alias verwenden, automatisch die neue Version. Wenn sich die Filterversion nicht ändern soll, verweisen Sie die Vorlage auf eine bestimmte Filterversion.

Sie können aus den folgenden Aliasnamen auswählen:

Latest: Der Alias mit den neuesten Modellen und Schutzmaßnahmen, der häufig gegen neue Bedrohungen aktualisiert wird. Dieser Alias bietet Standard-Service Level Objectives (SLOs), die Stabilität kann jedoch je nach Version variieren. Sie eignet sich für Tests, Staging und Arbeitslasten, bei denen aktuelle Erkennungsmodelle wichtiger sind als einheitliches Filterverhalten.
Stable: Der Standardalias für Versionen mit verfügbaren Vorlagen. Dieser Alias bietet eine zuverlässige, unveränderliche Erkennungslogik und eignet sich für Produktionsumgebungen und Arbeitslasten, die ein unverändertes Filterverhalten erfordern. Wenn eine neue Version Stable wird, wird die vorherige Stable-Version zu Legacy.
Legacy: Der Alias für eine frühere Stable-Version, die 90 Tage nach der Veröffentlichung einer neuen Stable-Version verfügbar bleibt. Sie können Ihre Produktionssysteme jederzeit während dieses Zeitraums zur neuen Stable-Version migrieren. Mit einer Legacy-Version können Sie keine neuen Vorlagen erstellen.
Retired: Der Alias für eine Version, die den 90-Tage-Zeitraum überschritten hat und nicht mehr verfügbar ist. Model Armor verwendet die Stable-Version, um Aufrufe von Vorlagen zu bereinigen, die noch eine Retired-Version verwenden.

Filter ohne Filterversionen

Die Einstellung für die Filterversion hat keine Auswirkungen auf die Filter für Sensitive Data Protection und schädliche URLs.

Versionslebenszyklus

Google Cloud bietet Benachrichtigungen zu Änderungen am Versionslebenszyklus, einschließlich des Zeitpunkts, zu dem eine Version Legacy wird, und des bevorstehenden Ausmusterungsdatums in jeder sanitize API-Antwort. Alle Vorlagen, in denen eine Legacy-Version verwendet wird, müssen innerhalb des 90‑Tage-Zeitraums zu Stable oder Latest migriert werden.

Im folgenden Beispiel wird der Versionslebenszyklus beschrieben:

Release (Latest): Google veröffentlicht eine neue Filterversion (v2) als Latest.
Promotion (Latest bis Stable): Wenn Google die Latest-Version auf Stable hochstuft (v2 wird zu Stable), passiert Folgendes:
1. Google verschiebt die vorherige Version Stable (v1) nach Legacy.
2. Eine neue Version (v3) wird zum neuen Latest. Google bewirbt eine Version, nachdem sie strengen Tests unterzogen wurde, eine konsistente tägliche Nutzung aufweist und nur minimale Kundenprobleme auftreten oder wenn ein kritischer Schutz vor Bedrohungen erforderlich wird.
Außerbetriebnahme (Legacy bis Retired): Wenn eine Filterversion 90 Tage lang den Status Legacy beibehält, wird sie von Google außer Betrieb genommen und ist nicht mehr verfügbar.

Zeitachse für die Veröffentlichung von Versionen

In der folgenden Tabelle finden Sie Details zu Filterversionen, einschließlich Aliasse, Veröffentlichungsdaten, Außerbetriebnahmedaten und unterstützte Regionen.

Version	Alias	Releasedatum	Ausmusterungsdatum	Unterstützte Region
`v1`	`Legacy` (`Stable` in `asia-northeast3`; `Legacy` ab dem 25. September 2026 in `australia-southeast2`)	2025-01-30	2026-12-17	`asia-northeast1` `asia-northeast3` (`Stable`) `asia-south1` `asia-southeast1` `australia-southeast2` (`Legacy` ab dem 25. September 2026) `europe-southwest1` `europe-west9` `northamerica-northeast2` `us` `us-central1` `us-east4` `us-west1`
`v2`	`Legacy`	2025-06-19	2026-12-17	`eu` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `us-east1`
`v3`	`Stable` (`Stable` ab dem 25. September 2026 in `australia-southeast2`)	2026-05-25	–	`asia-northeast1` `asia-south1` `asia-southeast1` `australia-southeast2` (`Stable` ab dem 25. September 2026) `eu` `europe-southwest1` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `europe-west9` `northamerica-northeast2` `us` `us-central1` `us-east1` `us-east4` `us-west1`
`v4`	`Latest`	2026-09-18	–	`asia-northeast1` `asia-south1` `asia-southeast1` `eu` `europe-southwest1` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `europe-west9` `northamerica-northeast2` `us` `us-central1` `us-east1` `us-east4` `us-west1`

Informationen zu den Änderungen in den einzelnen Versionen finden Sie unter Versionsverlauf filtern.

Verhalten von Vorlagen

Das Verhalten von Vorlagen hängt von der verwendeten Filterversion ab und folgt diesen Merkmalen:

Vorlagen ohne Version: Bei Vorlagen ohne angegebene Version, unabhängig davon, ob sie neu oder bereits vorhanden sind, wird standardmäßig die Version Stable verwendet.
Vorlagen mit den Aliasen Latest oder Stable: Bei diesen Vorlagen wird automatisch die Version verwendet, die diesen Aliasen zugewiesen ist. Wenn beispielsweise eine neue Filterversion zur Stable-Version wird, werden Vorlagen, die den Alias Stable verwenden, automatisch auf die neue Version umgestellt. Es sind keine Änderungen an der Vorlage erforderlich.

Hinweis :Sie können die Filterversion in einer Vorlage nicht auf Legacy oder Retired festlegen.
Vorlagen mit einer bestimmten Version:
- Wenn die Version einer Latest- oder Stable-Version entspricht, verhält sich die Vorlage wie erwartet.
- Wenn die Version einer Legacy-Version entspricht, verhält sich die Vorlage wie erwartet, wenn sie für Bereinigungsvorgänge über einen Zeitraum von 90 Tagen verwendet wird. Nach 90 Tagen wechselt die Version in die Phase Retired. In dieser Phase müssen Sie Ihre Vorlagen entweder zur Version Latest oder Stable migrieren.

Standardfilterversion für Mindesteinstellungen überschreiben

Für Mindesteinstellungen wird standardmäßig die Stable-Filterversion verwendet. Wenn Sie diese Einstellung für die Integration der Gemini Enterprise Agent Platform überschreiben möchten, geben Sie eine Vorlage im generateContent-Aufruf an das Gemini-Modell an. Erstellen Sie dazu eine Vorlage mit einer bestimmten Filterversion oder einem Alias in derselben Region, in der Sie die Gemini-Anfrage senden möchten.

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}'

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

Ersetzen Sie Folgendes:

FILTER_VERSION_ALIAS: Ihr bevorzugter Alias für die Filterversion. Verwenden Sie entweder FILTER_VERSION_ALIAS_STABLE oder FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: die ID des Projekts, zu dem die Vorlage gehört.
TEMPLATE_ID: die ID der zu erstellenden Vorlage.
LOCATION: die Region, in der die Model Armor-Vorlage gespeichert werden soll. Diese Region muss mit der Region übereinstimmen, in der Sie die Gemini-Anfrage senden möchten. Andernfalls wird in der Agent Platform ein Template not found-Fehler ausgegeben. Eine Liste der für diese Integration unterstützten Regionen finden Sie unter Integration mit der Gemini Enterprise Agent Platform.

Geben Sie die Vorlagen-ID im model_armor_config-Objekt in Ihrem Gemini-Aufruf an. Die im Template angegebene Filterkonfiguration wird anstelle der Mindesteinstellung auf Projektebene angewendet.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent" \
  -d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Your prompt here"
        }
      ]
    }
  ],
  "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: die Google Cloud Projekt-ID.
REGION: die Google Cloud Region des Gemini-Endpunkts.
LOCATION: die Region, in der die Model Armor-Vorlage gespeichert ist. Dies muss dieselbe Region sein, die für REGION angegeben ist.
TEMPLATE_ID: die ID der Model Armor-Vorlage.

Filterversion für eine Vorlage konfigurieren

Sie haben zwei Möglichkeiten, die Filterversion für eine Vorlage zu konfigurieren:

Alias verwenden: Verwenden Sie dynamische Aliase wie Stable oder Latest, damit in der Vorlage automatisch eine Versionsnummer verwendet wird, die Ihrem bevorzugten Alias entspricht. So sind keine manuellen Updates mehr erforderlich, wenn sich die zugrunde liegende Version ändert.
Mit einer Versionsnummer: Verwenden Sie eine Versionsnummer wie v1, um sicherzustellen, dass eine Vorlage auf eine bestimmte Version festgelegt ist. So wird ein unverändertes Verhalten gewährleistet, auch wenn Aliase aktualisiert werden.

Vorlage mit einem Versionsalias erstellen

Führen Sie den folgenden Befehl aus, um eine Vorlage mit einem bestimmten Versionsalias zu erstellen:

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}'

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

Ersetzen Sie Folgendes:

FILTER_VERSION_ALIAS: Ihr bevorzugter Alias für die Filterversion. Verwenden Sie entweder FILTER_VERSION_ALIAS_STABLE oder FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: die ID des Projekts, zu dem die Vorlage gehört.
TEMPLATE_ID: die ID der zu erstellenden Vorlage.
LOCATION: der Speicherort der Vorlage.

Das Ergebnis sieht etwa so aus:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T17:57:46.976854398Z",
  "updateTime": "2026-04-05T17:57:46.976854398Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}

Vorlage mit einer bestimmten Filterversion erstellen

Wenn Sie die Unveränderlichkeit von Filtern benötigen, können Sie eine Vorlage erstellen, die einer bestimmten Version entspricht. Führen Sie hierzu den folgenden Befehl aus:

export TEMPLATE_CONFIG='{
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "version": "FILTER_VERSION_NUMBER"
    }
  }
}'

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "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.
TEMPLATE_ID: die ID der zu erstellenden Vorlage.
LOCATION: der Speicherort der Vorlage.
FILTER_VERSION_NUMBER: Ihre bevorzugte Filterversionsnummer (z. B. v1).

Das Ergebnis sieht etwa so aus:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T18:03:29.134974974Z",
  "updateTime": "2026-04-05T18:03:29.134974974Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "version": "FILTER_VERSION_NUMBER"
    }
  }
}

Filterversion einer Vorlage aktualisieren

Führen Sie den folgenden Befehl aus, um die Filterversion oder den Alias für eine vorhandene Vorlage zu aktualisieren:

export TEMPLATE_CONFIG='{
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}'

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d "$TEMPLATE_CONFIG" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID?updateMask=templateMetadata.filterVersionSelector"

Ersetzen Sie Folgendes:

FILTER_VERSION_ALIAS: Ihr bevorzugter Alias für die Filterversion. Verwenden Sie entweder FILTER_VERSION_ALIAS_STABLE oder FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: die ID des Projekts, zu dem die Vorlage gehört.
TEMPLATE_ID: die ID der zu erstellenden Vorlage.
LOCATION: der Speicherort der Vorlage.

Das Ergebnis sieht etwa so aus:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
  "createTime": "2026-04-05T18:03:29.134974974Z",
  "updateTime": "2026-04-05T18:04:07.711205953Z",
  "filterConfig": {
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED"
    }
  },
  "templateMetadata": {
    "filterVersionSelector": {
      "alias": "FILTER_VERSION_ALIAS"
    }
  }
}

Filterversion für Bereinigungen ansehen

Die Metadaten der Antwort der Sanitize API enthalten Informationen zur Filterversion, die bei der Bereinigung verwendet wird. Sie erhalten 30 Tage vor der Einstellung der Version eine Warnung zur Einstellung in der API-Antwort von „sanitize“.

Das folgende Beispiel zeigt eine API-Antwort, die die Filterversion enthält:

"sanitizationResult": {
    "filterMatchState": "NO_MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "malicious_uris": {
        "maliciousUriFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "rai": {
        "raiFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND",
          "raiFilterTypeResults": {
            "sexually_explicit": {
              "matchState": "NO_MATCH_FOUND"
            },
            "hate_speech": {
              "matchState": "NO_MATCH_FOUND"
            },
            "harassment": {
              "matchState": "NO_MATCH_FOUND"
            }
          }
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "NO_MATCH_FOUND"
          }
        }
      }
    },
  "sanitizationMetadata": {
    "filterVersionConfig": {
      "filterVersion": "v2",
      "filterVersionAlias": "FILTER_VERSION_ALIAS_LEGACY",
      "releaseDate": {
        "year": 2025,
        "month": 6,
        "day": 19
      },
      "projectedDeprecationDate": {
        "year": 2026,
        "month": 12,
        "day": 17
      },
      "messageItems": [
        {
          "messageType": "WARNING",
          "message": "This filter version (v2) is in LEGACY state and will be
          RETIRED on 2026-12-17. Please migrate your template to the STABLE or
          LATEST version to ensure continued protection."
        }
      ]
   }
  },
}

Model Armor generiert Plattformlogs für Bereinigungsanfragen und deren Antworten in Cloud Logging. Weitere Informationen zu den automatisch generierten Audit-Logs finden Sie unter Audit-Logging für Model Armor.

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

Wann Filterversionen und ‑aliase konfiguriert werden sollten

Versionsaliasse

Filter ohne Filterversionen

Versionslebenszyklus

Zeitachse für die Veröffentlichung von Versionen

Verhalten von Vorlagen

Standardfilterversion für Mindesteinstellungen überschreiben

Filterversion für eine Vorlage konfigurieren

Vorlage mit einem Versionsalias erstellen

Vorlage mit einer bestimmten Filterversion erstellen

Filterversion einer Vorlage aktualisieren

Filterversion für Bereinigungen ansehen

Filterversion festlegen