Memorizzazione nella cache semantica con un endpoint privato (Private Service Connect)

Questa pagina si applica ad Apigee e ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come configurare e utilizzare le policy di memorizzazione nella cache semantica di Apigee per abilitare il riutilizzo intelligente delle risposte in base alla somiglianza semantica. In questo esempio, le policy eseguono la ricerca per somiglianza su un indice Vector Search di cui è stato eseguito il deployment su un endpoint privato (Private Service Connect). L'utilizzo di queste policy nel proxy API Apigee riduce al minimo le chiamate API di backend ridondanti, la latenza e i costi operativi.

Questa guida si applica sia ad Apigee che ad Apigee Hybrid. La configurazione della policy è identica su entrambe le piattaforme, cambia solo il modo in cui il runtime raggiunge l'endpoint privato, come descritto nel Passaggio 2: connettiti al collegamento al servizio. In Apigee Hybrid, la memorizzazione nella cache semantica su un endpoint privato (Private Service Connect) è supportata nella versione 1.16.11 e successive e nella versione 1.17.0 e successive. Per saperne di più, consulta Configura su Apigee Hybrid.

Prima di iniziare

Prima di iniziare, completa le seguenti attività:

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

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

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

  4. Abilita e configura l' API Text Embeddings di Vertex AI nel tuo progetto Google Cloud .
  5. Crea (o accedi a) un indice Vector Search di cui è stato eseguito il deployment su un endpoint privato (Private Service Connect). Questo tutorial non duplica i passaggi di configurazione di Vector Search; consulta i prerequisiti dell'indice della Ricerca di Vector Search per i requisiti specifici di SemanticCacheLookup e i link alla documentazione di Vector Search.
  6. Verifica di avere un ambiente Intermedio o Completo disponibile nella tua istanza Apigee. È possibile eseguire il deployment delle policy di memorizzazione nella cache semantica solo negli ambienti di tipo intermedio o completo.
  7. Verifica di avere un gruppo di ambienti con un nome host di runtime che puoi utilizzare per inviare richieste al proxy API.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e utilizzare le policy di memorizzazione nella cache semantica, chiedi all'amministratore di concederti il ruolo IAM AI Platform User (roles/aiplatform.user) sul account di servizio che utilizzi per eseguire il deployment dei proxy Apigee. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Imposta le variabili di ambiente

Nel progetto Google Cloud che contiene l'istanza Apigee, utilizza il comando seguente per impostare le variabili di ambiente: 

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

Dove:

  • PROJECT_ID è l'ID del progetto con l'istanza Apigee.
  • REGION è la regione Google Cloud della tua istanza Apigee.
  • RUNTIME_HOSTNAME è il nome host del runtime Apigee.

Per verificare che le variabili di ambiente siano impostate correttamente, esegui questo comando ed esamina l'output: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Imposta il progetto

Imposta il progetto Google Cloud nel tuo ambiente di sviluppo: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Prerequisiti dell'indice Vector Search

Questo tutorial presuppone che tu abbia già (o creerai) un indice Vector Search di cui è stato eseguito il deployment su un endpoint privato (Private Service Connect). La creazione, la formattazione e il deployment di un indice Vector Search sono documentati nelle guide di Vector Search, pertanto questo tutorial non duplica questi passaggi. Segui la documentazione di Vector Search per:

Quando crei l'indice, questo deve soddisfare i seguenti requisiti specifici di SemanticCacheLookup:

  • L'indice deve utilizzare STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE") in modo che le chiamate upsertDatapoints della policy SemanticCachePopulate diventino interrogabili quasi in tempo reale.
  • L'indice dimensions deve corrispondere alla dimensionalità di output del modello di embedding che utilizzi nella policy SemanticCacheLookup. Questo tutorial utilizza gemini-embedding-001, che produce embedding a 3072 dimensioni per impostazione predefinita. Se tronchi l'output a una dimensionalità inferiore (ad esempio 768 o 1536), imposta dimensions sullo stesso valore.
  • Crea l'indice con la misura della distanza (distanceMeasureType) corrispondente al <DistanceMeasureType> della tua policy. L'elemento <SimilaritySearch><VertexAI><DistanceMeasureType> nella policy SemanticCacheLookup è facoltativo e il valore predefinito è DOT_PRODUCT_DISTANCE; è supportato anche COSINE_DISTANCE. La misura della distanza dell'indice e la policy <DistanceMeasureType> devono essere uguali.

