Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
A política SemanticCachePopulate é uma política de armazenamento em cache avançada projetada para otimizar o desempenho das 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 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 os custos reduzindo o volume de chamadas para LLMs.
Essa política funciona em conjunto com a 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, conclua as seguintes tarefas:
- Crie um projeto da Vertex AI.
- Crie um índice da 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 políticas de 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 do AI Platform (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 usando papéis personalizados ou outros papéis predefinidos.
Ativar APIs
Ative as APIs Compute Engine, Vertex AI e Cloud Storage.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder
papéis.
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 da 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 Upsert datapoints. O prazo de validade 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 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.
| Valor padrão | N/A |
| Obrigatório? | Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado |
| Tipo | String |
| Elemento pai | <PolicyElement> |
| Elemento filho | 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 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.
| 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 Upsert datapoints.
O prazo de validade 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 ou 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>O elemento URL é compatível com o uso de modelos de URL. Se quiser, forneça uma variável nesse elemento
para armazenar o valor do URL, conforme mostrado no exemplo a seguir:
<URL>https://{URL_VARIABLE}</URL><TTLInSeconds>
Elemento que especifica o time to live (TTL) para as 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 configuram o comportamento dinâmico do ambiente de execução para políticas e fluxos, com base nos cabeçalhos HTTP, no conteúdo de mensagens ou no contexto disponível no fluxo. Para mais informações sobre as variáveis de fluxo, consulte a Referência de variáveis de fluxo.
Essa política fornece o seguinte conjunto de variáveis de fluxo somente leitura durante a execução. É possível usar essas variáveis de fluxo com a política DataCapture para criar relatórios de análise personalizados. Para mais informações, consulte Coletar dados do cliente com a política de captura de dados.
| Nome da variável | Descrição |
|---|---|
response.content |
Contém todo o conteúdo da resposta da API. |
semanticcache.populate.policy_name.upsert_index_request |
Contém o payload da solicitação enviado à API Vertex AI Vector Search para atualizar o índice de vetor 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
Nesta seção, descrevemos os códigos de falha e as mensagens de erro 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 não estiver disponí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 for 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 vai 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.