Esta página foi traduzida pela API Cloud Translation.

Política SanitizeModelResponse

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

Confira a documentação da Apigee Edge.

A política "SanitizeModelResponse" protege os clientes de IA contra conteúdo nocivo ou ofensivo, higienizando as respostas de modelos de IA generativa. A política usa o Model Armor para avaliar as respostas do modelo em busca de conteúdo prejudicial ou ofensivo, permitindo a proteção nativa para clientes e 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 é usada com a 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 "SanitizeModelResponse", conclua as seguintes tarefas:

Crie um modelo do Model Armor. Essa etapa precisa ser concluída antes da criação de uma política "SanitizeModelResponse".
Defina o endpoint de API para o serviço Model Armor.

Funções exigidas

Para receber as permissões necessárias para aplicar e usar a política "SanitizeModelResponse", 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 APIs.

Enable the APIs

Elemento `<SanitizeModelResponse>`

Define uma política SanitizeModelResponse.

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

O elemento <SanitizeModelResponse> usa a seguinte sintaxe:

Sintaxe

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

Política padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política SanitizeModelResponse ao fluxo de solicitação na interface da Apigee:

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

Quando você insere uma nova política SanitizeModelResponse usando a interface do 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 <SanitizeModelResponse>:

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.
`<TemplateName>`	Obrigatório	O modelo do Model Armor usado para higienizar a resposta do LLM. Esse valor pode ser modelado usando as seguintes variáveis de fluxo do Apigee: projects/{organization.name}/locations/{system.region.name}/templates/{id}
`<UserPromptSource>`	Obrigatório	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 do Apigee, incluindo o uso de variáveis ou funções de caminho JSON. Por exemplo: {jsonpath('$.contents[-1].parts[-1].text',request.content,false)}
`<LLMResponseSource>`	Obrigatório	O local do payload para extrair o texto da resposta do LLM. Somente valores de texto de string são aceitos. Esse campo aceita a sintaxe de modelo de mensagem do Apigee, incluindo o uso de variáveis ou funções de caminho JSON. Por exemplo: {jsonpath('$.input.prompt.text',request.content,false)}

Referência a elementos filhos

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

