Comece a usar políticas de colocação em cache semântica

Esta página aplica-se ao Apigee, mas não ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Esta página descreve como configurar e usar as políticas de cache semântica do Apigee para ativar a reutilização inteligente de respostas com base na semelhança semântica. A utilização destas políticas no seu proxy de API do Apigee minimiza as chamadas de API de back-end redundantes, reduz a latência e diminui 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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Configure a API Text Embeddings e a pesquisa vetorial do Vertex AI no seu Google Cloud projeto.
2. Confirme que tem um ambiente Abrangente disponível na sua instância do Apigee. As políticas de colocação em cache semântica só podem ser implementadas em ambientes Abrangente.

Funções necessárias

Para receber as autorizações de que precisa para criar e usar as políticas de colocação em cache semântica, peça ao seu administrador para lhe conceder a função do IAM Utilizador da plataforma de IA (roles/aiplatform.user) na conta de serviço que usa para implementar proxies do Apigee. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Defina variáveis de ambiente

No Google Cloud projeto que contém a 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

Onde:

• PROJECT_ID é o ID do projeto com a sua instância do Apigee.
• REGION é a Google Cloud região da sua instância do Apigee.
• RUNTIME_HOSTNAME é o nome do anfitrião do seu tempo de execução do Apigee.

Para confirmar que as variáveis de ambiente estão definidas corretamente, execute o seguinte comando e reveja o resultado:

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Defina o projeto

Defina o Google Cloud projeto no seu ambiente de desenvolvimento:

    gcloud auth login
    gcloud config set project $PROJECT_ID

Vista geral

As políticas de cache semântica ajudam os utilizadores do Apigee com modelos LLM a publicar de forma inteligente comandos 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 pedidos e respostas, respetivamente, de um proxy de API do Apigee. Quando o proxy recebe um pedido, a política SemanticCacheLookup extrai o comando do utilizador do pedido e converte o comando numa representação numérica através da API Text embeddings. Uma pesquisa de semelhança semântica é realizada através da pesquisa vetorial para encontrar comandos semelhantes. Se for encontrado um ponto de dados de comando semelhante, é realizada uma pesquisa na cache. Se forem encontrados dados em cache, a resposta em cache é devolvida ao cliente.

Se a pesquisa de semelhanças não devolver um comando anterior semelhante, o modelo GML gera conteúdo em resposta ao comando do utilizador e preenche a cache do Apigee com a resposta. É criado um ciclo de feedback para atualizar as entradas do índice de pesquisa vetorial em preparação para pedidos futuros.

As secções seguintes descrevem os passos para criar e configurar as políticas de colocação em cache semântica:

1. Configure uma conta de serviço para o índice do Vector Search.
2. Crie e implemente um índice do Vector Search.
3. Crie um proxy de API para ativar o armazenamento em cache semântico.
4. Configure as políticas de colocação em cache semântica.
5. Teste as políticas de colocação em cache semântica.

Configure uma conta de serviço para o índice do Vector Search

Para configurar uma conta de serviço para o índice de pesquisa vetorial, conclua os passos seguintes:

1. Crie uma conta de serviço com o seguinte comando:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --description="DESCRIPTION" \
     --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

   Onde:

   • 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 a apresentar da conta de serviço.

   Por exemplo:

   gcloud iam service-accounts create ai-client \
     --description="semantic cache client" \
     --display-name="ai-client"

2. Conceda à conta de serviço a função AI Platform User através do 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 no passo anterior.

3. Atribua a função do IAM Service Account User à conta de serviço através do 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 no passo anterior.

Crie e implemente um índice do Vector Search

Para criar e implementar um índice do Vector Search:

