Política SanitizeUserPrompt

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

Confira a documentação da Apigee Edge.

Visão geral

A política "SanitizeUserPrompt" protege os aplicativos de IA contra conteúdo nocivo, limpando os comandos do usuário enviados a modelos de IA generativa. A política usa o Model Armor para avaliar comandos do usuário em busca de conteúdo prejudicial, permitindo a proteção nativa para cargas de trabalho de IA usando a Apigee. O Model Armor é um Google Cloud serviço 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 é usada 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, você precisa concluir as seguintes tarefas:

• Crie um modelo do Model Armor. Esta etapa precisa ser concluída antes de criar uma política SanitizeUserPrompt.
• Defina o endpoint de API para o serviço de proteção de modelos.
• Crie uma política SanitizeModelResponse. Essa tarefa precisa ser concluída 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)
• Visualizador 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 por meio de papéis personalizados ou de outros papéis predefinidos.

Ativar APIs

Enable the Model Armor API.

Enable the API

Elemento <SanitizeUserPrompt>

Define uma política SanitizeUserPrompt.

O elemento <SanitizeUserPrompt> usa a seguinte 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>

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

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

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

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

Exemplo

Esta seção apresenta um exemplo que usa <SanitizeUserPrompt>.

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

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

O elemento <DisplayName> usa a seguinte sintaxe:

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

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

<ModelArmor>

Contém as informações necessárias para especificar o modelo de proteção.

O elemento <ModelArmor> usa a seguinte sintaxe:

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

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

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 oferece suporte à sintaxe de modelos de mensagens da Apigee, incluindo o uso de variáveis ou funções de caminho JSON. Exemplo:

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

Variáveis de fluxo

As variáveis de fluxo podem ser usadas para configurar o comportamento dinâmico do ambiente de execução para políticas e fluxos, com base nos cabeçalhos HTTP, no conteúdo da mensagem ou no contexto disponível no fluxo. Para mais informações sobre variáveis de fluxo, consulte a Referência de variáveis de fluxo.

A política pode definir essas variáveis somente leitura durante a execução.

Referência de erros

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee específicas 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.

Erros de implantação

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

Variáveis de falha

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

Exemplo de resposta de erro

{
  "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 Armor oferece suporte à substituição de 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 do fluxo.

Por exemplo, uma resposta com códigos e mensagens de erro do Model Armor pode ser semelhante a esta:

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