Norme di SanitizeModelResponse

Policy estensibile

Questa pagina si applica ad Apigee e ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Nota: questa policy è supportata su Apigee e su Apigee hybrid versione 1.15.1 e successive.

La policy SanitizeModelResponse protegge i client AI da contenuti dannosi o offensivi sanificando le risposte dei modelli di AI generativa. La policy utilizza Model Armor per valutare le risposte del modello alla ricerca di contenuti dannosi o offensivi, abilitando la protezione nativa per i client e i workload di AI che utilizzano Apigee. Model Armor è un servizio Google Cloud che offre misure di sicurezza e protezione dell'AI per mitigare i rischi associati ai modelli linguistici di grandi dimensioni (LLM).

Questa policy viene utilizzata in combinazione con la policy SanitizeUserPrompt.

Questa policy è una policy estensibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Nota: se hai configurato un proxy di inoltro per il tuo ambiente, le chiamate in uscita effettuate da questa policy a Model Armor vengono instradate tramite il proxy. Non è richiesta alcuna configurazione a livello di policy. Questo vale per Apigee e Apigee Hybrid 1.16.10 e versioni successive e 1.17.0 e versioni successive. Per saperne di più, consulta Configura il forwarding proxy (Apigee) o Configura il forwarding proxy per i proxy API (Apigee Hybrid).

Prima di iniziare

Prima di utilizzare la policy SanitizeModelResponse, devi completare le seguenti attività:

• Crea un template Model Armor. Questo passaggio deve essere completato prima di creare una policy SanitizeModelResponse.
• Imposta l'endpoint API per il servizio Model Armor.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per applicare e utilizzare la policy SanitizeModelResponse, chiedi all'amministratore di concederti i seguenti ruoli IAM sul account di servizio che utilizzi per eseguire il deployment dei proxy Apigee:

• Model Armor User (roles/modelarmor.user)
• Model Armor Viewer (roles/modelarmor.viewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilita API

Abilita le API Model Armor, se non sono già abilitate.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Elemento <SanitizeModelResponse>

Definisce una policy SanitizeModelResponse.

Valore predefinito	Consulta la scheda Policy predefinita di seguito
Obbligatorio?	Obbligatorio
Tipo	Oggetto complesso
Elemento principale	N/D
Elementi secondari	<DisplayName> <IgnoreUnresolvedVariables> <ModelArmor> <UserPromptSource> <LLMResponseSource> <FunctionCallSource> <ContinuousScan>

L'elemento <SanitizeModelResponse> utilizza la seguente sintassi:

Sintassi

<SanitizeModelResponse async="false" continueOnError="false" enabled="true" name="sanitize-response">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>sanitize-response-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content)}</UserPromptSource>
  <LLMResponseSource>{jsonPath('$.candidates[-1].content.parts',response.content)}</LLMResponseSource>
  <FunctionCallSource>{jsonPath('$.candidates[-1].content.parts[-1].functionCall.args',response.content)}</FunctionCallSource>
  <ContinuousScan>false</ContinuousScan>
</SanitizeModelResponse>

Policy predefinita

L'esempio seguente mostra le impostazioni predefinite quando aggiungi una policy SanitizeModelResponse al flusso di richiesta nell'interfaccia utente di Apigee:

<SanitizeModelResponse async="false" continueOnError="false" enabled="true" name="sanitize-response">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>sanitize-response-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content)}</UserPromptSource>
  <LLMResponseSource>{jsonPath('$.candidates[-1].content.parts',response.content)}</LLMResponseSource>
  <FunctionCallSource>{jsonPath('$.candidates[-1].content.parts[-1].functionCall.args',response.content)}</FunctionCallSource>
</SanitizeModelResponse>

Quando inserisci una nuova policy SanitizeModelResponse utilizzando l'interfaccia utente di Apigee, il modello contiene stub per tutte le possibili operazioni. Consulta di seguito le informazioni sugli elementi obbligatori.

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/D	Obbligatorio	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
enabled	true	Facoltativo	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async	falso	Ritirato	Questo attributo è stato ritirato.

La tabella seguente fornisce una descrizione generale degli elementi secondari di <SanitizeModelResponse>:

