Questa pagina è stata tradotta dall'API Cloud Translation.

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 i criteri 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à:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Go to project selector

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

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

Enable the APIs

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

Go to project selector

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

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

Enable the APIs

Configura l' API Text embeddings e Vector Search di Vertex AI nel tuo Google Cloud progetto.
Verifica di avere un ambiente completo disponibile nell'istanza Apigee. I criteri di memorizzazione nella cache semantica possono essere implementati solo negli ambienti Completi.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e utilizzare i criteri di memorizzazione nella cache semantica, chiedi all'amministratore di concederti il ruolo IAM Utente piattaforma AI (roles/aiplatform.user) nell'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 Google Cloud progetto 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 l'istanza Apigee.
REGION è la Google Cloud regione della tua istanza Apigee.
RUNTIME_HOSTNAME è il nome host del runtime Apigee.

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

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Imposta il progetto

Imposta il Google Cloud progetto nell'ambiente di sviluppo:

    gcloud auth login
    gcloud config set project $PROJECT_ID

Panoramica

Le norme di memorizzazione nella cache semantica sono progettate per aiutare gli utenti di Apigee con modelli LLM a pubblicare in modo intelligente prompt identici o semanticamente simili, riducendo al minimo le chiamate API di backend e il consumo di risorse.

I criteri SemanticCacheLookup e SemanticCachePopulate sono associati rispettivamente ai flussi di richiesta e risposta di un proxy API Apigee. Quando il proxy riceve una richiesta, il criterio SemanticCacheLookup estrae la richiesta dell'utente dalla richiesta e la converte in una rappresentazione numerica utilizzando l'API Text embeddings. Viene eseguita una ricerca di somiglianza semantica utilizzando la ricerca vettoriale 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 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 per le richieste future.

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

Configura un account di servizio per l'indice Vector Search.
Crea ed esegui il deployment di un indice Vector Search.
Crea un proxy API per abilitare la memorizzazione nella cache semantica.
Configura i criteri di memorizzazione nella cache semantica.
Esegui il test dei 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 di ricerca vettoriale, completa i seguenti passaggi:

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 dell'account di servizio.
DESCRIPTION è una descrizione dell'account di servizio.
SERVICE_ACCOUNT_DISPLAY_NAME è il nome visualizzato dell'account di servizio.

Ad esempio:

gcloud iam service-accounts create ai-client \
  --description="semantic cache client" \
  --display-name="ai-client"

Concedi all'account di servizio il ruolo AI Platform User utilizzando il seguente 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 dell'account di servizio creato nel passaggio precedente.

Assegna il ruolo IAM Service Account User all'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"

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

Crea ed esegui il deployment di un indice Vector Search

Per creare ed eseguire il deployment di un indice Vector Search:

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 di questa 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, consulta Creare un indice.

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 ulteriori informazioni sulla creazione di un IndexEndpoint, vedi Creare un IndexEndpoint.

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

Nota: il comando per eseguire il deployment dell'indice nell'endpoint richiede jq. Se questa utilità di elaborazione JSON non è già installata nel tuo ambiente di sviluppo, puoi installarla utilizzando il seguente comando: $ sudo apt install jq.

Il deployment iniziale di un indice in un endpoint può richiedere da 20 a 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, dovrai creare 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:

Vai alla pagina Proxy API nella Google Cloud console.
Vai ai proxy API
Fai clic su + Crea per aprire il riquadro Crea proxy API.
Nella casella Modello proxy, seleziona Proxy con cache semantica.
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, Destinazione (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
```
Inserisci i seguenti URL della cache semantica:
Nota: questi URL possono essere aggiunti alla configurazione XML anche nell'editor proxy nella scheda Sviluppa.
- 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 quanto segue:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
```
- Query Nearest Neighbor URL: questo servizio Vertex AI cerca input di testo simili nelle richieste precedenti nell'indice di ricerca vettoriale per evitare la rielaborazione.
  Per questo tutorial, l'URL può essere impostato su quanto segue:
```
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 indice upsert: questo servizio Vertex AI aggiorna l'indice con voci nuove o modificate.
  Per questo tutorial, l'URL può essere impostato su quanto segue:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
Fai clic su Avanti.
Fai clic su Crea.

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

Configura i criteri di memorizzazione nella cache semantica

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

Modifica i criteri:

Criterio 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 <Threshold> di somiglianza semantica per determinare quando due prompt sono considerati una corrispondenza. Il valore predefinito è 0,9, ma puoi modificarlo in base alla sensibilità della tua applicazione. Più il numero è elevato, più i prompt devono essere correlati per essere considerati una successo della cache. Per questo tutorial, 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 è 60s. Tieni presente che Apigee ignora le intestazioni cache-control ricevute dal modello LLM.
- Fai clic su Salva.

Aggiungere l'autenticazione Google al proxy API

Per abilitare le chiamate proxy al target, devi anche aggiungere l'autenticazione Google all'endpoint target del proxy API.

Per aggiungere il token di accesso Google:

Nella scheda Sviluppa, fai clic su predefinito nella cartella Endpoint target. La Visualizzazione codice mostra la configurazione XML dell'elemento <TargetEndpoint>.

Modifica il file XML per aggiungere la seguente configurazione in <HTTPTargetConnection>:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Fai clic su Salva.

Esegui il deployment del proxy API

Per eseguire il deployment del proxy API:

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

Testa i criteri di memorizzazione nella cache semantica

Per testare i criteri di memorizzazione nella cache semantica:

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 percorso base del proxy API di cui hai eseguito il deployment nel passaggio precedente.

Perché il cielo è blu?
Perché il cielo è blu?
Perché il cielo è blu?
Puoi spiegare perché il cielo è blu?
Perché il cielo è blu?

Confronta il tempo di risposta per ogni chiamata dopo aver memorizzato nella cache un prompt simile.

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

Best practice

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

Evita la memorizzazione nella cache di dati sensibili con Model Armor.
Per impedire la memorizzazione nella cache di dati sensibili, ti consigliamo di utilizzare Model Armor per il filtro dei contenuti. Model Armor può segnalare 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 e il tempo di vita (TTL) di Vertex AI.
Ti consigliamo di implementare strategie di convalida dei punti dati appropriate per assicurarti 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 ricostruire un indice attivo.

Puoi anche modificare il TTL per le risposte memorizzate nella cache in base alla volatilità e alla frequenza degli aggiornamenti dei dati. Per ulteriori informazioni 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'IA: configura un TTL lungo (ad esempio un'ora) per le risposte non specifiche per 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 urgenti: configura un TTL breve (ad esempio cinque minuti) per le risposte che richiedono aggiornamenti in tempo reale o frequenti.

Limitazioni

Ai criteri di memorizzazione nella cache semantica si applicano le seguenti limitazioni:

La dimensione massima del testo memorizzabile nella cache è 256 KB. Per ulteriori informazioni, consulta la sezione Dimensioni del valore della cache nella pagina Limiti di Apigee.
Apigee ignorerà 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 per distinguere tra input con significati molto simili, la risposta potrebbe restituire informazioni obsolete o errate.
La funzionalità 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, dovrai creare endpoint dell'indice in una regione diversa da quella della tua organizzazione Apigee.
I criteri di memorizzazione nella cache semantica non sono supportati per l'utilizzo con i proxy API che utilizzano EventFlow 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 null o vuoti vengono ignorati durante l'applicazione del modello di messaggio.

Passaggi successivi

Scopri come iniziare a utilizzare i criteri di Model Armor.