Esta página foi traduzida pela API Cloud Translation.

Política SanitizeUserPrompt

Esta página aplica-se ao Apigee, mas não ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Vista geral

A política SanitizeUserPrompt protege as aplicações de IA contra conteúdo prejudicial através da higienização dos comandos do utilizador enviados para modelos de IA generativa. A política usa o Model Armor para avaliar os comandos do utilizador quanto a conteúdo prejudicial, o que permite a proteção nativa para cargas de trabalho de IA através do Apigee. O Model Armor é uma Google Cloud oferta de serviços de segurança e medidas de segurança da IA para mitigar os riscos associados a modelos de linguagem (conteúdo extenso) (MDLs/CEs).

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

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Antes de começar

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

Crie um modelo de armadura de modelo. Conclua este passo antes de criar uma política SanitizeUserPrompt.
Defina o ponto final da API para o serviço Model Armor.
Crie uma política SanitizeModelResponse. Conclua esta tarefa antes de implementar a política SanitizeUserPrompt.

Funções necessárias

Para receber as autorizações de que precisa para aplicar e usar a política SanitizeUserPrompt, peça ao seu administrador para lhe conceder as seguintes funções do IAM na conta de serviço que usa para implementar proxies do Apigee:

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

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

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

`<SanitizeUserPrompt>` elemento

Define uma política SanitizeUserPrompt.

Valor predefinido	Consulte o separador Política predefinida abaixo
Obrigatório?	Obrigatória
Tipo	Objeto complexo
Elemento principal	N/A
Elementos subordinados	`<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 predefinida

O exemplo seguinte mostra as definições predefinidas quando adiciona uma política SanitizeUserPrompt ao fluxo de pedidos na IU do 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 insere uma nova política SanitizeUserPrompt através da IU do Apigee, o modelo contém marcadores para todas as operações possíveis. Consulte abaixo informações sobre os elementos obrigatórios.

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

Atributo	Predefinição	Obrigatório?	Descrição
`name`	N/A	Obrigatório	O nome interno da política. O valor do atributo `name` pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento `<DisplayName>` para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
`continueOnError`	falso	Opcional	Definido como `false` para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como `true` para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual
`enabled`	verdadeiro	Opcional	Defina como `true` para aplicar a política. Defina como `false` para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.
`async`	falso	Descontinuado	Este atributo foi descontinuado.

A tabela seguinte apresenta uma descrição geral dos elementos secundários de <SanitizeUserPrompt>:

Elemento secundário	Obrigatório?	Descrição
`<DisplayName>`	Opcional	O nome da política.
`<IgnoreUnresolvedVariables>`	Opcional	Especifica se o processamento é interrompido se a variável usada para o nome do modelo ou o payload do Model Armor não for resolvido.
`<ModelArmor>`	Obrigatória	Contém as informações necessárias para especificar o modelo Model Armor.
`<UserPromptSource>`	Opcional	A localização da carga útil para o texto do comando do utilizador a ser extraído. Apenas são suportados valores de texto de string. Este campo suporta a sintaxe de modelos de mensagens do Apigee, incluindo a utilização de variáveis ou funções de caminho JSON. Por exemplo: {jsonpath('$.input.prompt.text',request.content,false)}

Exemplo

Esta secção apresenta um exemplo com o <SanitizeUserPrompt>.

Este exemplo usa todos os valores predefinidos para a deteção de modelos e a 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 de elemento secundário

Esta secção descreve os elementos subordinados de <SanitizeUserPrompt>.

`<DisplayName>`

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.

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

Valor predefinido	N/A
Obrigatório?	Opcional. Se omitir `<DisplayName>`, é usado o valor do atributo `name` da política.
Tipo	String
Elemento principal	<`PolicyElement`>
Elementos subordinados	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 nem elementos subordinados.

<IgnoreUnresolvedVariables>

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

Valor predefinido	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	`<SanitizeUserPrompt>`
Elementos subordinados	Nenhum

`<ModelArmor>`

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

Valor predefinido	N/A
Obrigatório?	Obrigatória
Tipo	String
Elemento principal
Elementos subordinados	`<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 do Apigee para preencher as informações necessárias.

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

A tabela seguinte fornece uma descrição geral dos elementos secundários de <ModelArmor>.

Elemento secundário Obrigatório? Descrição

Elemento secundário	Obrigatório?	Descrição
`<TemplateName>`	Obrigatória	String O modelo Model Armor usado para limpar o comando do utilizador. Este valor pode ser criado com base em modelos através das seguintes variáveis de fluxo do Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}

<TemplateName>

Obrigatória

String

O modelo Model Armor usado para limpar o comando do utilizador.

Este valor pode ser criado com base em modelos através das seguintes variáveis de fluxo do Apigee:

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

`<UserPromptSource>`

A localização da carga útil para o texto do comando do utilizador a ser extraído. Este campo suporta a sintaxe de modelo de mensagem do Apigee, incluindo a utilização de variáveis ou funções de caminho JSON. Por exemplo:

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

