Questa pagina è stata tradotta dall'API Cloud Translation.

Norme di SemanticCacheLookup

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

Il criterio SemanticCacheLookup è 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 incorporamenti per il testo e Vector Search per trovare prompt simili in base alla somiglianza semantica, anziché a corrispondenze esatte.

Il criterio SemanticCacheLookup 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 SemanticCachePopulate.

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 la policy SemanticCacheLookup, 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 obbligatori

Per ottenere le autorizzazioni necessarie per applicare e utilizzare il criterio SemanticCacheLookup, 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 `<SemanticCacheLookup>`

Definisce una policy SemanticCacheLookup.

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

L'elemento <SemanticCacheLookup> utilizza la seguente sintassi:

Sintassi

L'elemento <SemanticCacheLookup> utilizza la seguente sintassi:

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Norme predefinite

L'esempio seguente mostra le impostazioni predefinite quando aggiungi una norma SemanticCacheLookup al flusso nell'interfaccia utente Apigee:

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Quando inserisci un nuovo criterio SemanticCacheLookup nell'interfaccia utente di 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: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
`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 <SemanticCacheLookup>:

Elemento secondario	Obbligatorio?	Descrizione
`<DisplayName>`	Facoltativo	Il nome della policy.
`<IgnoreUnresolvedVariables>`	Facoltativo	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.
`<UserPromptSource>`	Facoltativo	La posizione del payload per l'estrazione del testo del prompt dell'utente. Sono supportati solo i valori di testo stringa. Questo campo supporta la sintassi dei modelli di messaggi Apigee, incluso l'utilizzo di variabili o funzioni JSON Path. Ad esempio: {jsonPath($.contents[-1].parts[-1].text,request.content,true)}
`<Embeddings>`	Obbligatorio	Elemento contenente le informazioni necessarie per generare gli incorporamenti.
`<SimilaritySearch>`	Obbligatorio	Elemento contenente le informazioni necessarie per eseguire ricerche per similarità. Per maggiori informazioni, consulta Eseguire query sull'indice pubblico per ottenere i punti più vicini.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <SemanticCacheLookup>.

`<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	`<SemanticCacheLookup>`
Elementi secondari	Nessuno

`<UserPromptSource>`

La posizione del payload per l'estrazione del testo del prompt dell'utente. Sono supportati solo i valori di testo stringa.

Questo campo supporta la sintassi del modello di messaggio Apigee, incluso l'utilizzo di variabili o funzioni del percorso JSON.

Ad esempio:

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

Valore predefinito	{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	`<SemanticCacheLookup>`
Elementi secondari	Nessuno

`<Embeddings>`

Questo elemento contiene le informazioni necessarie per generare incorporamenti di testo.

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

L'elemento <Embeddings> utilizza la seguente sintassi:

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

<VertexAI> (elemento secondario di `<Embeddings>`)

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

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

L'elemento VertexAI utilizza la seguente sintassi:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

<URL> (figlio di `<VertexAI>`)

L'URL utilizzato per generare gli incorporamenti di testo. Consulta la sezione Modelli supportati per un elenco dei modelli che possono fornire incorporamenti di testo per il criterio SemanticCacheLookup.

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}/publishers/google/models/{MODEL_ID}:predict</URL>

`<SimilaritySearch>`

Questo elemento contiene le informazioni necessarie per eseguire ricerche per similarità.

Per maggiori informazioni, consulta Eseguire query sull'indice pubblico per ottenere i punti più vicini.

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

L'elemento <SimilaritySearch> utilizza la seguente sintassi:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </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://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <VertexAI>.

Elemento secondario Obbligatorio? Descrizione

Elemento secondario	Obbligatorio?	Descrizione
`<URL>`	Obbligatorio	Stringa L'URL utilizzato per eseguire ricerche per similarità. Verrà utilizzato solo il punto dati corrispondente più alto, in base alla soglia di somiglianza.
`<Threshold>`	Facoltativo	Stringa Punteggio di similarità utilizzato per determinare se due prompt sono considerati una corrispondenza. Un valore compreso tra 0 e 1. Il valore predefinito è 0,9.
`<DeployedIndexID>`	Obbligatorio	Stringa L'ID dell'indice di cui è stato eseguito il deployment sull'endpoint dell'indice utilizzato per la memorizzazione nella cache semantica.

<URL>

Obbligatorio

Stringa

L'URL utilizzato per eseguire ricerche per similarità. Verrà utilizzato solo il punto dati corrispondente più alto, in base alla soglia di somiglianza.

<Threshold>

Facoltativo

Stringa

Punteggio di similarità utilizzato per determinare se due prompt sono considerati una corrispondenza. Un valore compreso tra 0 e 1.

Il valore predefinito è 0,9.

<DeployedIndexID>

Obbligatorio

Stringa

