Política SanitizeUserPrompt

Política extensível

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Observação:essa política é compatível com a Apigee e a Apigee híbrida versão 1.15.1 e mais recentes.

A política SanitizeUserPrompt protege aplicativos de IA contra conteúdo prejudicial ao limpar os comandos enviados para modelos de IA generativa. A política usa o Model Armor para avaliar comandos de usuários em busca de conteúdo prejudicial, permitindo a proteção nativa de cargas de trabalho de IA usando a Apigee. O Model Armor é um serviço do Google Cloud que oferece medidas de segurança e proteção de IA para reduzir os riscos associados a modelos de linguagem grandes (LLMs).

Essa política funciona em conjunto com a política SanitizeModelResponse.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Observação:se você tiver configurado um proxy de encaminhamento para seu ambiente, as chamadas de saída que essa política faz para o Model Armor serão roteadas pelo proxy. Não é necessário fazer nenhuma configuração no nível da política. Isso se aplica à Apigee e à Apigee híbrida 1.16.10 e mais recentes, além da 1.17.0 e mais recentes. Para mais informações, consulte Configurar proxy de encaminhamento (Apigee) ou Configurar proxy de encaminhamento para proxies de API (Apigee Hybrid).

Antes de começar

Antes de usar a política SanitizeUserPrompt, conclua as seguintes tarefas:

• Criar um modelo do Model Armor. Conclua esta etapa antes de criar uma política SanitizeUserPrompt.
• Defina o endpoint de API para o serviço Model Armor.
• Crie uma política SanitizeModelResponse. Conclua esta tarefa antes de implantar a política SanitizeUserPrompt.

Funções exigidas

Para receber as permissões necessárias para aplicar e usar a política SanitizeUserPrompt, peça ao administrador para conceder a você os seguintes papéis do IAM na conta de serviço usada para implantar proxies da Apigee:

• Usuário do Model Armor (roles/modelarmor.user)
• Leitor do Model Armor (roles/modelarmor.viewer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar APIs

Ative a API Model Armor, se ainda não estiver ativada.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Elemento <SanitizeUserPrompt>

Define uma política SanitizeUserPrompt.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Obrigatório
Tipo	Objeto complexo
Elemento pai	N/A
Elemento filho	<DisplayName> <IgnoreUnresolvedVariables> <TemplateName> <UserPromptSource>

O elemento <SanitizeUserPrompt> usa a seguinte sintaxe:

Sintaxe

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

Política padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política SanitizeUserPrompt ao fluxo de solicitação na interface da 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 você insere uma nova política SanitizeUserPrompt usando a interface da Apigee, o modelo contém stubs para todas as operações possíveis. Veja abaixo as informações sobre os elementos obrigatórios.

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

A tabela a seguir fornece uma descrição resumida dos elementos filhos de <SanitizeUserPrompt>:

Elemento filho	Obrigatório?	Descrição
<DisplayName>	Opcional	O nome da política.
<IgnoreUnresolvedVariables>	Opcional	Especifica se o processamento será interrompido se a variável usada para o nome do modelo ou o payload do Model Armor não for resolvida.
<ModelArmor>	Obrigatório	Contém as informações necessárias para especificar o modelo do Model Armor.
<UserPromptSource>	Opcional	O local do payload para extrair o texto do comando do usuário. Somente valores de texto de string são aceitos. Esse campo aceita a sintaxe de modelo de mensagem da Apigee, incluindo o uso de variáveis ou funções de caminho JSON. Exemplo: {jsonpath('$.input.prompt.text',request.content,false)}
<FunctionResponseSource>	Opcional	O local dos dados de resposta da função/ferramenta a serem extraídos. Usado como substituto quando <UserPromptSource> retorna vazio em turnos de chamada de função. Padrão: {jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}

Exemplo

Nesta seção, fornecemos um exemplo que usa o <SanitizeUserPrompt>.

Este exemplo usa todos os valores padrão para detecção de modelo e extração de comandos:

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

Referência a elementos filhos

Esta seção descreve os elementos filhos de <SanitizeUserPrompt>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo	String
Elemento pai	<PolicyElement>
Elemento filho	Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

O elemento <DisplayName> não tem atributos ou elementos filhos.

<IgnoreUnresolvedVariables>

Determina se o processamento é interrompido quando uma variável não é resolvida. Defina como true para ignorar variáveis não resolvidas e continuar o processamento.

Valor padrão	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<SanitizeUserPrompt>
Elemento filho	Nenhum

<ModelArmor>

Contém as informações necessárias para especificar o modelo do Model Armor.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	String
Elemento pai
Elemento filho	<TemplateName>

O elemento <ModelArmor> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

Este exemplo usa variáveis de fluxo da Apigee para preencher as informações necessárias.

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

A tabela a seguir fornece uma descrição resumida dos elementos filhos de <ModelArmor>.

Elemento filho	Obrigatório?	Descrição
<TemplateName>	Obrigatório	String O modelo do Model Armor usado para limpar o comando do usuário. Esse valor pode ser modelado usando as seguintes variáveis de fluxo da Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}

