O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Definir a versão do filtro

Neste documento, descrevemos como as versões de filtro do Model Armor funcionam e como instruir o Model Armor a usar uma versão de filtro específica ou um alias de versão de filtro nas 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.

Quando configurar versões e aliases de filtro

Veja alguns casos de uso comuns:

Bloquear o comportamento de filtragem determinista: defina os modelos para uma versão de filtro específica para evitar mudanças na lógica de detecção de ameaças em sistemas essenciais.
Receber atualizações de segurança automáticas: use o alias Stable para adotar automaticamente modelos de detecção de ameaças atualizados à medida que eles passam pela validação.
Testar os próximos recursos de detecção: use o alias Latest em ambientes de pré-produção para avaliar novas regras de filtro em relação a padrões de tráfego reais.
Ativar ciclos de lançamento previsíveis: valide as cargas de trabalho em relação às versões de filtro recém-lançadas antes de atualizar manualmente os modelos de produção.

Aliases da versão

Em um modelo do Model Armor, é possível usar um alias para especificar a versão de filtro de sua preferência. Um alias representa um estágio 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 usam automaticamente 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 as 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 de filtro consistente.
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 inalterado. Quando uma nova versão se torna Stable, a versão Stable anterior se torna Legacy.
Legacy: o alias de uma versão anterior do Stable que permanece disponível por 90 dias após o lançamento de uma nova versão do Stable. É possível 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 novos modelos usando uma versão Legacy.
Retired: o alias de uma versão que ultrapassou o período de versões legadas de 90 dias e não está mais disponível. O Model Armor usa a versão Stable para limpar as chamadas para modelos que ainda usam uma versão Retired.

Filtros que não usam versões de filtro

A configuração da versão do filtro não afeta a Proteção de Dados Sensíveis nem os filtros de URLs maliciosos.

Ciclo de vida das versões

AGoogle Cloud fornece notificações sobre mudanças no ciclo de vida das versões, incluindo quando uma versão se torna Legacy e a data de desativação dela em cada resposta da API Sanitize. É preciso migrar 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:

Versão (Latest): o Google lança uma nova versão de filtro (v2) como Latest.
Promoção (Latest para Stable): quando o Google promove a versão Latest para Stable (v2 se torna Stable), ocorre o seguinte:
1. O Google move a versão anterior do Stable (v1) para Legacy.
2. Uma nova versão (v3) se torna o novo Latest. O Google promove 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.
Desativação (Legacy para Retired): depois que uma versão de filtro permanece no estado Legacy por 90 dias, o Google a desativa, e ela não fica mais disponível.

Cronograma de lançamento de versões

A tabela a seguir mostra detalhes sobre as versões de filtro, incluindo aliases, datas de lançamento, datas de desativação e regiões com disponibilidade.

Versão	Alias	Data de lançamento	Data de desativação	Região com disponibilidade
`v1`	`Legacy` (`Stable` em `asia-northeast3`; `Legacy` a partir de 25 de setembro de 2026 em `australia-southeast2`)	2025-01-30	2026-12-17	`asia-northeast1` `asia-northeast3` (`Stable`) `asia-south1` `asia-southeast1` `australia-southeast2` (`Legacy` a partir de 25 de setembro 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 de 25 de setembro de 2026 em `australia-southeast2`)	2026-05-25	—	`asia-northeast1` `asia-south1` `asia-southeast1` `australia-southeast2` (`Stable` a partir de 25 de setembro de 2026) `eu` `europe-southwest1` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `europe-west9` `northamerica-northeast2` `southamerica-east1` `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` `southamerica-east1` `us` `us-central1` `us-east1` `us-east4` `us-west1`

Para saber o que mudou em cada versão, consulte o histórico de versões do filtro.

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 como padrão a versão Stable.
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 são movidos para a nova versão sem exigir alterações no modelo.

Observação : não é possível definir a versão do filtro em um modelo como Legacy ou Retired.
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 conforme o 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.

Substituir a versão padrão do filtro para as configurações de preço mínimo

Com as configurações de piso, a integração da Gemini Enterprise Agent Platform usa a versão de filtro Stable por padrão. Para substituir essa configuração, especifique um modelo na chamada generateContent para o modelo do Gemini. Para fazer isso, crie um modelo com uma versão ou um alias de filtro específico na mesma região em que você planeja enviar a solicitação do 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"

Substitua:

FILTER_VERSION_ALIAS: o alias da versão do filtro de sua preferência. Use FILTER_VERSION_ALIAS_STABLE ou FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: o ID do projeto ao qual o modelo pertence.
TEMPLATE_ID: o ID do modelo a ser criado.
LOCATION: a região para armazenar o modelo do Model Armor. Essa região precisa ser a mesma em que você planeja enviar a solicitação do Gemini. Caso contrário, a Agent Platform vai receber um erro Template not found. Para uma lista de regiões compatíveis com essa integração, consulte Integração com a Gemini Enterprise Agent Platform.

Informe o ID do modelo no objeto model_armor_config na chamada do Gemini. A configuração de filtro especificada no modelo é aplicada em vez da configuração mínima para envolvidos no projeto.

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

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud .
REGION: a região doGoogle Cloud do endpoint do Gemini.
LOCATION: a região em que o modelo do Model Armor está armazenado. Precisa ser a mesma região especificada para REGION.
TEMPLATE_ID: o ID do modelo do Model Armor.

Configurar uma versão de filtro para um modelo

É 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 é alterada.
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 do filtro de sua preferência. Use FILTER_VERSION_ALIAS_STABLE ou FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: o ID do projeto ao qual 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 de filtro específica

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 ao qual 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 seguinte 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"

Substitua:

FILTER_VERSION_ALIAS: o alias da versão do filtro de sua preferência. Use FILTER_VERSION_ALIAS_STABLE ou FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: o ID do projeto ao qual 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 de 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": 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."
        }
      ]
   }
  },
}

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

Definir a versão do filtro Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Quando configurar versões e aliases de filtro

Aliases da versão

Filtros que não usam versões de filtro

Ciclo de vida das versões

Cronograma de lançamento de versões

Comportamento do modelo

Substituir a versão padrão do filtro para as configurações de preço mínimo

Configurar uma versão de filtro para um modelo

Criar um modelo usando um alias de versão

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

Atualizar a versão do filtro de um modelo

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

Definir a versão do filtro