Política SemanticCachePopulate

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 SemanticCachePopulate é 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 do Vertex AI para gerar incorporações de texto e a Vector Search para colocar em cache as respostas da API com base na semelhança semântica, em vez de correspondências exatas.

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

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

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 SemanticCachePopulate, 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 e permissões

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

<SemanticCachePopulate> elemento

Define uma política SemanticCachePopulate.

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

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

Elemento secundário 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ória Elemento que contém as informações necessárias para atualizar o índice vetorial.

Para mais informações, consulte o artigo Inserir ou atualizar pontos de dados.

O tempo de validade dos pontos de dados é de <TTLInSeconds> a partir do momento da entrada.

<TTLInSeconds> Opcional O tempo de vida (TTL) das respostas em cache, em segundos.

O valor predefinido é 60.

Exemplo

Esta secção apresenta um exemplo com <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 de elemento secundário

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

<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 <SemanticCachePopulate>
Elementos subordinados Nenhum

<SimilaritySearch>

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

Para mais informações, consulte o artigo Inserir ou atualizar pontos de dados.

O tempo de validade dos pontos de dados é de <TTLInSeconds> a partir do momento da entrada.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <SemanticCachePopulate>
Elementos subordinados <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> (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://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (elemento secundário de <VertexAI>)

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

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

<TTLInSeconds>

Elemento que especifica o tempo de vida (TTL) para as respostas em cache, em segundos. O valor predefinido é 60.

Para mais informações, consulte o artigo Atualize e recrie um índice ativo.

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <SemanticCachePopulate>
Elementos subordinados Nenhum

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
response.content Contém o conteúdo completo da resposta da API.
semanticcache.populate.policy_name.upsert_index_request Contém o payload do pedido enviado para a API Vertex AI Vector Search para atualizar o índice vetorial com novas incorporações e metadados.
semanticcache.populate.policy_name.upsert_index_response Contém a resposta da API Vertex AI Vector Search, indicando o êxito ou a falha da operação de atualização do índice.

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 <SemanticCachePopulate>. Estas informações são importantes se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre os erros de políticas e Como resolver falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha Estado de HTTP Causa
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable 400

Este erro ocorre se a API Vector Search Upsert Datapoints estiver indisponível.
steps.semanticcache.populate.VectorSearchUpsertAPIFailed 500

Este erro ocorre se o serviço da API Vector Search Upsert Datapoints falhar.
steps.semanticcache.populate.AuthenticationFailure 500

Este erro ocorre se a conta de serviço não tiver as autorizações necessárias.
steps.semanticcache.populate.CalloutError 500 A chamada do serviço Vertex AI falhou.
steps.semanticcache.populate.InternalError 500

Este erro ocorre no caso de um erro inesperado na política <SemanticCachePopulate>.

Erros de implementação

Estes erros podem ocorrer quando implementa 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 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.
The TTLInSeconds element must be >= 0. Se o valor for definido como zero ou um número negativo, a implementação do proxy de API falha.

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"
semanticcachepopulate.POLICY_NAME.failed POLICY_NAME é o nome especificado pelo utilizador da política que gerou 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íticas estão disponíveis no GitHub.