Cache semântico com um endpoint particular (Private Service Connect)

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 armazenamento em cache semântico da Apigee para permitir a reutilização inteligente de respostas com base na similaridade semântica. Neste exemplo, as políticas executam a pesquisa de similaridade em um índice da Busca Vetorial implantado em um endpoint particular (Private Service Connect). O uso dessas políticas no seu proxy de API da Apigee minimiza as chamadas de API de back-end redundantes, reduz a latência e diminui os custos operacionais.

Este guia se aplica à Apigee e à Apigee híbrida. A configuração da política é idêntica nas duas plataformas. A única diferença é como o ambiente de execução alcança o endpoint particular, conforme descrito na Etapa 2: conectar-se ao anexo de serviço. Na Apigee híbrida, o armazenamento em cache semântico em um endpoint particular (Private Service Connect) é compatível com as versões 1.16.11 e posteriores e 1.17.0 e posteriores. Para mais informações, consulte Configurar na Apigee híbrida.

Antes de começar

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

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

  2. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Compute Engine, AI Platform, and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Compute Engine, AI Platform, and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.
  8. Ative e configure a API de embedding de texto da Vertex AI no seu Google Cloud projeto.
  9. Crie (ou tenha acesso a) um índice da Pesquisa vetorial implantado em um endpoint particular (Private Service Connect). Este tutorial não duplica as etapas de configuração da Pesquisa Vetorial. Consulte Pré-requisitos do índice da Pesquisa Vetorial para ver os requisitos específicos do SemanticCacheLookup e links para a documentação da Pesquisa Vetorial.
  10. Confirme se você tem um ambiente intermediário ou abrangente disponível na sua instância da Apigee. As políticas de armazenamento em cache semântico só podem ser implantadas em ambientes intermediários ou abrangentes.
  11. Confirme se você tem um grupo de ambientes com um nome de host de ambiente de execução que possa ser usado para enviar solicitações ao proxy de API.

Funções exigidas

Para receber as permissões necessárias para criar e usar as políticas de armazenamento em cache semântico, peça ao administrador para conceder a você o papel do IAM de Usuário da plataforma de IA (roles/aiplatform.user) na conta de serviço usada para implantar proxies da 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 do Google Cloud que contém sua instância da 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 região Google Cloud da 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 seguinte comando e analise a saída: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Defina o projeto:

Defina o projeto do Google Cloud no ambiente de desenvolvimento: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Pré-requisitos do índice da Pesquisa Vetorial

Neste tutorial, presumimos que você já tenha (ou vai criar) um índice da Pesquisa Vetorial implantado em um endpoint particular (Private Service Connect). A criação, a formatação e a implantação de um índice da Pesquisa Vetorial estão documentadas nos guias da Pesquisa Vetorial. Portanto, este tutorial não duplica essas etapas. Siga a documentação da Pesquisa Vetorial para:

Ao criar o índice, ele precisa atender aos seguintes requisitos específicos do SemanticCacheLookup:

  • O índice precisa usar STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE") para que as chamadas upsertDatapoints da política SemanticCachePopulate se tornem consultáveis quase em tempo real.
  • O índice dimensions precisa corresponder à dimensionalidade de saída do modelo de embeddings usado na política SemanticCacheLookup. Este tutorial usa gemini-embedding-001, que produz embeddings de 3.072 dimensões por padrão. Se você truncar a saída para uma dimensionalidade menor (por exemplo, 768 ou 1536), defina dimensions com o mesmo valor.
  • Crie o índice com a medida de distância (distanceMeasureType) que corresponde ao <DistanceMeasureType> da sua política. O elemento <SimilaritySearch><VertexAI><DistanceMeasureType> na política SemanticCacheLookup é opcional e o padrão é DOT_PRODUCT_DISTANCE. COSINE_DISTANCE também é aceito. A medida de distância do índice e a política <DistanceMeasureType> precisam ser as mesmas.

