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

Ce document explique comment fonctionnent les versions de filtres 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 Filtres Model Armor.

Les versions de filtres Model Armor offrent de la 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 à 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 au niveau 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 spécifique du filtre.

Vous pouvez choisir parmi les alias suivants :

  • Latest : alias avec les modèles et les protections les plus récents, avec des mises à jour fréquentes contre les nouvelles menaces. Cet alias offre des objectifs de niveau de service (SLO) standards, mais la stabilité peut varier selon les versions. Il convient aux tests, à la mise en scène et aux charges de travail qui privilégient les modèles de détection récents par rapport au comportement cohérent des filtres.
  • Stable : alias par défaut pour les versions avec des modèles disponibles. Cet alias fournit une logique de détection fiable et immuable. Il convient aux environnements de production et aux charges de travail qui nécessitent un comportement de filtrage inchangé. Lorsqu'une nouvelle version devient Stable, la version Stable précédente devient Legacy.
  • Legacy : alias d'une ancienne version de Stable qui reste disponible pendant 90 jours après la sortie d'une nouvelle version de 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é l'ancienne période de 90 jours et n'est plus disponible. Model Armor utilise la version Stable pour assainir 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 du filtre n'a aucune incidence sur les filtres Sensitive Data Protection et URL malveillantes.

Cycle de vie des versions

Google Cloud fournit des notifications sur les modifications du cycle de vie des versions, y compris lorsqu'une version devient Legacy et sa prochaine date d'arrêt dans chaque réponse de l'API sanitize. 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 des versions :

  1. Version (Latest) : Google publie une nouvelle version du filtre (v2) en tant que Latest.
  2. Promotion (Latest vers Stable) : lorsque nous promouvons la version Latest vers Stable (v2 devient Stable), nous procédons comme suit :
    1. Nous déplaçons la version précédente de Stable (v1) vers Legacy.
    2. Une nouvelle version (v3) devient la nouvelle Latest. Nous promouvons 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 (du Legacy au Retired) : si une version de filtre reste à l'état Legacy pendant 90 jours, nous la retirons et elle n'est plus disponible.

Chronologie des versions

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

Version Alias Région où le service est disponible Date de disponibilité
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

 2025-01-30
v2 Stable

eu

europe-west1

europe-west2

europe-west3

europe-west4

us-east1

 2025-06-19
v3 Latest

eu

europe-west1

europe-west2

europe-west3

europe-west4

europe-southwest1

europe-west9

us

us-central1

us-east1

us-east4

us-east7

us-west1

 2026-05-25

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

Comportement des modèles

Le comportement du modèle dépend de la version du 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 sur une période de 90 jours. Au bout de 90 jours, la version passe à la phase Retired. Au cours de cette phase, vous devez migrer vos modèles vers la version Latest ou Stable.

Configurer une version de filtre

Vous pouvez configurer la version du filtre pour un modèle de deux manières :

  • En utilisant un alias : utilisez des alias dynamiques tels que Stable ou Latest pour que le modèle utilise automatiquement un numéro de version correspondant à votre alias préféré. Vous n'aurez ainsi plus besoin d'effectuer de mises à jour manuelles lorsque la version sous-jacente change.
  • En utilisant 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écifique, 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 la 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 : emplacement du modèle.

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 spécifique d'un filtre

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 : emplacement du modèle.
  • FILTER_VERSION_NUMBER : numéro de version du 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 du filtre d'un modèle

Pour mettre à jour la version ou l'alias du filtre pour 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 la 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 : emplacement du modèle.

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 du filtre utilisée dans les opérations de nettoyage

Les métadonnées de la réponse de l'API Sanitize incluent des informations sur la version du filtre utilisée lors de la désinfection. Vous recevez un avertissement d'obsolescence dans la réponse de l'API Sanitize 30 jours avant que Google ne mette hors service la version.

L'exemple suivant montre une réponse d'API qui inclut la version du 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 demandes de désinfection et leurs réponses dans Cloud Logging. Pour en savoir plus sur les journaux d'audit générés automatiquement, consultez Journalisation des audits Model Armor.