Filterversion für eine Vorlage 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 sorgen für Stabilität bei Produktionsarbeitslasten und bieten Zugriff auf die neuesten Modelle zur Erkennung von Bedrohungen. Sie konfigurieren eine einzelne Filterversion auf Vorlagenebene. Sie können keine verschiedenen Versionen für einzelne Filter angeben.

Versionsaliasse

In einer Model Armor-Vorlage können Sie einen Alias verwenden, um Ihre bevorzugte Filterversion anzugeben. Ein Alias stellt eine Phase im Lebenszyklus der Version dar. Jeder Alias wird im Laufe des Lebenszyklus auf die entsprechende Version festgelegt.

Wenn Sie einen Alias auswählen, verwendet die Vorlage die Version, auf die der Alias festgelegt ist. Wenn die zugrunde liegende Version für diesen Alias aktualisiert wird (z. B. wenn eine neue Version zu 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 zwischen den folgenden Aliassen wählen:

  • Latest: Der Alias mit den neuesten Modellen und Schutzmaßnahmen, der häufig gegen neue Bedrohungen aktualisiert wird. Dieser Alias bietet Standard-SLOs (Service Level Objectives), die Stabilität kann jedoch je nach Version variieren. Er eignet sich für Tests, Staging und Arbeitslasten, bei denen aktuelle Erkennungsmodelle wichtiger sind als ein 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, bei denen ein unverändertes Filterverhalten erforderlich ist. 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. Sie können keine neuen Vorlagen mit einer Legacy-Version erstellen.
  • Retired: Der Alias für eine Version, die den 90-Tage-Zeitraum für die Legacy-Version überschritten hat und nicht mehr verfügbar ist. Model Armor verwendet die Stable-Version, um Aufrufe an Vorlagen zu bereinigen, die noch eine Retired-Version verwenden.

Filter, die keine Filterversionen verwenden

Die Einstellung für die Filterversion wirkt sich nicht auf die Filter für Sensitive Data Protection und schädliche URLs aus.

Versionslebenszyklus

Google Cloud sendet Benachrichtigungen zu Änderungen am Lebenszyklus der Version, einschließlich des Zeitpunkts, zu dem eine Version zu Legacy wird, und des bevorstehenden Einstellungsdatums in jeder Antwort der Bereinigungs-API. Sie müssen alle Vorlagen, die eine Legacy-Version verwenden, innerhalb von 90 Tagen zu Stable oder Latest migrieren.

Im folgenden Beispiel wird der Lebenszyklus der Version beschrieben:

  1. Veröffentlichung (Latest): Google veröffentlicht eine neue Filterversion (v2) als Latest.
  2. Hochstufung (Latest zu Stable): Wenn wir die Latest-Version zu Stable hochstufen (v2 wird zu Stable), tun wir Folgendes:
    1. Wir verschieben die vorherige Stable-Version (v1) zu Legacy.
    2. Eine neue Version (v3) wird zur neuen Latest-Version. Wir stufen eine Version hoch, nachdem sie strengen Tests unterzogen wurde, eine konsistente tägliche Nutzung aufweist und nur minimale Kundenprobleme verursacht, oder wenn ein kritischer Schutz vor Bedrohungen erforderlich wird.
  3. Einstellung (Legacy zu Retired): Nachdem eine Filterversion 90 Tage lang den Status Legacy beibehalten hat, wird sie eingestellt und ist nicht mehr verfügbar.

Zeitplan für die Veröffentlichung von Versionen

In der folgenden Tabelle finden Sie Details zu Filterversionen, einschließlich Aliassen, Hochstufungsdaten, Einstellungsdaten und unterstützten Regionen.

Version Alias Datum der Hochstufung zu „Stable“ Datum der Einstellung Unterstützte Region
v1 Legacy (gültig ab 31. August 2026) Bereits „Stable“ 2026-11-29 asia-northeast1

asia-northeast3

asia-south1

asia-southeast1

australia-southeast1

australia-southeast2

europe-southwest1

europe-west9

northamerica-northeast2

us

us-central1

us-east4

us-west1
v2 Legacy (gültig ab 31. August 2026) Bereits „Stable“ 2026-11-29

eu

europe-west1

europe-west2

europe-west3

europe-west4

us-east1
v3 Stable (gültig ab 31. August 2026) 2026-08-31 –

asia-south1

asia-southeast1

eu

europe-west1

europe-west2

europe-west3

europe-west4

europe-southwest1

europe-west9

northamerica-northeast2

us

us-central1

us-east1

us-east4

us-east7

us-west1

Informationen zu den Änderungen in der neuesten Version finden Sie unter Versionsverlauf.

Vorlagenverhalten

Das Vorlagenverhalten hängt von der verwendeten Filterversion ab und weist die folgenden Merkmale auf:

  • Vorlagen ohne Version: Für Vorlagen ohne angegebene Version, unabhängig davon, ob sie neu oder bereits vorhanden sind, wird standardmäßig die Stable Version verwendet.

  • Vorlagen mit Latest oder Stable Aliassen: Diese Vorlagen verwenden automatisch die Version, die diesen Aliassen zugewiesen ist. Wenn beispielsweise eine neue Filterversion zur Stable-Version wird, werden Vorlagen, die den Stable-Alias verwenden, automatisch zur neuen Version migriert, ohne dass Änderungen an der Vorlage erforderlich sind.

  • Vorlagen, die eine bestimmte Version verwenden:

    • 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 90 Tage lang für Bereinigungsvorgänge verwendet wird. Nach 90 Tagen wechselt die Version in die Phase Retired. Während dieser Phase müssen Sie Ihre Vorlagen zur Latest- oder Stable-Version migrieren.

Filterversion konfigurieren

Sie können die Filterversion für eine Vorlage auf zwei Arten konfigurieren:

  • Mit einem Alias: Verwenden Sie dynamische Aliase wie Stable oder Latest, damit die Vorlage automatisch eine Versionsnummer verwendet, die Ihrem bevorzugten Alias entspricht. So sind keine manuellen Updates 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 festes, 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.

Die Antwort ähnelt dem folgenden Beispiel:

{
  "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 die Filter unveränderlich sein müssen, 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).

Die Antwort ähnelt dem folgenden Beispiel:

{
  "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.

Die Antwort ähnelt dem folgenden Beispiel:

{
  "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"
    }
  }
}

Verwendete Filterversion in Bereinigungsvorgängen ansehen

Die Metadaten der Antwort der Bereinigungs-API enthalten Informationen zur Filterversion, die während der Bereinigung verwendet wird. Sie erhalten 30 Tage vor der Einstellung der Version durch Google eine Warnung zur Einstellung in der Antwort der Bereinigungs-API.

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": 5,
        "day": 1
      },
      "projectedDeprecationDate": {
        "year": 2026,
        "month": 5,
        "day": 1
      },
      "messageItems": [
        {
          "messageType": "WARNING",
          "message": "This filter version (v2) is in LEGACY state and will be
          RETIRED on 2026-05-01. 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.