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 um alias ou versão de filtro específica 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 comando em prompts 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.

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, preparação 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 de 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 do filtro não afeta os filtros de proteção de dados sensíveis e de URL maliciosa.

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 todas as respostas da API de higienização. 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:

1. Lançamento (Latest): o Google lança uma nova versão de 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 Stable anterior (v1) para Legacy.
   2. Uma nova versão (v3) se torna a nova Latest. Promovemos 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.
3. Desativação (Legacy para 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, datas de promoção, datas de desativação e regiões compatíveis.

Versão	Alias	Data de promoção para estável	Data de desativação	Região compatível
v1	Legacy (em vigor a partir de 31 de agosto de 2026)	Já estável	2026-11-29	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	Legacy (em vigor a partir de 31 de agosto de 2026)	Já estável	2026-11-29	eu europe-west1 europe-west2 europe-west3 europe-west4 us-east1
v3	Stable (em vigor a partir de 31 de agosto de 2026)	2026-08-31	—	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 informações sobre o que mudou na versão mais recente, consulte 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: 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 se comportará como esperado.
  • Se a versão corresponder a uma versão Legacy, o modelo se comportará como 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, você precisa migrar seus modelos para a versão Latest ou Stable.

Configurar uma versão de filtro

Você pode 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 a que 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 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 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 a que 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 de higienização 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 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.