Définir la version du filtre pour un modèle

Ce document explique comment fonctionnent les versions de filtre Model Armor et comment demander à Model Armor d'utiliser une version de filtre ou un alias de version de filtre spécifique dans les opérations.

Model Armor utilise des filtres pour détecter et bloquer les contenus nuisibles, les données sensibles, les URL malveillantes et les attaques par injection de prompt dans les prompts et les réponses des LLM. Pour en savoir plus, consultez la section Filtres Model Armor.

Les versions de filtre Model Armor offrent une stabilité pour les charges de travail de production et un accès aux derniers modèles de détection des menaces. Vous configurez une seule version de filtre au niveau du modèle. Vous ne pouvez pas spécifier différentes versions pour des filtres individuels.

Alias de version

Dans un modèle Model Armor, vous pouvez utiliser un alias pour spécifier la version de filtre de votre choix. Un alias représente une étape du cycle de vie d'une version. Chaque alias est défini sur la version appropriée à mesure que le cycle de vie progresse.

Si vous sélectionnez un alias, le modèle utilise la version sur laquelle l'alias est défini. Lorsque la version sous-jacente de cet alias est mise à jour (par exemple, lorsqu'une nouvelle version est promue en Stable), les modèles qui utilisent l'alias utilisent automatiquement la nouvelle version. Si vous ne souhaitez pas que la version du filtre change, pointez le modèle vers une version de filtre spécifique.

Vous pouvez choisir parmi les alias suivants :

  • Latest: alias avec les derniers modèles et protections, avec des mises à jour fréquentes contre les menaces émergentes. Cet alias offre des objectifs de niveau de service (SLO) standards, mais la stabilité peut varier d'une version à l'autre. Il convient aux tests, à la préparation et aux charges de travail qui privilégient les modèles de détection récents par rapport à un comportement de filtre cohérent.
  • Stable: alias par défaut pour les versions avec des modèles disponibles. Cet alias fournit une logique de détection fiable et immuable, et convient aux environnements de production et aux charges de travail qui nécessitent un comportement de filtre inchangé. Lorsqu'une nouvelle version devient Stable, la version Stable précédente devient Legacy.
  • Legacy: alias d'une version Stable antérieure qui reste disponible pendant 90 jours après la sortie d'une nouvelle version Stable. Vous pouvez migrer vos systèmes de production vers la nouvelle version Stable à tout moment pendant cette période. Vous ne pouvez pas créer de modèles à l'aide d'une version Legacy.
  • Retired: alias d'une version qui a dépassé la période de 90 jours et n'est plus disponible. Model Armor utilise la version Stable pour nettoyer les appels aux modèles qui utilisent encore une version Retired.

Filtres qui n'utilisent pas de versions de filtre

Le paramètre de version de filtre n'affecte pas les filtres Sensitive Data Protection et URL malveillantes.

Cycle de vie des versions

Google Cloud envoie des notifications concernant les modifications du cycle de vie des versions, y compris lorsqu'une version devient Legacy et sa date de retrait à venir dans chaque réponse de l'API de nettoyage. Vous devez migrer tous les modèles qui utilisent une version Legacy vers Stable ou Latest dans un délai de 90 jours.

L'exemple suivant décrit le cycle de vie d'une version :

  1. Publication (Latest) : Google publie une nouvelle version de filtre (v2) en tant que Latest.
  2. Promotion (Latest à Stable) : lorsque nous faisons passer la version Latest à Stable (v2 devient Stable), nous procédons comme suit :
    1. Nous déplaçons la version Stable précédente (v1) vers Legacy.
    2. Une nouvelle version (v3) devient la nouvelle version Latest. Nous faisons passer une version après qu'elle a subi des tests rigoureux, qu'elle a démontré une utilisation quotidienne cohérente et qu'elle a rencontré un minimum de problèmes client, ou lorsque la protection contre les menaces critiques devient nécessaire.
  3. Retrait (Legacy à Retired) : après qu'une version de filtre est restée à l'état Legacy pendant 90 jours, nous la retirons et elle n'est plus disponible.

Calendrier de sortie des versions

Le tableau suivant fournit des informations sur les versions de filtre, y compris les alias, les régions compatibles et leurs dates de sortie.