L'ID dell'indice di cui è stato eseguito il deployment sull'endpoint dell'indice utilizzato per la memorizzazione nella cache semantica.

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
`request.content`	Contiene i contenuti completi della richiesta API in entrata.
`request.url`	Contiene l'URL della richiesta API in entrata.
`semanticcache.lookup.policy_name.user_prompt`	Contiene componenti specifici estratti dal prompt della richiesta, che viene utilizzato per generare embedding o eseguire ricerche di similarità.
`semanticcache.lookup.policy_name.embeddings_request`	Contiene il payload della richiesta inviato all'API Vertex AI Embeddings per generare gli embedding di testo per il testo di input.
`semanticcache.lookup.policy_name.embeddings_response`	Contiene la risposta dell'API Vertex AI Embeddings, che include gli embedding di testo generati.
`semanticcache.lookup.policy_name.dense_embeddings`	Contiene i valori numerici effettivi dell'embedding generati dall'API Vertex AI Embeddings.
`semanticcache.lookup.policy_name.is_nearest_neighbor_hit`	Specifica se è stato trovato un vicino più prossimo nel database vettoriale per la richiesta e se il punto dati soddisfa la soglia di somiglianza.
`semanticcache.lookup.policy_name.cache_hit`	Specifica se la risposta è stata trovata nella cache semantica.
`semanticcache.lookup.policy_name.cached_llm_response`	Contiene la risposta recuperata dalla cache semantica (se si è verificato un successo della cache).

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 <SemanticCacheLookup>. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire i guasti. Per scoprire 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.semanticcache.lookup.MessageTemplateExtractionFailed`	`400`	Impossibile estrarre i dati dalla richiesta utilizzando l'espressione JSON Path.
`steps.semanticcache.lookup.FailedToExtractUserPrompt`	`500`	Impossibile estrarre il prompt utente dalla richiesta API.
`steps.semanticcache.lookup.EmbeddingsServiceUnavailable`	`400`	Il servizio Vertex AI Embeddings non è al momento disponibile.
`steps.semanticcache.lookup.EmbeddingsAPIFailed`	`400`	Il servizio Vertex AI Embeddings non è riuscito.
`steps.semanticcache.lookup.VectorSearchServiceUnavailable`	`400`	Il servizio Vertex AI Vector Search non è attualmente disponibile.
`steps.semanticcache.lookup.VectorSearchAPIFailed`	`400`	Il servizio Vertex AI Vector Search non è riuscito.
`steps.semanticcache.lookup.AuthenticationFailure`	`500`	Il account di servizio non dispone delle autorizzazioni richieste.
`steps.semanticcache.lookup.InternalError`	`500`	Si è verificato un errore imprevisto all'interno del criterio SemanticCacheLookup.
`steps.semanticcache.lookup.CalloutError`	`500`	La chiamata al servizio Vertex AI non è andata a buon fine.

Errori di deployment

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

Nome dell'errore	Causa
`The Embeddings/VertexAI element is required.`	Si verifica se l'elemento <VertexAI> in <Embeddings> è vuoto.
`The SimilaritySearch/VertexAI element is required.`	Si verifica se l'elemento <VertexAI> in <SimilaritySearch> è vuoto.
`The Embeddings/URL element is required.`	Si verifica se l'elemento <URL> in <Embeddings> è vuoto.
`The SimilaritySearch/URL element is required.`	Si verifica se l'elemento <URL> in <SimilaritySearch> è vuoto.
`Embeddings URL {url} is invalid.`	Si verifica se l'elemento <URL> in <Embeddings> è vuoto o non valido.
`The SimilaritySearch URL {url} is invalid.`	Si verifica se l'elemento <URL> in <SimilaritySearch> è vuoto o non valido.
`The scheme {http-scheme} of Embeddings URL {url} must be one of http, https.`	Si verifica se lo schema `http` dell'elemento Embeddings<URL> 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.
`SimilaritySearch/Threshold element must be >= 0 and <= 1.`	Se l'attributo non è compreso tra 0 e 1, il deployment del proxy API non va a buon fine.
`SimilaritySearch/DeployedIndexID element is required.`	Si verifica se l'elemento <DeployedIndexID> in <SimilaritySearch> è vuoto.
`SimilaritySearch/DeployedIndexID element must not contain spaces.`	Si verifica se l'elemento <DeployedIndexID> in <SimilaritySearch> contiene spazi.

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"`
`semanticcachelookup.POLICY_NAME.failed`	`POLICY_NAME` è il nome specificato dall'utente del criterio che ha generato l'errore.	`semanticcachelookup.SC-lookup.failed = true`

Esempio di risposta di errore

Nota:per la gestione degli errori, la best practice consiste nell'intercettare la parte errorcode della risposta di errore. Non fare affidamento sul testo faultstring, perché potrebbe cambiare.

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.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.

Norme di SemanticCacheLookup Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Panoramica

Prima di iniziare

Ruoli obbligatori

Abilita API

Elemento <SemanticCacheLookup>

Sintassi

Norme predefinite

Riferimento all'elemento secondario

<DisplayName>

Sintassi

Esempio

<IgnoreUnresolvedVariables>

<UserPromptSource>

<Embeddings>

<VertexAI> (elemento secondario di <Embeddings>)

<URL> (figlio di <VertexAI>)

<SimilaritySearch>

<VertexAI> (elemento secondario di <SimilaritySearch>)

Variabili di flusso

Messaggi di errore

Errori di runtime

Errori di deployment

Variabili di errore

Esempio di risposta di errore

Regola di errore di esempio

Schemi

Norme di SemanticCacheLookup

Elemento `<SemanticCacheLookup>`

`<DisplayName>`

`<UserPromptSource>`

`<Embeddings>`

<VertexAI> (elemento secondario di `<Embeddings>`)

<URL> (figlio di `<VertexAI>`)

`<SimilaritySearch>`

<VertexAI> (elemento secondario di `<SimilaritySearch>`)