En este documento, se describe cómo funcionan las versiones de filtros de Model Armor y cómo indicarle a Model Armor que use una versión de filtro o un alias de versión de filtro específicos en las operaciones.
Model Armor usa filtros para detectar y bloquear contenido dañino, datos sensibles, URLs maliciosas y ataques de inyección de instrucciones en las instrucciones y respuestas de los LLM. Para obtener más información, consulta Filtros de Model Armor.
Las versiones de filtros de Model Armor proporcionan estabilidad para las cargas de trabajo de producción y acceso a los modelos de detección de amenazas más recientes. Configuras una sola versión de filtro a nivel de la plantilla. No puedes especificar diferentes versiones para filtros individuales.
Alias de versiones
En una plantilla de Model Armor, puedes usar un alias para especificar la versión de filtro que prefieras. Un alias representa una etapa en el ciclo de vida de la versión. Cada alias se establece en la versión adecuada a medida que avanza el ciclo de vida.
Si seleccionas un alias, la plantilla usa la versión a la que está configurado el alias.
Cuando se actualiza la versión subyacente de ese alias (por ejemplo, cuando se promueve una versión nueva a Stable), las plantillas que usan el alias usan automáticamente la versión nueva. Si no quieres que cambie la versión del filtro, dirige la plantilla a una versión de filtro específica.
Puedes elegir entre los siguientes alias:
Latest: Es el alias con los modelos y las protecciones más recientes, con actualizaciones frecuentes contra amenazas emergentes. Este alias ofrece objetivos de nivel de servicio (SLO) estándar, pero la estabilidad puede variar entre las versiones. Es adecuado para pruebas, etapas de pruebas y cargas de trabajo que priorizan los modelos de detección recientes sobre el comportamiento coherente de los filtros.Stable: Es el alias predeterminado para las versiones con plantillas disponibles. Este alias ofrece una lógica de detección confiable e inmutable, y es adecuado para entornos de producción y cargas de trabajo que requieren un comportamiento de filtro inmutable. Cuando una versión nueva se convierte enStable, la versiónStableanterior se convierte enLegacy.Legacy: Es el alias de una versiónStableanterior que permanece disponible durante 90 días después de que se lanza una versiónStablenueva. Puedes migrar tus sistemas de producción a la nueva versiónStableen cualquier momento durante este período. No puedes crear plantillas nuevas con una versiónLegacy.Retired: Es el alias de una versión que superó el período heredado de 90 días y ya no está disponible. Model Armor usa la versiónStablepara limpiar las llamadas a las plantillas que aún usan una versiónRetired.
Filtros que no usan versiones de filtros
La configuración de la versión del filtro no afecta los filtros de Sensitive Data Protection ni de URLs maliciosas.
Ciclo de vida de las versiones
Google Cloud proporciona notificaciones sobre los cambios en el ciclo de vida de las versiones,
incluido cuando una versión se convierte en Legacy y su próxima fecha de baja en
cada respuesta de la API de limpieza. Debes migrar las plantillas que usan una versión Legacy a Stable o Latest en un período de 90 días.
En el siguiente ejemplo, se describe el ciclo de vida de la versión:
- Lanzamiento (
Latest): Google lanza una nueva versión de filtro (v2) comoLatest. - Promoción (
LatestaStable): Cuando promovemos la versiónLatestaStable(v2se convierte enStable), hacemos lo siguiente:- Movemos la versión
Stableanterior (v1) aLegacy. - Una versión nueva (
v3) se convierte en la nuevaLatest. Promovemos una versión después de que se somete a pruebas rigurosas, demuestra un uso diario coherente y tiene problemas mínimos para los clientes, o cuando se vuelve necesaria la protección contra amenazas críticas.
- Movemos la versión
- Baja (
LegacyaRetired): Después de que una versión de filtro permanece en el estadoLegacydurante 90 días, la damos de baja y ya no está disponible.
Cronograma de lanzamiento de versiones
En la siguiente tabla, se comparten detalles sobre las versiones de filtros, incluidos los alias, las regiones admitidas y sus fechas de lanzamiento.
| Versión | Alias | Región admitida | Fecha de lanzamiento |
|---|---|---|---|
v1 |
Stable |
asia-northeast1
|
2025-01-30 |
v2 |
Stable |
|
2025-06-19 |
v3 |
Latest |
|
2026-05-25 |
Para obtener información sobre los cambios en la versión más reciente, consulta Historial de versiones.
Comportamiento de la plantilla
El comportamiento de la plantilla depende de la versión del filtro que se use y sigue estas características:
- Plantillas sin una versión: Las plantillas sin una versión especificada,
ya sean nuevas o existentes, usan la versión
Stablede forma predeterminada. Plantillas con
LatestoStablealias: Estas plantillas usan automáticamente la versión asignada a estos alias. Por ejemplo, cuando una versión de filtro nueva se convierte en la versiónStable, las plantillas que usan el aliasStablese mueven a la versión nueva sin requerir ningún cambio en la plantilla.Plantillas que usan una versión específica:
- Si la versión corresponde a una versión
LatestoStable, la plantilla se comporta como se espera. - Si la versión corresponde a una versión
Legacy, la plantilla se comporta como se espera cuando se usa para operaciones de limpieza durante un período de 90 días. Después de 90 días, la versión pasa a la faseRetired. Durante esta fase, debes migrar tus plantillas a la versiónLatestoStable.
- Si la versión corresponde a una versión
Configura una versión de filtro
Puedes configurar la versión del filtro para una plantilla de una de estas dos maneras:
- Con un alias: Usa alias dinámicos como
StableoLatestpara que la plantilla use automáticamente un número de versión que corresponda a tu alias preferido. De esta manera, se elimina la necesidad de realizar actualizaciones manuales cuando cambia la versión subyacente. - Con un número de versión: Usa un número de versión como
v1para asegurarte de que una plantilla esté configurada en una versión especificada, lo que garantiza un comportamiento fijo e inmutable, incluso cuando se actualizan los alias.
Crea una plantilla con un alias de versión
Para crear una plantilla con un alias de versión específico, ejecuta el siguiente comando:
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"
Reemplaza lo siguiente:
FILTER_VERSION_ALIAS: Es el alias de la versión de filtro que prefieras. UsaFILTER_VERSION_ALIAS_STABLEoFILTER_VERSION_ALIAS_LATEST.PROJECT_ID: Es el ID del proyecto al que pertenece la plantilla.TEMPLATE_ID: Es el ID de la plantilla que se creará.LOCATION: Es la ubicación de la plantilla.
La respuesta es similar al ejemplo a continuación:
{
"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"
}
}
}
Crea una plantilla con una versión de filtro específica
Si necesitas inmutabilidad del filtro, puedes crear una plantilla que corresponda a una versión específica. Para ello, ejecuta el comando que se indica a continuación:
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"
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto al que pertenece la plantilla.TEMPLATE_ID: Es el ID de la plantilla que se creará.LOCATION: Es la ubicación de la plantilla.FILTER_VERSION_NUMBER: Es el número de versión de filtro que prefieras (por ejemplo,v1).
La respuesta es similar al ejemplo a continuación:
{
"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"
}
}
}
Actualiza la versión del filtro de una plantilla
Para actualizar la versión o el alias del filtro de una plantilla existente, ejecuta el siguiente comando:
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"
Reemplaza lo siguiente:
FILTER_VERSION_ALIAS: Es el alias de la versión de filtro que prefieras. UsaFILTER_VERSION_ALIAS_STABLEoFILTER_VERSION_ALIAS_LATEST.PROJECT_ID: Es el ID del proyecto al que pertenece la plantilla.TEMPLATE_ID: Es el ID de la plantilla que se creará.LOCATION: Es la ubicación de la plantilla.
La respuesta es similar al ejemplo a continuación:
{
"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"
}
}
}
Visualiza la versión del filtro que se usa en las operaciones de limpieza
Los metadatos de respuesta de la API de limpieza incluyen información sobre la versión del filtro que se usa durante la limpieza. Recibirás una advertencia de baja en la respuesta de la API de limpieza 30 días antes de que Google dé de baja la versión.
En el siguiente ejemplo, se muestra una respuesta de la API que incluye la versión del filtro:
"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 genera registros de la plataforma para las solicitudes de limpieza y sus respuestas en Cloud Logging. Para obtener más información sobre los registros de auditoría generados automáticamente, consulta Registro de auditoría de Model Armor.