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 i modelli linguistici di grandi dimensioni (LLM).

Il criterio utilizza l'API Text Embeddings di Vertex AI per generare embedding per il testo e Vector Search per memorizzare nella cache le risposte dell'API in base alla somiglianza 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 agli LLM.

Questo criterio viene utilizzato in combinazione con il criterio SemanticCacheLookup.

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'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 un criterio SemanticCachePopulate.

Per ulteriori informazioni su come completare queste attività, consulta la guida introduttiva ai criteri 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 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.

Abilita API

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

Enable the APIs

Elemento <SemanticCachePopulate>

Definisce un criterio SemanticCachePopulate.

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

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

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

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

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

Esempio

Questa sezione fornisce un esempio con l'utilizzo di <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.

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

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

<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 è risolta. Imposta su true per ignorare le variabili non risolte e continuare l'elaborazione.

IgnoreUnresolvedVariables non è applicabile se viene fornito <DefaultValue>.

<SimilaritySearch>

Elemento contenente le informazioni necessarie per aggiornare l'indice del vettore.

Per ulteriori informazioni, vedi Eseguire l'upsert dei punti dati.

La data e l'ora di scadenza per i punti dati è <TTLInSeconds> dal momento dell'inserimento.

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

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

La sintassi dell'elemento VertexAI è la seguente:

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

<URL> (elemento secondario di <VertexAI>)

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

La sintassi dell'elemento URL è la seguente:

<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, consulta Aggiornare e ricreare un indice attivo.

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 o al contesto disponibile nel flusso. Per ulteriori informazioni sulle variabili di flusso, consulta la sezione Riferimento alle variabili di flusso.

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

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 scoprire di più, consulta Informazioni importanti sugli errori delle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore in fase di esecuzione. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Esempio di risposta di errore

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

Esempio di regola di errore

<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 norma è definito da uno schema XML (.xsd). Come riferimento, gli schemi delle norme sono disponibili su GitHub.