<UserPromptSource>

O local do payload para extrair o texto do comando do usuário. Esse campo é compatível com a sintaxe do modelo de mensagem da Apigee, incluindo o uso de variáveis ou funções de caminho JSON. Exemplo:

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

Valor padrão	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
Obrigatório?	Opcional
Tipo	String
Elemento pai	<SanitizeUserPrompt>
Elemento filho	Nenhum

<FunctionResponseSource>

O local dos dados de resposta da função ou ferramenta a serem extraídos da solicitação. Esse elemento é usado como substituto quando <UserPromptSource> retorna vazio, o que ocorre em turnos de chamada de função em que a última entrada de conteúdo contém uma resposta de função em vez de texto. Os dados de resposta da função precisam ser higienizados porque contêm dados externos não confiáveis de APIs e bancos de dados.

Esse campo é compatível com a sintaxe do modelo de mensagem, incluindo funções de caminho JSON.

Valor padrão	{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}
Obrigatório?	Opcional
Tipo	String
Elemento pai	<SanitizeUserPrompt>
Elemento filho	Nenhum

Variáveis de fluxo

As variáveis de fluxo configuram o comportamento dinâmico de políticas e fluxos no ambiente de execução, com base em cabeçalhos HTTP, conteúdo de mensagens ou o contexto disponível no fluxo. Para mais informações, consulte a Referência de variáveis de fluxo.

Essa política fornece o seguinte conjunto de variáveis de fluxo somente leitura durante a execução. É possível usar essas variáveis de fluxo com a política DataCapture para criar relatórios de análise personalizados. Para mais informações, consulte Como coletar dados do cliente com a política de captura de dados.

Nome da variável	Descrição
SanitizeUserPrompt.POLICY_NAME.templateUsed	Especifica qual modelo de proteção de modelo é usado. Por exemplo: projects/myproject/locations/us-west1/templates/mytemplate
SanitizeUserPrompt.POLICY_NAME.userPrompt	Especifica o conteúdo do comando usado para a chamada ao Model Armor e limpa o conteúdo.
SanitizeUserPrompt.POLICY_NAME.modelResponse	Especifica o conteúdo da resposta do LLM usado para a chamada ao Model Armor para higienizar o conteúdo.
SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor	Especifica a resposta JSON do Model Armor.
SanitizeUserPrompt.POLICY_NAME.filterMatchState	Especifica se o filtro correspondeu. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.invocationResult	Um campo que indica o resultado da invocação, independentemente do status de correspondência. Ela pode ter o seguinte: SUCESSO: todos os filtros foram executados. PARCIAL: alguns filtros foram ignorados ou não foram executados. FALHA: todos os filtros foram ignorados ou falharam na execução.
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState	Resultado da execução do filtro RAI. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState	Estado de correspondência do filtro RAI. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState	Estado de execução do resultado da inspeção do filtro SDP. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState	O resultado da inspeção do filtro SDP corresponde ao estado. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	Estado de execução do resultado de desidentificação do filtro SDP. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	Estado de correspondência do resultado da desidentificação do filtro SDP. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState	Estado de execução dos resultados do filtro de injeção de comando e jailbreak. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState	Os resultados do filtro de injeção de comando e jailbreak correspondem ao estado. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState	Estado de execução do filtro de CSAM. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState	Estado de correspondência do filtro de CSAM. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState	Estado de execução do filtro de URI malicioso. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState	Estado de correspondência do filtro de URIs maliciosos. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode	Código do erro personalizado substituído, se presente na resposta do Model Armor.
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage	Código do erro personalizado substituído, se presente na resposta do Model Armor.
SanitizeUserPrompt.POLICY_NAME.csamFilterMatched	Valor booleano que indica se o filtro de CSAM correspondeu.
SanitizeUserPrompt.POLICY_NAME.maliciousURIs	Lista anexada de URIs maliciosos detectados pelo filtro de URIs maliciosos.
SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected	Valor booleano que indica se o filtro de URI malicioso encontrou uma correspondência.
SanitizeUserPrompt.POLICY_NAME.matchesFound	Valor booleano que indica se algum dos filtros correspondeu.
SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected	Valor booleano que indica se o filtro de injeção de comando correspondeu.
SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence	Nível de confiança da detecção de injeção de comandos.
SanitizeUserPrompt.POLICY_NAME.raiMatchesFound	Valor booleano que indica se o filtro de RAI correspondeu.
SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor	Valor booleano que indica se uma solicitação foi enviada ao Model Armor.
SanitizeUserPrompt.POLICY_NAME.sanitizeOperation	Especifica a operação realizada pela política. Os valores válidos incluem SANITIZE_USER_PROMPT e SANITIZE_MODEL_RESPONSE.

