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 armazenamento em cache avançada projetada para otimizar o desempenho de 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 semelhança semântica, em vez de correspondências exatas.

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

Essa política é usada em conjunto com a política 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, é necessário concluir as seguintes tarefas:

• Crie um projeto da Vertex AI.
• Crie um índice de 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 as políticas de armazenamento em cache semântico.

Funções exigidas

Para receber 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 plataforma de IA (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.

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>

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

Este elemento tem os seguintes atributos comuns a todas as políticas:

A tabela a seguir fornece uma descrição resumida dos elementos filhos de <SemanticCacheLookup>:

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

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.

O elemento <DisplayName> usa a seguinte sintaxe:

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

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

<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 aceita a sintaxe do modelo de mensagem da Apigee, incluindo o uso de variáveis ou funções de caminho JSON.

Exemplo:

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

<Embeddings>

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

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.

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 conferir uma lista de modelos que podem fornecer embeddings de texto para a política SemanticCacheLookup.

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.

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.

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

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.

Referência de erros

Esta seção descreve os códigos de falha e as mensagens de erro que são 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.

Erros de implantação

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

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.

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