Esta página foi traduzida pela API Cloud Translation.

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

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.

Go to project selector

Make sure 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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the 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.

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:

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

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.

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:

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.

Criar e implantar um índice da Pesquisa de vetor

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

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

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

Acesse a página Proxies de API no Google Cloud console.
Acessar proxies de API
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:
Observação:esses URLs também podem ser adicionados à configuração XML no Editor de proxy na guia Desenvolver.
- 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 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, o URL pode ser definido como:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
Clique em Próxima.
Clique em Criar.

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:

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 "cache-control" 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:

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.

Implante o proxy de API

Para implantar o proxy de API:

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.

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

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

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.

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.

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:

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.

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

A seguir

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