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.
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 Opcionalmente, use o elemento |
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 é |
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 |
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.