Elemento secondario	Obbligatorio?	Descrizione
<DisplayName>	Facoltativo	Il nome della policy.
<IgnoreUnresolvedVariables>	Facoltativo	Specifica se l'elaborazione si interrompe se la variabile utilizzata per il nome del template o il payload di Model Armor non viene risolta.
<ModelArmor>	Obbligatorio	Contiene le informazioni necessarie per specificare il template Model Armor.
<UserPromptSource>	Facoltativo	La posizione del payload da cui estrarre il testo del prompt dell'utente. La policy invia questo testo a Model Armor come contesto per la sanitizzazione della risposta. Se ometti questo elemento, la policy invia solo la risposta dell'LLM a Model Armor per la sanitizzazione e viene eseguito il deployment e l'esecuzione della policy. Supporta solo valori di testo stringa. Questo campo supporta la sintassi del modello di messaggio Apigee, incluso l'utilizzo di variabili o funzioni JSON Path. Ad esempio: {jsonpath('$.contents[-1].parts[-1].text',request.content,false)}
<LLMResponseSource>	Facoltativo	La posizione del payload per il testo della risposta LLM da estrarre. Se omesso, viene applicato il percorso JSON generateContent predefinito di Agent Platform: {jsonPath('$.candidates[-1].content.parts',response.content)}. Sono supportati solo i valori di testo delle stringhe. Questo campo supporta la sintassi del modello di messaggio Apigee, incluso l'utilizzo di variabili o funzioni di percorso JSON. Ad esempio: {jsonpath('$.input.prompt.text',request.content,false)}
<FunctionCallSource>	Facoltativo	La posizione degli argomenti della chiamata di funzione da estrarre dalle risposte del modello. La policy utilizza questo elemento come riserva quando <LLMResponseSource> restituisce un valore vuoto nei turni di chiamata di funzione. Valore predefinito: {jsonPath('$.candidates[-1].content.parts[-1].functionCall.args',response.content)}
<ContinuousScan>	Facoltativo	Specifica se controllare l'intera risposta in streaming (SSE), inviando ogni evento al client solo dopo che Model Armor lo ha controllato. Si applica solo quando la policy viene eseguita in un SSE EventFlow. Valore predefinito: false

Sanifica le risposte di streaming di Server-Sent Events (SSE)