`<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	`<SanitizeModelResponse>`
Elemento filho	Nenhum

`<TemplateName>`

O modelo do Model Armor.

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

O elemento <TemplateName> 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>

`<UserPromptSource>`

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

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

`<LLMResponseSource>`

O local da carga útil para extrair a resposta do LLM. 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)}

Valor padrão	{jsonPath($.candidates[-1].content.parts,response.content,true)}
Obrigatório?	Obrigatório
Tipo	String
Elemento pai	`<SanitizeModelResponse>`
Elemento filho	Nenhum

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

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

Nome da variável	Descrição
`SanitizeModelResponse.POLICY_NAME.templateUsed`	Especifica qual modelo de proteção de modelo é usado. Por exemplo: `projects/myproject/locations/us-west1/templates/mytemplate`
`SanitizeModelResponse.POLICY_NAME.userPrompt`	Especifica o conteúdo do comando usado para a chamada ao Model Armor para higienizar o conteúdo.
`SanitizeModelResponse.POLICY_NAME.modelResponse`	Especifica o conteúdo da resposta do LLM usado para a chamada ao Model Armor para higienizar o conteúdo.
`SanitizeModelResponse.POLICY_NAME.responseFromModelArmor`	Especifica a resposta JSON do Model Armor. Model Armor.
`SanitizeModelResponse.POLICY_NAME.filterMatchState`	Especifica se o filtro foi correspondido. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.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.
`SanitizeModelResponse.POLICY_NAME.raiFilterResult.executionState`	Resultado da execução do filtro RAI. Os valores válidos incluem `EXECUTION_SUCCESS` e `EXECUTION_SKIPPED`.
`SanitizeModelResponse.POLICY_NAME.raiFilterResult.matchState`	Estado de correspondência do filtro RAI. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.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`.
`SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.matchState`	Sdp filter inspect result match state. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.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`.
`SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState`	Sdp filter de identify result match state. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.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`.
`SanitizeModelResponse.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`.
`SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.executionState`	Estado de execução do filtro de CSAM. Os valores válidos incluem `EXECUTION_SUCCESS` e `EXECUTION_SKIPPED`.
`SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.matchState`	Estado da correspondência do filtro de CSAM. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.executionState`	Estado de execução do filtro de URI malicioso. Os valores válidos incluem `EXECUTION_SUCCESS` e `EXECUTION_SKIPPED`.
`SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.matchState`	Estado de correspondência do filtro de URI malicioso. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorCode`	Código de erro personalizado substituído, se presente na resposta do Model Armor.
`SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage`	Código de erro personalizado substituído, se presente na resposta do Model Armor.
`SanitizeModelResponse.POLICY_NAME.csamFilterMatched/code>`	Valor booleano que indica se o filtro de CSAM fez uma correspondência.
`SanitizeModelResponse.POLICY_NAME.maliciousURIs`	Lista anexada de URIs maliciosos detectados pelo filtro de URI malicioso.
`SanitizeModelResponse.POLICY_NAME.maliciousURIsDetected`	Valor booleano que indica se o filtro de URI malicioso encontrou uma correspondência.
`SanitizeModelResponse.POLICY_NAME.matchesFound`	Valor booleano que indica se algum dos filtros correspondeu.
`SanitizeModelResponse.POLICY_NAME.promptInjectionDetected`	Valor booleano que indica se o filtro de injeção de comandos fez uma correspondência.
`SanitizeModelResponse.POLICY_NAME.promptInjectionConfidence`	Nível de confiança da detecção de injeção de comandos.
`SanitizeModelResponse.POLICY_NAME.raiMatchesFound`	Valor booleano que indica se o filtro de RAI correspondeu.
`SanitizeModelResponse.POLICY_NAME.requestSentToModelArmor`	Valor booleano que indica se uma solicitação foi enviada ao Model Armor.
`SanitizeModelResponse.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 retornadas, bem como as variáveis de falha definidas pela Apigee específicas para a política <SanitizeModelResponse>. 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

Código de falha	Status HTTP	Causa
`steps.sanitize.model.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.model.response.SanitizationResponseParsingFailed`	`500`	Esse erro ocorre se não for possível analisar a resposta do Model Armor.
`steps.sanitize.model.response.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.model.response.FailedToExtractLLMResponse`	`500`	Esse erro ocorre se a extração automática da resposta do modelo para o valor padrão falhar.
`steps.sanitize.model.response.InternalError`	`500`	Esse erro ocorre quando há um erro interno do servidor.
`steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed`	`500`	Esse erro ocorre se o nome do modelo não puder ser resolvido.
`steps.sanitize.model.response.AuthenticationFailure`	`500`	Esse erro ocorre se a conta de serviço não tiver permissão para chamar a API Model Armor.
`steps.sanitize.model.response.ModelArmorAPIFailed`	`500`	Esse erro ocorre se a API Model Armor gerar um erro.
`steps.sanitize.model.response.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

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.

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"`
`SanitizeModelResponse.POLICY_NAME.failed`	`POLICY_NAME` é o nome especificado pelo usuário da política que causou a falha.	`SanitizeModelResponse.sanitize-response.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": "SanitizeModelResponse[sanitize-response]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizemodelresponse.UnresolvedVariable"
    }
  }
}

Exemplo de regra de falha

<FaultRule name="SanitizeModelResponse Faults">
    <Step>
        <Name>SMR-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizemodelresponse.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 SanitizeModelResponse. 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 SanitizeModelResponse Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Ativar APIs

Elemento <SanitizeModelResponse>

Sintaxe

Política padrão

Referência a elementos filhos

<DisplayName>

Sintaxe

Exemplo

<IgnoreUnresolvedVariables>

<TemplateName>

Sintaxe

Exemplo

<UserPromptSource>

<LLMResponseSource>

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 SanitizeModelResponse

Elemento `<SanitizeModelResponse>`

`<DisplayName>`

`<TemplateName>`

`<UserPromptSource>`

`<LLMResponseSource>`