Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
Nesta página, descrevemos como configurar e usar as políticas de cache semântico da Apigee para ativar a reutilização inteligente de respostas com base na similaridade semântica. Usar essas políticas no proxy de API do Apigee pode minimizar chamadas redundantes de API de back-end, reduzir a latência e diminuir os custos operacionais.
Antes de começar
Antes de começar, conclua as seguintes tarefas:
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Compute Engine, AI Platform, and Cloud Storage APIs.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Compute Engine, AI Platform, and Cloud Storage APIs.
- Configure e configure a API Text Embeddings e a Pesquisa de vetores da Vertex AI no seu projeto Google Cloud .
- Confirme se você tem um ambiente Completo disponível na sua instância da Apigee. As políticas de cache semântico só podem ser implantadas em ambientes abrangentes.
PROJECT_ID
é o ID do projeto com sua instância da Apigee.REGION
é a Google Cloud região da sua instância da Apigee.RUNTIME_HOSTNAME
é o nome do host do ambiente de execução da Apigee.- Configure uma conta de serviço para o índice de pesquisa de vetor.
- Crie e implante um índice da Pesquisa de vetor.
- Crie um proxy de API para ativar o cache semântico.
- Configure as políticas de armazenamento em cache semântico.
- Teste as políticas de cache semântico.
- Crie uma conta de serviço usando o seguinte comando:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --description="DESCRIPTION" \ --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"
Em que:
SERVICE_ACCOUNT_NAME
é o nome da conta de serviço.DESCRIPTION
é uma descrição da conta de serviço.SERVICE_ACCOUNT_DISPLAY_NAME
é o nome de exibição da conta de serviço.
Exemplo:
gcloud iam service-accounts create ai-client \ --description="semantic cache client" \ --display-name="ai-client"
- Conceda à conta de serviço o papel
AI Platform User
usando o seguinte comando:gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/aiplatform.user"
Em que
SERVICE_ACCOUNT_NAME
é o nome da conta de serviço criada na etapa anterior. - Atribua o papel
Service Account User
do IAM à conta de serviço usando o seguinte comando:gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountUser"
Em que
SERVICE_ACCOUNT_NAME
é o nome da conta de serviço criada na etapa anterior. - Crie um índice da Pesquisa de vetor que permita atualizações de streaming:
ACCESS_TOKEN=$(gcloud auth print-access-token) && curl --location --request POST \ "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --data-raw \ '{ "displayName": "semantic-cache-index", "description": "semantic-cache-index", "metadata": { "config": { "dimensions": "768", "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "featureNormType": "NONE", "algorithmConfig": { "treeAhConfig": { "leafNodeEmbeddingCount": "10000", "fractionLeafNodesToSearch": 0.05 } }, "shardSize": "SHARD_SIZE_MEDIUM" }, }, "indexUpdateMethod": "STREAM_UPDATE" }'
$REGION define a região em que o índice da pesquisa de vetor é implantado. Recomendamos que você use a mesma região da sua instância do Apigee. Essa variável de ambiente foi definida em uma etapa anterior.
Quando essa operação for concluída, você vai ver uma resposta semelhante a esta:
{ "name": "projects/976063410430/locations/us-west1/indexes/5695338290484346880/operations/9084564741162008576", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2025-04-25T18:45:27.996136Z", "updateTime": "2025-04-25T18:45:27.996136Z" } } }
Para mais informações sobre como criar índices de pesquisa de vetor, consulte Criar um índice.
- Crie um
IndexEndpoint
usando o seguinte comando:gcloud ai index-endpoints create \ --display-name=semantic-cache-index-endpoint \ --public-endpoint-enabled \ --region=$REGION \ --project=$PROJECT_ID
Essa etapa pode levar alguns minutos para ser concluída. Quando ele for concluído, você vai ver uma resposta semelhante a esta:
Waiting for operation [8278420407862689792]...done. Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.
Para mais informações sobre como criar um
IndexEndpoint
, consulte Criar umIndexEndpoint
. - Implante o índice no endpoint usando o seguinte comando:
INDEX_ENDPOINT_ID=$(gcloud ai index-endpoints list \ --project=$PROJECT_ID \ --region=$REGION \ --format="json" | jq -c -r \ '.[] | select(.displayName=="semantic-cache-index-endpoint") | .name | split("/") | .[5]' \ ) && INDEX_ID=$(gcloud ai indexes list \ --project=$PROJECT_ID \ --region=$REGION \ --format="json" | jq -c -r \ '.[] | select(.displayName=="semantic-cache-index") | .name | split("/") | .[5]' \ ) && gcloud ai index-endpoints deploy-index \ $INDEX_ENDPOINT_ID \ --deployed-index-id=semantic_cache \ --display-name=semantic-cache \ --index=$INDEX_ID \ --region=$REGION \ --project=$PROJECT_ID
- Acesse a página Proxies de API no Google Cloud console.
- Clique em + Criar para abrir o painel Criar proxy de API.
- Na caixa Modelo de proxy, selecione Proxy com cache semântico.
- Digite os seguintes detalhes:
- Nome do proxy: insira o nome do proxy.
- Descrição: (opcional) insira uma descrição do proxy.
- Destino (API atual): insira o URL do serviço de back-end que o proxy chama. Este
é o endpoint do modelo LLM usado para gerar conteúdo.
Para este tutorial, o Destino (API atual) pode ser definido como:
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
- Insira os seguintes URLs de cache semântico:
- Gerar URL de embeddings: esse serviço da Vertex AI
converte a entrada de texto em uma forma numérica para análise semântica.
Para este tutorial, o URL pode ser definido como:
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
- URL de consulta do vizinho mais próximo: esse serviço da Vertex AI
pesquisa entradas de texto semelhantes de solicitações anteriores no índice da Pesquisa Vetorial para evitar o reprocessamento.
Para este tutorial, o URL pode ser definido como:
PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors
Os valores de
PUBLIC_DOMAIN_NAME
eINDEX_ENDPOINT_ID
foram definidos em uma etapa anterior. Para extrair esses valores, use os seguintes comandos:echo $PUBLIC_DOMAIN_NAME
echo $INDEX_ENDPOINT_ID
- URL de upsert do índice: esse serviço da Vertex AI atualiza o índice com entradas novas ou modificadas.
Para este tutorial, o URL pode ser definido como:
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
- Gerar URL de embeddings: esse serviço da Vertex AI
converte a entrada de texto em uma forma numérica para análise semântica.
- Clique em Próxima.
- Clique em Criar.
- Política SemanticCacheLookup:
- Remova o elemento
<UserPromptSource>
para usar o valor padrão. - Atualize o elemento
<DeployedIndexId>
para usar o valorsemantic_cache
. - Configure o valor de similaridade semântica
<Threshold>
para determinar quando dois comandos são considerados uma correspondência. O padrão é 0,9, mas você pode ajustar esse valor com base na sensibilidade do seu aplicativo. Quanto maior o número, mais relacionadas as solicitações precisam ser para serem consideradas um ocorrência em cache. Para este tutorial, recomendamos definir esse valor como 0,95. - Clique em Salvar.
- Remova o elemento
- Política SemanticCachePopulate:
- Defina o elemento
<TTLInSeconds>
para especificar o número de segundos até que o cache expire. O valor padrão é 60s. A Apigee ignora todos os cabeçalhos "cache-control" recebidos do modelo de LLM. - Clique em Salvar.
- Defina o elemento
- Na guia Desenvolver, clique em padrão na pasta Endpoints de destino. A visualização de código mostra a configuração XML do elemento <TargetEndpoint>.
- Edite o XML para adicionar a seguinte configuração em <HTTPTargetConnection>:
<Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
- Clique em Salvar.
- Clique em Implantar para abrir o painel Implantar proxy de API.
- O campo Revisão precisa ser definido como 1. Caso contrário, clique em 1 para selecionar.
- Na lista Ambiente, selecione o ambiente em que você quer implantar o proxy. O ambiente precisa ser abrangente.
- Insira a conta de serviço que você criou em uma etapa anterior.
- Clique em Implantar.
- Envie uma solicitação ao proxy usando o seguinte comando:
curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{ "contents": [ { "role": "user", "parts": [ { "text": "Why is the sky blue?" } ] } ] }'
Em que
PROXY_NAME
é o basepath do proxy de API implantado na etapa anterior.
Repita a chamada de API, substituindo a string de comando pelas seguintes strings semanticamente semelhantes:
- Por que o céu é azul?
- O que faz o céu ser azul?
- Por que o céu é azul?
- Você pode explicar por que o céu é azul?
- O céu é azul, por quê?
- Compare o tempo de resposta de cada chamada depois que um comando semelhante é armazenado em cache.
- Evite o armazenamento em cache de dados sensíveis com o Model Armor.
Para evitar o armazenamento em cache de dados sensíveis, recomendamos usar o Model Armor para filtragem de conteúdo. O Model Armor pode sinalizar respostas como não armazenáveis em cache se detectar informações sensíveis. Para mais informações, consulte a visão geral do Model Armor.
- Gerencie a atualização dos dados com a invalidação de pontos de dados da Vertex AI e o tempo de vida (TTL).
Recomendamos implementar estratégias adequadas de invalidação de pontos de dados para garantir que as respostas em cache estejam atualizadas e reflitam as informações mais recentes dos seus sistemas de back-end. Para saber mais, consulte Atualizar e recriar um índice ativo.
Também é possível ajustar o TTL das respostas armazenadas em cache com base na volatilidade dos dados e na frequência das atualizações. Para mais informações sobre como usar o TTL na política SemanticCachePopulate, consulte <TTLInSeconds>.
- Use estratégias de cache predefinidas para garantir os dados de resposta mais precisos.
Recomendamos implementar estratégias de cache predefinidas semelhantes a estas:
- Respostas genéricas de IA: configure um TTL longo (por exemplo, uma hora) para respostas não específicas do usuário.
- Respostas específicas do usuário: não implemente o armazenamento em cache nem defina um TTL curto (por exemplo, cinco minutos) para respostas que contenham informações específicas do usuário.
- Respostas sensíveis ao tempo: configure um TTL curto (por exemplo, cinco minutos) para respostas que exigem atualizações em tempo real ou frequentes.
- O tamanho máximo de texto armazenável em cache é de 256 KB. Para mais informações, consulte Tamanho do valor do cache na página Limites da Apigee.
- A Apigee vai ignorar todos os cabeçalhos de controle de cache recebidos do modelo de LLM.
- Se o cache não for invalidado corretamente ou se o algoritmo de similaridade semântica não for preciso o suficiente para diferenciar entradas com significados muito semelhantes, a resposta poderá retornar informações desatualizadas ou incorretas.
- O recurso de pesquisa vetorial não está disponível em todas as regiões. Para conferir uma lista de regiões com suporte, consulte a seção Disponibilidade de recursos na página "Locais da Vertex AI". Se a organização da Apigee estiver em uma região sem suporte, crie endpoints de índice em uma região diferente da organização da Apigee.
- As políticas de cache semântico não são compatíveis com proxies de API que usam EventFlows para streaming contínuo de respostas de eventos enviados pelo servidor (SSE).
- A função JsonPath em <UserPromptSource> não é compatível com a funcionalidade
ignoreUnresolvedVariables
. Por padrão, valores nulos ou vazios são ignorados durante a aplicação do modelo de mensagem.
Funções exigidas
Para receber as permissões necessárias
para criar e usar as políticas de cache semântico,
peça ao administrador para conceder a você o papel
Usuário da AI Platform (roles/aiplatform.user
)
do IAM 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.
Defina as variáveis de ambiente
No projeto Google Cloud que contém sua instância do Apigee, use o seguinte comando para definir variáveis de ambiente:
export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME
Em que:
Para confirmar se as variáveis de ambiente estão definidas corretamente, execute o comando a seguir e analise a saída:
echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME
Definir o projeto
Defina o projeto Google Cloud no ambiente de desenvolvimento:
gcloud auth login
gcloud config set project $PROJECT_ID
Visão geral
As políticas de cache semântico foram projetadas para ajudar os usuários da Apigee com modelos de LLM a veicular de forma inteligente comandos idênticos ou semanticamente semelhantes de maneira eficiente, minimizando as chamadas de API de back-end e reduzindo o consumo de recursos.
As políticas SemanticCacheLookup e SemanticCachePopulate são anexadas aos fluxos de solicitação e resposta, respectivamente, de um proxy de API do Apigee. Quando o proxy recebe uma solicitação, a política SemanticCacheLookup extrai o comando do usuário da solicitação e o converte em uma representação numérica usando a API Text Embeddings. Uma pesquisa de similaridade semântica é realizada usando a pesquisa vetorial para encontrar comandos semelhantes. Se um ponto de dados de solicitação semelhante for encontrado, uma pesquisa de cache será realizada. Se os dados em cache forem encontrados, a resposta em cache será retornada ao cliente.
Se a pesquisa de similaridade não retornar um comando anterior semelhante, o modelo de LLM vai gerar conteúdo em resposta ao comando do usuário, e o cache da Apigee será preenchido com a resposta. Um ciclo de feedback é criado para atualizar as entradas do índice da Pesquisa de vetores em preparação para solicitações futuras.
As seções a seguir descrevem as etapas necessárias para criar e configurar as políticas de cache semântico:
Configurar uma conta de serviço para o índice de pesquisa de vetor
Para configurar uma conta de serviço para o índice da pesquisa vetorial, siga estas etapas:
Criar e implantar um índice da Pesquisa de vetor
Para criar e implantar um índice da Pesquisa de vetor:
A implantação inicial de um índice em um endpoint pode levar de 20 a 30 minutos para ser concluída. Para verificar o status da operação, use o seguinte comando:
gcloud ai operations describe OPERATION_ID \ --project=$PROJECT_ID \ --region=$REGION
Confirme se o índice foi implantado:
gcloud ai operations describe OPERATION_ID \ --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID
O comando retornará $ done: true
.
Criar um proxy de API para ativar o cache semântico
Nesta etapa, você vai criar um proxy de API usando o modelo Proxy com cache semântico, se ainda não tiver feito isso.
Antes de criar o proxy de API, defina a seguinte variável de ambiente:
export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')
Para criar um proxy para uso com o cache semântico:
A configuração XML do proxy de API pode ser visualizada na guia Desenvolver. As políticas SemanticCacheLookup e SemanticCachePopulate que contêm valores padrão já estão anexadas aos fluxos de solicitação e resposta do proxy.
Configurar as políticas de armazenamento em cache semântico
Para conferir a configuração XML de cada política, clique no nome dela na visualização Detalhes da guia Desenvolver do proxy de API. As edições no XML da política podem ser feitas diretamente na Visualização de código da guia Desenvolver.
Edite as políticas:
Adicionar autenticação do Google ao proxy de API
Também é preciso adicionar a autenticação do Google ao endpoint de destino do proxy de API para ativar as chamadas de proxy ao destino.
Para adicionar o token de acesso do Google:
Implante o proxy de API
Para implantar o proxy de API:
Testar as políticas de armazenamento em cache semântico
Para testar as políticas de armazenamento em cache semântico:
Para verificar se as chamadas estão sendo veiculadas do cache, confira os cabeçalhos de resposta. Um cabeçalho Cached-Content: true
precisa estar anexado.
Práticas recomendadas
Recomendamos incorporar as seguintes práticas recomendadas ao seu programa de gerenciamento de API ao usar as políticas de cache semântico:
Limitações
As seguintes limitações se aplicam às políticas de cache semântico:
A seguir
Saiba como começar a usar as políticas do Model Armor.