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 del filtro Model Armor e come indicare a Model Armor di utilizzare una versione specifica del filtro o un alias della versione del filtro 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 Model Armor.

Le versioni dei filtri 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.

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 dell'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 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à può variare a seconda delle versioni. È adatto per test, staging e carichi di lavoro che danno la priorità ai modelli di rilevamento recenti rispetto a un comportamento coerente dei filtri.
Stable: l'alias predefinito per le versioni con modelli disponibili. Questo alias fornisce una logica di rilevamento affidabile e invariabile ed è adatto a ambienti di produzione e workload che richiedono un comportamento di filtro invariato. Quando una nuova versione diventa Stable, la versione Stable precedente diventa Legacy.
Legacy: l'alias per 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 Stable in qualsiasi momento durante questo periodo. Non puoi creare nuovi modelli utilizzando una versione di Legacy.
Retired: l'alias di una versione che ha superato il periodo legacy di 90 giorni e non è più disponibile. Model Armor utilizza la versione Stable per sanificare 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 Sensitive Data Protection e URL dannosi.

Ciclo di vita delle versioni

Google Cloud fornisce notifiche sulle modifiche al ciclo di vita delle versioni, incluso quando una versione diventa Legacy e la relativa data di ritiro imminente in ogni risposta dell'API sanitize. Devi eseguire la migrazione di tutti i modelli che utilizzano una versione di 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 alla versione Stable (v2 diventa Stable), si verifica quanto segue:
1. Google sposta la versione precedente Stable (v1) in Legacy.
2. Una nuova versione (v3) diventa il nuovo Latest. Google promuove una versione dopo che è stata sottoposta a test rigorosi, dimostra un utilizzo quotidiano coerente e presenta problemi minimi per i clienti o quando diventa necessaria una protezione dalle minacce critiche.
Ritiro (dal giorno Legacy al giorno Retired): dopo 90 giorni in stato Legacy, Google ritira una versione del filtro, che 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` a partire 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` a partire 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` a partire dal 25 settembre 2026 in `australia-southeast2`)	2026-05-25	—	`asia-northeast1` `asia-south1` `asia-southeast1` `australia-southeast2` (`Stable` a partire 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`	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`

Per informazioni sulle modifiche apportate a ogni versione, vedi Filtrare la cronologia delle versioni.

Comportamento dei modelli

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 modello si comporta come previsto.
- Se la versione corrisponde a una versione di 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 migrare i tuoi modelli alla versione Latest o Stable.

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

Le impostazioni di base utilizzano per impostazione predefinita la versione del filtro Stable. Per l'integrazione di Gemini Enterprise Agent Platform, se vuoi ignorare questa impostazione, specifica un modello nella chiamata generateContent al modello Gemini. A questo scopo, crea un modello con una versione o un alias di 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 template 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 a Gemini. Viene applicata la configurazione del filtro specificata nel modello anziché l'impostazione del minimo 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 Google Cloud regione dell'endpoint Gemini.
LOCATION: la regione in cui è archiviato il template Model Armor. Deve essere la stessa regione specificata per REGION.
TEMPLATE_ID: l'ID del modello Model Armor.

Configurare una versione del filtro per un modello

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

Utilizzando un alias: utilizza alias dinamici come Stable o Latest per fare in modo che il modello utilizzi automaticamente un numero di versione corrispondente al tuo alias preferito. In questo modo non sono necessari aggiornamenti manuali quando cambia la versione sottostante.
Utilizzando un numero di versione: utilizza un numero di versione come v1 per assicurarti che un modello sia impostato su una versione specifica, 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 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 modello.
TEMPLATE_ID: l'ID del modello da creare.
LOCATION: la posizione 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"
    }
  }
}

Creare un modello utilizzando una versione specifica del filtro

Se hai bisogno dell'immutabilità del filtro, puoi creare un modello 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 modello.
TEMPLATE_ID: l'ID del modello da creare.
LOCATION: la posizione 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"
    }
  }
}

Aggiornare 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 posizione 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"
    }
  }
}

Visualizzare la versione del filtro utilizzata nelle operazioni di pulizia

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

Il seguente esempio 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 sanificazione e le relative risposte in Cloud Logging. Per ulteriori informazioni sui log di controllo generati automaticamente, vedi Log di controllo di Model Armor.

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

Alias versione

Filtri che non utilizzano le versioni dei filtri

Ciclo di vita delle versioni

Cronologia di rilascio delle versioni

Comportamento dei modelli

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

Configurare una versione del filtro per un modello

Crea un modello utilizzando un alias di versione

Creare un modello utilizzando una versione specifica del filtro

Aggiornare la versione del filtro di un modello

Visualizzare la versione del filtro utilizzata nelle operazioni di pulizia

Impostare la versione del filtro