Começar a usar políticas de armazenamento em cache semântica

Esta página se aplica à Apigee, mas não à 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 minimiza chamadas de API de back-end redundantes, reduz a latência e diminui os custos operacionais.

Antes de começar

Antes de começar, faça o seguinte:

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

Enable the APIs

1. Configure a API Text Embeddings e a Pesquisa de vetor da Vertex AI no seu projeto Google Cloud .
2. Confirme se você tem um ambiente Comprehensive disponível na sua instância da Apigee. As políticas de cache semântico só podem ser implantadas em ambientes abrangentes.

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 do IAM de Usuário da 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.

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:

• 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.

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 armazenamento em cache semântico ajudam os usuários da Apigee com modelos de LLM a veicular de forma inteligente prompts idênticos ou semanticamente semelhantes, 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 preencher o cache da Apigee com a resposta. Um ciclo de feedback é criado para atualizar as entradas do índice da pesquisa vetorial em preparação para solicitações futuras.

As seções a seguir descrevem as etapas para criar e configurar as políticas de cache semântico:

1. Configure uma conta de serviço para o índice da pesquisa de vetor.
2. Crie e implante um índice da Pesquisa de vetor.
3. Crie um proxy de API para ativar o cache semântico.
4. Configure as políticas de armazenamento em cache semântico.
5. Teste 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:

1. 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"

2. 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"

   Substitua SERVICE_ACCOUNT_NAME pelo nome da conta de serviço criada na etapa anterior.

3. Atribua o papel do IAM Service Account User à 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"

   Substitua SERVICE_ACCOUNT_NAME pelo nome da conta de serviço criada na etapa anterior.

Criar e implantar um índice da Pesquisa de vetor

Para criar e implantar um índice da Pesquisa de vetor:

1. 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.

2. 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. 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 um IndexEndpoint.

3. 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

   Observação:o comando para implantar o índice no endpoint exige jq. Se esse utilitário de processamento JSON ainda não estiver instalado no seu ambiente de desenvolvimento, instale-o usando o seguinte comando: $ sudo apt install jq.

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, crie 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:

1. Acesse a página Proxies de API no Google Cloud console.

   Acessar proxies de API

2. Clique em + Criar para abrir o painel Criar proxy de API.
3. Na caixa Modelo de proxy, selecione Proxy com cache semântico.
4. 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 de LLM que gera conteúdo.

     Para este tutorial, defina o Destino (API atual) como:

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent

5. Insira os seguintes URLs de cache semântico:
   Observação:também é possível adicionar esses URLs à configuração XML no Editor de proxy na guia Desenvolver.
   • Gerar URL de embeddings: esse serviço da Vertex AI converte entradas de texto em uma forma numérica para análise semântica.

     Para este tutorial, defina o URL 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, defina o URL como:

     PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors

     Os valores de PUBLIC_DOMAIN_NAME e INDEX_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, defina o URL como:

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints

6. Clique em Próxima.
7. Clique em Criar.

A configuração XML do proxy de API aparece 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.

Observação: as políticas SemanticCachePopulate e SemanticCacheLookup aceitam o uso de modelos de URL para esses elementos. Se quiser, forneça uma variável nesse elemento para armazenar o valor do URL, como mostrado no exemplo a seguir:

<URL>https://{URL_VARIABLE}</URL>

Configurar as políticas de armazenamento em cache semântico

Clique no nome da política na visualização Detalhes da guia Desenvolver do proxy de API para conferir a configuração XML de cada política. Edite o XML da política diretamente na Visualização de código da guia Desenvolver.

Edite as políticas:

• Política SemanticCacheLookup:
  • Remova o elemento <UserPromptSource> para usar o valor padrão.
  • Atualize o elemento <DeployedIndexId> para usar o valor semantic_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.
• 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 de controle de cache recebidos do modelo de LLM.
  • Clique em Salvar.

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:

1. 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>.
2. 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>

3. Clique em Salvar.

Implante o proxy de API

Para implantar o proxy de API:

1. Clique em Implantar para abrir o painel Implantar proxy de API.
2. O campo Revisão precisa ser definido como 1. Caso contrário, clique em 1 para selecionar.
3. Na lista Ambiente, selecione o ambiente em que você quer implantar o proxy. O ambiente precisa ser abrangente.
4. Insira a Conta de serviço que você criou em uma etapa anterior.
5. Clique em Implantar.

Testar as políticas de cache semântico

Para testar as políticas de cache semântico:

1. 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?"
                 }
             ]
         }
     ]
   }'

   Substitua PROXY_NAME pelo 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ê?
2. Compare o tempo de resposta de cada chamada depois que um comando semelhante é armazenado em cache.

Para verificar se as chamadas estão sendo veiculadas do cache, confira os cabeçalhos de resposta. Um cabeçalho Cached-Content: true é 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:

• 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 armazenadas 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.

Aumentar as cotas para serviços dependentes

Se você tiver gargalos de desempenho resultantes de um aumento nas consultas por segundo (QPS), talvez seja necessário aumentar as seguintes cotas para serviços dependentes no projeto Google Cloud :

• Solicitações de previsão on-line por minuto e região (selecione por região)
• Solicitações regionais de previsão on-line por modelo base, por minuto e por região (selecione por região e o modelo textembedding-gecko)
• Solicitações de atualização de stream do Matching Engine por minuto e região (selecione por região)

Para aumentar uma cota de um desses serviços:

1. Acesse a página Cotas e limites do sistema:

   Acesse "Cotas e limites do sistema"

2. Na barra de filtro, insira o nome da cota específica que você quer aumentar, junto com a região e o modelo, se relevante.

   Por exemplo, filtre por Solicitações de previsão on-line regionais por modelo base, por minuto e por região, textembedding-gecko e us-west1.

3. Clique no menu do serviço que você quer aumentar e selecione Editar cota.
4. Insira um valor novo e maior para a cota.
5. Clique em Concluído.
6. Clique em Enviar solicitação.

Depois de enviar a solicitação, o aumento de cota será processado. Monitore o status na página Cotas e limites do sistema usando a guia Aumentar o número de solicitações.

Limitações

As seguintes limitações se aplicam às políticas de cache semântico:

• 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 ignora todos os cabeçalhos "cache-control" 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.
  • Para mais informações sobre como configurar o TTL para gerenciar a atualização de dados, consulte a seção Práticas recomendadas.
  • Para mais informações sobre como configurar o limite de similaridade semântica, consulte a seção Configurar as políticas de cache semântico.
  • Para mais informações sobre como ajustar o algoritmo de similaridade semântica, consulte Filtrar correspondências de vetores.
• O recurso de pesquisa vetorial não está disponível em todas as regiões. Para uma lista de regiões com suporte, consulte a seção Disponibilidade de recursos na página "Locais da Vertex AI". Se a sua organização da Apigee estiver em uma região sem suporte, crie endpoints de índice em uma região diferente da sua 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).
• As políticas de cache semântico usam APIs de LLM, o que pode resultar em latências mais altas na ordem de centenas de milissegundos.

A seguir

Saiba como começar a usar as políticas do Model Armor.