L'esempio minimo seguente crea un indice compatibile. Per il corpo della richiesta completo e tutte le opzioni disponibili, consulta Crea e gestisci un indice:

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

Prendi nota del valore numerico INDEX_ID restituito nella risposta, che utilizzerai nella policy SemanticCachePopulate. Dopo aver creato l'indice, crea un endpoint indice Private Service Connect ed esegui il deployment dell'indice.

Quando crei l'endpoint indice Private Service Connect, questo deve soddisfare i seguenti requisiti specifici di SemanticCacheLookup:

  • projectAllowlist deve includere il progetto Apigee che avvia la connessione:
    • Apigee: utilizza il progetto tenant Apigee. Recupera l'ID progetto tenant dall'API Organizations (campo apigeeProjectId).
    projectAllowlist non può essere modificato dopo la creazione dell'endpoint indice. Se inserisci nella lista consentita il progetto sbagliato, devi eliminare e ricreare l'endpoint indice.

Prendi nota del valore numerico INDEX_ENDPOINT_ID dell'endpoint dell'indice.

Configura il account di servizio per il proxy Apigee

Il proxy Apigee utilizza un account di servizio per le chiamate REST di Vertex AI: l'API Embeddings nella policy SemanticCacheLookup, upsertDatapoints nella policy SemanticCachePopulate e il target del modello. Concedi a questo account di servizio il ruolo AI Platform User (roles/aiplatform.user):

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

Dove SERVICE_ACCOUNT è l'indirizzo email del account di servizio utilizzato dal proxy. Fai riferimento a questo account di servizio quando esegui il deployment del proxy nel Passaggio 4: importa ed esegui il deployment del proxy API.

Prerequisiti aggiuntivi per i deployment di Apigee Hybrid

Per i deployment di Apigee Hybrid, verifica i seguenti requisiti aggiuntivi:

  • Un runtime ibrido versione 1.16.11 o successive o 1.17.0 o successive, installato nel tuo cluster Kubernetes. Consulta la documentazione di installazione di Apigee Hybrid. Questa funzionalità non aggiunge requisiti propri per i cluster: qualsiasi cluster ibrido supportato funziona.
  • Un ambiente intermedio o completo e un gruppo di ambienti con un nome host di runtime, lo stesso di Apigee. Il deployment delle policy di memorizzazione nella cache semantica viene eseguito solo negli ambienti Intermedio o Completo.
  • Connettività di rete dal runtime all'endpoint privato. Il processore di messaggi deve essere in grado di aprire una connessione gRPC in testo non crittografato all'endpoint Private Service Connect di Vector Search su TARGET_HOST:10000.
  • Traffico in uscita per le chiamate REST. Le chiamate Embeddings, Populate e model-target vanno alla superficie REGION-aiplatform.googleapis.com pubblica, quindi il runtime ha bisogno anche di un percorso verso le API di Google, direttamente o tramite un percorso privato se il tuo cluster non ha un traffico in uscita pubblico.

Configura su Apigee Hybrid

La memorizzazione nella cache semantica su un endpoint privato (Private Service Connect) è supportata su Apigee Hybrid versione 1.16.11 e successive e versione 1.17.0 e successive. La configurazione della policy e i passaggi di Vector Search in questo tutorial sono identici a quelli di Apigee. La differenza è che in hybrid esegui il runtime e fornisci la connettività in autonomia. Poiché i deployment ibridi variano notevolmente, questa sezione fornisce indicazioni generali anziché comandi esatti. L'unico requisito aggiunto da questa funzionalità è che il runtime deve essere in grado di raggiungere l'endpoint privato tramite gRPC in testo non crittografato.