In un SSE EventFlow, utilizza <ContinuousScan> per scegliere una delle due opzioni: controlla ogni evento separatamente (false, l'impostazione predefinita) o controlla l'intero stream utilizzando la sanificazione dello streaming di Model Armor (true). Con true, la risposta completa di solito termina prima, perché la policy controlla lo stream su una connessione mentre il modello è ancora in fase di generazione, anziché effettuare una richiesta separata per ogni evento. Tuttavia, il tempo fino al primo token può essere più lungo. Per aggiungere la policy a un EventFlow, consulta Utilizza una policy Apigee Model Armor in un EventFlow.

La tabella seguente mette a confronto le due opzioni:

Comportamento	false (valore predefinito): ogni evento separatamente	true: intero stream
Come viene controllato il testo	Ogni evento singolarmente, senza il testo degli eventi precedenti.	L'intero stream, con il testo degli eventi precedenti come contesto.
Quando il client riceve un evento	Dopo il controllo dell'evento.	Dopo che Model Armor lo ha controllato.
Richieste Model Armor	Uno per evento.	Uno per risposta.
Limite di token	Per richiesta.	Nessun limite al numero totale di token in una risposta.

Nota: con <ContinuousScan>true</ContinuousScan>, Apigee fornisce ogni evento SSE intero, invariato e in ordine, solo dopo che Model Armor lo ha controllato, quindi gli eventi possono arrivare leggermente più tardi rispetto allo stream originale.

L'elemento <ContinuousScan> esiste solo nella policy SanitizeModelResponse, non nella policy SanitizeUserPrompt.

Configura la scansione continua

Imposta <ContinuousScan>true</ContinuousScan> e indirizza <LLMResponseSource> al testo nell'evento corrente, response.event.current.data:

<SanitizeModelResponse async="false" continueOnError="false"
    enabled="true" name="SMR-ContinuousScan">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>SMR-ContinuousScan</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <LLMResponseSource>{jsonPath('$.candidates[-1].content.parts[-1].text',response.event.current.data,true)}</LLMResponseSource>
  <ContinuousScan>true</ContinuousScan>
</SanitizeModelResponse>

Utilizza l'espressione <LLMResponseSource> corrispondente al formato di streaming del tuo modello:

Formato di streaming	<LLMResponseSource>
Gemini (streamGenerateContent?alt=sse)	{jsonPath('$.candidates[-1].content.parts[-1].text',response.event.current.data,true)}
Completamenti della chat compatibili con OpenAI	{jsonPath('$.choices[-1].delta.content',response.event.current.data,true)}
Anthropic Claude	{jsonPath('$.delta.text',response.event.current.data,true)}

Corrispondenze ed errori

Con <ContinuousScan> impostato su true, gli errori sono temporanei o terminali:

Tipo	Esempi	Come viene gestito
Temporaneo	Una connessione interrotta a Model Armor o Model Armor temporaneamente non disponibile.	Nuovo tentativo. Apigee si riconnette e controlla nuovamente il testo non ancora consegnato, in modo che nessun evento venga saltato o consegnato senza controllo. Questo avviene fino a due volte per risposta, indipendentemente da continueOnError. Se il problema persiste, l'errore diventa terminale.
Terminale	Una corrispondenza del filtro, un errore di autenticazione o autorizzazione, una quota di Model Armor superata o nessuna risposta da Model Armor entro il timeout di 60 secondi.	Nessun nuovo tentativo. Il controllo termina e continueOnError determina ciò che riceve il client, come descritto nella tabella successiva.

Con <ContinuousScan> impostato su true, la policy non fornisce il testo anonimizzato (oscurato) di Sensitive Data Protection (SDP) da Model Armor. Apigee rilascia gli eventi invariati e gestisce una corrispondenza di anonimizzazione come qualsiasi altra corrispondenza.

In caso di errore irreversibile, l'attributo continueOnError determina ciò che riceve il client:

continueOnError	Cosa riceve il cliente
false (valore predefinito)	Il client riceve gli eventi che hanno superato il controllo e poi un evento SSE con l'errore, ad esempio steps.sanitize.model.response.FilterMatched, steps.sanitize.modelarmor.ModelArmorAPIFailed o steps.sanitize.modelarmor.AuthenticationFailure. Lo stream termina. Il client non riceve testo non controllato o corrispondente.
true	Il client riceve la risposta completa, incluso il testo corrispondente e tutto ciò che lo segue. Gli errori terminali non generano un errore e il resto della risposta passa senza controllo. La policy imposta SanitizeModelResponse.POLICY_NAME.failed su true in modo che un passaggio successivo in EventFlow possa agire di conseguenza.

Con <ContinuousScan> impostato su false, ogni evento è una richiesta separata e non sono previsti tentativi di riconnessione. Con continueOnError="true", una corrispondenza influisce solo su quell'evento e la policy continua a controllare gli eventi successivi.

Quote e limiti

• Con <ContinuousScan>true</ContinuousScan>, un'intera risposta in streaming viene conteggiata come una richiesta rispetto alla quota di Model Armor del tuo progetto, più una per ogni riconnessione. Con false, ogni evento SSE è una richiesta separata.
• Con <ContinuousScan>true</ContinuousScan>, non esiste un limite al numero totale di token in una risposta. In caso contrario, ogni richiesta è soggetta ai limiti di token di Model Armor.

Riferimento dell'elemento secondario

Questa sezione descrive gli elementi secondari di <SanitizeModelResponse>.

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito	N/D
Obbligatorio?	Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo	Stringa
Elemento principale	<PolicyElement>
Elementi secondari	Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<IgnoreUnresolvedVariables>

Determina se l'elaborazione si interrompe quando una variabile non viene risolta. Imposta su true per ignorare le variabili non risolte e continuare l'elaborazione.

Valore predefinito	Falso
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<SanitizeModelResponse>
Elementi secondari	Nessuno

<ModelArmor>

Contiene la configurazione del template Model Armor. L'elemento secondario <TemplateName> specifica quale template di Model Armor viene utilizzato per sanitizzare la risposta dell'LLM.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Oggetto complesso
Elemento principale	<SanitizeModelResponse>
Elementi secondari	<TemplateName>

L'elemento <ModelArmor> utilizza la seguente sintassi:

<ModelArmor>
  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
</ModelArmor>

<TemplateName>

Il template Model Armor.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Stringa
Elemento principale	<ModelArmor>
Elementi secondari	Nessuno

L'elemento <TemplateName> utilizza la seguente sintassi:

Sintassi

<ModelArmor>
  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
</ModelArmor>

Esempio

Questo esempio utilizza le variabili di flusso Apigee per compilare le informazioni richieste.

<ModelArmor>
  <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName>
</ModelArmor>

<UserPromptSource>

La posizione del payload da cui estrarre il testo del prompt dell'utente. Se fornisci questo elemento, la policy invia il prompt dell'utente a Model Armor insieme alla risposta del modello per la sanitizzazione sensibile al contesto. Se ometti questo elemento, la policy esegue la sanitizzazione solo della risposta del modello e viene eseguito il deployment e l'esecuzione della policy. Supporta solo valori di testo stringa.

Questo campo supporta la sintassi del modello di messaggio Apigee, incluso l'utilizzo di variabili o funzioni di percorso JSON. Ad esempio:

{jsonpath('$.input.prompt.text',request.content,false)}

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<SanitizeModelResponse>
Elementi secondari	Nessuno

<LLMResponseSource>

La posizione del payload per la risposta LLM da estrarre. Sono supportati solo i valori di testo stringa.

Questo campo supporta la sintassi del modello di messaggio Apigee, incluso l'utilizzo di variabili o funzioni di percorso JSON. Ad esempio:

{jsonpath('$.input.prompt.text',request.content,false)}

Valore predefinito	{jsonPath('$.candidates[-1].content.parts',response.content)}
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<SanitizeModelResponse>
Elementi secondari	Nessuno

<FunctionCallSource>

La posizione degli argomenti della chiamata di funzione da estrarre dalla risposta del modello. La policy utilizza questo elemento come riserva quando <LLMResponseSource> restituisce un valore vuoto, il che accade quando il modello restituisce una chiamata di funzione anziché contenuti di testo.

Questo campo supporta la sintassi del modello di messaggio, incluse le funzioni JSON Path.

Valore predefinito	{jsonPath('$.candidates[-1].content.parts[-1].functionCall.args',response.content)}
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<SanitizeModelResponse>
Elementi secondari	Nessuno

<ContinuousScan>

Imposta su true per controllare l'intera risposta in streaming (SSE) come un unico stream, utilizzando la sanitizzazione dello streaming di Model Armor. La policy controlla ogni evento insieme al testo di tutti gli eventi precedenti e il client riceve ogni evento intero e invariato solo dopo che Model Armor lo ha controllato. La policy non fornisce il testo anonimizzato (oscurato) di Sensitive Data Protection (SDP) da Model Armor.

Se impostata su false o se omessa, la policy controlla ogni evento separatamente. L'elemento si applica solo quando la policy viene eseguita in un SSE EventFlow e non ha alcun effetto altrove. Per saperne di più, consulta Sanitizza le risposte degli eventi inviati dal server (SSE) in streaming.

Valore predefinito	Falso
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<SanitizeModelResponse>
Elementi secondari	Nessuno

L'elemento <ContinuousScan> utilizza la seguente sintassi:

<ContinuousScan>true</ContinuousScan>

Variabili di flusso

Le variabili di flusso possono essere utilizzate per configurare il comportamento di runtime dinamico per policy e flussi, in base alle intestazioni HTTP o ai contenuti dei messaggi o al contesto disponibile nel flusso. Per saperne di più sulle variabili di flusso, consulta il Riferimento per le variabili di flusso.

Questa policy fornisce il seguente insieme di variabili di flusso di sola lettura durante l'esecuzione. Puoi utilizzare queste variabili di flusso con la policy DataCapture per creare report di analisi personalizzati. Per saperne di più, consulta Raccolta dei dati dei clienti con la policy di acquisizione dei dati.

Nome variabile	Descrizione
SanitizeModelResponse.POLICY_NAME.templateUsed	Specifica quale template Model Armor viene utilizzato. Ad esempio: projects/myproject/locations/us-west1/templates/mytemplate
SanitizeModelResponse.POLICY_NAME.userPrompt	Specifica i contenuti del prompt utilizzati per la chiamata a Model Armor per la sanitizzazione dei contenuti.
SanitizeModelResponse.POLICY_NAME.modelResponse	Specifica i contenuti della risposta dell'LLM utilizzati per la chiamata a Model Armor per la sanitizzazione dei contenuti.
SanitizeModelResponse.POLICY_NAME.responseFromModelArmor	Specifica la risposta JSON di Model Armor. Quando <ContinuousScan> è impostato su true, contiene la risposta più recente.
SanitizeModelResponse.POLICY_NAME.filterMatchState	Specifica se il filtro è stato trovato. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.invocationResult	Un campo che indica il risultato della chiamata, indipendentemente dallo stato della corrispondenza. Può avere i seguenti elementi: SUCCESS: All filters executed successfully. PARTIAL: l'esecuzione di alcuni filtri è stata saltata o non è riuscita. ERRORE: tutti i filtri sono stati ignorati o l'esecuzione non è riuscita.
SanitizeModelResponse.POLICY_NAME.raiFilterResult.executionState	Risultato dell'esecuzione del filtro AI responsabile. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.raiFilterResult.matchState	Stato della corrispondenza del filtro AI responsabile. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.executionState	Stato di esecuzione del risultato dell'ispezione del filtro SDP. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.matchState	Stato di corrispondenza del risultato dell'ispezione del filtro SDP. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	Stato di esecuzione del risultato dell'anonimizzazione del filtro SDP. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	Stato di corrispondenza del risultato dell'anonimizzazione del filtro SDP. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.executionState	Stato di esecuzione dei risultati del filtro prompt injection e jailbreak. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.matchState	Stato di corrispondenza dei risultati del filtro per prompt injection e jailbreak. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.executionState	Stato di esecuzione del filtro CSAM. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.matchState	Stato della corrispondenza del filtro CSAM. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.executionState	Stato di esecuzione del filtro URI dannoso. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.matchState	Stato di corrispondenza del filtro URI dannoso. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorCode	Codice di errore personalizzato sottoposto a override, se presente nella risposta di Model Armor.
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage	Codice di errore personalizzato sottoposto a override, se presente nella risposta di Model Armor.
SanitizeModelResponse.POLICY_NAME.csamFilterMatched	Valore booleano che indica se il filtro CSAM ha trovato una corrispondenza.
SanitizeModelResponse.POLICY_NAME.maliciousURIs	Elenco aggiunto di URI dannosi rilevati dal filtro URI dannoso.
SanitizeModelResponse.POLICY_NAME.maliciousURIsDetected	Valore booleano che indica se il filtro URI dannoso ha trovato una corrispondenza.
SanitizeModelResponse.POLICY_NAME.matchesFound	Valore booleano che indica se uno dei filtri corrisponde.
SanitizeModelResponse.POLICY_NAME.promptInjectionDetected	Valore booleano che indica se il filtro di prompt injection ha trovato una corrispondenza.
SanitizeModelResponse.POLICY_NAME.promptInjectionConfidence	Livello di confidenza del rilevamento di prompt injection.
SanitizeModelResponse.POLICY_NAME.raiMatchesFound	Valore booleano che indica se il filtro RAI ha trovato una corrispondenza.
SanitizeModelResponse.POLICY_NAME.requestSentToModelArmor	Specifica la richiesta JSON inviata a Model Armor. Quando <ContinuousScan> è impostato su true, contiene la richiesta più recente.
SanitizeModelResponse.POLICY_NAME.sanitizeOperation	Specifica l'operazione eseguita dalla policy. I valori validi includono SANITIZE_USER_PROMPT e SANITIZE_MODEL_RESPONSE.
SanitizeModelResponse.POLICY_NAME.streamReplacements	Specifica il numero di volte in cui la policy si è ricollegata a Model Armor durante la risposta quando <ContinuousScan> è impostato su true. Impostato solo se la policy è stata ricollegata.
SanitizeModelResponse.POLICY_NAME.lastStreamReplacementCause	Specifica l'errore che ha causato la riconnessione più recente quando <ContinuousScan> è impostato su true. Impostato solo se la policy è stata ricollegata.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee specifiche per la policy <SanitizeModelResponse>. Queste informazioni sono importanti per sapere se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Cosa devi sapere sugli errori delle policy e Gestione degli errori.

Errori di runtime

Codice di errore	Stato HTTP	Causa
steps.sanitize.model.response.FilterMatched	400	Questo errore si verifica se il prompt dell'utente non supera il controllo del template di Model Armor.
steps.sanitize.model.response.SanitizationResponseParsingFailed	500	Questo errore si verifica se non è possibile analizzare la risposta di Model Armor.
steps.sanitize.model.response.FailedToExtractUserPrompt	500	Questo errore si verifica se l'estrazione automatica del prompt utente per il valore predefinito non è riuscita.
steps.sanitize.model.response.FailedToExtractLLMResponse	500	Questo errore si verifica se l'estrazione automatica della risposta del modello per il valore predefinito non è riuscita.
steps.sanitize.model.response.InternalError	500	Questo errore si verifica quando si verifica un errore interno del server.
steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed	500	Questo errore si verifica se non è possibile risolvere il nome del template.
steps.sanitize.model.response.AuthenticationFailure	500	Questo errore si verifica se il account di servizio non dispone dell'autorizzazione per chiamare l'API Model Armor.
steps.sanitize.model.response.ModelArmorAPIFailed	500	Questo errore si verifica se l'API Model Armor genera un errore.
steps.sanitize.model.response.ModelArmorCalloutError	500	Questo errore si verifica se la chiamata API Model Armor non va a buon fine.
steps.sanitize.modelarmor.ServiceUnavailable	500	Questo errore si verifica se il servizio Model Armor non è disponibile.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questa policy.

Nome errore	Causa
The ModelArmor/TemplateName element is required.	Si verifica se l'elemento <TemplateName> in <ModelArmor> non è presente.
The TemplateName element value is required.	Si verifica se il valore <TemplateName> è vuoto.

Variabili di errore

Queste variabili vengono impostate quando questa policy attiva un errore in fase di runtime. Per saperne di più, consulta Informazioni sugli errori relativi alle norme.

Variabili	Dove	Esempio
fault.name="FAULT_NAME"	FAULT_NAME è il nome dell'errore, come elencato nella tabella Errori di runtime riportata sopra. Il nome dell'errore è l'ultima parte del codice di errore.	fault.name Matches "UnresolvedVariable"
SanitizeModelResponse.POLICY_NAME.failed	POLICY_NAME è il nome specificato dall'utente della policy che ha generato l'errore.	SanitizeModelResponse.sanitize-response.failed = true

Esempio di risposta di errore

Nota: per la gestione degli errori, la best practice consiste nell'intercettare la parte errorcode della risposta di errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

{
  "fault": {
    "faultstring": "SanitizeModelResponse[sanitize-response]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizemodelresponse.UnresolvedVariable"
    }
  }
}

Esempio di regola di errore

<FaultRule name="SanitizeModelResponse Faults">
    <Step>
        <Name>SMR-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizemodelresponse.failed = true)</Condition>
</FaultRule>

Codice di errore e messaggi di errore del template Model Armor

Il template Model Armor supporta l'override dei codici di errore e dei messaggi di errore generati dalle richieste API della policy SanitizeModelResponse. Se l'utente imposta gli override, i codici di errore e i messaggi di errore di Model Armor compilano le variabili di flusso.

Ad esempio, una risposta con codici e messaggi di errore di Model Armor potrebbe essere simile alla seguente:

{
"sanitizationResult": {
  "filterMatchState": "MATCH_FOUND",
  "filterResults": {...},
  "sanitizationMetadata": {
    "errorCode": "890",
    "errorMessage": "get out"
  },
  "invocationResult": "SUCCESS"
  }
}

Schemi

Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.