Questa pagina è stata tradotta dall'API Cloud Translation.

Norme di SanitizeModelResponse

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio SanitizeModelResponse protegge i client AI da contenuti dannosi o offensivi sanificando le risposte dei modelli di AI generativa. Le norme utilizzano Model Armor per valutare le risposte del modello in merito a contenuti dannosi o offensivi, consentendo la protezione nativa per i client e i carichi di lavoro AI che utilizzano Apigee. Model Armor è un'offerta di servizi che fornisce misure di sicurezza e protezione dell'AI per mitigare i rischi associati ai modelli linguistici di grandi dimensioni (LLM). Google Cloud

Questo criterio viene utilizzato insieme al criterio SanitizeModelResponse.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Prima di iniziare

Prima di utilizzare il criterio SanitizeModelResponse, devi completare le seguenti attività:

Crea un modello 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 il deployment dei proxy Apigee:

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

Per ulteriori informazioni 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

Enable the Model Armor APIs.

Enable the APIs

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>` `<TemplateName>` `<UserPromptSource>` `<LLMResponseSource>`

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,true)}</UserPromptSource>
  <LLMResponseSource>{jsonPath($.candidates[-1].content.parts,response.content,true)}</LLMResponseSource>
</SanitizeModelResponse>

Norme predefinite

Il seguente esempio mostra le impostazioni predefinite quando aggiungi un criterio SanitizeModelResponse al flusso di richiesta nell'interfaccia utente 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,true)}</UserPromptSource>
  <LLMResponseSource>{jsonPath($.candidates[-1].content.parts,response.content,true)}</LLMResponseSource>
</SanitizeModelResponse>

Quando inserisci un nuovo criterio SanitizeModelResponse utilizzando l'UI di Apigee, il modello contiene stub per tutte le operazioni possibili. Di seguito sono riportate 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 modello o il payload di Model Armor non viene risolta.
`<TemplateName>`	Obbligatorio	Il modello Model Armor utilizzato per sanificare la risposta del modello LLM. Questo valore può essere creato come modello utilizzando le seguenti variabili di flusso Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}
`<UserPromptSource>`	Obbligatorio	La posizione del payload per l'estrazione del testo del prompt dell'utente. 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 del percorso JSON. Ad esempio: {jsonpath('$.contents[-1].parts[-1].text',request.content,false)}
`<LLMResponseSource>`	Obbligatorio	La posizione del payload per l'estrazione del testo della risposta LLM. 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 del percorso JSON. Ad esempio: {jsonpath('$.input.prompt.text',request.content,false)}

Riferimento all'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

`<TemplateName>`

Il modello Model Armor.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Stringa
Elemento principale	`<SanitizeModelResponse>`
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 per l'estrazione del testo del prompt dell'utente. 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 del percorso JSON. Ad esempio:

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

Valore predefinito	{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
Obbligatorio?	Obbligatorio
Tipo	Stringa
Elemento principale	`<SanitizeModelResponse>`
Elementi secondari	Nessuno

`<LLMResponseSource>`

La posizione del payload da cui estrarre la risposta LLM. 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 del percorso JSON. Ad esempio:

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

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

Variabili di flusso

Le variabili di flusso possono essere utilizzate per configurare il comportamento di runtime dinamico per criteri e flussi, in base alle intestazioni HTTP o ai contenuti dei messaggi oppure al contesto disponibile nel flusso. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento alle variabili di flusso.

Il criterio può impostare queste variabili di sola lettura durante l'esecuzione.

Nome variabile	Descrizione
`SanitizeModelResponse.POLICY_NAME.templateUsed`	Specifica quale modello di Model Armor viene utilizzato. Ad esempio: `projects/myproject/locations/us-west1/templates/mytemplate`
`SanitizeModelResponse.POLICY_NAME.userPrompt`	Specifica il contenuto del prompt utilizzato per la chiamata a Model Armor per sanificare i contenuti.
`SanitizeModelResponse.POLICY_NAME.modelResponse`	Specifica i contenuti della risposta del modello LLM utilizzati per la chiamata a Model Armor per sanificare i contenuti.
`SanitizeModelResponse.POLICY_NAME.responseFromModelArmor`	Specifica la risposta JSON di Model Armor. Model Armor.
`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 le seguenti caratteristiche: SUCCESS: All filters executed successfully. PARZIALE: alcuni filtri sono stati ignorati o non sono stati eseguiti. 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 di 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`	Sdp filter inspect result match state. I valori validi includono `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState`	Stato di esecuzione del risultato di identificazione del filtro SDP. I valori validi includono `EXECUTION_SUCCESS` e `EXECUTION_SKIPPED`.
`SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState`	Sdp filter de identify result match state. 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`	Lo stato di corrispondenza dei risultati del filtro 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 di 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/code>`	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 per l'iniezione di prompt 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`	Valore booleano che indica se è stata inviata una richiesta a Model Armor.
`SanitizeModelResponse.POLICY_NAME.sanitizeOperation`	Specifica l'operazione eseguita dalla policy. I valori validi includono `SANITIZE_USER_PROMPT` e `SANITIZE_MODEL_RESPONSE`.

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 il criterio <SanitizeModelResponse>. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Cosa devi sapere sugli errori relativi alle norme e Gestione dei guasti.

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 modello Model Armor.
`steps.sanitize.model.response.SanitizationResponseParsingFailed`	`500`	Questo errore si verifica se la risposta di Model Armor non può essere analizzata.
`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 se si verifica un errore interno del server.
`steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed`	`500`	Questo errore si verifica se non è possibile risolvere il nome del modello.
`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 implementi un proxy contenente questo criterio.

Nome dell'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 norma genera un errore in fase di runtime. Per saperne di più, consulta Cosa devi sapere 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 del guasto è l'ultima parte del codice di guasto.	`fault.name Matches "UnresolvedVariable"`
`SanitizeModelResponse.POLICY_NAME.failed`	`POLICY_NAME` è il nome specificato dall'utente del criterio 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 faultstring, perché potrebbe cambiare.

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

Regola di errore di esempio

<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 modello Model Armor

Il modello Model Armor supporta l'override dei codici di errore e dei messaggi di errore generati dalle richieste API del criterio SanitizeModelResponse. Se l'utente imposta gli override, le variabili di flusso verranno compilate con i codici di errore e i messaggi di errore di Model Armor.

Ad esempio, una risposta con codici e messaggi di errore di Model Armor potrebbe avere il seguente aspetto:

{
"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.

Norme di SanitizeModelResponse Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Ruoli obbligatori

Abilita API

Elemento <SanitizeModelResponse>

Sintassi

Norme predefinite

Riferimento all'elemento secondario

<DisplayName>

Sintassi

Esempio

<IgnoreUnresolvedVariables>

<TemplateName>

Sintassi

Esempio

<UserPromptSource>

<LLMResponseSource>

Variabili di flusso

Messaggi di errore

Errori di runtime

Errori di deployment

Variabili di errore

Esempio di risposta di errore

Regola di errore di esempio

Codice di errore e messaggi di errore del modello Model Armor

Schemi

Norme di SanitizeModelResponse

Elemento `<SanitizeModelResponse>`

`<DisplayName>`

`<TemplateName>`

`<UserPromptSource>`

`<LLMResponseSource>`