1. Crie um índice do Vector Search 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"
       }'

   A variável $REGION define a região onde o índice do Vector Search é implementado. Recomendamos que use a mesma região que a sua instância do Apigee. Esta variável de ambiente foi definida num passo anterior.

   Quando esta operação estiver concluída, deverá ver uma resposta semelhante à seguinte:

   {
     "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 a criação de índices de pesquisa vetorial, consulte o artigo Crie um índice.

2. Crie um IndexEndpoint com o seguinte comando:

   gcloud ai index-endpoints create \
     --display-name=semantic-cache-index-endpoint \
     --public-endpoint-enabled \
     --region=$REGION \
     --project=$PROJECT_ID

   Este passo pode demorar vários minutos a ser concluído. Quando terminar, deve ver uma resposta semelhante à seguinte:

   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 o artigo Crie um IndexEndpoint.

3. Implemente o índice no ponto final através do 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

   Nota: o comando para implementar o índice no ponto final requer jq. Se esta utilidade de processamento JSON ainda não estiver instalada no seu ambiente de desenvolvimento, pode instalá-la através do seguinte comando: $ sudo apt install jq.

A implementação inicial de um índice num ponto final pode demorar entre 20 e 30 minutos a ser concluída. Para verificar o estado da operação, use o seguinte comando:

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

Confirme se o índice implementado:

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

O comando deve devolver $ done: true.

Crie um proxy de API para ativar o armazenamento em cache semântico

Neste passo, crie um novo proxy de API com o modelo Proxy com cache semântica, se ainda não o tiver feito.

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 utilização com o armazenamento em cache semântico:

1. Aceda à página Proxies de API na Google Cloud consola.

   Aceda aos 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ântica.
4. Introduza os seguintes detalhes:
   • Nome do proxy: introduza o nome do proxy.
   • Descrição: (opcional) introduza uma descrição do proxy.
   • Destino (API existente): introduza o URL do serviço de back-end que o proxy chama. Este é o ponto final do modelo MDI/CE que gera conteúdo.

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

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

5. Introduza os seguintes URLs da cache semântica:
   Nota: também pode adicionar estes URLs à configuração XML no editor de proxy no separador Desenvolver.
   • Gerar URL de incorporações: este serviço do Vertex AI converte a entrada de texto num formato numérico para análise semântica.

     Para este tutorial, defina este URL para o seguinte:

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict

   • URL do vizinho mais próximo da consulta: este serviço do Vertex AI pesquisa entradas de texto semelhantes de pedidos anteriores no índice de pesquisa vetorial para evitar o reprocessamento.

     Para este tutorial, defina este URL para o seguinte:

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

     Os valores PUBLIC_DOMAIN_NAME e INDEX_ENDPOINT_ID foram definidos num passo anterior. Para obter estes valores, use os seguintes comandos:

       echo $PUBLIC_DOMAIN_NAME
       echo $INDEX_ENDPOINT_ID

   • URL do índice de inserção/atualização: este serviço do Vertex AI atualiza o índice com entradas novas ou modificadas.

     Para este tutorial, defina este URL para o seguinte:

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

6. Clicar em Seguinte.
7. Clique em Criar.

A configuração XML do proxy de API aparece no separador Desenvolver. As políticas SemanticCacheLookup e SemanticCachePopulate que contêm valores predefinidos já estão anexadas aos fluxos de pedidos e respostas do proxy.

Nota: as políticas SemanticCachePopulate e SemanticCacheLookup suportam a utilização de modelos de URL para estes elementos. Se quiser, pode fornecer uma variável neste elemento para conter o valor do URL, conforme mostrado no exemplo seguinte:

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

Configure as políticas de cache semântica

Veja a configuração XML de cada política clicando no nome da política na vista Detalhes do separador Desenvolver do proxy de API. Edite o XML da política diretamente na vista de código do separador Desenvolver.

Edite as políticas:

• Política SemanticCacheLookup:
  • Remova o elemento <UserPromptSource> para usar o valor predefinido.
  • Atualize o elemento <DeployedIndexId> para usar o valor semantic_cache.
  • Configure o valor de semelhança semântica <Threshold> para determinar quando dois comandos são considerados uma correspondência. O valor predefinido é 0,9, mas pode ajustar este valor com base na sensibilidade da sua aplicação. Quanto maior for o número, mais estreitamente os comandos têm de estar relacionados para serem considerados um resultado da cache. Para este tutorial, recomendamos que defina este valor como 0,95.
  • Clique em Guardar.
• Política SemanticCachePopulate:
  • Defina o elemento <TTLInSeconds> para especificar o número de segundos até a cache expirar. O valor predefinido é 60s. Tenha em atenção que o Apigee ignora todos os cabeçalhos cache-control que recebe do modelo de LLM.
  • Clique em Guardar.

Adicione a autenticação Google ao proxy de API

Também tem de adicionar a autenticação Google ao ponto final de destino do proxy de API para ativar as chamadas de proxy para o destino.

Para adicionar o token de acesso da Google:

1. No separador Desenvolver, clique em predefinição na pasta Pontos finais de destino. A vista de código apresenta 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 Guardar.

Implemente o proxy de API

Para implementar o proxy da API:

1. Clique em Implementar para abrir o painel Implementar proxy de API.
2. O campo Revision deve ser definido como 1. Caso contrário, clique em 1 para a selecionar.
3. Na lista Ambiente, selecione o ambiente onde quer implementar o proxy. O ambiente tem de ser um ambiente Abrangente.
4. Introduza a conta de serviço que criou num passo anterior.
5. Clique em Implementar.

Teste as políticas de colocação em cache semântica

Para testar as políticas de colocação em cache semântica:

1. Envie um pedido ao proxy através do 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 caminho base do proxy de API que implementou no passo anterior.

Repita a chamada da API, substituindo a string de comando pelas seguintes strings de comando semanticamente semelhantes:
• Porque é que o céu é azul?
• O que faz com que o céu seja azul?
• Porque é que o céu é azul?
• Podes explicar por que motivo o céu é azul?
• O céu é azul. Porquê?
2. Compare o tempo de resposta de cada chamada depois de uma instrução semelhante ter sido colocada em cache.

Para verificar se as suas chamadas estão a ser publicadas a partir da cache, verifique os cabeçalhos de resposta. É anexado um cabeçalho Cached-Content: true.

Práticas recomendadas

Recomendamos que incorpore as seguintes práticas recomendadas no seu programa de gestão de APIs quando usar as políticas de colocação em cache semântica:

• Impeça o armazenamento em cache de dados confidenciais com o Model Armor.

  Para evitar o armazenamento em cache de dados confidenciais, recomendamos a utilização do Model Armor para a filtragem de conteúdo. O Model Armor pode denunciar respostas como não armazenáveis em cache se detetar informações confidenciais. Para mais informações, consulte a vista geral do Model Armor.

• Faça a gestão da atualidade dos dados com a invalidação de pontos de dados e o tempo de vida (TTL) da Vertex AI.

  Recomendamos que implemente estratégias de invalidação de pontos de dados adequadas para garantir que as respostas em cache estão atualizadas e refletem as informações mais recentes dos seus sistemas de back-end. Para saber mais, consulte o artigo Atualize e recrie um índice ativo.

  Também pode ajustar o TTL das respostas em cache com base na volatilidade dos dados e na frequência das atualizações. Para mais informações sobre a utilização de TTL na política SemanticCachePopulate, consulte <TTLInSeconds>.

• Use estratégias de colocação em cache predefinidas para garantir os dados de resposta mais precisos.

  Recomendamos a implementação de estratégias de colocação em cache predefinidas semelhantes às seguintes:

  • Respostas genéricas da IA: configure um TTL longo (por exemplo, uma hora) para respostas não específicas do utilizador.
  • Respostas específicas do utilizador: 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 utilizador.
  • Respostas sensíveis ao tempo: configure um TTL curto (por exemplo, cinco minutos) para respostas que requerem atualizações em tempo real ou frequentes.

Aumente as quotas para serviços dependentes

Se tiver problemas de desempenho devido a um número mais elevado de consultas por segundo (QPS), pode ter de aumentar as seguintes quotas para os serviços dependentes no seu Google Cloud projeto:

• Solicitações de previsão online por minuto por região (selecione por região)
• Pedidos de previsão online regionais por modelo base por minuto por região (selecione por região e pelo modelo textembedding-gecko)
• Pedidos de atualização de streams do motor de correspondência por minuto por região (selecione por região)

Para aumentar uma quota de um destes serviços:

1. Aceda à página Quota e limites do sistema:

   Aceda a Quota e limites do sistema

2. Na barra de filtros, introduza o nome da quota específica que quer aumentar, juntamente com a região e o nome do modelo, se relevante.

   Por exemplo, filtre por Pedidos de previsão online regionais por modelo base por minuto por região e textembedding-gecko e us-west1.

3. Clique no menu do serviço que quer aumentar e, de seguida, selecione Editar quota.
4. Introduza um novo valor superior para a quota.
5. Clique em Concluído.
6. Clique em Enviar pedido.

Depois de enviar o pedido, o aumento da quota é processado. Pode monitorizar o estado na página Quotas e limites do sistema através do separador Pedidos de aumento.

Limitações

Aplicam-se as seguintes limitações às políticas de colocação em cache semântica:

• O tamanho máximo do texto armazenável em cache é de 256 KB. Para mais informações, consulte o Tamanho do valor da cache na página Limites do Apigee.
• O Apigee ignora todos os cabeçalhos cache-control que recebe do modelo de MDG.
• Se a cache não for invalidada corretamente ou se o algoritmo de semelhança semântica não for suficientemente preciso para diferenciar as entradas com significados muito semelhantes, a resposta pode devolver informações desatualizadas ou incorretas.
  • Para mais informações sobre a configuração do TTL para gerir a atualidade dos dados, consulte a secção Práticas recomendadas.
  • Para mais informações sobre a configuração do limite de semelhança semântica, consulte a secção Configure as políticas de colocação em cache semântica.
  • Para mais informações sobre o ajuste do algoritmo de semelhança semântica, consulte o artigo Filtre as correspondências de vetores.
• A funcionalidade de pesquisa vetorial não é suportada em todas as regiões. Para ver uma lista das regiões suportadas, consulte a secção Disponibilidade de funcionalidades da página Localizações do Vertex AI. Se a sua organização do Apigee estiver numa região não suportada, tem de criar pontos finais de índice numa região diferente da sua organização do Apigee.
• As políticas de colocação em cache semântica não são suportadas para utilização com proxies de API que usam EventFlows para streaming contínuo de respostas de eventos enviados pelo servidor (SSE).
• As políticas de colocação em cache semântica usam APIs de MDIs, o que pode resultar em latências mais elevadas na ordem das centenas de milissegundos.

O que se segue?

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