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

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

O Model Armor usa filtros para detectar e bloquear conteúdo prejudicial, dados sensíveis, URLs mal-intencionados 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 de detecção de ameaças mais recentes. 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 modelos para uma versão de filtro específica para evitar mudanças na lógica de detecção de ameaças em sistemas de missão crítica.
Receber atualizações de segurança automáticas: use o alias Stable para adotar modelos de detecção de ameaças atualizados automaticamente à medida que eles passam pela validação.
Testar os recursos de detecção futuros: 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, você pode usar um alias para especificar a versão de filtro preferida. Um alias representa um estágio no ciclo de vida da versão. Cada alias é definido para a versão apropriada à medida que o ciclo de vida avança.

Se você selecionar um alias, o modelo vai usar a versão para a qual o alias está definido. 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 seja alterada, aponte o modelo para uma versão de filtro 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 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 e é adequado para ambientes de produção e cargas de trabalho que exigem 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 Stable anterior que permanece disponível por 90 dias após o lançamento de uma nova versão Stable. Você pode migrar seus sistemas de produção para a nova versão 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 legado de 90 dias e não está mais disponível. O Model Armor usa a versão Stable para higienizar chamadas para modelos que ainda estão usando uma versão Retired.

Filtros que não usam versões de filtro

A configuração da versão de filtro não afeta a Proteção de Dados Sensíveis e os filtros de URLs mal-intencionados.

Ciclo de vida das versões

Google 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 desativação futura em cada resposta da API Sanitize. Você precisa 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:

Lançamento (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), o seguinte ocorre:
1. O Google move a versão Stable anterior (v1) para Legacy.
2. Uma nova versão (v3) se torna a nova Latest. O Google promove uma versão depois que ela passa por testes rigorosos, demonstra uso diário consistente e tem problemas mínimos do 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 da versão

A tabela a seguir compartilha 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` `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 informações sobre o que mudou em cada versão, consulte 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: os modelos sem uma versão especificada, novos ou atuais, são definidos como 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 são movidos para a nova versão sem exigir mudanças 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 conforme o esperado quando usado para operações de higienização por um período de 90 dias. Após 90 dias, a versão passa para a fase Retired. Durante essa fase, é necessário migrar os modelos para a versão Latest ou Stable.

Substituir a versão de filtro padrão para configurações mínimas

Com as configurações mínimas, a integração da Gemini Enterprise Agent Platform usa a versão de Stable filtro 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 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 de filtro preferida. 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 plataforma de agentes vai receber um erro Template not found. Para uma lista de regiões compatíveis com essa integração, consulte Integração com a plataforma de agentes do Gemini Enterprise.

Forneça 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 Google Cloud ID do projeto.
REGION: a Google Cloud região do endpoint do Gemini.
LOCATION: a região em que o modelo do Model Armor está armazenado. Essa 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 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 especificada, 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 preferida. 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.

A resposta é semelhante a:

{
  "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 do 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 de filtro preferida (por exemplo, v1).

A resposta é semelhante a:

{
  "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 atual, 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 de filtro preferida. 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.

A resposta é semelhante a:

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

Conferir a versão do filtro usada em operações de higienização

Os metadados de resposta da API Sanitize incluem informações sobre a versão do filtro usada durante a higienizaçã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 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.

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 da versão

Comportamento do modelo

Substituir a versão de filtro padrão para configurações mínimas

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

Conferir a versão do filtro usada em operações de higienização

Definir a versão do filtro