Esta página foi traduzida pela API Cloud Translation.

Política SanitizeUserPrompt

Esta página se aplica à Apigee, mas não à Apigee híbrida.

Confira a documentação da Apigee Edge.

Visão geral

A política SanitizeUserPrompt protege aplicativos de IA contra conteúdo prejudicial ao limpar os comandos enviados pelos usuários para modelos de IA generativa. A política usa o Model Armor para avaliar comandos do usuário em busca de conteúdo nocivo, permitindo a proteção nativa para cargas de trabalho de IA usando a Apigee. O Model Armor é um serviço 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.

Antes de começar

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

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

Enable the Model Armor API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the 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>
</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>
</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 da carga útil 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)}

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 de alto nível dos elementos filhos de <ModelArmor>.

Elemento filho Obrigatório? Descrição

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 do Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}

<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 do Apigee:

projects/{organization.name}/locations/{system.region.name}/templates/{id}

`<UserPromptSource>`

O local da carga útil para extrair o texto do comando do usuário. 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)}

Valor padrão	{jsonPath('$.contents[-1].parts[-1].text',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 do ambiente de execução para políticas e fluxos, com base nos cabeçalhos HTTP, no conteúdo de mensagens ou no contexto disponível no fluxo. Para mais informações sobre as variáveis de fluxo, 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. Você pode usar essas variáveis de fluxo com a política DataCapture para criar relatórios de análise personalizados. Para mais informações, consulte Coletar dados de clientes 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 para higienizar 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, independente do status da correspondência. Ela pode ter o seguinte: SUCESSO: todos os filtros foram executados. PARCIAL: alguns filtros foram ignorados ou não foram executados. FAILURE: All filters were skipped or failed execution.
`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`	Sdp filter inspect result match state. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState`	Filtro do SDP para identificar o estado de execução do resultado. Os valores válidos incluem `EXECUTION_SUCCESS` e `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState`	Sdp filter de identify result match state. 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`	O estado dos resultados do filtro de jailbreak e injeção de comando corresponde. 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 da 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 URI malicioso. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode`	Código de erro personalizado substituído, se presente na resposta do Model Armor.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage`	Código de erro personalizado substituído, se presente na resposta do Model Armor.
`SanitizeUserPrompt.POLICY_NAME.csamFilterMatched/code>`	Valor booleano que indica se o filtro de CSAM fez uma correspondência.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIs`	Lista anexada de URIs maliciosos detectados pelo filtro de URI malicioso.
`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 comandos fez uma correspondência.
`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, bem como as variáveis de falha definidas pela Apigee 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 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 se não for possível analisar a resposta do Model Armor.
`steps.sanitize.user.prompt.FailedToExtractUserPrompt`	`500`	Esse erro ocorre se a extração automática de solicitações 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 o nome do modelo não puder ser resolvido.
`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 gerar 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 Model Armor não estiver disponí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 <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 e mensagens de erro do modelo do Model Armor

O modelo do Model Armor permite substituir códigos 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 e as mensagens de erro do Model Armor vão preencher as variáveis de fluxo.

Por exemplo, uma resposta com códigos e mensagens de erro 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.

Política SanitizeUserPrompt Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Antes de começar

Funções exigidas

Ativar APIs

Elemento <SanitizeUserPrompt>

Sintaxe

Política padrão

Exemplo

Referência a elementos filhos

<DisplayName>

Sintaxe

Exemplo

<IgnoreUnresolvedVariables>

<ModelArmor>

Sintaxe

Exemplo

<UserPromptSource>

Variáveis de fluxo

Referência de erros

Erros de execução

Erros de implantação

Variáveis de falha

Exemplo de resposta de erro

Exemplo de regra de falha

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

Esquemas

Política SanitizeUserPrompt

Elemento `<SanitizeUserPrompt>`

`<DisplayName>`

`<ModelArmor>`

`<UserPromptSource>`