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 come funzionano le versioni dei filtri di Model Armor e come indicare a Model Armor di utilizzare una versione o un alias di versione del filtro specifico nelle operazioni.

Model Armor utilizza i 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 carichi di lavoro di produzione e l'accesso ai modelli di rilevamento delle minacce più recenti. Configuri 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 filtraggio deterministico: imposta i modelli su una versione del 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 quando 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 rispetto ai pattern di traffico reali.
Attiva cicli di implementazione prevedibili: convalida i carichi di lavoro rispetto alle versioni dei filtri appena rilasciate prima di aggiornare manualmente i modelli di produzione.

Alias versione

In un modello 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. Man mano che il ciclo di vita procede, ogni alias viene impostato sulla versione appropriata.

Se selezioni un alias, il modello 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 modello a una versione del filtro specifica.

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 di livello di servizio (SLO) standard, ma la stabilità potrebbe variare a seconda delle versioni. È adatto per test, staging e carichi di lavoro che danno la priorità ai modelli di rilevamento recenti rispetto al comportamento coerente dei filtri.
Stable: l'alias predefinito per le versioni con modelli disponibili. Questo alias offre una logica di rilevamento affidabile e invariabile ed è adatto per ambienti di produzione e carichi di lavoro che richiedono un comportamento invariato dei filtri. Quando una nuova versione diventa Stable, la versione Stable precedente diventa Legacy.
Legacy: l'alias per una versione Stable precedente che rimane disponibile per 90 giorni dopo il rilascio di una nuova versione Stable. Puoi eseguire la migrazione dei sistemi di produzione alla nuova versione Stable in qualsiasi momento durante questo periodo. Non puoi creare nuovi modelli utilizzando una versione Legacy.
Retired: l'alias per una versione che ha superato il periodo di legacy di 90 giorni e non è più disponibile. Model Armor utilizza la versione Stable per sanitizzare le chiamate ai modelli 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 URL dannosi.

Ciclo di vita delle versioni

Google Cloud fornisce notifiche sulle modifiche del ciclo di vita delle versioni, inclusa la data in cui una versione diventa Legacy e la data di ritiro imminente in ogni risposta dell'API di sanitizzazione. 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 (Latest a Stable): quando Google promuove la versione Latest a Stable (v2 diventa Stable), si verifica quanto segue:
1. Google sposta la versione Stable precedente (v1) a Legacy.
2. Una nuova versione (v3) diventa la nuova Latest. Google promuove una versione dopo che ha superato test rigorosi, dimostra un utilizzo quotidiano coerente e presenta problemi minimi per i clienti oppure quando diventa necessaria una protezione dalle minacce critica.
Ritiro (Legacy a Retired): dopo che una versione del filtro rimane nello stato Legacy per 90 giorni, Google la ritira e non è più disponibile.

Sequenza temporale del rilascio delle versioni

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

Versione	Alias	Data di rilascio	Data di ritiro	Regione supportata
`v1`	`Legacy` (`Stable` in `asia-northeast3`; `Legacy` dal 25 settembre 2026 in `australia-southeast2`)	30/01/2025	17/12/2026	`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`	19/06/2025	17/12/2026	`eu` `europe-west1` `europe-west2` `europe-west3` `europe-west4` `us-east1`
`v3`	`Stable` (`Stable` dal 25 settembre 2026 in `australia-southeast2`)	25/05/2026	—	`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` `us` `us-central1` `us-east1` `us-east4` `us-west1`
`v4`	`Latest`	18/09/2026	—	`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`

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

Comportamento dei modelli

Il comportamento dei modelli dipende dalla versione del filtro utilizzata e presenta le seguenti 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 modello si comporta come previsto.
- Se la versione corrisponde a una versione Legacy, il modello 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 di base

Con le impostazioni di base, l'integrazione di Gemini Enterprise Agent Platform utilizza per impostazione predefinita la versione del Stable filtro. Per eseguire l'override di questa impostazione, specifica un modello nella chiamata generateContent al modello Gemini. Per farlo, crea un modello con una versione o un alias del filtro specifico nella stessa regione in cui prevedi di inviare la richiesta 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 modello.
TEMPLATE_ID: l'ID del modello da creare.
LOCATION: la regione in cui archiviare il modello Model Armor. Questa regione deve essere la stessa in cui prevedi di inviare la richiesta Gemini; in caso contrario, 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 modello nell'oggetto model_armor_config nella chiamata Gemini. La configurazione del filtro specificata nel modello viene applicata al posto dell'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' Google Cloud ID progetto.
REGION: la Google Cloud regione dell'endpoint Gemini.
LOCATION: la regione in cui è archiviato il modello Model Armor. Deve essere la stessa regione specificata per REGION.
TEMPLATE_ID: l'ID del modello Model Armor.

Configura una versione del filtro per un modello

Puoi configurare la versione del filtro per un modello in due modi:

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

Crea un modello utilizzando un alias di versione

Per creare un modello utilizzando un alias di versione specifico, esegui il seguente 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 modello.
TEMPLATE_ID: l'ID del modello da creare.
LOCATION: la località del modello.

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 del filtro specifica

Se hai bisogno dell'immutabilità del filtro, puoi creare un modello che corrisponda a una versione specifica. Per farlo, esegui il seguente 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 modello.
TEMPLATE_ID: l'ID del modello da creare.
LOCATION: la località del modello.
FILTER_VERSION_NUMBER: il numero della 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 modello

Per aggiornare la versione o l'alias del filtro per un modello esistente, esegui il seguente 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 modello.
TEMPLATE_ID: l'ID del modello da creare.
LOCATION: la località del modello.

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 di sanitizzazione includono informazioni sulla versione del filtro utilizzata durante la sanitizzazione. Riceverai un avviso di ritiro nella risposta dell'API di sanitizzazione 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

Sequenza temporale del rilascio delle versioni

Comportamento dei modelli

Esegui l'override della versione del filtro predefinita per le impostazioni di base

Configura una versione del filtro per un modello

Crea un modello utilizzando un alias di versione

Crea un modello utilizzando una versione del filtro specifica

Aggiorna la versione del filtro di un modello

Visualizza la versione del filtro utilizzata nelle operazioni di sanitizzazione

Impostare la versione del filtro