Esta página foi traduzida pela API Cloud Translation.

Política SemanticCacheLookup

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

Confira a documentação da Apigee Edge.

Visão geral

A política SemanticCacheLookup é uma política de cache avançada criada para otimizar a performance das cargas de trabalho de IA, principalmente aquelas que envolvem modelos de linguagem grandes (LLMs).

A política usa a API Text Embeddings da Vertex AI para gerar embeddings de texto e a Pesquisa vetorial para encontrar comandos semelhantes com base na similaridade semântica, em vez de correspondências exatas.

A política SemanticCacheLookup pode reduzir os tempos de resposta para consultas repetidas e otimizar os custos, diminuindo o volume de chamadas para LLMs.

Essa política é usada com a SemanticCachePopulate.

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 SemanticCacheLookup, conclua as seguintes tarefas:

Crie um projeto da Vertex AI.
Crie um índice da Pesquisa de vetor.
Crie um endpoint da Vertex AI para o índice.
Crie uma política SemanticCachePopulate.

Para mais informações sobre como concluir essas tarefas, consulte Começar a usar políticas de cache semântico.

Funções exigidas

Para ter as permissões necessárias para aplicar e usar a política SemanticCacheLookup, peça ao administrador para conceder a você o papel do IAM de Usuário da AI Platform (roles/aiplatform.user) 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 Compute Engine, Vertex AI, and Cloud Storage APIs.

Enable the APIs

Elemento `<SemanticCacheLookup>`

