Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Cómo establecer la versión del filtro

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

Cuándo configurar versiones y alias de filtros

A continuación, se muestran algunos casos de uso comunes:

Bloquea el comportamiento de filtrado determinista: Establece plantillas en una versión de filtro específica para evitar cambios en la lógica de detección de amenazas en sistemas de misión crítica.
Recibe actualizaciones de seguridad automáticas: Usa el alias Stable para adoptar automáticamente los modelos de detección de amenazas actualizados a medida que pasan la validación.
Prueba las próximas capacidades de detección: Usa el alias Latest en entornos de preproducción para evaluar las nuevas reglas de filtro en función de los patrones de tráfico del mundo real.
Habilita ciclos de lanzamiento predecibles: Valida las cargas de trabajo en función de las versiones de filtros recién lanzadas antes de actualizar manualmente las plantillas de producción.

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 (SLOs) estándar, pero la estabilidad puede variar entre las versiones. Es adecuado para pruebas, etapa de pruebas y cargas de trabajo que priorizan los modelos de detección recientes por sobre el comportamiento coherente del filtro.
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 en Stable, la versión Stable anterior se convierte en Legacy.
Legacy: Es el alias de una versión Stable anterior que permanece disponible durante 90 días después de que se lanza una versión Stable nueva. Puedes migrar tus sistemas de producción a la nueva versión Stable en cualquier momento durante este período. No puedes crear plantillas nuevas con una versión Legacy.
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ón Stable para limpiar las llamadas a las plantillas que aún usan una versión Retired.

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, incluso cuando una versión se convierte en Legacy y su próxima fecha de retiro en cada respuesta de la API de Sanitize. 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) como Latest.
Promoción (Latest a Stable): Cuando Google promueve la versión Latest a Stable (v2 se convierte en Stable), sucede lo siguiente:
1. Google mueve la versión Stable anterior (v1) a Legacy.
2. Una versión nueva (v3) se convierte en la nueva Latest. Google promueve 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.
Retiro (Legacy a Retired): Después de que una versión de filtro permanece en el estado Legacy durante 90 días, Google la retira 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 fechas de lanzamiento, las fechas de retiro y las regiones admitidas.

Versión	Alias	Fecha de lanzamiento	Fecha de retiro	Región admitida
`v1`	`Legacy` (`Stable` en `asia-northeast3`; `Legacy` a partir del 25 de septiembre de 2026 en `australia-southeast2`)	2025-01-30	2026-12-17	`asia-northeast1` `asia-northeast3` (`Stable`) `asia-south1` `asia-southeast1` `australia-southeast2` (`Legacy` a partir del 25 de septiembre de 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` a partir del 25 de septiembre de 2026 en `australia-southeast2`)	2026-05-25	—	`asia-northeast1` `asia-south1` `asia-southeast1` `australia-southeast2` (`Stable` a partir del 25 de septiembre de 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`

Para obtener información sobre los cambios en cada versión, consulta Historial de versiones de filtros.

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 Stable de forma predeterminada.
Plantillas con Latest o Stable alias: 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ón Stable, las plantillas que usan el alias Stable se mueven a la versión nueva sin requerir ningún cambio en la plantilla.

Nota: No puedes establecer la versión del filtro en una plantilla como Legacy o Retired.
Plantillas que usan una versión específica:
- Si la versión corresponde a una versión Latest o Stable, 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 fase Retired. Durante esta fase, debes migrar tus plantillas a la versión Latest o Stable.

Anula la versión de filtro predeterminada para la configuración de límites

Con la configuración de límites, la integración de Gemini Enterprise Agent Platform usa la versión de Stable filtro de forma predeterminada. Para anular esta configuración, especifica una plantilla en la llamada generateContent al modelo de Gemini. Para ello, crea una plantilla con una versión o un alias de filtro específicos en la misma región en la que planeas enviar la solicitud de Gemini.

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. Usa FILTER_VERSION_ALIAS_STABLE o FILTER_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 región en la que se almacenará la plantilla de Model Armor. Esta región debe ser la misma en la que planeas enviar la solicitud de Gemini; de lo contrario, Agent Platform recibirá un error Template not found. Para obtener una lista de las regiones admitidas para esta integración, consulta Integración con Gemini Enterprise Agent Platform.

Proporciona el ID de la plantilla en el objeto model_armor_config en tu llamada a Gemini. Se aplica la configuración de filtro especificada en la plantilla en lugar de la configuración de límites a nivel del proyecto.

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

Reemplaza lo siguiente:

PROJECT_ID: Es el Google Cloud ID del proyecto.
REGION: Es la Google Cloud región del extremo de Gemini.
LOCATION: Es la región en la que se almacena la plantilla de Model Armor. Debe ser la misma región especificada para REGION.
TEMPLATE_ID: Es el ID de la plantilla de Model Armor.

Configura una versión de filtro para una plantilla

Puedes configurar la versión del filtro para una plantilla de una de estas dos maneras:

Usa un alias: Usa alias dinámicos como Stable o Latest para 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.
Usa un número de versión: Usa un número de versión como v1 para asegurarte de que una plantilla esté establecida 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. Usa FILTER_VERSION_ALIAS_STABLE o FILTER_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. Usa FILTER_VERSION_ALIAS_STABLE o FILTER_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 Sanitize 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 Sanitize 30 días antes de que Google retire 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": 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 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 de forma automática, consulta Registro de auditoría de Model Armor.

Cómo establecer la versión del filtro Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Cuándo configurar versiones y alias de filtros

Alias de versiones

Filtros que no usan versiones de filtros

Ciclo de vida de las versiones

Cronograma de lanzamiento de versiones

Comportamiento de la plantilla

Anula la versión de filtro predeterminada para la configuración de límites

Configura una versión de filtro para una plantilla

Crea una plantilla con un alias de versión

Crea una plantilla con una versión de filtro específica

Actualiza la versión del filtro de una plantilla

Visualiza la versión del filtro que se usa en las operaciones de limpieza

Cómo establecer la versión del filtro