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ù, vedi 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.
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. Ogni alias viene impostato sulla versione appropriata man mano che il ciclo di vita procede.
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 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 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 diventaStable, la versioneStableprecedente diventaLegacy.Legacy: l'alias per una versioneStableprecedente che rimane disponibile per 90 giorni dopo il rilascio di una nuova versioneStable. Durante questo periodo, puoi eseguire la migrazione dei sistemi di produzione alla nuova versioneStablein qualsiasi momento. Non puoi creare nuovi modelli utilizzando una versioneLegacy.Retired: l'alias per una versione che ha superato il periodo di legacy di 90 giorni e non è più disponibile. Model Armor utilizza la versioneStableper sanitizzare le chiamate ai modelli che utilizzano ancora una versioneRetired.
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 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) comeLatest. - Promozione (
LatestaStable): quando promuoviamo la versioneLatestaStable(v2diventaStable), eseguiamo le seguenti operazioni:- Spostiamo la versione
Stableprecedente (v1) aLegacy. - Una nuova versione (
v3) diventa la nuovaLatest. Promuoviamo una versione dopo che ha superato test rigorosi, ha dimostrato un utilizzo quotidiano coerente e ha problemi minimi per i clienti oppure quando diventa necessaria una protezione dalle minacce critica.
- Spostiamo la versione
- Ritiro (
LegacyaRetired): dopo che una versione del filtro rimane nello statoLegacyper 90 giorni, la ritiriamo e non è più disponibile.
Cronologia di rilascio delle versioni
La tabella seguente condivide i dettagli sulle versioni dei filtri, inclusi gli alias, le regioni supportate e le date di rilascio.
| Versione | Alias | Regione supportata | Data di uscita |
|---|---|---|---|
v1 |
Stable |
asia-northeast1
|
30/01/2025 |
v2 |
Stable |
|
19/06/2025 |
v3 |
Latest |
|
25/05/2026 |
Per informazioni sulle modifiche apportate all'ultima versione, vedi Cronologia delle versioni.
Comportamento dei modelli
Il comportamento dei modelli 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
LatestoStable: questi modelli utilizzano automaticamente la versione assegnata a questi alias. Ad esempio, quando una nuova versione del filtro diventa la versioneStable, i modelli che utilizzano l'aliasStablepassano alla nuova versione senza richiedere modifiche al modello.Modelli che utilizzano una versione specifica:
- Se la versione corrisponde a una versione
LatestoStable, 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 faseRetired. Durante questa fase, devi eseguire la migrazione dei modelli alla versioneLatestoStable.
- Se la versione corrisponde a una versione
Configurare una versione del filtro
Puoi configurare la versione del filtro per un modello in due modi:
- Utilizzando un alias: utilizza alias dinamici come
StableoLatestper fare in modo che il modello utilizzi automaticamente un numero di versione che corrisponde 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
v1per assicurarti che un modello sia impostato su una versione specificata, garantendo un comportamento fisso e invariato anche quando gli alias vengono aggiornati.
Creare 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. UtilizzaFILTER_VERSION_ALIAS_STABLEoFILTER_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"
}
}
}
Creare un modello utilizzando una versione del filtro specifica
Se hai bisogno dell'immutabilità dei filtri, puoi creare un modello che corrisponda a una versione specifica. Per farlo, esegui il comando seguente:
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"
}
}
}
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. UtilizzaFILTER_VERSION_ALIAS_STABLEoFILTER_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"
}
}
}
Visualizzare 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": 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 sanitizzazione e le relative risposte in Cloud Logging. Per saperne di più sui log di controllo generati automaticamente, vedi Log di controllo di Model Armor.