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.
Elemento <SemanticCacheLookup>
Define uma política SemanticCacheLookup.
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> <UserPromptSource> <Embeddings> <SimilaritySearch> |
O elemento <SemanticCacheLookup>
usa a seguinte sintaxe:
Sintaxe
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>
Política padrão
O exemplo a seguir mostra as configurações padrão quando você adiciona uma política SemanticCacheLookup ao fluxo na interface da Apigee:
<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>
Quando você insere uma nova política SemanticCacheLookup 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 <SemanticCacheLookup>
:
Elemento filho | Obrigatório? | Descrição |
---|---|---|
<DisplayName> |
Opcional | O nome da política. |
<IgnoreUnresolvedVariables> |
Opcional | 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.
|
<UserPromptSource> |
Opcional | O local do payload para extrair o texto do comando do usuário. Somente valores de texto de string são aceitos.
Esse campo oferece suporte à 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> |
Obrigatório | Elemento que contém as informações necessárias para gerar embeddings. |
<SimilaritySearch> |
Obrigatório | Elemento que 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. |
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.
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 |
<SemanticCacheLookup>
|
Elemento filho | Nenhum |
<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)}
Valor padrão | {jsonPath($.contents[-1].parts[-1].text,request.content,true)} |
Obrigatório? | Opcional |
Tipo | String |
Elemento pai |
<SemanticCacheLookup>
|
Elemento filho | Nenhum |
<Embeddings>
Esse elemento contém as informações necessárias para gerar incorporações de texto.
Valor padrão | N/A |
Obrigatório? | Opcional |
Tipo | String |
Elemento pai |
<SemanticCacheLookup>
|
Elemento filho |
<VertexAI>
|
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.
Valor padrão | N/A |
Obrigatório? | Obrigatório |
Tipo | String |
Elemento pai |
<Embeddings>
|
Elemento filho |
<URL> |
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.
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}/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.
Valor padrão | N/A |
Obrigatório? | Obrigatório |
Tipo | String |
Elemento pai |
<SemanticCacheLookup>
|
Elemento filho |
<VertexAI> |
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.
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://{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>
.
Elemento filho | Obrigatório? | Descrição |
---|---|---|
<URL> |
Obrigatório | String O URL usado para realizar pesquisas de similaridade. O ponto de dados com maior correspondência, com base no limite de similaridade, será o único ponto de dados usado. |
<Threshold> |
Opcional | String Pontuação de similaridade usada para determinar se duas instruções são consideradas correspondentes. Um valor entre 0 e 1. O valor padrão é 0,9. |
<DeployedIndexID> |
Obrigatório | String O ID do índice implantado no endpoint do índice usado para armazenamento em cache semântico. |
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 |
---|---|
request.content |
Contém o conteúdo completo da solicitação de API recebida. |
request.url |
Contém o URL da solicitação de API recebida. |
semanticcache.lookup.policy_name.user_prompt |
Contém componentes específicos extraídos do comando de solicitação, que é usado para gerar embeddings ou realizar pesquisas de similaridade. |
semanticcache.lookup.policy_name.embeddings_request |
Contém o payload da solicitação enviado à API Embeddings da Vertex AI para gerar embeddings de texto para o texto de entrada. |
semanticcache.lookup.policy_name.embeddings_response |
Contém a resposta da API Embeddings da Vertex AI, que inclui os embeddings de texto gerados. |
semanticcache.lookup.policy_name.dense_embeddings |
Contém os valores reais de embedding numérico gerados pela API Vertex AI Embeddings. |
semanticcache.lookup.policy_name.is_nearest_neighbor_hit |
Especifica se um vizinho mais próximo foi encontrado no banco de dados de vetores para a solicitação e o ponto de dados atende ao limite de semelhança. |
semanticcache.lookup.policy_name.cache_hit |
Especifica se a resposta foi encontrada no cache semântico. |
semanticcache.lookup.policy_name.cached_llm_response |
Contém a resposta recuperada do cache semântico (se um ocorrência em cache ocorreu). |
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.
Código de falha | Status HTTP | Causa |
---|---|---|
steps.semanticcache.lookup.MessageTemplateExtractionFailed |
400 |
Não foi possível extrair dados da solicitação usando a expressão de caminho JSON. |
steps.semanticcache.lookup.FailedToExtractUserPrompt |
500 |
Não foi possível extrair a solicitação do usuário da solicitação da API. |
steps.semanticcache.lookup.EmbeddingsServiceUnavailable |
400 |
O serviço de incorporação da Vertex AI está indisponível no momento. |
steps.semanticcache.lookup.EmbeddingsAPIFailed |
400 |
O serviço de embeddings da Vertex AI falhou. |
steps.semanticcache.lookup.VectorSearchServiceUnavailable |
400 |
O serviço de pesquisa vetorial da Vertex AI está indisponível no momento. |
steps.semanticcache.lookup.VectorSearchAPIFailed |
400 |
O serviço de pesquisa vetorial da Vertex AI falhou. |
steps.semanticcache.lookup.AuthenticationFailure |
500 |
A conta de serviço não tem as permissões necessárias. |
steps.semanticcache.lookup.InternalError |
500 |
Ocorreu um erro inesperado na política SemanticCacheLookup. |
steps.semanticcache.lookup.CalloutError |
500 |
A chamada de serviço da Vertex AI falhou. |
Erros de implantação
Esses erros podem ocorrer quando você implanta um proxy que contém esta política.
Nome do erro | Causa |
---|---|
The Embeddings/VertexAI element is required. |
Ocorre se o elemento <VertexAI> em <Embeddings> estiver vazio. |
The SimilaritySearch/VertexAI element is required. |
Ocorre se o elemento <VertexAI> em <SimilaritySearch> estiver vazio. |
The Embeddings/URL element is required. |
Ocorre se o elemento <URL> em <Embeddings> estiver vazio. |
The SimilaritySearch/URL element is required. |
Ocorre se o elemento <URL> em <SimilaritySearch> estiver vazio. |
Embeddings URL {url} is invalid. |
Ocorre quando o elemento <URL> em <Embeddings> está vazio ou inválido. |
The SimilaritySearch URL {url} is invalid. |
Ocorre se o elemento <URL> em <SimilaritySearch> estiver vazio ou inválido. |
The scheme {http-scheme} of Embeddings URL {url} must be one of http, https. |
Ocorre se o esquema http do elemento "Embeddings <URL>" 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. |
SimilaritySearch/Threshold element must be >= 0 and <= 1. |
Se o atributo não estiver entre 0 e 1, a implantação do proxy de API vai falhar. |
SimilaritySearch/DeployedIndexID element is required. |
Ocorre se o elemento <DeployedIndexID> em <SimilaritySearch> estiver vazio. |
SimilaritySearch/DeployedIndexID element must not contain spaces. |
Ocorre se o elemento <DeployedIndexID> em <SimilaritySearch> contiver espaços. |
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" |
semanticcachelookup.POLICY_NAME.failed |
POLICY_NAME é o nome especificado pelo usuário da política que causou a falha. | semanticcachelookup.SC-lookup.failed = true |
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.