Valor predefinido	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
Obrigatório?	Opcional
Tipo	String
Elemento principal	`<SanitizeUserPrompt>`
Elementos subordinados	Nenhum

Variáveis de fluxo

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

Esta política fornece o seguinte conjunto de variáveis de fluxo de só de leitura durante a execução. Pode usar estas variáveis de fluxo com a política DataCapture para criar relatórios de estatísticas personalizados. Para mais informações, consulte o artigo Recolher dados de clientes com a Política de Captura de Dados.

Nome da variável	Descrição
`SanitizeUserPrompt.POLICY_NAME.templateUsed`	Especifica que modelo de armadura 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 MDI/CE 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 estado de correspondência. Pode ter o seguinte: SUCESSO: todos os filtros foram executados com êxito. PARCIAL: alguns filtros foram ignorados ou a execução falhou. FAILURE: 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 de RAI. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState`	Sdp filter inspect result execution state. 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`	Sdp filter de identify result execution state. 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 comandos e jailbreak. Os valores válidos incluem `EXECUTION_SUCCESS` e `EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState`	O estado de correspondência dos resultados do filtro de injeção de comandos e jailbreak. 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 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 estiver presente na resposta do Model Armor.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage`	Código de erro personalizado substituído, se estiver presente na resposta do Model Armor.
`SanitizeUserPrompt.POLICY_NAME.csamFilterMatched/code>`	Valor booleano que indica se o filtro de CSAM correspondeu.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIs`	Lista anexada de URIs maliciosos detetados pelo filtro de URIs maliciosos.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected`	Valor booleano que indica se o filtro de URI malicioso correspondeu.
`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 correspondeu.
`SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence`	Nível de confiança da deteçã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 foi enviado um pedido para o 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 erro

Esta secção descreve os códigos de falhas e as mensagens de erro que o Apigee devolve, bem como as variáveis de falhas que o Apigee define para a política SanitizeUserPrompt. Estas informações são importantes se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre os erros de políticas e Como resolver falhas.

Erros de tempo de execução

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

Código de falha	Estado de HTTP	Causa
`steps.sanitize.user.prompt.response.FilterMatched`	`400`	Este erro ocorre se o comando do utilizador não passar na verificação do modelo Model Armor.
`steps.sanitize.user.prompt.SanitizationResponseParsingFailed`	`500`	Este erro ocorre se não for possível analisar a resposta do Model Armor.
`steps.sanitize.user.prompt.FailedToExtractUserPrompt`	`500`	Este erro ocorre se a extração automática de comandos do utilizador para o valor predefinido falhar.
`steps.sanitize.user.prompt.InternalError`	`500`	Este erro ocorre se existir um erro interno do servidor.
`steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed`	`500`	Este erro ocorre se não for possível resolver o nome do modelo.
`steps.sanitize.modelarmor.AuthenticationFailure`	`500`	Este erro ocorre se a conta de serviço não tiver autorização para chamar a API Model Armor.
`steps.sanitize.modelarmor.ModelArmorAPIFailed`	`500`	Este erro ocorre se a API Model Armor gerar um erro.
`steps.sanitize.modelarmor.ModelArmorCalloutError`	`500`	Este erro ocorre se a chamada API Model Armor falhar.
`steps.sanitize.modelarmor.ServiceUnavailable`	`500`	Este erro ocorre se o serviço Model Armor estiver indisponível.

Erros de implementação

Estes erros podem ocorrer quando implementa 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

Esta política define estas variáveis quando aciona um erro no tempo de execução. Para mais informações, consulte o artigo O que precisa de saber sobre os erros de políticas.

Variáveis	Onde	Exemplo
`fault.name="FAULT_NAME"`	`FAULT_NAME` é o nome da falha, conforme indicado na tabela Erros de tempo 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 utilizador da política que gerou a falha.	`SanitizeUserPrompt.sanitize-prompt.failed = true`

Exemplo de resposta de erro

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque 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 de erro e mensagens de erro do modelo Model Armor

O modelo Model Armor suporta a substituição de códigos de erro e mensagens de erro gerados pelos pedidos da API da política SanitizeUserPrompt. Se o utilizador definir as substituições, os códigos de erro e as mensagens de erro do Model Armor preenchem as variáveis de fluxo.

Por exemplo, uma resposta com códigos e mensagens de erro do Model Armor pode ter o seguinte aspeto:

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

Vista geral

Antes de começar

Funções necessárias

Ativar APIs

<SanitizeUserPrompt> elemento

Sintaxe

Política predefinida

Exemplo

Referência de elemento secundário

<DisplayName>

Sintaxe

Exemplo

<IgnoreUnresolvedVariables>

<ModelArmor>

Sintaxe

Exemplo

<UserPromptSource>

Variáveis de fluxo

Referência de erro

Erros de tempo de execução

Erros de implementação

Variáveis de falha

Exemplo de resposta de erro

Exemplo de regra de falha

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

Esquemas

Política SanitizeUserPrompt

`<SanitizeUserPrompt>` elemento

`<DisplayName>`

`<ModelArmor>`

`<UserPromptSource>`