Inizia a utilizzare le norme di memorizzazione nella cache semantica

Questa pagina si applica ad Apigee e 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 attivare il riutilizzo intelligente delle risposte in base alla somiglianza semantica. L'utilizzo di questi criteri nel proxy API Apigee può ridurre al minimo le chiamate API di backend ridondanti, ridurre la latenza e abbassare i costi operativi.

Prima di iniziare

Prima di iniziare, assicurati di completare le seguenti attività:

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

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

    Go to project selector

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

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

    Enable the APIs

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

    Go to project selector

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

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

    Enable the APIs

    8.
  8. Configura l'API Vertex AI Text Embeddings e Vector Search all'interno del tuo progetto Google Cloud .
  9. Verifica di avere un ambiente Comprehensive disponibile nella tua istanza Apigee. I criteri di memorizzazione nella cache semantica possono essere implementati solo negli ambienti Completo.

    10. Ruoli obbligatori

    Per ottenere le autorizzazioni necessarie per creare e utilizzare le norme di memorizzazione nella cache semantica, chiedi all'amministratore di concederti il ruolo IAM Utente AI Platform (roles/aiplatform.user) nell'account di servizio che utilizzi per 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 seguente comando 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 la tua 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 il comando seguente ed esamina l'output: 

    echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

    Impostare il progetto

    Imposta il Google Cloud progetto nell'ambiente di sviluppo: 

        gcloud auth login
    gcloud config set project $PROJECT_ID

    Panoramica

    Le policy di memorizzazione nella cache semantica sono progettate per aiutare gli utenti Apigee con i 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.

    I criteri SemanticCacheLookup e SemanticCachePopulate sono collegati rispettivamente ai flussi di richiesta e risposta di un proxy API Apigee. Quando il proxy riceve una richiesta, il criterio SemanticCacheLookup estrae il prompt dell'utente dalla richiesta e lo converte in una rappresentazione numerica utilizzando l'API Text Embeddings. Viene eseguita una ricerca di similarità semantica 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 somiglianze non restituisce un prompt precedente simile, il modello LLM genera contenuti in risposta al prompt dell'utente e la cache di Apigee viene compilata con la risposta. Viene creato un ciclo di feedback per aggiornare le voci dell'indice Vector Search in preparazione alle richieste future.

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

    1. Configura un account di servizio per l'indice Vector Search.
    2. Crea ed esegui il deployment di un indice Vector Search.
    3. Crea un proxy API per abilitare la memorizzazione nella cache semantica.
    4. Configura i criteri di memorizzazione nella cache semantica.
    5. Testa i criteri di memorizzazione nella cache semantica.

    Configura un account di servizio per l'indice Vector Search

    Per configurare un account di servizio per l'indice Vector Search, completa i seguenti passaggi:

    1. Crea un account di servizio utilizzando il seguente comando: 
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

      Dove:

      • SERVICE_ACCOUNT_NAME è il nome del account di servizio.
      • DESCRIPTION è una descrizione del account di servizio.
      • SERVICE_ACCOUNT_DISPLAY_NAME è il nome visualizzato del account di servizio.

      Ad esempio: 

      gcloud iam service-accounts create ai-client \
  --description="semantic cache client" \
  --display-name="ai-client"
    2. Concedi all'account di servizio il ruolo AI Platform User utilizzando questo comando: 
      gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

      dove SERVICE_ACCOUNT_NAME è il nome del account di servizio creato nel passaggio precedente.

    3. Assegna il ruolo IAM Service Account User al account di servizio utilizzando questo comando: 
      gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

      dove SERVICE_ACCOUNT_NAME è il nome del account di servizio creato nel passaggio precedente.

    Crea ed esegui il deployment di un indice Vector Search

    Per creare e implementare un indice Vector Search:

    1. Crea un indice Vector Search che consenta gli aggiornamenti in 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 definisce la regione in cui viene eseguito il deployment dell'indice Vector Search. Ti consigliamo di utilizzare la stessa regione dell'istanza Apigee. Questa variabile di ambiente è stata impostata in un passaggio precedente.

      Al termine dell'operazione, dovresti visualizzare una risposta simile alla seguente: 

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

      Per saperne di più sulla creazione di indici Vector Search, vedi Creare un indice.

    2. Crea un IndexEndpoint utilizzando il seguente comando: 
      gcloud ai index-endpoints create \
  --display-name=semantic-cache-index-endpoint \
  --public-endpoint-enabled \
  --region=$REGION \
  --project=$PROJECT_ID

      Il completamento di questo passaggio potrebbe richiedere diversi minuti. Al termine, dovresti visualizzare una risposta simile alla seguente: 

      Waiting for operation [8278420407862689792]...done.
  Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

      Per maggiori informazioni sulla creazione di un IndexEndpoint, vedi Creare un IndexEndpoint.

    3. Esegui il deployment dell'indice nell'endpoint utilizzando il seguente 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

    Il deployment iniziale di un indice in un endpoint può richiedere tra 20 e 30 minuti. Per controllare lo stato dell'operazione, utilizza il seguente comando: 

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

    Verifica che l'indice sia stato implementato: 

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

    Il comando dovrebbe restituire $ done: true.

    Crea un proxy API per abilitare la memorizzazione nella cache semantica

    In questo passaggio, se non l'hai già fatto, creerai un nuovo proxy API utilizzando il modello Proxy con cache semantica.

    Prima di creare il proxy API, imposta la seguente variabile di ambiente: 

    export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

    Per creare un proxy da utilizzare con la memorizzazione nella cache semantica:

    1. Vai alla pagina Proxy API nella console Google Cloud .

      Vai ai proxy API

    2. Fai clic su + Crea per aprire il riquadro Crea proxy API.
    3. Nella casella Modello proxy, seleziona Proxy con cache semantica.
    4. Inserisci i seguenti dettagli:
      • Nome proxy: inserisci il nome del proxy.
      • (Facoltativo) Descrizione: inserisci una descrizione del proxy.
      • Destinazione (API esistente): inserisci l'URL del servizio di backend chiamato dal proxy. Questo è l'endpoint del modello LLM utilizzato per generare contenuti.

        Per questo tutorial, Target (API esistente) può essere impostato su: 

        REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
    5. Inserisci i seguenti URL della cache semantica:
      • Genera URL di incorporamento: questo servizio Vertex AI converte l'input di testo in una forma numerica per l'analisi semantica.

        Per questo tutorial, questo URL può essere impostato su: 

        REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
      • URL query Nearest Neighbor: questo servizio Vertex AI cerca input di testo simili dalle richieste precedenti nell'indice Vector Search per evitare la rielaborazione.

        Per questo tutorial, questo URL può essere impostato su: 

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

        I valori PUBLIC_DOMAIN_NAME e INDEX_ENDPOINT_ID sono stati impostati in un passaggio precedente. Per ottenere questi valori, puoi utilizzare i seguenti comandi: 

          echo $PUBLIC_DOMAIN_NAME
  echo $INDEX_ENDPOINT_ID

      • URL di upsert dell'indice: questo servizio Vertex AI aggiorna l'indice con voci nuove o modificate.

        Per questo tutorial, questo URL può essere impostato su: 

        REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
    6. Fai clic su Avanti.
    7. Fai clic su Crea.

    La configurazione XML del proxy API può essere visualizzata nella scheda Sviluppa. Le policy SemanticCacheLookup e SemanticCachePopulate contenenti valori predefiniti sono già associate ai flussi di richiesta e risposta del proxy.

    Configura le policy di memorizzazione nella cache semantica

    Puoi visualizzare la configurazione XML di ogni policy facendo clic sul nome della policy nella visualizzazione Dettagli della scheda Sviluppa del proxy API. Le modifiche al file XML del criterio possono essere apportate direttamente nella Vista codice della scheda Sviluppa.

    Modifica le policy:

    • Norma SemanticCacheLookup:
      • Rimuovi l'elemento <UserPromptSource> per utilizzare il valore predefinito.
      • Aggiorna l'elemento <DeployedIndexId> in modo da utilizzare il valore semantic_cache.
      • Configura il valore di similarità semantica <Threshold> per determinare quando due prompt vengono considerati una corrispondenza. Il valore predefinito è 0,9, ma puoi modificarlo in base alla sensibilità della tua applicazione. Più il numero è alto, più le richieste devono essere correlate per essere considerate un successo della cache. Per questo tutorial, ti consigliamo di impostare questo valore su 0,95.
      • Fai clic su Salva.
    • Criterio SemanticCachePopulate:
      • Imposta l'elemento <TTLInSeconds> per specificare il numero di secondi fino alla scadenza della cache. Il valore predefinito è 60 secondi. Tieni presente che Apigee ignorerà tutte le intestazioni cache-control che riceve dal modello LLM.
      • Fai clic su Salva.

    Aggiungere l'autenticazione Google al proxy API

    Devi anche aggiungere l'autenticazione Google all'endpoint di destinazione del proxy API per abilitare le chiamate proxy alla destinazione.

    Per aggiungere il token di accesso Google:

    1. Nella scheda Sviluppa, fai clic su predefinito nella cartella Endpoint di destinazione. La Vista codice mostra la configurazione XML dell'elemento <TargetEndpoint>.
    2. Modifica l'XML per aggiungere la seguente configurazione in <HTTPTargetConnection>: 
      <Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>
    3. Fai clic su Salva.

    Esegui il deployment del proxy API

    Per eseguire il deployment del proxy API:

    1. Fai clic su Esegui il deployment per aprire il riquadro Esegui il deployment del proxy API.
    2. Il campo Revisione deve essere impostato su 1. In caso contrario, fai clic su 1 per selezionarlo.
    3. Nell'elenco Ambiente, seleziona l'ambiente in cui vuoi eseguire il deployment del proxy. L'ambiente deve essere un ambiente completo.
    4. Inserisci l'account di servizio che hai creato in un passaggio precedente.
    5. Fai clic su Esegui il deployment.

    Testa i criteri di memorizzazione nella cache semantica

    Per testare le norme di memorizzazione nella cache semantica:

    1. Invia una richiesta al proxy utilizzando il seguente comando: 
      curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
  "contents": [
      {
          "role": "user",
          "parts": [
              {
                  "text": "Why is the sky blue?"
              }
          ]
      }
  ]
}'

      dove PROXY_NAME è il basepath del proxy API di cui hai eseguito il deployment nel passaggio precedente.

      2. Ripeti la chiamata API sostituendo la stringa del prompt con le seguenti stringhe del prompt semanticamente simili:
      • Perché il cielo è blu?
      • Perché il cielo è blu?
      • Perché il cielo è blu?
      • Puoi spiegarmi perché il cielo è blu?
      • Il cielo è blu, perché?
    2. Confronta il tempo di risposta per ogni chiamata una volta memorizzato nella cache un prompt simile.

    Per verificare che le chiamate vengano pubblicate dalla cache, controlla le intestazioni della risposta. Deve essere allegata un'intestazione Cached-Content: true.

    Best practice

    Ti consigliamo di incorporare le seguenti best practice nel tuo programma di gestione delle API quando utilizzi i criteri di memorizzazione nella cache semantica:

    • Impedisci la memorizzazione nella cache dei dati sensibili con Model Armor.

      Per impedire la memorizzazione nella cache dei dati sensibili, ti consigliamo di utilizzare Model Armor per il filtraggio dei contenuti. Model Armor può contrassegnare le risposte come non memorizzabili nella cache se rileva informazioni sensibili. Per ulteriori informazioni, consulta la panoramica di Model Armor.

    • Gestisci l'aggiornamento dei dati con l'invalidazione dei punti dati di Vertex AI e la durata (TTL).

      Ti consigliamo di implementare strategie di invalidazione dei punti dati appropriate per garantire che le risposte memorizzate nella cache siano aggiornate e riflettano le informazioni più recenti dei tuoi sistemi di backend. Per scoprire di più, consulta Aggiornare e ricompilare un indice attivo.

      Puoi anche modificare il TTL per le risposte memorizzate nella cache in base alla volatilità dei dati e alla frequenza degli aggiornamenti. Per saperne di più sull'utilizzo del TTL nella policy SemanticCachePopulate, consulta <TTLInSeconds>.

    • Utilizza strategie di memorizzazione nella cache predefinite per garantire i dati di risposta più accurati.

      Ti consigliamo di implementare strategie di memorizzazione nella cache predefinite simili alle seguenti:

      • Risposte generiche dell'AI: configura un TTL lungo (ad esempio, un'ora) per le risposte non specifiche per l'utente.
      • Risposte specifiche per l'utente: non implementare la memorizzazione nella cache o impostare un TTL breve (ad esempio cinque minuti) per le risposte che contengono informazioni specifiche per l'utente.
      • Risposte sensibili al fattore tempo: configura un valore TTL breve (ad esempio cinque minuti) per le risposte che richiedono aggiornamenti in tempo reale o frequenti.

    Limitazioni

    Si applicano le seguenti limitazioni alle norme di memorizzazione nella cache semantica:

    • La dimensione massima del testo memorizzabile nella cache è 256 kB. Per ulteriori informazioni, consulta Dimensioni del valore della cache nella pagina Limiti di Apigee.
    • Apigee ignorerà tutte le intestazioni cache-control ricevute dal modello LLM.
    • Se la cache non viene invalidata correttamente o se l'algoritmo di similarità semantica non è sufficientemente accurato per distinguere tra input con significati molto simili, la risposta potrebbe restituire informazioni obsolete o errate.
    • La funzionalità di ricerca vettoriale 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, devi creare endpoint di indice in una regione diversa da quella della tua organizzazione Apigee.
    • Le norme di memorizzazione nella cache semantica non sono supportate per l'utilizzo con proxy API che utilizzano EventFlows per lo streaming continuo delle risposte degli eventi inviati dal server (SSE).
    • La funzione JsonPath all'interno di <UserPromptSource> non supporta la funzionalità ignoreUnresolvedVariables. Per impostazione predefinita, i valori nulli o vuoti vengono ignorati durante l'applicazione del modello di messaggio.