O exemplo mínimo a seguir cria um índice compatível. Para ver o corpo completo da solicitação e todas as opções disponíveis, consulte Criar e gerenciar um índice:

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl -X POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "semantic-cache-index",
    "metadata": {
      "config": {
        "dimensions": 3072,
        "distanceMeasureType": "DOT_PRODUCT_DISTANCE"
      }
    },
    "indexUpdateMethod": "STREAM_UPDATE"
  }'

Anote o INDEX_ID numérico retornado na resposta. Você vai usá-lo na política SemanticCachePopulate. Depois de criar o índice, crie um endpoint de índice do Private Service Connect e implante o índice nele.

Ao criar o endpoint de índice do Private Service Connect, ele precisa atender aos seguintes requisitos específicos do SemanticCacheLookup:

  • O projectAllowlist precisa incluir o projeto da Apigee que inicia a conexão:
    • Apigee:use o projeto de locatário da Apigee. Consiga o ID do projeto de locatário na API Organizations (campo apigeeProjectId).
    O projectAllowlist não pode ser modificado depois que o endpoint de índice é criado. Se você colocar o projeto errado na lista de permissões, será necessário excluir e recriar o endpoint de índice.

Anote o INDEX_ENDPOINT_ID numérico do endpoint do índice.

Configurar a conta de serviço para o proxy da Apigee

O proxy da Apigee usa uma conta de serviço para as chamadas REST da Vertex AI: a API Embeddings na política SemanticCacheLookup, upsertDatapoints na política SemanticCachePopulate e o destino do modelo. Conceda a essa conta de serviço o papel AI Platform User (roles/aiplatform.user):

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

Em que SERVICE_ACCOUNT é o endereço de e-mail da conta de serviço que o proxy usa. Você vai referenciar essa conta de serviço ao implantar o proxy na Etapa 4: importar e implantar o proxy de API.

Pré-requisitos adicionais para implantações da Apigee híbrida

Para implantações da Apigee híbrida, confirme os seguintes requisitos adicionais:

  • Um ambiente de execução híbrido na versão 1.16.11 ou posterior, ou 1.17.0 ou posterior, instalado no seu próprio cluster do Kubernetes. Consulte a documentação de instalação da Apigee híbrida. Esse recurso não adiciona requisitos de cluster próprios. Qualquer cluster híbrido compatível funciona.
  • Um ambiente intermediário ou abrangente e um grupo de ambientes com um nome de host de ambiente de execução, o mesmo da Apigee. As políticas de armazenamento em cache semântico são implantadas apenas em ambientes intermediários ou abrangentes.
  • Network Reachability do ambiente de execução para o endpoint particular. O processador de mensagens precisa ser capaz de abrir uma conexão gRPC de texto simples com o endpoint do Private Service Connect da Pesquisa Vetorial em TARGET_HOST:10000.
  • Saída para as chamadas REST. As chamadas de embeddings, preenchimento e destino do modelo vão para a superfície pública REGION-aiplatform.googleapis.com. Portanto, o ambiente de execução também precisa de um caminho para as APIs do Google, diretamente ou por um caminho particular, se o cluster não tiver saída pública.

Configurar na Apigee híbrida

O armazenamento em cache semântico em um endpoint particular (Private Service Connect) é compatível com a Apigee híbrida versão 1.16.11 e mais recentes e versão 1.17.0 e mais recentes. A configuração da política e as etapas da Pesquisa Vetorial neste tutorial são idênticas às da Apigee. A diferença é que, na híbrida, você executa o ambiente de execução e fornece a conectividade por conta própria. Como as implantações híbridas variam muito, esta seção é uma orientação geral, e não comandos exatos. O único requisito que esse recurso adiciona é que o ambiente de execução precisa ser capaz de alcançar o endpoint particular por meio de gRPC de texto simples.

Fornecer Network Reachability

