Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Impostare la versione del filtro

Questo documento descrive il funzionamento delle versioni dei filtri di Model Armor e come indicare a Model Armor di utilizzare una versione del filtro o un alias della versione del filtro specifici nelle operazioni.

Model Armor utilizza filtri per rilevare e bloccare contenuti dannosi, dati sensibili, URL dannosi e attacchi di prompt injection nei prompt e nelle risposte degli LLM. Per saperne di più, consulta Filtri di Model Armor.

Le versioni dei filtri di Model Armor garantiscono la stabilità dei workload di produzione e l'accesso ai modelli di rilevamento delle minacce più recenti. Puoi configurare una singola versione del filtro a livello di modello. Non puoi specificare versioni diverse per i singoli filtri.

Quando configurare le versioni e gli alias dei filtri

Ecco alcuni casi d'uso comuni:

Blocca il comportamento di filtro deterministico: imposta i template su una versione di filtro specifica per impedire modifiche alla logica di rilevamento delle minacce nei sistemi mission-critical.
Ricevi aggiornamenti automatici della sicurezza: utilizza l'alias Stable per adottare automaticamente i modelli di rilevamento delle minacce aggiornati non appena superano la convalida.
Testa le funzionalità di rilevamento imminenti: utilizza l'alias Latest negli ambienti di pre-produzione per valutare le nuove regole di filtro in base ai pattern di traffico reali.
Abilita cicli di implementazione prevedibili: convalida i workload rispetto alle versioni dei filtri appena rilasciate prima di aggiornare manualmente i template di produzione.

Alias versione

In un template di Model Armor, puoi utilizzare un alias per specificare la versione del filtro che preferisci. Un alias rappresenta una fase del ciclo di vita della versione. Ogni alias viene impostato sulla versione appropriata man mano che il ciclo di vita avanza.

Se selezioni un alias, il template utilizza la versione a cui è impostato l'alias. Quando la versione sottostante per l'alias viene aggiornata (ad esempio, quando una nuova versione viene promossa a Stable), i modelli che utilizzano l'alias utilizzano automaticamente la nuova versione. Se non vuoi che la versione del filtro cambi, indirizza il template a una versione specifica del filtro.

Puoi scegliere tra i seguenti alias:

Latest: l'alias con i modelli e le protezioni più recenti, con aggiornamenti frequenti contro le minacce emergenti. Questo alias offre obiettivi del livello di servizio (SLO) standard, ma la stabilità potrebbe variare tra le versioni. È adatto per test, gestione temporanea e workload che danno la priorità ai modelli di rilevamento recenti rispetto a un comportamento dei filtri coerente.
Stable: l'alias predefinito per le versioni con modelli disponibili. Questo alias fornisce una logica di rilevamento affidabile e invariata ed è adatto per ambienti di produzione e workload che richiedono un comportamento dei filtri invariato. Quando una nuova versione diventa Stable, la versione Stable precedente diventa Legacy.
Legacy: l'alias di una versione precedente di Stable che rimane disponibile per 90 giorni dopo il rilascio di una nuova versione di Stable. Puoi eseguire la migrazione dei tuoi sistemi di produzione alla nuova versione di Stable in qualsiasi momento durante questo periodo. Non puoi creare nuovi template utilizzando una versione Legacy.
Retired: l'alias di una versione che ha superato il periodo di supporto legacy di 90 giorni e non è più disponibile. Model Armor utilizza la versione Stable per sanitizzare le chiamate ai template che utilizzano ancora una versione Retired.

Filtri che non utilizzano le versioni dei filtri

L'impostazione della versione del filtro non influisce sui filtri di Sensitive Data Protection e degli URL dannosi.

Ciclo di vita delle versioni

Google Cloud fornisce notifiche sulle modifiche al ciclo di vita delle versioni, tra cui quando una versione diventa Legacy e la data di ritiro imminente in ogni risposta dell'API sanitize. Devi eseguire la migrazione di tutti i modelli che utilizzano una versione Legacy a Stable o Latest entro il periodo di 90 giorni.