Version Alias Région compatible
v1 Stable 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 Stable

eu

europe-west1

europe-west2

europe-west3

europe-west4

us-east1
v3 Latest

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

Pour en savoir plus sur les modifications apportées à la dernière version, consultez l'historique des versions.

Comportement des modèles

Le comportement des modèles dépend de la version de filtre utilisée et présente les caractéristiques suivantes :

  • Modèles sans version : les modèles sans version spécifiée, qu'ils soient nouveaux ou existants, sont définis par défaut sur la version Stable.

  • Modèles avec des alias Latest ou Stable : ces modèles utilisent automatiquement la version attribuée à ces alias. Par exemple, lorsqu'une nouvelle version de filtre devient la version Stable, les modèles utilisant l'alias Stable passent à la nouvelle version sans nécessiter de modification.

  • Modèles utilisant une version spécifique :

    • Si la version correspond à une version Latest ou Stable, le modèle se comporte comme prévu.
    • Si la version correspond à une version Legacy, le modèle se comporte comme prévu lorsqu'il est utilisé pour des opérations de nettoyage pendant une période de 90 jours. Après 90 jours, la version passe à la phase Retired. Pendant cette phase, vous devez migrer vos modèles vers la version Latest ou Stable.

Configurer une version de filtre

Vous pouvez configurer la version de filtre d'un modèle de deux manières :

  • À l'aide d'un alias : utilisez des alias dynamiques tels que Stable ou Latest pour que le modèle utilise automatiquement un numéro de version correspondant à l'alias de votre choix. Cela évite d'avoir à effectuer des mises à jour manuelles lorsque la version sous-jacente change.
  • À l'aide d'un numéro de version : utilisez un numéro de version tel que v1 pour vous assurer qu'un modèle est défini sur une version spécifiée, ce qui garantit un comportement fixe et inchangé, même lorsque les alias sont mis à jour.

Créer un modèle à l'aide d'un alias de version

Pour créer un modèle à l'aide d'un alias de version spécifique, exécutez la commande suivante :

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"

Remplacez les éléments suivants :

  • FILTER_VERSION_ALIAS : alias de version de filtre de votre choix. Utilisez FILTER_VERSION_ALIAS_STABLE ou FILTER_VERSION_ALIAS_LATEST.
  • PROJECT_ID : ID du projet auquel appartient le modèle.
  • TEMPLATE_ID : ID du modèle à créer.
  • LOCATION: the location of the template.

La réponse est semblable à ce qui suit :

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

Créer un modèle à l'aide d'une version de filtre spécifique

Si vous avez besoin d'une immuabilité des filtres, vous pouvez créer un modèle correspondant à une version spécifique. Pour ce faire, exécutez la commande suivante :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet auquel appartient le modèle.
  • TEMPLATE_ID : ID du modèle à créer.
  • LOCATION: the location of the template.
  • FILTER_VERSION_NUMBER: numéro de version de filtre de votre choix (par exemple, v1).

La réponse est semblable à ce qui suit :

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

Mettre à jour la version de filtre d'un modèle

Pour mettre à jour la version ou l'alias de filtre d'un modèle existant, exécutez la commande suivante :

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"

Remplacez les éléments suivants :

  • FILTER_VERSION_ALIAS : alias de version de filtre de votre choix. Utilisez FILTER_VERSION_ALIAS_STABLE ou FILTER_VERSION_ALIAS_LATEST.
  • PROJECT_ID : ID du projet auquel appartient le modèle.
  • TEMPLATE_ID : ID du modèle à créer.
  • LOCATION: the location of the template.

La réponse est semblable à ce qui suit :

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

Afficher la version de filtre utilisée dans les opérations de nettoyage

Les métadonnées de réponse de l'API de nettoyage incluent des informations sur la version de filtre utilisée lors du nettoyage. Vous recevez un avertissement d'abandon dans la réponse de l'API de nettoyage 30 jours avant que Google ne retire la version.

L'exemple suivant illustre une réponse d'API qui inclut la version de filtre :

"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 génère des journaux de plate-forme pour les requêtes de nettoyage et leurs réponses dans Cloud Logging. Pour en savoir plus sur les journaux d'audit générés automatiquement, consultez la section Journalisation d'audit Model Armor.