Referência de erros

Nesta seção, descrevemos os códigos de falha e as mensagens de erro que a Apigee retorna, além das variáveis de falha que a Apigee define para a política SanitizeUserPrompt. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de tempo de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha	Status HTTP	Causa
steps.sanitize.user.prompt.response.FilterMatched	400	Esse erro ocorre se o comando do usuário não passar na verificação do modelo do Model Armor.
steps.sanitize.user.prompt.SanitizationResponseParsingFailed	500	Esse erro ocorre quando não é possível analisar a resposta do Model Armor.
steps.sanitize.user.prompt.FailedToExtractUserPrompt	500	Esse erro ocorre se a extração automática do comando do usuário para o valor padrão falhar.
steps.sanitize.user.prompt.InternalError	500	Esse erro ocorre quando há um erro interno do servidor.
steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed	500	Esse erro ocorre se não for possível resolver o nome do modelo.
steps.sanitize.modelarmor.AuthenticationFailure	500	Esse erro ocorre se a conta de serviço não tiver permissão para chamar a API Model Armor.
steps.sanitize.modelarmor.ModelArmorAPIFailed	500	Esse erro ocorre se a API Model Armor gera um erro.
steps.sanitize.modelarmor.ModelArmorCalloutError	500	Esse erro ocorre se a chamada de API do Model Armor falhar.
steps.sanitize.modelarmor.ServiceUnavailable	500	Esse erro ocorre se o serviço do Model Armor estiver indisponível.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Nome do erro	Causa
The ModelArmor/TemplateName element is required.	Ocorre se o elemento <TemplateName> em <ModelArmor> não estiver presente.
The TemplateName element value is required.	Ocorre se o valor de <TemplateName> estiver vazio.

Variáveis de falha

Essa política define essas variáveis quando aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="FAULT_NAME"	FAULT_NAME é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "UnresolvedVariable"
SanitizeUserPrompt.POLICY_NAME.failed	POLICY_NAME é o nome especificado pelo usuário da política que causou a falha.	SanitizeUserPrompt.sanitize-prompt.failed = true

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

{
  "fault": {
    "faultstring": "SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizeuserprompt.UnresolvedVariable"
    }
  }
}

Exemplo de regra de falha

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

Código do erro e mensagens de erro do modelo do Model Armor

O modelo do Model Armor permite substituir códigos do erro e mensagens de erro gerados pelas solicitações de API da política SanitizeUserPrompt. Se o usuário definir as substituições, os códigos do erro e as mensagens de erro do Model Armor vão preencher as variáveis de fluxo.

Por exemplo, uma resposta com códigos do erro e mensagens do Model Armor pode ser assim:

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

Esquemas

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.