Norme relative alla funzionalità SanitizeUserPrompt

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Le norme SanitizeUserPrompt proteggono le applicazioni di AI da contenuti dannosi sanificando i prompt degli utenti inviati ai modelli di AI generativa. Il criterio utilizza Model Armor per valutare i prompt degli utenti alla ricerca di contenuti dannosi, consentendo la protezione nativa per i carichi di lavoro AI che utilizzano Apigee. Model Armor è un servizio Google Cloud che offre misure di sicurezza per l'AI per mitigare i rischi associati ai modelli linguistici di grandi dimensioni (LLM).

Questo criterio funziona insieme al criterio SanitizeModelResponse.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di 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 Configurare il proxy di inoltro (Apigee) o Configurare il proxy di inoltro per i proxy API (Apigee Hybrid).

Prima di iniziare

Prima di utilizzare il criterio SanitizeUserPrompt, completa le seguenti attività:

• Crea un modello Model Armor. Completa questo passaggio prima di creare un criterio SanitizeUserPrompt.
• Imposta l'endpoint API per il servizio Model Armor.
• Crea una policy SanitizeModelResponse. Completa questa attività prima di implementare il criterio SanitizeUserPrompt.

Ruoli obbligatori

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

• Utente Model Armor (roles/modelarmor.user)
• Visualizzatore Model Armor (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 l'API Model Armor, se non è già abilitata.

Ruoli richiesti per abilitare le API

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

Abilitare l'API

Elemento <SanitizeUserPrompt>

Definisce una policy SanitizeUserPrompt.

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

L'elemento <SanitizeUserPrompt> utilizza la seguente sintassi:

Sintassi

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <FunctionResponseSource>{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}</FunctionResponseSource>
</SanitizeUserPrompt>

Policy predefinita

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

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <FunctionResponseSource>{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}</FunctionResponseSource>
</SanitizeUserPrompt>

Quando inserisci una nuova norma SanitizeUserPrompt utilizzando la UI di Apigee, il modello contiene stub per tutte le operazioni possibili. 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 <SanitizeUserPrompt>:

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.
<ModelArmor>	Obbligatorio	Contiene le informazioni richieste per specificare il modello Model Armor.
<UserPromptSource>	Facoltativo	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 dei modelli di messaggi Apigee, incluso l'utilizzo di variabili o funzioni del percorso JSON. Ad esempio: {jsonpath('$.input.prompt.text',request.content,false)}
<FunctionResponseSource>	Facoltativo	La posizione dei dati di risposta della funzione/dello strumento da estrarre. Utilizzato come riserva quando <UserPromptSource> restituisce un valore vuoto nei turni di chiamata di funzione. Valore predefinito: {jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}

Esempio

Questa sezione fornisce un esempio che utilizza <SanitizeUserPrompt>.

Questo esempio utilizza tutti i valori predefiniti per il rilevamento del modello e l'estrazione dei prompt:

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
</SanitizeUserPrompt>

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <SanitizeUserPrompt>.

<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	<SanitizeUserPrompt>
Elementi secondari	Nessuno

<ModelArmor>

Contiene le informazioni richieste per specificare il modello Model Armor.

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

L'elemento <ModelArmor> 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>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <ModelArmor>.

Elemento secondario	Obbligatorio?	Descrizione
<TemplateName>	Obbligatorio	Stringa Il modello Model Armor utilizzato per sanificare il prompt dell'utente. Questo valore può essere creato utilizzando le seguenti variabili di flusso Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}

<UserPromptSource>

La posizione del payload per l'estrazione del testo del prompt dell'utente. Questo campo supporta la sintassi dei modelli di messaggi 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?	Facoltativo
Tipo	Stringa
Elemento principale	<SanitizeUserPrompt>
Elementi secondari	Nessuno

<FunctionResponseSource>

La posizione dei dati di risposta della funzione o dello strumento da estrarre dalla richiesta. Questo elemento viene utilizzato come fallback quando <UserPromptSource> restituisce un valore vuoto, il che si verifica nei turni di chiamata di funzione in cui l'ultima voce di contenuti contiene una risposta della funzione anziché testo. I dati di risposta della funzione devono essere sanificati perché contengono dati esterni non attendibili provenienti da API e database.

Questo campo supporta la sintassi dei modelli di messaggio, incluse le funzioni JSON Path.

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

Variabili di flusso

Le variabili di flusso configurano il comportamento dinamico del runtime per criteri e flussi in base alle intestazioni HTTP o ai contenuti dei messaggi oppure al contesto disponibile nel flusso. Per saperne di più sulle variabili di flusso, consulta Riferimento alle 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 il criterio DataCapture per creare report Analytics personalizzati. Per saperne di più, consulta Raccolta dei dati dei clienti con le norme relative all'acquisizione dei dati.

Nome variabile	Descrizione
SanitizeUserPrompt.POLICY_NAME.templateUsed	Specifica quale modello di armatura viene utilizzato. Ad esempio: projects/myproject/locations/us-west1/templates/mytemplate
SanitizeUserPrompt.POLICY_NAME.userPrompt	Specifica i contenuti del prompt utilizzati per la chiamata a Model Armor per sanificare i contenuti.
SanitizeUserPrompt.POLICY_NAME.modelResponse	Specifica i contenuti della risposta LLM utilizzati per la chiamata a Model Armor per sanificare i contenuti.
SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor	Specifica la risposta JSON di Model Armor.
SanitizeUserPrompt.POLICY_NAME.filterMatchState	Specifica se il filtro ha trovato una corrispondenza. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.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.
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState	Risultato dell'esecuzione del filtro AI responsabile. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState	Stato di corrispondenza del filtro AI responsabile. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState	Sdp filter inspect result execution state. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState	Sdp filter inspect result match state. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	Sdp filter de identify result execution state. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	Stato di corrispondenza del risultato di deidentificazione del filtro SDP. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState	Stato di esecuzione dei risultati del filtro prompt injection e jailbreak. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.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.
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState	Stato di esecuzione del filtro CSAM. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState	Stato della corrispondenza del filtro CSAM. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState	Stato di esecuzione del filtro URI dannoso. I valori validi includono EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState	Stato di corrispondenza del filtro URI dannoso. I valori validi includono MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode	Codice di errore personalizzato sottoposto a override, se presente nella risposta di Model Armor.
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage	Codice di errore personalizzato sottoposto a override, se presente nella risposta di Model Armor.
SanitizeUserPrompt.POLICY_NAME.csamFilterMatched	Valore booleano che indica se il filtro CSAM ha trovato una corrispondenza.
SanitizeUserPrompt.POLICY_NAME.maliciousURIs	Elenco aggiunto di URI dannosi rilevati dal filtro URI dannoso.
SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected	Valore booleano che indica se il filtro URI dannoso ha trovato una corrispondenza.
SanitizeUserPrompt.POLICY_NAME.matchesFound	Valore booleano che indica se uno dei filtri corrisponde.
SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected	Valore booleano che indica se il filtro prompt injection ha trovato una corrispondenza.
SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence	Livello di confidenza del rilevamento di prompt injection.
SanitizeUserPrompt.POLICY_NAME.raiMatchesFound	Valore booleano che indica se il filtro RAI ha trovato una corrispondenza.
SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor	Valore booleano che indica se una richiesta è stata inviata a Model Armor.
SanitizeUserPrompt.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 da Apigee e le variabili di errore impostate da Apigee per il criterio SanitizeUserPrompt. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi alle norme e Gestione dei guasti.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione della policy.

Codice di errore	Stato HTTP	Causa
steps.sanitize.user.prompt.response.FilterMatched	400	Questo errore si verifica se il prompt utente non supera il controllo del modello Model Armor.
steps.sanitize.user.prompt.SanitizationResponseParsingFailed	500	Questo errore si verifica se non è possibile analizzare la risposta di Model Armor.
steps.sanitize.user.prompt.FailedToExtractUserPrompt	500	Questo errore si verifica se l'estrazione automatica del prompt utente per il valore predefinito non è riuscita.
steps.sanitize.user.prompt.InternalError	500	Questo errore si verifica se si verifica un errore interno del server.
steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed	500	Questo errore si verifica se il nome del modello non può essere risolto.
steps.sanitize.modelarmor.AuthenticationFailure	500	Questo errore si verifica se il account di servizio non dispone dell'autorizzazione per chiamare l'API Model Armor.
steps.sanitize.modelarmor.ModelArmorAPIFailed	500	Questo errore si verifica se l'API Model Armor genera un errore.
steps.sanitize.modelarmor.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 di <TemplateName> è vuoto.

Variabili di errore

Questa policy imposta queste variabili quando attiva 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"
SanitizeUserPrompt.POLICY_NAME.failed	POLICY_NAME è il nome specificato dall'utente della policy che ha generato l'errore.	SanitizeUserPrompt.sanitize-prompt.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": "SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizeuserprompt.UnresolvedVariable"
    }
  }
}

Regola di errore di esempio

<FaultRule name="SanitizeUserPrompt Faults">
    <Step>
        <Name>SUP-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizeuserprompt.failed = true)</Condition>
</FaultRule>

Codice di errore e messaggi di errore del template Model Armor

Il modello Model Armor supporta l'override dei codici di errore e dei messaggi di errore generati dalle richieste API del criterio SanitizeUserPrompt. Se l'utente imposta gli override, i codici di errore e i messaggi di errore di Model Armor vengono inseriti nelle variabili di flusso.

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 norma è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle norme sono disponibili su GitHub.