Fornisci la connettività di rete

Nei deployment ibridi, devi gestire la connettività manualmente perché non esiste un collegamento endpoint gestito da Apigee. Crea un endpoint Private Service Connect nel VPC consumer che punta a Vector Search SERVICE_ATTACHMENT e utilizza il suo indirizzo IP interno come TARGET_HOST nel proxy. Per saperne di più, consulta il Passaggio 2: connettiti al collegamento al servizio. Il routing specifico (ad es. VPC condiviso o GKE nativo di VPC) dipende dalla configurazione del cluster.

Se il tuo cluster non dispone di traffico in uscita verso internet pubblico, assicurati che il runtime abbia un percorso privato verso le API di Google, ad esempio l'accesso privato Google, per gestire la comunicazione REST.

Dopo aver stabilito la connettività a grpc://TARGET_HOST:10000, segui i passaggi successivi (creazione e deployment dell'indice, creazione del proxy e test), che sono identici sia per Apigee che per Apigee Hybrid.

Panoramica

Le policy di memorizzazione nella cache semantica aiutano gli utenti di Apigee con modelli LLM a gestire in modo intelligente prompt identici o semanticamente simili in modo efficiente, riducendo al minimo le chiamate API di backend e il consumo di risorse.

Le policy SemanticCacheLookup e SemanticCachePopulate si collegano rispettivamente ai flussi di richiesta e risposta di un proxy API Apigee. Quando il proxy riceve una richiesta, la policy SemanticCacheLookup estrae il prompt dell'utente dalla richiesta e lo converte in una rappresentazione numerica utilizzando l'API Text Embeddings. Una ricerca di somiglianza semantica viene eseguita utilizzando Vector Search per trovare prompt simili. Se viene trovato un punto dati del prompt simile, viene eseguita una ricerca nella cache. Se vengono trovati dati memorizzati nella cache, la risposta memorizzata nella cache viene restituita al client.

Se la ricerca di somiglianza non restituisce un prompt precedente simile, il modello LLM genera contenuti in risposta al prompt dell'utente e compila la cache di Apigee con la risposta. Viene creato un feedback loop per aggiornare le voci dell'indice di Vector Search in preparazione per le richieste future.

In questo scenario, l'indice di Vector Search viene distribuito su un endpoint privato (Private Service Connect) tramite gRPC. Scopri di più sul supporto di Private Service Connect per Vector Search in Esegui query sugli indici di accesso privato ai servizi o di Private Service Connect.

Le sezioni seguenti descrivono i passaggi per creare e configurare le policy di memorizzazione nella cache semantica:

  1. Verifica le risorse e ottieni i valori necessari per Apigee.
  2. Connettiti al collegamento al servizio.
  3. Crea il bundle del proxy API.
  4. Importa ed esegui il deployment del proxy API.
  5. Testa le policy di memorizzazione nella cache semantica.

Passaggio 1: verifica le risorse e ottieni i valori richiesti da Apigee

Prima di configurare Apigee, verifica che l'endpoint dell'indice di Vector Search sia abilitato per Private Service Connect e che sia stato eseguito il deployment dell'indice. Poi leggi i due valori utilizzati dal proxy Apigee: il collegamento al servizio e DEPLOYED_INDEX_ID.

Verifica che il deployment dell'indice sia stato eseguito e che l'endpoint esponga un collegamento al servizio Private Service Connect:

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

Il comando restituisce un nome risorsa del collegamento al servizio nel formato projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME. Questa guida fa riferimento a questo valore come SERVICE_ATTACHMENT. Se il comando restituisce un valore vuoto, l'indice non è ancora stato distribuito su un endpoint Private Service Connect. Torna ai prerequisiti dell'indice Vector Search e completa il deployment dell'indice prima di continuare.

Leggi il DEPLOYED_INDEX_ID dell'indice di cui è stato eseguito il deployment sull'endpoint:

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