Em implantações híbridas, é necessário gerenciar a conectividade manualmente, porque não há um anexo de endpoint gerenciado pela Apigee. Crie um endpoint do Private Service Connect na VPC do consumidor que aponte para o SERVICE_ATTACHMENT da busca vetorial e use o endereço IP interno dele como o TARGET_HOST no proxy. Consulte a Etapa 2: conectar-se ao anexo de serviço para mais informações. O roteamento específico (por exemplo, VPC compartilhada ou GKE nativo de VPC) depende da configuração do cluster.

Se o cluster não tiver saída de dados para a internet pública, verifique se o ambiente de execução tem um caminho privado para as APIs do Google, como o Acesso privado do Google, para processar a comunicação REST.

Depois de estabelecer a conectividade com o grpc://TARGET_HOST:10000, siga as etapas seguintes: criar e implantar o índice, criar o proxy e testar, que são idênticas para a Apigee e a Apigee híbrida.

Visão geral

As políticas de armazenamento em cache semântico ajudam os usuários da Apigee com modelos de LLM a exibir 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 da 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 de embedding de texto. Uma pesquisa de similaridade semântica é realizada usando a Pesquisa Vetorial para encontrar comandos semelhantes. Se um ponto de dados de comando semelhante for encontrado, uma pesquisa de cache será realizada. Se 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 loop de feedback é criado para atualizar as entradas do índice da Pesquisa Vetorial em preparação para solicitações futuras.

Neste cenário, o índice da Pesquisa Vetorial é implantado em um endpoint particular (Private Service Connect) por gRPC. Confira mais detalhes sobre o suporte do Private Service Connect da Busca Vetorial em Consultar índices do acesso a serviços particulares ou do Private Service Connect.

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

  1. Verifique seus recursos e receba os valores necessários para a Apigee.
  2. Conecte-se ao anexo de serviço.
  3. Crie o pacote de proxy de API.
  4. Importe e implante o proxy de API.
  5. Testar as políticas de armazenamento em cache semântico.

Etapa 1: verificar seus recursos e receber os valores necessários para a Apigee

Antes de configurar a Apigee, confirme se o endpoint do índice da Pesquisa Vetorial está com o Private Service Connect ativado e se o índice está implantado. Em seguida, leia os dois valores que o proxy da Apigee consome: o anexo de serviço e o DEPLOYED_INDEX_ID.

Confirme se o índice foi implantado e se o endpoint expõe um anexo de serviço do Private Service Connect:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"

O comando retorna um nome de recurso de anexo de serviço no formato projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME. Neste guia, esse valor é chamado de SERVICE_ATTACHMENT. Se o comando retornar um valor vazio, o índice ainda não foi implantado em um endpoint do Private Service Connect. Volte para os pré-requisitos do índice da Pesquisa Vetorial e conclua a implantação do índice antes de continuar.

Leia o DEPLOYED_INDEX_ID do índice implantado no endpoint:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.id)"

Neste guia, esse valor é chamado de DEPLOYED_INDEX_ID. Você vai usá-lo na política SemanticCacheLookup na Etapa 3: criar o pacote de proxy de API.

Para mais informações sobre como implantar e consultar endpoints de índice particulares, consulte Implantar um índice em um endpoint do Private Service Connect e Consultar índices do acesso a serviços particulares ou do Private Service Connect.

Etapa 2: conectar-se ao anexo de serviço

Essa etapa fornece o host particular que o <GrpcEndpoint> do proxy chama. A maneira de criá-lo depende da sua plataforma. A configuração do proxy nas etapas posteriores é idêntica em ambos os casos.

Apigee: criar um anexo de endpoint

Na Apigee, crie um anexo de endpoint da Apigee. O anexo de endpoint é o lado do consumidor do Private Service Connect da Apigee. Ele se conecta ao anexo de serviço da Pesquisa Vetorial e fornece um host particular que o proxy chama.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "'"$REGION"'",
        "serviceAttachment": "SERVICE_ATTACHMENT"
      }' \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT"

