Esta página foi traduzida pela API Cloud Translation.

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

Esta página aplica-se ao Apigee e 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 pode minimizar as chamadas de API de back-end redundantes, reduzir a latência e diminuir os custos operacionais.

Antes de começar

Antes de começar, certifique-se de que conclui 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

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.

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

Configure a API Text Embeddings e a pesquisa vetorial do Vertex AI no seu Google Cloud projeto.
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 de utilizador da AI Platform (roles/aiplatform.user) do IAM 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 colocação em cache semântica foram concebidas para ajudar os utilizadores do Apigee com modelos de LLM a apresentar de forma inteligente pedidos idênticos ou semanticamente semelhantes de forma eficiente, minimizando as chamadas de API de back-end e reduzindo o consumo de recursos.

As políticas SemanticCacheLookup e SemanticCachePopulate estã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. É realizada uma pesquisa de semelhanças semânticas 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 a cache do Apigee é preenchida 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 necessários para criar e configurar as políticas de colocação em cache semântica:

Configure uma conta de serviço para o índice de pesquisa vetorial.
Crie e implemente um índice de pesquisa vetorial.
Crie um proxy de API para ativar o armazenamento em cache semântico.
Configure as políticas de colocação em cache semântica.
Teste as políticas de colocação em cache semântica.

Configure uma conta de serviço para o índice de pesquisa vetorial

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

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"

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"

Em que SERVICE_ACCOUNT_NAME é o nome da conta de serviço criada no passo anterior.

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"

Em que SERVICE_ACCOUNT_NAME é o nome da conta de serviço criada no passo anterior.

Crie e implemente um índice de pesquisa vetorial

Para criar e implementar um índice de pesquisa vetorial:

Crie um índice de pesquisa vetorial 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 de pesquisa vetorial está 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 como criar índices de pesquisa vetorial, consulte o artigo Crie um índice.

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 alguns minutos a ser concluído. Quando estiver concluído, 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.

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

Aceda à página Proxies de API na Google Cloud consola.
Aceda aos proxies de API
Clique em + Criar para abrir o painel Criar proxy de API.
Na caixa Modelo de proxy, selecione Proxy com cache semântica.
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 de MDG usado para gerar conteúdo.
  Para este tutorial, o Destino (API existente) pode ser definido como:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
Introduza os seguintes URLs da cache semântica:
Nota: estes URLs também podem ser adicionados à 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, este URL pode ser definido como 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, este URL pode ser definido como 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, pode usar 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, este URL pode ser definido como o seguinte:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
Clicar em Seguinte.
Clique em Criar.

Pode ver a configuração XML do proxy de API 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.

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

Pode ver a configuração XML de cada política clicando no nome da política na vista Detalhes do separador Desenvolver do proxy de API. As edições ao XML da política podem ser feitas 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é o cache expirar, em segundos. 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:

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

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

Implemente o proxy de API

Para implementar o proxy da API:

Clique em Implementar para abrir o painel Implementar proxy de API.
O campo Revision deve ser definido como 1. Caso contrário, clique em 1 para o selecionar.
Na lista Ambiente, selecione o ambiente onde quer implementar o proxy. O ambiente tem de ser um ambiente Abrangente.
Introduza a conta de serviço que criou num passo anterior.
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:

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

Onde PROXY_NAME é o caminho base do proxy da API que implementou no passo anterior.

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ê?

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. Deve existir um cabeçalho Cached-Content: true anexado.

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

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.
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).
A função JsonPath em <UserPromptSource> não suporta a funcionalidade ignoreUnresolvedVariables. Por predefinição, os valores nulos ou vazios são ignorados durante a aplicação do modelo de mensagem.

O que se segue?

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