Define uma política SemanticCacheLookup.

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>` `<UserPromptSource>` `<Embeddings>` `<SimilaritySearch>`

O elemento <SemanticCacheLookup> usa a seguinte sintaxe:

Sintaxe

O elemento <SemanticCacheLookup> usa a seguinte sintaxe:

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Política padrão

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

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Quando você insere uma nova política SemanticCacheLookup na interface da 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 <SemanticCacheLookup>:

Elemento filho	Obrigatório?	Descrição
`<DisplayName>`	Opcional	O nome da política.
`<IgnoreUnresolvedVariables>`	Opcional	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.
`<UserPromptSource>`	Opcional	O local da carga útil para extrair o texto da solicitação 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. Exemplo: {jsonPath($.contents[-1].parts[-1].text,request.content,true)}
`<Embeddings>`	Obrigatório	Elemento que contém as informações necessárias para gerar embeddings.
`<SimilaritySearch>`	Obrigatório	Elemento que contém as informações necessárias para realizar pesquisas de similaridade. Para mais informações, consulte Consultar o índice público para encontrar os vizinhos mais próximos.

Referência a elementos filhos

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

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

IgnoreUnresolvedVariables não é aplicável quando <DefaultValue> é fornecido.

Valor padrão	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	`<SemanticCacheLookup>`
Elemento filho	Nenhum

`<UserPromptSource>`

O local da carga útil para extrair o texto da solicitação 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.

Exemplo:

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

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

`<Embeddings>`

Esse elemento contém as informações necessárias para gerar incorporações de texto.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	`<SemanticCacheLookup>`
Elemento filho	`<VertexAI>`

O elemento <Embeddings> usa a seguinte sintaxe:

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

<VertexAI> (filho de `<Embeddings>`)

Contém o elemento <URL> para atributos específicos da Vertex AI.

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

O elemento VertexAI usa a seguinte sintaxe:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

<URL> (filho de `<VertexAI>`)

O URL usado para gerar embeddings de texto. Consulte Modelos compatíveis para ver uma lista de modelos que podem fornecer embeddings de texto para a política SemanticCacheLookup.

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

O elemento URL usa a seguinte sintaxe:

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>

`<SimilaritySearch>`

Esse elemento contém as informações necessárias para realizar pesquisas de similaridade.

Para mais informações, consulte Consultar o índice público para encontrar os vizinhos mais próximos.

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

O elemento <SimilaritySearch> usa a seguinte sintaxe:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (filho de `<SimilaritySearch>`)

Contém o elemento <URL> para atributos específicos da Vertex AI.

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

O elemento VertexAI usa a seguinte sintaxe:

<VertexAI>
  <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <VertexAI>.

Elemento filho Obrigatório? Descrição

Elemento filho	Obrigatório?	Descrição
`<URL>`	Obrigatório	String O URL usado para realizar pesquisas de similaridade. O ponto de dados correspondente mais alto, com base no limite de similaridade, será o único usado.
`<Threshold>`	Opcional	String Pontuação de similaridade usada para determinar se dois comandos são considerados uma correspondência. Um valor entre 0 e 1. O valor padrão é 0,9.
`<DeployedIndexID>`	Obrigatório	String O ID do índice implantado no endpoint do índice usado para o cache semântico.

<URL>

Obrigatório

String

O URL usado para realizar pesquisas de similaridade. O ponto de dados correspondente mais alto, com base no limite de similaridade, será o único usado.

<Threshold>

Opcional

String

Pontuação de similaridade usada para determinar se dois comandos são considerados uma correspondência. Um valor entre 0 e 1.

O valor padrão é 0,9.

<DeployedIndexID>

Obrigatório

String

O ID do índice implantado no endpoint do índice usado para o cache semântico.

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
`request.content`	Contém todo o conteúdo da solicitação de API recebida.
`request.url`	Contém o URL da solicitação de API recebida.
`semanticcache.lookup.policy_name.user_prompt`	Contém componentes específicos extraídos do comando da solicitação, que é usado para gerar embeddings ou realizar pesquisas de similaridade.
`semanticcache.lookup.policy_name.embeddings_request`	Contém o payload da solicitação enviado à API Embeddings da Vertex AI para gerar embeddings de texto para o texto de entrada.
`semanticcache.lookup.policy_name.embeddings_response`	Contém a resposta da API Embeddings da Vertex AI, que inclui os embeddings de texto gerados.
`semanticcache.lookup.policy_name.dense_embeddings`	Contém os valores numéricos reais de embedding gerados pela API Vertex AI Embeddings.
`semanticcache.lookup.policy_name.is_nearest_neighbor_hit`	Especifica se um vizinho mais próximo foi encontrado no banco de dados de vetores para a solicitação e o ponto de dados especificados atende ao limite de similaridade.
`semanticcache.lookup.policy_name.cache_hit`	Especifica se a resposta foi encontrada no cache semântico.
`semanticcache.lookup.policy_name.cached_llm_response`	Contém a resposta recuperada do cache semântico (se houver um ocorrência em cache).

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

Código de falha	Status HTTP	Causa
`steps.semanticcache.lookup.MessageTemplateExtractionFailed`	`400`	Não foi possível extrair dados da solicitação usando a expressão JSONPath.
`steps.semanticcache.lookup.FailedToExtractUserPrompt`	`500`	Não foi possível extrair o comando do usuário da solicitação de API.
`steps.semanticcache.lookup.EmbeddingsServiceUnavailable`	`400`	O serviço Vertex AI Embeddings está indisponível no momento.
`steps.semanticcache.lookup.EmbeddingsAPIFailed`	`400`	O serviço de embeddings da Vertex AI falhou.
`steps.semanticcache.lookup.VectorSearchServiceUnavailable`	`400`	O serviço Vertex AI Vector Search está indisponível no momento.
`steps.semanticcache.lookup.VectorSearchAPIFailed`	`400`	O serviço Vertex AI Vector Search falhou.
`steps.semanticcache.lookup.AuthenticationFailure`	`500`	A conta de serviço não tem as permissões necessárias.
`steps.semanticcache.lookup.InternalError`	`500`	Ocorreu um erro inesperado na política SemanticCacheLookup.
`steps.semanticcache.lookup.CalloutError`	`500`	A chamada de serviço da Vertex AI falhou.

Erros de implantação

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

Nome do erro	Causa
`The Embeddings/VertexAI element is required.`	Ocorre se o elemento <VertexAI> em <Embeddings> estiver vazio.
`The SimilaritySearch/VertexAI element is required.`	Ocorre se o elemento <VertexAI> em <SimilaritySearch> estiver vazio.
`The Embeddings/URL element is required.`	Ocorre se o elemento <URL> em <Embeddings> estiver vazio.
`The SimilaritySearch/URL element is required.`	Ocorre se o elemento <URL> em <SimilaritySearch> estiver vazio.
`Embeddings URL {url} is invalid.`	Ocorre se o elemento <URL> em <Embeddings> estiver vazio ou for inválido.
`The SimilaritySearch URL {url} is invalid.`	Ocorre se o elemento <URL> em <SimilaritySearch> estiver vazio ou for inválido.
`The scheme {http-scheme} of Embeddings URL {url} must be one of http, https.`	Ocorre se o esquema `http` do elemento Embeddings <URL> for inválido.
`The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https.`	Ocorre se o esquema `http` do elemento SimilaritySearch <URL> for inválido.
`SimilaritySearch/Threshold element must be >= 0 and <= 1.`	Se o atributo não estiver entre 0 e 1, a implantação do proxy de API vai falhar.
`SimilaritySearch/DeployedIndexID element is required.`	Ocorre se o elemento <DeployedIndexID> em <SimilaritySearch> estiver vazio.
`SimilaritySearch/DeployedIndexID element must not contain spaces.`	Ocorre se o elemento <DeployedIndexID> em <SimilaritySearch> contiver espaços.

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

Exemplo de regra de falha

<FaultRule name="SemanticCacheLookup Faults">
    <Step>
        <Name>SCL-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

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 SemanticCacheLookup Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Antes de começar

Funções exigidas

Ativar APIs

Elemento <SemanticCacheLookup>

Sintaxe

Política padrão

Referência a elementos filhos

<DisplayName>

Sintaxe

Exemplo

<IgnoreUnresolvedVariables>

<UserPromptSource>

<Embeddings>

<VertexAI> (filho de <Embeddings>)

<URL> (filho de <VertexAI>)

<SimilaritySearch>

<VertexAI> (filho de <SimilaritySearch>)

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

Esquemas

Política SemanticCacheLookup

Elemento `<SemanticCacheLookup>`

`<DisplayName>`

`<UserPromptSource>`

`<Embeddings>`

<VertexAI> (filho de `<Embeddings>`)

<URL> (filho de `<VertexAI>`)

`<SimilaritySearch>`

<VertexAI> (filho de `<SimilaritySearch>`)