Criterio SemanticCachePopulate

Panoramica

Il criterio SemanticCachePopulate è un criterio di memorizzazione nella cache avanzato progettato per ottimizzare le prestazioni dei carichi di lavoro di AI, in particolare quelli che coinvolgono modelli linguistici di grandi dimensioni (LLM).

Il criterio utilizza l'API Text Embeddings di Vertex AI per generare embedding per il testo e la ricerca vettoriale per memorizzare nella cache le risposte API in base alla similarità semantica, anziché alle corrispondenze esatte.

Il criterio SemanticCachePopulate può ridurre i tempi di risposta per le query ripetute e ottimizzare i costi riducendo il volume di chiamate ai LLM.

Questo criterio viene utilizzato insieme al criterio SemanticCacheLookup.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Prima di iniziare

Prima di utilizzare il criterio SemanticCachePopulate, devi completare le seguenti attività:

  • Crea un progetto Vertex AI.
  • Crea un indice Vector Search.
  • Crea un endpoint Vertex AI per l'indice.
  • Crea una policy SemanticCachePopulate.

Per ulteriori informazioni sul completamento di queste attività, consulta la pagina Guida introduttiva alle norme di memorizzazione nella cache semantica.

Ruoli e autorizzazioni

Per ottenere le autorizzazioni necessarie per applicare e utilizzare il criterio SemanticCachePopulate, chiedi all'amministratore di concederti il ruolo IAM Utente AI Platform (roles/aiplatform.user) sul 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.

Abilita API

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

Enable the APIs

Elemento <SemanticCachePopulate>

Definisce una policy SemanticCachePopulate.

Valore predefinito Consulta la scheda Policy predefinita di seguito.
Obbligatorio? Obbligatorio
Tipo Oggetto complesso
Elemento principale N/D
Elementi secondari <DisplayName>
<IgnoreUnresolvedVariables>
<SimilaritySearch>
<TTLInSeconds>

L'elemento <SemanticCachePopulate> utilizza la seguente sintassi:

Sintassi

L'elemento <SemanticCachePopulate> utilizza la seguente sintassi:

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

Norme predefinite

L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio SemanticCachePopulate al proxy API nell'interfaccia utente Apigee:

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

Quando inserisci un nuovo criterio SemanticCachePopulate nell'interfaccia utente Apigee, il modello contiene stub per tutte le operazioni possibili. Di seguito sono riportate informazioni sugli elementi obbligatori.

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo Predefinito Obbligatorio? Descrizione
name N/D Obbligatorio

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError falso Facoltativo Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:
enabled true Facoltativo Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async   falso Ritirato Questo attributo è stato ritirato.

La tabella seguente fornisce una descrizione generale degli elementi secondari di <SemanticCachePopulate>:

Elemento secondario Obbligatorio? Descrizione
<DisplayName> Facoltativo Il nome della policy.
<IgnoreUnresolvedVariables> Facoltativo Determina se l'elaborazione si interrompe quando un insieme di proprietà non viene risolto.
<SimilaritySearch> Obbligatorio Elemento contenente le informazioni necessarie per aggiornare l'indice vettoriale.

Per ulteriori informazioni, vedi Inserisci o aggiorna punti dati.

Il tempo di scadenza per i punti dati è <TTLInSeconds> dal momento dell'inserimento.

<TTLInSeconds> Facoltativo La durata (TTL) delle risposte memorizzate nella cache, in secondi.

Il valore predefinito è 60.

Esempio

Questa sezione fornisce un esempio che utilizza <SemanticCachePopulate>.

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

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <SemanticCachePopulate>.

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito N/D
Obbligatorio? Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo Stringa
Elemento principale <PolicyElement>
Elementi secondari Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<IgnoreUnresolvedVariables>

Determina se l'elaborazione si interrompe quando una variabile non viene risolta. Imposta su true per ignorare le variabili non risolte e continuare l'elaborazione.

IgnoreUnresolvedVariables non è applicabile quando viene fornito <DefaultValue>.

Valore predefinito Falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <SemanticCachePopulate>
Elementi secondari Nessuno

<SimilaritySearch>

Elemento contenente le informazioni necessarie per aggiornare l'indice vettoriale.

Per ulteriori informazioni, vedi Inserisci o aggiorna punti dati.

