Inizia a utilizzare le norme di memorizzazione nella cache semantica

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come configurare e utilizzare i criteri di memorizzazione nella cache semantica di Apigee per consentire il riutilizzo intelligente delle risposte in base alla somiglianza semantica. L'utilizzo di queste norme nel proxy API Apigee riduce al minimo le chiamate API di backend ridondanti, la latenza e i costi operativi.

Prima di iniziare

Prima di iniziare, completa 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.

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

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 (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.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    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 policy 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 dell'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 aiutano gli utenti di 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.

    Le norme SemanticCacheLookup e SemanticCachePopulate vengono associate 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. Una ricerca di similarità 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 somiglianze non restituisce un prompt precedente simile, il modello LLM genera contenuti in risposta al prompt dell'utente e popola la cache di Apigee 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 per creare e configurare le norme 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 attivare la memorizzazione nella cache semantica.
    4. Configura le policy 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"

      Sostituisci SERVICE_ACCOUNT_NAME con il nome del account di servizio creato nel passaggio precedente.

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

      Sostituisci SERVICE_ACCOUNT_NAME con 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 ulteriori informazioni 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, crea un nuovo proxy API utilizzando il modello Proxy con cache semantica, se non l'hai già fatto.

    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 semantica nella cache:

    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.
      • Descrizione: (facoltativo) inserisci una descrizione del proxy.
      • Destinazione (API esistente): inserisci l'URL del servizio di backend chiamato dal proxy. Questo è l'endpoint del modello LLM che genera contenuti.

        Per questo tutorial, imposta Destinazione (API esistente) 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, imposta questo URL sul seguente valore: 

        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, imposta questo URL sul seguente valore: 

        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, utilizza 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, imposta questo URL sul seguente valore: 

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

    Visualizza la configurazione XML di ogni policy facendo clic sul nome della policy nella visualizzazione Dettagli della scheda Sviluppo del proxy API. Modifica il file XML delle norme direttamente nella Vista codice della scheda Sviluppo.

    Modifica le policy:

    • Norma SemanticCacheLookup:
      • Rimuovi l'elemento <UserPromptSource> per utilizzare il valore predefinito.
      • Aggiorna l'elemento <DeployedIndexId> in modo che utilizzi 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 ignora 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 il service account che hai creato in un passaggio precedente.
    5. Fai clic su Esegui il deployment.

    Testa i criteri di memorizzazione nella cache semantica

    Per testare i criteri 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?"
              }
          ]
      }
  ]
}'

      Sostituisci PROXY_NAME con il basepath del proxy API che 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. Viene 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ù, vedi 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 di 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 tempo: configura un TTL breve (ad esempio, cinque minuti) per le risposte che richiedono aggiornamenti frequenti o in tempo reale.

    Aumentare le quote per i servizi dipendenti

    Se riscontri colli di bottiglia delle prestazioni derivanti da un numero maggiore di query al secondo (QPS), potrebbe essere necessario aumentare le seguenti quote per i servizi dipendenti nel tuo progetto Google Cloud :

    • Richieste di previsione online al minuto per regione (seleziona per regione)
    • Richieste di previsione online regionali per modello di base al minuto per regione (seleziona per regione e modello textembedding-gecko)
    • Richieste di aggiornamento dello stream di Matching Engine al minuto per regione (seleziona per regione)

    Per aumentare una quota per uno di questi servizi:

    1. Vai alla pagina Quote e limiti di sistema:

      Vai a Quote e limiti di sistema

    2. Nella barra dei filtri, inserisci il nome della quota specifica che vuoi aumentare, insieme al nome della regione e del modello, se pertinente.

      Ad esempio, filtra per Richieste di previsione online regionali per modello di base al minuto per regione e textembedding-gecko e us-west1.

    3. Fai clic sul menu per il servizio che vuoi aumentare e poi seleziona Modifica quota.
    4. Inserisci un nuovo valore più alto per la quota.
    5. Fai clic su Fine.
    6. Fai clic su Invia richiesta.

    Dopo aver inviato la richiesta, la quota viene aumentata. Puoi monitorare lo stato nella pagina Quote e limiti di sistema utilizzando la scheda Richieste di aumento.

    Limitazioni

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

    • 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 ignora tutte le intestazioni cache-control che riceve 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).
    • I criteri di memorizzazione nella cache semantica utilizzano le API LLM, il che può comportare latenze più elevate nell'ordine di centinaia di millisecondi.