Impostare la versione del filtro per un modello

Questo documento descrive come funzionano le versioni dei filtri 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 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 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 Legacy a Stable o Latest entro il periodo di 90 giorni.

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

  1. Release (Latest): Google rilascia una nuova versione del filtro (v2) come Latest.
  2. Promozione (dal giorno Latest al giorno Stable): quando promuoviamo la versione Latest alla versione Stable (v2 diventa Stable), eseguiamo le seguenti operazioni:
    1. Spostiamo la versione precedente di Stable (v1) su Legacy.
    2. Una nuova versione (v3) diventa il nuovo Latest. Promuoviamo una versione dopo che è stata sottoposta a test rigorosi, ha dimostrato un utilizzo quotidiano coerente e presenta problemi minimi per i clienti oppure quando diventa necessaria una protezione dalle minacce critiche.
  3. Ritiro (dal giorno Legacy al giorno Retired): dopo che una versione del filtro rimane nello stato Legacy per 90 giorni, viene ritirata e non è più disponibile.

Cronologia di rilascio delle versioni

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

Versione Alias Regione supportata
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
v2 Stable

eu

europe-west1

europe-west2

europe-west3

europe-west4

us-east1
v3 Latest

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

Per informazioni sulle modifiche apportate nell'ultima versione, vedi 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.

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

Configurare una versione del filtro

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 più necessari 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 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 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 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": 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."
        }
      ]
   }
  },
}

Model Armor genera log della piattaforma per le richieste di sanificazione e le relative risposte in Cloud Logging. Per saperne di più sui log di controllo generati automaticamente, vedi Log di controllo di Model Armor.