Política SemanticCachePopulate

Visão geral

A política SemanticCachePopulate é uma política de 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 armazenar em cache as respostas da API com base na similaridade semântica, em vez de correspondências exatas.

A política SemanticCachePopulate 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 SemanticCacheLookup.

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 SemanticCachePopulate, você precisa 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.

Papéis e permissões

Para receber as permissões necessárias para aplicar e usar a política SemanticCachePopulate, 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 <SemanticCachePopulate>

Define uma política SemanticCachePopulate.

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

O elemento <SemanticCachePopulate> usa a seguinte sintaxe:

Sintaxe

O elemento <SemanticCachePopulate> usa a seguinte sintaxe:

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>{EXPIRATION_TIME_IN_SECONDS}</TTLInSeconds>
</SemanticCachePopulate>

Política padrão

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

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

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

Elemento filho Obrigatório? Descrição
<DisplayName> Opcional O nome da política.

<IgnoreUnresolvedVariables> Opcional Determina se o processamento é interrompido quando um conjunto de propriedades não é resolvido.
<SimilaritySearch> Obrigatório Elemento que contém as informações necessárias para atualizar o índice vetorial.

Para mais informações, consulte Inserir e atualizar pontos de dados.

O tempo de expiração dos pontos de dados é <TTLInSeconds> a partir do momento da entrada.

<TTLInSeconds> Opcional O time to live (TTL) das respostas armazenadas em cache, em segundos.

O valor padrão é 60.

Exemplo

Nesta seção, fornecemos um exemplo que usa <SemanticCachePopulate>.

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

Referência a elementos filhos

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

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<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 <SemanticCachePopulate>
Elemento filho Nenhum

<SimilaritySearch>

Elemento que contém as informações necessárias para atualizar o índice vetorial.

Para mais informações, consulte Inserir e atualizar pontos de dados.

O tempo de expiração dos pontos de dados é de <TTLInSeconds> a partir do momento da entrada.

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

O elemento <SimilaritySearch> usa a seguinte sintaxe:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </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://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (filho de <VertexAI>)

O URL usado para inserir e atualizar pontos de dados no índice vetorial.

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}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

Elemento que especifica o time to live (TTL) das respostas armazenadas em cache, em segundos. O valor padrão é 60.

Para mais informações, consulte Atualizar e recriar um índice ativo.

Valor padrão N/A
Obrigatório? Opcional
Tipo String
Elemento pai <SemanticCachePopulate>
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
response.content Contém o conteúdo completo da resposta da API.
semanticcache.populate.policy_name.upsert_index_request Contém o payload da solicitação enviado à API Vector Search da Vertex AI para atualizar o índice de vetores com novos embeddings e metadados.
semanticcache.populate.policy_name.upsert_index_response Contém a resposta da API Vertex AI Vector Search, indicando o sucesso ou a falha da operação de atualização do índice.

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 <SemanticCachePopulate>. 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.semanticcachepopulate.VectorSearchUpsertServiceUnavailable 400

Esse erro ocorre se a API Vector Search Upsert Datapoints estiver indisponível.

steps.semanticcache.populate.VectorSearchUpsertAPIFailed 500

Esse erro ocorre se o serviço da API Vector Search Upsert Datapoints falhar.

steps.semanticcache.populate.AuthenticationFailure 500

Esse erro ocorre se a conta de serviço não tiver as permissões necessárias.

steps.semanticcache.populate.CalloutError 500 A chamada de serviço da Vertex AI falhou.
steps.semanticcache.populate.InternalError 500

Esse erro ocorre quando há um erro inesperado na política <SemanticCachePopulate>.

Erros de implantação

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

Nome do erro Causa
The SimilaritySearch URL {url} is invalid. Ocorre se o elemento <URL> em <SimilaritySearch> estiver vazio ou 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.
The TTLInSeconds element must be >= 0. Se o valor for definido como zero ou um número negativo, a implantação do proxy de API falhará.

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"
semanticcachepopulate.POLICY_NAME.failed POLICY_NAME é o nome especificado pelo usuário da política que causou a falha. semanticcachepopulate.SC-populate.failed = true

Exemplo de resposta de erro

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.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.