L'esempio seguente descrive il ciclo di vita della versione:

Release (Latest): Google rilascia una nuova versione del filtro (v2) come Latest.
Promozione (da Latest a Stable): quando Google promuove la versione Latest a Stable (v2 diventa Stable), si verifica quanto segue:
1. Google sposta la versione precedente di Stable (v1) in Legacy.
2. Una nuova versione (v3) diventa la nuova Latest. Google promuove una versione dopo che è stata sottoposta a test rigorosi, dimostra un utilizzo quotidiano costante e presenta problemi minimi per i clienti o quando diventa necessaria una protezione dalle minacce critiche.
Ritiro (da Legacy a Retired): dopo che una versione del filtro rimane nello stato Legacy per 90 giorni, Google la ritira e non è più disponibile.

Cronologia di rilascio delle versioni

La tabella seguente fornisce dettagli sulle versioni dei filtri, inclusi alias, date di rilascio, date di ritiro e regioni supportate.

Versione	Alias	Data di uscita	Data di ritiro	Regione supportata
`v1`	`Legacy` (`Stable` in `asia-northeast3`; `Legacy` dal 25 settembre 2026 in `australia-southeast2`)	30/01/2025	2026-12-17	`asia-northeast1` `asia-northeast3` (`Stable`) `asia-south1` `asia-southeast1` `australia-southeast2` (`Legacy` dal 25 settembre 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` dal 25 settembre 2026 in `australia-southeast2`)	2026-05-25	—	`asia-northeast1` `asia-south1` `asia-southeast1` `australia-southeast2` (`Stable` dal 25 settembre 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`

Per informazioni sulle modifiche apportate in ogni versione, consulta Cronologia delle versioni dei filtri.

Comportamento del modello

Il comportamento del modello dipende dalla versione del filtro utilizzata e segue queste caratteristiche:

Modelli senza versione: i modelli senza una versione specificata, nuovi o esistenti, utilizzano per impostazione predefinita la versione Stable.
Modelli con alias Latest o Stable: questi modelli utilizzano automaticamente la versione assegnata a questi alias. Ad esempio, quando una nuova versione del filtro diventa la versione Stable, i modelli che utilizzano l'alias Stable passano alla nuova versione senza richiedere modifiche al modello.

Nota: non puoi impostare la versione del filtro in un modello su Legacy o Retired.
Modelli che utilizzano una versione specifica:
- Se la versione corrisponde a una versione Latest o Stable, il template si comporta come previsto.
- Se la versione corrisponde a una versione Legacy, il template si comporta come previsto quando viene utilizzato per le operazioni di sanitizzazione per un periodo di 90 giorni. Dopo 90 giorni, la versione passa alla fase Retired. Durante questa fase, devi eseguire la migrazione dei modelli alla versione Latest o Stable.

Esegui l'override della versione del filtro predefinita per le impostazioni dei prezzi minimi

Con le impostazioni di base, l'integrazione di Gemini Enterprise Agent Platform utilizza la versione del filtro Stable per impostazione predefinita. Per eseguire l'override di questa impostazione, specifica un template nella chiamata generateContent al modello Gemini. Per farlo, crea un template con una versione o un alias di filtro specifico nella stessa regione in cui prevedi di inviare la richiesta di 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"

Sostituisci quanto segue:

FILTER_VERSION_ALIAS: l'alias della versione del filtro che preferisci. Utilizza FILTER_VERSION_ALIAS_STABLE o FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: l'ID del progetto a cui appartiene il template.
TEMPLATE_ID: l'ID del template da creare.
LOCATION: la regione in cui archiviare il template di Model Armor. Questa regione deve essere la stessa in cui prevedi di inviare la richiesta Gemini, altrimenti Agent Platform riceve un errore Template not found. Per un elenco delle regioni supportate per questa integrazione, consulta Integrazione con Gemini Enterprise Agent Platform.

Fornisci l'ID template nell'oggetto model_armor_config nella chiamata a Gemini. Viene applicata la configurazione del filtro specificata nel template anziché l'impostazione di base a livello di progetto.

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

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto Google Cloud .
REGION: la regioneGoogle Cloud dell'endpoint Gemini.
LOCATION: la regione in cui è archiviato il template di Model Armor. Deve essere la stessa regione specificata per REGION.
TEMPLATE_ID: l'ID del template Model Armor.

Configura una versione del filtro per un modello

Puoi configurare la versione del filtro per un modello in uno dei seguenti modi:

Utilizzando un alias: utilizza alias dinamici come Stable o Latest per fare in modo che il template utilizzi automaticamente un numero di versione corrispondente all'alias che preferisci. In questo modo non sono necessari aggiornamenti manuali quando la versione sottostante cambia.
Utilizzando un numero di versione: utilizza un numero di versione come v1 per assicurarti che un template sia impostato su una versione specificata, garantendo un comportamento fisso e invariato anche quando gli alias vengono aggiornati.

Crea un template utilizzando un alias di versione

Per creare un template utilizzando un alias di versione specifico, esegui questo 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"

Sostituisci quanto segue:

FILTER_VERSION_ALIAS: l'alias della versione del filtro che preferisci. Utilizza FILTER_VERSION_ALIAS_STABLE o FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: l'ID del progetto a cui appartiene il template.
TEMPLATE_ID: l'ID del template da creare.
LOCATION: la località del template.

La risposta è simile alla seguente:

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

Crea un modello utilizzando una versione specifica del filtro

Se hai bisogno dell'immutabilità dei filtri, puoi creare un template che corrisponda a una versione specifica. Per farlo, esegui questo 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"

Sostituisci quanto segue:

PROJECT_ID: l'ID del progetto a cui appartiene il template.
TEMPLATE_ID: l'ID del template da creare.
LOCATION: la località del template.
FILTER_VERSION_NUMBER: il numero di versione del filtro che preferisci (ad esempio v1).

La risposta è simile alla seguente:

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

Aggiorna la versione del filtro di un template

Per aggiornare la versione o l'alias del filtro per un template esistente, esegui questo 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"

Sostituisci quanto segue:

FILTER_VERSION_ALIAS: l'alias della versione del filtro che preferisci. Utilizza FILTER_VERSION_ALIAS_STABLE o FILTER_VERSION_ALIAS_LATEST.
PROJECT_ID: l'ID del progetto a cui appartiene il template.
TEMPLATE_ID: l'ID del template da creare.
LOCATION: la località del template.

La risposta è simile alla seguente:

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

Visualizza la versione del filtro utilizzata nelle operazioni di sanitizzazione

I metadati della risposta dell'API Sanitize includono informazioni sulla versione del filtro utilizzata durante la sanitizzazione. Riceverai un avviso di ritiro nella risposta dell'API sanitize 30 giorni prima che Google ritiri la versione.

L'esempio seguente mostra una risposta dell'API che include la versione del 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."
        }
      ]
   }
  },
}

Model Armor genera log della piattaforma per le richieste di sanitizzazione e le relative risposte in Cloud Logging. Per saperne di più sugli audit log generati automaticamente, consulta Audit logging di Model Armor.

Impostare la versione del filtro Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Quando configurare le versioni e gli alias dei filtri

Alias versione

Filtri che non utilizzano le versioni dei filtri

Ciclo di vita delle versioni

Cronologia di rilascio delle versioni

Comportamento del modello

Esegui l'override della versione del filtro predefinita per le impostazioni dei prezzi minimi

Configura una versione del filtro per un modello

Crea un template utilizzando un alias di versione

Crea un modello utilizzando una versione specifica del filtro

Aggiorna la versione del filtro di un template

Visualizza la versione del filtro utilizzata nelle operazioni di sanitizzazione

Impostare la versione del filtro