Política SemanticCacheLookup

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 SemanticCacheLookup é uma política de colocação em cache avançada concebida para otimizar o desempenho das cargas de trabalho de IA, especialmente as que envolvem grandes modelos de linguagem (GMLs).

A política usa a API Text embeddings da Vertex AI para gerar incorporações de texto e a pesquisa vetorial para encontrar comandos semelhantes com base na semelhança semântica, em vez de correspondências exatas.

A política SemanticCacheLookup reduz os tempos de resposta para consultas repetidas e otimiza os custos reduzindo o volume de chamadas para os MDIs.

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

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

  • Crie um projeto do Vertex AI.
  • Crie um índice do Vector Search.
  • Crie um ponto final do Vertex AI para o índice.
  • Crie uma política SemanticCachePopulate.

Para mais informações sobre como concluir estas tarefas, consulte o artigo Comece a usar as políticas de cache semântica.

Funções necessárias

Para receber as autorizações de que precisa para aplicar e usar a política SemanticCacheLookup, peça ao seu administrador para lhe conceder a função de IAM utilizador da AI Platform (roles/aiplatform.user) na conta de serviço que usa para implementar proxies do Apigee. 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 Compute Engine, Vertex AI, and Cloud Storage 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

<SemanticCacheLookup> elemento

Define uma política SemanticCacheLookup.

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

O exemplo seguinte mostra as predefinições quando adiciona uma política SemanticCacheLookup ao seu fluxo na IU do 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 insere uma nova política SemanticCacheLookup na IU do Apigee, o modelo contém stubs 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:
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 <SemanticCacheLookup>:

Elemento secundário 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. Definido como true para ignorar as variáveis não resolvidas e continuar o processamento.
<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('$.contents[-1].parts[-1].text',request.content,true)}

<Embeddings> Obrigatória Elemento que contém as informações necessárias para gerar incorporações.
<SimilaritySearch> Obrigatória Elemento que contém as informações necessárias para realizar pesquisas de semelhanças.

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

Referência de elemento secundário

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

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

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

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

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

<Embeddings>

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

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <SemanticCacheLookup>
Elementos subordinados <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> (elemento secundário de <Embeddings>)

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

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <Embeddings>
Elementos subordinados <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> (elemento secundário de <VertexAI>)

O URL usado para gerar incorporações de texto. Consulte Modelos suportados para ver uma lista de modelos que fornecem incorporações de texto para a política SemanticCacheLookup.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <VertexAI>
Elementos subordinados 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>

O elemento URL suporta a utilização de modelos de URL. Se quiser, forneça uma variável neste elemento para conter o valor do URL, como mostrado no exemplo seguinte: 

<URL>https://{URL_VARIABLE}</URL>

<SimilaritySearch>

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

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

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <SemanticCacheLookup>
Elementos subordinados <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> (elemento secundário de <SimilaritySearch>)

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

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <SimilaritySearch>
Elementos subordinados <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 seguinte fornece uma descrição geral dos elementos secundários de <VertexAI>.

Elemento secundário Obrigatório? Descrição
<URL> Obrigatória String

O URL usado para fazer pesquisas de semelhanças. O ponto de dados com a correspondência mais elevada, com base no limite de semelhança, é o único ponto de dados usado.

O elemento URL suporta a utilização de modelos de URL. Se quiser, forneça uma variável neste elemento para conter o valor do URL, como mostrado no exemplo seguinte: 

<URL>https://{URL_VARIABLE}</URL>
<Threshold> Opcional String

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

O valor predefinido é 0,9.

Consulte

<DeployedIndexID> Obrigatória String

O ID do índice implementado no ponto final do índice usado para o armazenamento em cache semântico.

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
request.content Contém o conteúdo completo do pedido de API recebido.
request.url Contém o URL do pedido de API recebido.
semanticcache.lookup.policy_name.user_prompt Contém componentes específicos extraídos do comando de pedido, que é usado para gerar incorporações ou realizar pesquisas de semelhanças.
semanticcache.lookup.policy_name.embeddings_request Contém o payload do pedido enviado para a API Vertex AI Embeddings para gerar incorporações de texto para o texto introduzido.
semanticcache.lookup.policy_name.embeddings_response Contém a resposta da API Vertex AI Embeddings, que inclui as incorporações de texto geradas.
semanticcache.lookup.policy_name.dense_embeddings Contém os valores de incorporação numéricos reais gerados pela API Vertex AI Embeddings.
semanticcache.lookup.policy_name.is_nearest_neighbor_hit Especifica se foi encontrado um vizinho mais próximo na base de dados vetorial para o pedido fornecido e se o ponto de dados cumpre o limite de semelhança.
semanticcache.lookup.policy_name.cache_hit Especifica se a resposta foi encontrada na cache semântica.
semanticcache.lookup.policy_name.cached_llm_response Contém a resposta obtida da cache semântica (se ocorreu um acerto da cache).

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, específicas da política <SemanticCacheLookup>. É importante conhecer estas informações se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre erros de políticas e Como resolver falhas.

Erros de tempo de execução

Estes erros ocorrem quando a política é executada.

Código de falha Estado de HTTP Causa
steps.semanticcache.lookup.MessageTemplateExtractionFailed 400 Não foi possível extrair dados do pedido através da expressão JSON Path.
steps.semanticcache.lookup.FailedToExtractUserPrompt 500 Não é possível extrair o comando do utilizador do pedido da API.
steps.semanticcache.lookup.EmbeddingsServiceUnavailable 400 O serviço Vertex AI Embeddings está atualmente indisponível.
steps.semanticcache.lookup.EmbeddingsAPIFailed 400 O serviço Vertex AI Embeddings falhou.
steps.semanticcache.lookup.VectorSearchServiceUnavailable 400 O serviço Vertex AI Vector Search está atualmente indisponível.
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 autorizações necessárias.
steps.semanticcache.lookup.InternalError 500 Ocorreu um erro inesperado na política SemanticCacheLookup.
steps.semanticcache.lookup.CalloutError 500 A chamada do serviço Vertex AI falhou.

Erros de implementação

Estes erros ocorrem quando implementa 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 <URL> de incorporações for inválido.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. Ocorre se o esquema http do elemento <URL> do SimilaritySearch for inválido.
SimilaritySearch/Threshold element must be >= 0 and <= 1. Se o atributo não estiver entre 0 e 1, a implementação do proxy de API falha.
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

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"
semanticcachelookup.POLICY_NAME.failed POLICY_NAME é o nome especificado pelo utilizador da política que gerou a falha. semanticcachelookup.SC-lookup.failed = true

Exemplo de resposta de erro

{
  "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íticas estão disponíveis no GitHub.