Questa guida fa riferimento a questo valore come DEPLOYED_INDEX_ID. Lo utilizzerai nella policy SemanticCacheLookup nel Passaggio 3: crea il bundle del proxy API.

Per saperne di più sul deployment e sulla query di endpoint di indici privati, consulta Esegui il deployment di un indice su un endpoint Private Service Connect ed Esegui query sugli indici di accesso ai servizi privati o di Private Service Connect.

Passaggio 2: connettiti al collegamento al servizio

Questo passaggio ti fornisce l'host privato chiamato da <GrpcEndpoint> del proxy. La modalità di creazione dipende dalla piattaforma. La configurazione del proxy nei passaggi successivi è identica in entrambi i casi.

Apigee: crea un collegamento dell'endpoint

Su Apigee, crea un collegamento endpoint Apigee. L'allegato endpoint è il lato consumer di Private Service Connect di Apigee. Si connette al collegamento al servizio Vector Search e ti fornisce un host privato che viene chiamato dal proxy.

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"

Esegui il polling finché il valore state del collegamento non è ACTIVE e il valore connectionState non è ACCEPTED, quindi prendi nota dell'host: 

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

La risposta contiene l'host nel campo host. Questa guida fa riferimento a questo valore come TARGET_HOST.

Per connetterti al collegamento al servizio Vector Search dal proxy, puoi utilizzare:

  • L'indirizzo IP: utilizza l'indirizzo IP restituito nel campo host direttamente come TARGET_HOST (ad esempio, 7.0.3.4).
  • Un record DNS privato: se hai configurato una zona Cloud DNS privata nel tuo progetto Google Cloud con peering DNS ad Apigee, puoi creare un record A nella zona privata che punta all'indirizzo IP del collegamento endpoint e utilizzare il nome di dominio (ad esempiovectorsearch.example.com) come TARGET_HOST. Per saperne di più, consulta Utilizza un record DNS e Connessione con zone di peering DNS privato.

Endpoint Private Service Connect per Apigee Hybrid

In Apigee, Google fornisce una risorsa "collegamento endpoint" che gestisce la connessione Private Service Connect. Tuttavia, in Apigee Hybrid gestisci il runtime e l'ambiente di rete. Indipendentemente da dove viene eseguito il cluster, deve essere in grado di raggiungere l'endpoint Private Service Connect di Vector Search tramite una connessione gRPC in testo non crittografato a host:10000.

Per Apigee Hybrid, crea un endpoint Private Service Connect in un VPC consumer Google Cloud che punta a Vector Search SERVICE_ATTACHMENT. Utilizza l'indirizzo IP interno dell'endpoint come TARGET_HOST nella configurazione del proxy. Assicurati che il progetto Google Cloud che ospita questo endpoint sia incluso nelprojectAllowlistdell'endpoint di indice Vector Search. Per maggiori dettagli, consulta i prerequisiti per l'indice Vector Search.

Passaggio 3: crea il bundle del proxy API

Crea il bundle del proxy

Crea il seguente layout di directory: 

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

policies/SCL-1.xml: la policy SemanticCacheLookup. Il blocco <SimilaritySearch> utilizza <PrivateServiceConnect><GrpcEndpoint> (nessun <URL>).

Nota: regole di <GrpcEndpoint>:

  • Il formato è grpc://TARGET_HOST:PORT; lo schema deve essere grpc://. grpcs:// (TLS) non è supportato in questa versione.
  • La porta è 10000 per Vector Search. Gli endpoint del piano dati di Private Service Connect gestiscono gRPC sulla porta 10000, quindi l'endpoint è sempre grpc://TARGET_HOST:10000.
  • TARGET_HOST può essere l'indirizzo IP del collegamento endpoint (dal passaggio 2) o un record DNS personalizzato creato nella tua zona DNS privata.
  • L'hop gRPC è in testo non crittografato e non autenticato (protetto dall'isolamento della rete).
<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: la policy SemanticCachePopulate. Populate è solo REST e deve utilizzare <URL> (rifiuta <PrivateServiceConnect> al momento del deployment): 