Sondar até que o state do anexo seja ACTIVE e o connectionState seja ACCEPTED. Em seguida, anote o host: 

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments/ENDPOINT_ATTACHMENT"

A resposta contém o host no campo host. Neste guia, esse valor é chamado de TARGET_HOST.

Para se conectar ao anexo de serviço da busca vetorial pelo proxy, use:

  • O endereço IP:use o endereço IP retornado no campo host diretamente como TARGET_HOST (por exemplo, 7.0.3.4).
  • Um registro DNS particular:se você configurou uma zona particular do Cloud DNS no projeto do Google Cloud com peering de DNS para a Apigee, é possível criar um registro A na zona particular que aponte para o endereço IP do anexo do endpoint e usar esse nome de domínio (como vectorsearch.example.com) como TARGET_HOST. Para mais informações, consulte Usar um registro DNS e Como se conectar com zonas de peering de DNS particular.

Endpoint do Private Service Connect para a Apigee híbrida

Na Apigee, o Google fornece um recurso de "anexo de endpoint" que processa a conexão do Private Service Connect. No entanto, na Apigee híbrida, você gerencia o ambiente de execução e o ambiente de rede. Não importa onde o cluster é executado, ele precisa ser capaz de acessar o endpoint do Private Service Connect da Pesquisa Vetorial por uma conexão gRPC de texto simples com host:10000.

Para a Apigee híbrida, crie um endpoint do Private Service Connect em uma Google Cloud VPC do consumidor que aponte para o SERVICE_ATTACHMENT da busca vetorial. Use o endereço IP interno do endpoint como o TARGET_HOST na configuração do proxy. Verifique se o projeto do Google Cloud que hospeda esse endpoint está incluído no projectAllowlist do endpoint de índice da Pesquisa Vetorial. Consulte os pré-requisitos do índice da Pesquisa Vetorial para mais detalhes.

Etapa 3: criar o pacote de proxy de API

Criar o pacote de proxy

Crie o seguinte layout de diretório: 

apiproxy/
├── PROXY_NAME.xml
├── proxies/default.xml
├── targets/default.xml
└── policies/
    ├── SCL-1.xml
    └── SCP-1.xml

policies/SCL-1.xml: a política SemanticCacheLookup. O bloco <SimilaritySearch> usa <PrivateServiceConnect><GrpcEndpoint> (sem <URL>).

Observação: regras de <GrpcEndpoint>:

  • O formato é grpc://TARGET_HOST:PORT. O esquema precisa ser grpc://. grpcs:// (TLS) não é compatível com esta versão.
  • A porta é 10000 para a Pesquisa Vetorial. Os endpoints do plano de dados do Private Service Connect disponibilizam gRPC na porta 10000, então o endpoint é sempre grpc://TARGET_HOST:10000.
  • TARGET_HOST pode ser o endereço IP do anexo do endpoint (da Etapa 2) ou um registro DNS personalizado criado na sua zona de DNS particular.
  • O salto do gRPC é em texto simples e não autenticado (protegido por isolamento de rede).
<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-1">
  <DisplayName>SCL-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-embedding-001:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <PrivateServiceConnect>
        <GrpcEndpoint>grpc://TARGET_HOST:10000</GrpcEndpoint>
      </PrivateServiceConnect>
      <DeployedIndexID>DEPLOYED_INDEX_ID</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

policies/SCP-1.xml: a política SemanticCachePopulate. O preenchimento é somente REST e precisa usar <URL> (ele rejeita <PrivateServiceConnect> no momento da implantação): 

<SemanticCachePopulate async="false" continueOnError="true" enabled="true" name="SCP-1">
  <DisplayName>SCP-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>3600</TTLInSeconds>
</SemanticCachePopulate>

targets/default.xml: o destino do modelo. O destino chama uma API do Google, então ele precisa de um token. O <GoogleAccessToken> usa a conta de serviço da implantação: 

<TargetEndpoint name="default">
  <PreFlow name="PreFlow"><Request/><Response/></PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