Il tempo di scadenza per i punti dati è <TTLInSeconds> dal momento dell'inserimento.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Stringa
Elemento principale <SemanticCachePopulate>
Elementi secondari <VertexAI>

L'elemento <SimilaritySearch> utilizza la seguente sintassi:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (elemento secondario di <SimilaritySearch>)

Contiene l'elemento <URL> per gli attributi specifici di Vertex AI.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Stringa
Elemento principale <SimilaritySearch>
Elementi secondari <URL>

L'elemento VertexAI utilizza la seguente sintassi:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (figlio di <VertexAI>)

L'URL utilizzato per eseguire l'upsert dei punti dati nell'indice vettoriale.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Stringa
Elemento principale <VertexAI>
Elementi secondari Nessuno

L'elemento URL utilizza la seguente sintassi:

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

Elemento che specifica la durata (TTL) delle risposte memorizzate nella cache, in secondi. Il valore predefinito è 60.

Per ulteriori informazioni, vedi Aggiornare e ricompilare un indice attivo.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <SemanticCachePopulate>
Elementi secondari Nessuno

Variabili di flusso

Le variabili di flusso possono essere utilizzate per configurare il comportamento di runtime dinamico per criteri e flussi, in base alle intestazioni HTTP o ai contenuti dei messaggi oppure al contesto disponibile nel flusso. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento alle variabili di flusso.

Il criterio può impostare queste variabili di sola lettura durante l'esecuzione.

Nome variabile Descrizione
response.content Contiene l'intero contenuto della risposta API.
semanticcache.populate.policy_name.upsert_index_request Contiene il payload della richiesta inviato all'API Vertex AI Vector Search per aggiornare l'indice vettoriale con nuovi incorporamenti e metadati.
semanticcache.populate.policy_name.upsert_index_response Contiene la risposta dell'API Vertex AI Vector Search, che indica l'esito positivo o negativo dell'operazione di aggiornamento dell'indice.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee specifiche per il criterio <SemanticCachePopulate>. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per saperne di più, consulta Informazioni sugli errori relativi alle norme e Gestione dei guasti.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione della policy.

Codice di errore Stato HTTP Causa
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable 400

Questo errore si verifica se l'API Vector Search Upsert Datapoints non è disponibile.
steps.semanticcache.populate.VectorSearchUpsertAPIFailed 500

Questo errore si verifica se il servizio API Vector Search Upsert Datapoints non va a buon fine.
steps.semanticcache.populate.AuthenticationFailure 500

Questo errore si verifica se il account di servizio non dispone delle autorizzazioni richieste.
steps.semanticcache.populate.CalloutError 500 La chiamata al servizio Vertex AI non è andata a buon fine.
steps.semanticcache.populate.InternalError 500

Questo errore si verifica in caso di errore imprevisto all'interno delle norme <SemanticCachePopulate>.

Errori di deployment

Questi errori possono verificarsi quando implementi un proxy contenente questo criterio.

Nome dell'errore Causa
The SimilaritySearch URL {url} is invalid. Si verifica se l'elemento <URL> in <SimilaritySearch> è vuoto o non valido.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. Si verifica se lo schema http dell'elemento<URL> di SimilaritySearch non è valido.
The TTLInSeconds element must be >= 0. Se il valore è impostato su zero o su un numero negativo, il deployment del proxy API non va a buon fine.

Variabili di errore

Queste variabili vengono impostate quando questa norma genera un errore in fase di runtime. Per ulteriori informazioni, consulta Cosa devi sapere sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="FAULT_NAME" FAULT_NAME è il nome dell'errore, come elencato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di guasto. fault.name Matches "UnresolvedVariable"
semanticcachepopulate.POLICY_NAME.failed POLICY_NAME è il nome specificato dall'utente del criterio che ha generato l'errore. semanticcachepopulate.SC-populate.failed = true

Esempio di risposta di errore

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.UnresolvedVariable"
  }
}
}

Regola di errore di esempio

<FaultRule name="SemanticCacheLookup Faults">
  <Step>
      <Name>SCL-CustomSetVariableErrorResponse</Name>
      <Condition>(fault.name = "SetVariableFailed")</Condition>
  </Step>
  <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

Schemi

Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.