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í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 comando em prompts e respostas de LLM. 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, é possível 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.

É possível 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. É possível 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 limpar 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 cada resposta da API de limpeza. É necessário 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, regiões compatíveis e datas de lançamento.

Versão Alias Região compatível Data de lançamento
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

 2025-01-30
v2 Stable

eu

europe-west1

europe-west2

europe-west3

europe-west4

us-east1

 2025-06-19
v3 Latest

eu

europe-west1

europe-west2

europe-west3

europe-west4

europe-southwest1

europe-west9

us

us-central1

us-east1

us-east4

us-east7

us-west1

 2026-05-25

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, sejam 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.

  • 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 limpeza 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.

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 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 limpeza

Os metadados de resposta da API Sanitize incluem informações sobre a versão do filtro usada durante a limpeza. Você recebe um aviso de descontinuação na resposta da API de limpeza 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 limpeza 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.