Esta página foi traduzida pela API Cloud Translation.

Política SanitizeModelResponse

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

Veja a documentação do Apigee Edge.

A política SanitizeModelResponse protege os clientes de IA contra conteúdo prejudicial ou ofensivo ao higienizar as respostas dos modelos de IA generativa. A política usa o Model Armor para avaliar as respostas do modelo quanto a conteúdo prejudicial ou ofensivo, permitindo a proteção nativa para clientes e cargas de trabalho de IA que usam o 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 é usada 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 SanitizeModelResponse, tem de concluir as seguintes tarefas:

Crie um modelo de armadura de modelo. Tem de concluir este passo antes de criar uma política SanitizeModelResponse.
Defina o ponto final da API para o serviço Model Armor.

Funções necessárias

Para receber as autorizações de que precisa para aplicar e usar a política SanitizeModelResponse, 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 APIs.

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 APIs

`<SanitizeModelResponse>` elemento

Define uma política SanitizeModelResponse.

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

O exemplo seguinte mostra as predefinições quando adiciona uma política SanitizeModelResponse ao fluxo de pedidos na IU do 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 insere uma nova política SanitizeModelResponse 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 <SanitizeModelResponse>:

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.
`<TemplateName>`	Obrigatória	O modelo Model Armor usado para limpar a resposta do MDI/CE. 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>`	Obrigatória	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('$.contents[-1].parts[-1].text',request.content,false)}
`<LLMResponseSource>`	Obrigatória	A localização da carga útil para o texto de resposta do MDI/CE 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)}

Referência de elemento secundário

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

`<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 variáveis não resolvidas e continuar o processamento.

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

`<TemplateName>`

O modelo Model Armor.

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

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

`<UserPromptSource>`

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

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

`<LLMResponseSource>`

A localização do payload para a resposta do MDG a ser extraída. 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)}

Valor predefinido	{jsonPath($.candidates[-1].content.parts,response.content,true)}
Obrigatório?	Obrigatória
Tipo	String
Elemento principal	`<SanitizeModelResponse>`
Elementos subordinados	Nenhum

Variáveis de fluxo

As variáveis de fluxo podem ser usadas para configurar o comportamento dinâmico de tempo de execução para políticas e fluxos, com base nos cabeçalhos HTTP ou no conteúdo das 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
`SanitizeModelResponse.POLICY_NAME.templateUsed`	Especifica que modelo de armadura 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 MDI/CE 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 correspondeu. 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 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.
`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 de RAI. Os valores válidos incluem `MATCH_FOUND` e `NO_MATCH_FOUND`.
`SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.executionState`	Sdp filter inspect result execution state. 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`	Sdp filter de identify result execution state. 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 comandos e jailbreak. Os valores válidos incluem `EXECUTION_SUCCESS` e `EXECUTION_SKIPPED`.
`SanitizeModelResponse.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`.
`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 de 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 estiver presente na resposta do Model Armor.
`SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage`	Código de erro personalizado substituído, se estiver presente na resposta do Model Armor.
`SanitizeModelResponse.POLICY_NAME.csamFilterMatched/code>`	Valor booleano que indica se o filtro de CSAM correspondeu.
`SanitizeModelResponse.POLICY_NAME.maliciousURIs`	Lista anexada de URIs maliciosos detetados pelo filtro de URIs maliciosos.
`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 correspondeu.
`SanitizeModelResponse.POLICY_NAME.promptInjectionDetected`	Valor booleano que indica se o filtro de injeção de comandos correspondeu.
`SanitizeModelResponse.POLICY_NAME.promptInjectionConfidence`	Nível de confiança da deteçã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 foi enviado um pedido 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 erro

Esta secção descreve os códigos de falhas e as mensagens de erro devolvidas, bem como as variáveis de falhas definidas pelo Apigee específicas da política <SanitizeModelResponse>. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

Código de falha	Estado de HTTP	Causa
`steps.sanitize.model.response.FilterMatched`	`400`	Este erro ocorre se o comando do utilizador não passar na verificação do modelo Model Armor.
`steps.sanitize.model.response.SanitizationResponseParsingFailed`	`500`	Este erro ocorre se não for possível analisar a resposta do Model Armor.
`steps.sanitize.model.response.FailedToExtractUserPrompt`	`500`	Este erro ocorre se a extração automática de comandos do utilizador para o valor predefinido falhar.
`steps.sanitize.model.response.FailedToExtractLLMResponse`	`500`	Este erro ocorre se a extração automática da resposta do modelo para o valor predefinido falhar.
`steps.sanitize.model.response.InternalError`	`500`	Este erro ocorre se existir um erro interno do servidor.
`steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed`	`500`	Este erro ocorre se não for possível resolver o nome do modelo.
`steps.sanitize.model.response.AuthenticationFailure`	`500`	Este erro ocorre se a conta de serviço não tiver autorização para chamar a API Model Armor.
`steps.sanitize.model.response.ModelArmorAPIFailed`	`500`	Este erro ocorre se a API Model Armor gerar um erro.
`steps.sanitize.model.response.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

Estas variáveis são definidas quando esta política 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"`
`SanitizeModelResponse.POLICY_NAME.failed`	`POLICY_NAME` é o nome especificado pelo utilizador da política que gerou a falha.	`SanitizeModelResponse.sanitize-response.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": "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 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 SanitizeModelResponse. Se o utilizador definir as substituições, os códigos de erro 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 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 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 necessárias

Ativar APIs

<SanitizeModelResponse> elemento

Sintaxe

Política predefinida

Referência de elemento secundário

<DisplayName>

Sintaxe

Exemplo

<IgnoreUnresolvedVariables>

<TemplateName>

Sintaxe

Exemplo

<UserPromptSource>

<LLMResponseSource>

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 SanitizeModelResponse

`<SanitizeModelResponse>` elemento

`<DisplayName>`

`<TemplateName>`

`<UserPromptSource>`

`<LLMResponseSource>`