Cómo establecer la versión del filtro para una plantilla

En este documento, se describe cómo funcionan las versiones de los 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 los 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 del filtro a nivel de la plantilla. No puedes especificar versiones diferentes para filtros individuales.

Alias de versiones

En una plantilla de Model Armor, puedes usar un alias para especificar la versión del 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 usará la versión a la que se configuró 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 automáticamente usan la versión nueva. Si no quieres que cambie la versión del filtro, apunta la plantilla a una versión específica del filtro.

Puedes elegir entre los siguientes alias:

• Latest: Es el alias con los modelos y las protecciones más recientes, con actualizaciones frecuentes contra las amenazas emergentes. Este alias ofrece objetivos de nivel de servicio (SLO) estándares, pero la estabilidad puede variar entre las versiones. Es adecuado para pruebas, entornos 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 proporciona una lógica de detección confiable y constante, y es adecuado para entornos de producción y cargas de trabajo que requieren un comportamiento de filtro sin cambios. 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 anterior de Stable que permanece disponible durante 90 días después del lanzamiento de una nueva versión de Stable. Puedes migrar tus sistemas de producción a la nueva versión de Stable en cualquier momento durante este período. No puedes crear plantillas nuevas con una versión de 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 filtro

El parámetro de configuración de la versión del filtro no afecta los filtros de Sensitive Data Protection ni de URLs maliciosas.

Ciclo de vida de la versión

Google Cloud proporciona notificaciones sobre los cambios en el ciclo de vida de la versión, incluso cuando una versión se convierte en Legacy y su próxima fecha de baja en cada respuesta de la API de saneamiento. Debes migrar todas las plantillas que usen una versión de Legacy a Stable o Latest en un plazo de 90 días.

En el siguiente ejemplo, se describe el ciclo de vida de la versión:

1. Lanzamiento (Latest): Google lanza una nueva versión del filtro (v2) como Latest.
2. Promoción (de Latest a Stable): Cuando promocionamos la versión Latest a Stable (v2 se convierte en Stable), hacemos lo siguiente:
   1. Movemos la versión anterior de Stable (v1) a Legacy.
   2. Una nueva versión (v3) se convierte en la nueva Latest. Promocionamos una versión después de que se somete a pruebas rigurosas, demuestra un uso diario constante y tiene problemas mínimos para los clientes, o cuando se hace necesaria la protección contra amenazas críticas.
3. Retiro (Legacy a Retired): Después de que una versión del filtro permanece en el estado Legacy durante 90 días, la retiramos y ya no está disponible.

Cronograma de lanzamiento de la versión

En la siguiente tabla, se comparten detalles sobre las versiones de los filtros, incluidos los alias, las regiones admitidas y las fechas de lanzamiento.

Versión	Alias	Región admitida
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

Para obtener información sobre los cambios en la versión más reciente, consulta el 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 versión: Las plantillas sin una versión especificada, ya sean nuevas o existentes, se establecen de forma predeterminada en la versión Stable.

• Plantillas con alias Latest o Stable: Estas plantillas usan automáticamente la versión asignada a estos alias. Por ejemplo, cuando una nueva versión del filtro se convierte en la versión Stable, las plantillas que usan el alias Stable se mueven a la nueva versión sin necesidad de realizar cambios en las plantillas.

  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 de Latest o Stable, la plantilla se comporta según lo esperado.
  • Si la versión corresponde a una versión de Legacy, la plantilla se comporta según lo esperado cuando se usa para operaciones de saneamiento 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.

Cómo configurar una versión de filtro

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

• Con 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, no es necesario realizar actualizaciones manuales cuando cambia la versión subyacente.
• Con un número de versión: Usa un número de versión, como v1, para asegurarte de que una plantilla esté configurada en una versión específica, lo que garantiza un comportamiento fijo y sin cambios, 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 del 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 a lo que se muestra 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 que el filtro sea inmutable, 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: El número de versión del filtro que prefieras (por ejemplo, v1).

La respuesta es similar a lo que se muestra 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 del 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 a lo que se muestra 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"
    }
  }
}

Cómo ver la versión del filtro que se usa en las operaciones de saneamiento

Los metadatos de la respuesta de la API de Sanitize incluyen información sobre la versión del filtro que se usa durante el saneamiento. Recibirás una advertencia de baja en la respuesta de la API de limpieza 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": 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.