<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: il target del modello. La destinazione chiama un'API di Google, quindi ha bisogno di un token; <GoogleAccessToken> utilizza il account di servizio del deployment: 

<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: esegui la policy SemanticCacheLookup sulla richiesta e la policy SemanticCachePopulate sulla risposta: 

<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: il descrittore del bundle: 

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

Passaggio 4: importa ed esegui il deployment del proxy API

Comprimi il bundle, importalo per creare una nuova revisione ed esegui il deployment della revisione con il tuo account di servizio: 

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"

Dove:

  • BUNDLE_DIR è la directory che contiene la cartella apiproxy/. L'archivio deve contenere la cartella apiproxy/ nella directory radice.
  • ENV è l'ambiente Apigee in cui esegui il deployment del proxy. L'ambiente deve essere di tipo intermedio o completo.
  • REVISION è il numero di revisione restituito dalla chiamata di importazione.
  • SERVICE_ACCOUNT è l'indirizzo email del account di servizio che utilizzi per eseguire il deployment del proxy.

Attendi che il deployment restituisca 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

Passaggio 5: testa le policy di memorizzazione nella cache semantica

Invia un nuovo prompt. Questo è un fallimento della cache: il modello viene chiamato e la risposta viene memorizzata nella 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."}]}]}'

Invia di nuovo lo stesso prompt. Si tratta di un successo della cache: la risposta viene fornita dalla cache e il modello non viene chiamato. 

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

In caso di hit, la risposta include l'intestazione Cached-content: true, la stessa risposta e una latenza notevolmente inferiore.

Puoi anche verificare la memorizzazione nella cache con una sessione di debug. In caso di hit, la policy SemanticCacheLookup imposta le seguenti variabili di flusso:

Variabile Valore di un hit
SemanticCacheLookup.SCL-1.dense_embeddings Il vettore di embedding del prompt.
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response La risposta memorizzata nella cache.

In caso di hit, il target del modello non viene richiamato: il flusso viene interrotto e restituisce la risposta memorizzata nella cache.

Risoluzione dei problemi

Per il riferimento completo agli errori, consulta le norme SemanticCacheLookup.

Limitazioni

Alle policy di memorizzazione nella cache semantica si applicano le seguenti limitazioni:

  • La dimensione massima del testo memorizzabile nella cache è di 256 kB. Per saperne di più, consulta Dimensioni del valore della cache nella pagina Limiti di Apigee.
  • Apigee ignora le intestazioni cache-control ricevute dal modello LLM.
  • Se la cache non viene invalidata correttamente o se l'algoritmo di somiglianza semantica non è sufficientemente accurato da distinguere tra input con significati molto simili, la risposta potrebbe restituire informazioni obsolete o errate.
  • La funzionalità Vector Search non è supportata in tutte le regioni. Per un elenco delle regioni supportate, consulta la sezione Disponibilità delle funzionalità della pagina Località di Vertex AI. Se la tua organizzazione Apigee si trova in una regione non supportata, dovrai creare endpoint indice in una regione diversa da quella della tua organizzazione Apigee.
  • Le policy di memorizzazione nella cache semantica non sono supportate per l'utilizzo con i proxy API che utilizzano EventFlows per lo streaming continuo delle risposte degli eventi inviati dal server (SSE).
  • Le policy di memorizzazione nella cache semantica utilizzano le API LLM, il che può comportare latenze più elevate nell'ordine di centinaia di millisecondi.
  • Nelle installazioni di Apigee hybrid, il supporto delle policy di memorizzazione nella cache semantica è limitato alle installazioni su Google Cloud Platform.
  • Quando la policy SemanticCacheLookup è configurata per utilizzare un endpoint Vector Search privato tramite Private Service Connect (PSC), la chiamata di ricerca per somiglianza viene inviata tramite una connessione gRPC diretta all'endpoint privato e non passa attraverso un proxy di inoltro configurato.

Passaggi successivi