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, limpando 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 nocivo ou ofensivo, permitindo a proteção nativa de clientes de IA e cargas de trabalho 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 SanitizeModelResponse, é necessário concluir as seguintes tarefas:

  • Crie um modelo do Model Armor. Esta etapa precisa ser concluída antes de criar uma política SanitizeModelResponse.
  • Defina o endpoint de API para o serviço de proteção de modelos.

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:

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 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ções 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:
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 é interrompido quando a variável usada para o nome do modelo ou o payload do Model Armor não é resolvida.
<TemplateName> Obrigatório Modelo do Model Armor usado para higienizar a resposta do LLM.

Esse valor pode ser criado como modelo usando as seguintes variáveis de fluxo da Apigee:

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

<UserPromptSource> Obrigatório 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 modelos de mensagem da 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 oferece suporte à sintaxe do modelo de mensagem da 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 do payload para extrair o texto do comando do usuário. Somente valores de texto de string são aceitos.

Esse campo oferece suporte à 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? Obrigatório
Tipo String
Elemento pai <SanitizeModelResponse>
Elemento filho Nenhum

<LLMResponseSource>

O local do payload para a extração da resposta do LLM. Somente valores de texto de string são aceitos.

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

Nome da variável Descrição
SanitizeModelResponse.POLICY_NAME.templateUsed Especifica qual modelo de blindagem é 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 limpar o conteúdo.
SanitizeModelResponse.POLICY_NAME.modelResponse Especifica o conteúdo da resposta do LLM usado para a chamada ao Model Armor para limpar 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, independentemente do status de correspondência. Ela pode ter o seguinte:
  • SUCESSO: todos os filtros foram executados.
  • PARCIAL: alguns filtros foram ignorados ou falharam na execução.
  • FALHA: todos os filtros foram ignorados ou a execução falhou.
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 O estado de execução do resultado da inspeção do filtro do SDP. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.matchState O filtro SDP inspeciona o estado de correspondência do resultado. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState Filtro 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 Filtro SDP para identificar o estado de correspondência do resultado. Os valores válidos incluem MATCH_FOUND e NO_MATCH_FOUND.
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.executionState Estado de execução dos resultados da injeção de comando e do filtro de jailbreak. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.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.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.executionState Estado de execução do filtro CSAM. Os valores válidos incluem EXECUTION_SUCCESS e EXECUTION_SKIPPED.
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.matchState Estado de correspondência do filtro 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 CSAM correspondeu.
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 correspondeu.
SanitizeModelResponse.POLICY_NAME.matchesFound Valor booleano que indica se algum dos filtros corresponde.
SanitizeModelResponse.POLICY_NAME.promptInjectionDetected Valor booleano que indica se o filtro de injeção de solicitação foi correspondente.
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 RAI correspondeu.
SanitizeModelResponse.POLICY_NAME.requestSentToModelArmor Valor booleano que indica se uma solicitação foi enviada para o 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

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 <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 a solicitação do usuário não passar na verificação do modelo do Model Armor.
steps.sanitize.model.response.SanitizationResponseParsingFailed 500 Esse erro ocorre se a resposta do Model Armor não puder ser analisada.
steps.sanitize.model.response.FailedToExtractUserPrompt 500 Esse erro ocorre se a extração automática de solicitação do usuário para o valor padrão falhar.
steps.sanitize.model.response.FailedToExtractLLMResponse 500 Esse erro ocorre se a extração automática de 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 da API Model Armor falhar.
steps.sanitize.modelarmor.ServiceUnavailable 500 Esse erro ocorre se o serviço 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 <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

{
  "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 de proteção de modelo oferece suporte à substituição de 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 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.