proxies/default.xml: execute a política SemanticCacheLookup na solicitação e a política SemanticCachePopulate na resposta: 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request><Step><Name>SCL-1</Name></Step></Request>
    <Response><Step><Name>SCP-1</Name></Step></Response>
  </PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPProxyConnection>
    <BasePath>/PROXY_NAME</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

PROXY_NAME.xml: o descritor do pacote: 

<APIProxy name="PROXY_NAME">
  <BasePaths>/PROXY_NAME</BasePaths>
  <Policies><Policy>SCL-1</Policy><Policy>SCP-1</Policy></Policies>
  <ProxyEndpoints><ProxyEndpoint>default</ProxyEndpoint></ProxyEndpoints>
  <TargetEndpoints><TargetEndpoint>default</TargetEndpoint></TargetEndpoints>
</APIProxy>

Etapa 4: importar e implantar o proxy de API

Compacte o pacote, importe-o para criar uma nova revisão e implante a revisão com sua conta de serviço: 

TOKEN=$(gcloud auth print-access-token)
(cd BUNDLE_DIR && zip -r ../PROXY_NAME.zip apiproxy)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@PROXY_NAME.zip" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?action=import&name=PROXY_NAME"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments?override=true&serviceAccount=SERVICE_ACCOUNT"

Em que:

  • BUNDLE_DIR é o diretório que contém a pasta apiproxy/. O arquivo precisa conter a pasta apiproxy/ na raiz.
  • ENV é o ambiente da Apigee em que você implanta o proxy. O ambiente precisa ser Intermediário ou Abrangente.
  • REVISION é o número da revisão retornado pela chamada de importação.
  • SERVICE_ACCOUNT é o endereço de e-mail da conta de serviço que você usa para implantar o proxy.

Aguarde até que a implantação informe READY: 

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments" | jq .state

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

Envie um novo comando. Isso é uma ausência no cache: o modelo é chamado e a resposta é armazenada em cache. 

curl -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

Envie o mesmo comando de novo. Isso é uma ocorrência em cache: a resposta é exibida do cache, e o modelo não é chamado. 

curl -i -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

No hit, a resposta inclui o cabeçalho Cached-content: true, a mesma resposta e uma latência visivelmente menor.

Também é possível verificar o armazenamento em cache com uma sessão de depuração. Em uma ocorrência, a política SemanticCacheLookup define as seguintes variáveis de fluxo:

Variável Valor em um hit
SemanticCacheLookup.SCL-1.dense_embeddings O vetor de embedding do comando.
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response A resposta armazenada em cache.

Em uma ocorrência, o destino do modelo não é invocado. O fluxo é interrompido e retorna a resposta armazenada em cache.

Solução de problemas

Para ver a referência de erro completa, consulte a política SemanticCacheLookup.

Limitações

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

  • O tamanho máximo de texto que pode ser armazenado 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 de controle de cache que recebe 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 uma lista de regiões com disponibilidade, consulte a seção Disponibilidade de recursos da página Locais da Vertex AI. Se a organização da Apigee estiver em uma região sem suporte, será necessário criar endpoints de índice em uma região diferente da organização da Apigee.
  • As políticas de armazenamento em cache semântico não são compatíveis com proxies de API que usam EventFlows para streaming de resposta contínua de eventos enviados pelo servidor (SSE).
  • As políticas de armazenamento em cache semântico usam APIs de LLM, o que pode resultar em latências mais altas, na casa das centenas de milissegundos.
  • Nas instalações da Apigee híbrida, o suporte às políticas de armazenamento em cache semântico é limitado às instalações no Google Cloud Platform.
  • Quando a política SemanticCacheLookup é configurada para usar um endpoint particular da Pesquisa Vetorial pelo Private Service Connect (PSC), a chamada de pesquisa de similaridade é enviada por uma conexão gRPC direta ao endpoint particular e não passa por um proxy de encaminhamento configurado.

A seguir