Definir a versão do filtro para um modelo

Este documento descreve como as versões de filtro do Model Armor funcionam e como instruir o Model Armor a usar uma versão de filtro ou um alias de versão de filtro específico em operações.

O Model Armor usa filtros para detectar e bloquear conteúdo nocivo, dados sensíveis, URLs maliciosos e ataques de injeção de comandos em comandos e respostas de LLMs. Para mais informações, consulte Filtros do Model Armor.

As versões de filtro do Model Armor oferecem estabilidade para cargas de trabalho de produção e acesso aos modelos mais recentes de detecção de ameaças. Você configura uma única versão de filtro no nível do modelo. Não é possível especificar versões diferentes para filtros individuais.

Aliases da versão

Em um modelo do Model Armor, é possível usar um alias para especificar sua versão de filtro preferida. Um alias representa uma etapa no ciclo de vida da versão. Cada alias é definido para a versão apropriada conforme o ciclo de vida avança.

Se você selecionar um alias, o modelo vai usar a versão definida para ele. Quando a versão subjacente desse alias é atualizada (por exemplo, quando uma nova versão é promovida para Stable), os modelos que usam o alias automaticamente usam a nova versão. Se você não quiser que a versão do filtro mude, aponte o modelo para uma versão específica.

Você pode escolher entre os seguintes aliases:

  • Latest: o alias com os modelos e proteções mais recentes, com atualizações frequentes contra ameaças emergentes. Esse alias oferece objetivos de nível de serviço (SLOs) padrão, mas a estabilidade pode variar entre as versões. Ele é adequado para testes, preparo e cargas de trabalho que priorizam modelos de detecção recentes em vez de um comportamento consistente do filtro.
  • Stable: o alias padrão para versões com modelos disponíveis. Esse alias oferece uma lógica de detecção confiável e imutável, sendo adequado para ambientes de produção e cargas de trabalho que exigem um comportamento de filtro imutável. Quando uma nova versão se torna Stable, a versão Stable anterior passa a ser Legacy.
  • Legacy: o alias de uma versão anterior do Stable que fica disponível por 90 dias após o lançamento de uma nova versão do Stable. Você pode migrar seus sistemas de produção para a nova versão do Stable a qualquer momento durante esse período. Não é possível criar modelos usando uma versão Legacy.
  • Retired: o alias de uma versão que ultrapassou o período legado de 90 dias e não está mais disponível. O Model Armor usa a versão Stable para limpar chamadas a modelos que ainda usam uma versão Retired.

Filtros que não usam versões de filtro

A configuração de versão do filtro não afeta a Proteção de dados sensíveis e os filtros de URL malicioso.

Ciclo de vida da versão

OGoogle Cloud fornece notificações sobre mudanças no ciclo de vida da versão, incluindo quando uma versão se torna Legacy e a data de descontinuação em cada resposta da API de limpeza. Migre todos os modelos que usam uma versão Legacy para Stable ou Latest dentro do período de 90 dias.

O exemplo a seguir descreve o ciclo de vida da versão:

  1. Versão (Latest): o Google lança uma nova versão do filtro (v2) como Latest.
  2. Promoção (Latest para Stable): quando promovemos a versão Latest para Stable (v2 se torna Stable), fazemos o seguinte:
    1. Movemos a versão anterior do Stable (v1) para Legacy.
    2. Uma nova versão (v3) se torna o novo Latest. Promovemos uma versão depois que ela passa por testes rigorosos, demonstra uso diário consistente e tem problemas mínimos para o cliente ou quando a proteção contra ameaças críticas se torna necessária.
  3. Desativação (Legacy a Retired): depois que uma versão de filtro permanece no estado Legacy por 90 dias, ela é desativada e não fica mais disponível.

Cronograma de lançamento da versão

A tabela a seguir compartilha detalhes sobre as versões de filtro, incluindo aliases, regiões compatíveis e datas de lançamento.

Versão Alias Região aceita
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 saber mais sobre as mudanças na versão mais recente, consulte o Histórico de versões.

Comportamento do modelo

O comportamento do modelo depende da versão do filtro usada e segue estas características:

  • Modelos sem uma versão: modelos sem uma versão especificada, sejam novos ou atuais, usam a versão Stable por padrão.

  • Modelos com aliases Latest ou Stable: esses modelos usam automaticamente a versão atribuída a esses aliases. Por exemplo, quando uma nova versão de filtro se torna a versão Stable, os modelos que usam o alias Stable mudam para a nova versão sem exigir alterações no modelo.

  • Modelos que usam uma versão específica:

    • Se a versão corresponder a uma versão Latest ou Stable, o modelo vai se comportar como esperado.
    • Se a versão corresponder a uma versão Legacy, o modelo vai se comportar como esperado quando usado para operações de limpeza por um período de 90 dias. Após 90 dias, a versão passa para a fase Retired. Durante essa fase, você precisa migrar seus modelos para a versão Latest ou Stable.

Configurar uma versão de filtro

É possível configurar a versão do filtro para um modelo de duas maneiras:

  • Usando um alias: use aliases dinâmicos, como Stable ou Latest, para que o modelo use automaticamente um número de versão que corresponda ao seu alias preferido. Isso elimina a necessidade de atualizações manuais quando a versão subjacente muda.
  • Usando um número de versão: use um número de versão, como v1, para garantir que um modelo seja definido para uma versão específica, garantindo um comportamento fixo e inalterado, mesmo quando os aliases são atualizados.

Criar um modelo usando um alias de versão

Para criar um modelo usando um alias de versão específico, execute o seguinte 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"

Substitua:

  • FILTER_VERSION_ALIAS: o alias da versão de filtro de sua preferência. Use FILTER_VERSION_ALIAS_STABLE ou FILTER_VERSION_ALIAS_LATEST.
  • PROJECT_ID: o ID do projeto a que o modelo pertence.
  • TEMPLATE_ID: o ID do modelo a ser criado.
  • LOCATION: o local do modelo.

O resultado parecido com este:

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

Criar um modelo usando uma versão específica do filtro

Se você precisar de imutabilidade de filtro, crie um modelo que corresponda a uma versão específica. Para isso, execute este comando:

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"

Substitua:

  • PROJECT_ID: o ID do projeto a que o modelo pertence.
  • TEMPLATE_ID: o ID do modelo a ser criado.
  • LOCATION: o local do modelo.
  • FILTER_VERSION_NUMBER: o número da versão do filtro de sua preferência (por exemplo, v1).

O resultado parecido com este:

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

Atualizar a versão do filtro de um modelo

Para atualizar a versão ou o alias do filtro de um modelo, execute o comando a seguir:

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"

Substitua:

  • FILTER_VERSION_ALIAS: o alias da versão de filtro de sua preferência. Use FILTER_VERSION_ALIAS_STABLE ou FILTER_VERSION_ALIAS_LATEST.
  • PROJECT_ID: o ID do projeto a que o modelo pertence.
  • TEMPLATE_ID: o ID do modelo a ser criado.
  • LOCATION: o local do modelo.

O resultado parecido com este:

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

Ver a versão do filtro usada em operações de limpeza

Os metadados da resposta da API Sanitize incluem informações sobre a versão do filtro usada durante a sanitização. Você recebe um aviso de descontinuação na resposta da API sanitize 30 dias antes de o Google desativar a versão.

O exemplo a seguir mostra uma resposta da API que inclui a versão do 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."
        }
      ]
   }
  },
}

O Model Armor gera registros da plataforma para solicitações de higienização e as respostas delas no Cloud Logging. Para mais informações sobre os registros de auditoria gerados automaticamente, consulte Registro de auditoria do Model Armor.