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 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 trovare prompt simili in base alla somiglianza semantica, anziché alle corrispondenze esatte.
Il criterio SemanticCacheLookup 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 SemanticCachePopulate.
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 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 un criterio SemanticCachePopulate.
Per ulteriori informazioni su come completare queste attività, consulta la guida introduttiva ai criteri 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 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.
Elemento <SemanticCacheLookup>
Definisce un criterio SemanticCacheLookup.
Valore predefinito | Consulta la scheda Criteri predefiniti di seguito |
Obbligatorio? | Obbligatorio |
Tipo | Oggetto complesso |
Elemento principale | N/D |
Elementi secondari |
<DisplayName> <IgnoreUnresolvedVariables> <UserPromptSource> <Embeddings> <SimilaritySearch> |
La sintassi dell'elemento <SemanticCacheLookup>
è la seguente:
Sintassi
La sintassi dell'elemento <SemanticCacheLookup>
è la seguente:
<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>
Criterio predefinito
L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio SemanticCacheLookup al flusso nell'interfaccia utente di 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 le 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 Se vuoi, utilizza l'elemento |
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 <SemanticCacheLookup>
:
Elemento secondario | Obbligatorio? | Descrizione |
---|---|---|
<DisplayName> |
Facoltativo | Il nome del criterio. |
<IgnoreUnresolvedVariables> |
Facoltativo | Determina se l'elaborazione si interrompe quando una variabile non è risolta.
Imposta su true per ignorare le variabili non risolte e continuare l'elaborazione.
|
<UserPromptSource> |
Facoltativo | La posizione del payload per il testo della richiesta all'utente da estrarre. 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 di percorso JSON. Ad esempio: {jsonPath($.contents[-1].parts[-1].text,request.content,true)} |
<Embeddings> |
Obbligatorio | Elemento contenente le informazioni necessarie per generare gli embedding. |
<SimilaritySearch> |
Obbligatorio | Elemento contenente le informazioni necessarie per eseguire ricerche di somiglianza.
Per ulteriori informazioni, consulta Eseguire query sull'indice pubblico per ottenere i vicini 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 è risolta. Imposta su
true
per ignorare le variabili non risolte e continuare l'elaborazione.
IgnoreUnresolvedVariables
non è applicabile se viene fornito <DefaultValue>
.
Valore predefinito | Falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale |
<SemanticCacheLookup>
|
Elementi secondari | Nessuno |
<UserPromptSource>
La posizione del payload per il testo della richiesta all'utente da estrarre. 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 di 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 gli embedding di testo.
Valore predefinito | N/D |
Obbligatorio? | Facoltativo |
Tipo | Stringa |
Elemento principale |
<SemanticCacheLookup>
|
Elementi secondari |
<VertexAI>
|
La sintassi dell'elemento <Embeddings>
è la seguente:
<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> |
La sintassi dell'elemento VertexAI
è la seguente:
<VertexAI> <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL> </VertexAI>
<URL> (elemento secondario di <VertexAI>
)
L'URL utilizzato per generare gli incorporamenti di testo. Consulta 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 |
La sintassi dell'elemento URL
è la seguente:
<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 di somiglianza.
Per ulteriori informazioni, consulta Eseguire query sull'indice pubblico per ottenere i vicini più vicini.
Valore predefinito | N/D |
Obbligatorio? | Obbligatorio |
Tipo | Stringa |
Elemento principale |
<SemanticCacheLookup>
|
Elementi secondari |
<VertexAI> |
La sintassi dell'elemento <SimilaritySearch>
è la seguente:
<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> |
La sintassi dell'elemento VertexAI
è la seguente:
<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 |
---|---|---|
<URL> |
Obbligatorio | Stringa L'URL utilizzato per eseguire ricerche di somiglianza. Il punto dati con la corrispondenza più alta, in base alla soglia di somiglianza, sarà l'unico punto dati utilizzato. |
<Threshold> |
Facoltativo | Stringa Punteggio di somiglianza 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 nell'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 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.
Nome variabile | Descrizione |
---|---|
request.content |
Contiene i contenuti completi della richiesta API in arrivo. |
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 vengono utilizzati per generare embedding o eseguire ricerche di somiglianza. |
semanticcache.lookup.policy_name.embeddings_request |
Contiene il payload della richiesta inviato all'API Vertex AI Embedding per generare embedding di testo per il testo inserito. |
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 degli 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 specificata 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 gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
Codice guasto | Stato HTTP | Causa |
---|---|---|
steps.semanticcache.lookup.MessageTemplateExtractionFailed |
400 |
Impossibile estrarre i dati dalla richiesta utilizzando l'espressione del percorso JSON. |
steps.semanticcache.lookup.FailedToExtractUserPrompt |
500 |
Impossibile estrarre la richiesta dell'utente dalla richiesta dell'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 |
L'account di servizio non dispone delle autorizzazioni richieste. |
steps.semanticcache.lookup.InternalError |
500 |
Si è verificato un errore imprevisto nel criterio SemanticCacheLookup. |
steps.semanticcache.lookup.CalloutError |
500 |
La chiamata al servizio Vertex AI non è riuscita. |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di 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 SimilaritySearch<URL> 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 questo criterio attiva un errore in fase di esecuzione. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="FAULT_NAME" |
FAULT_NAME è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. | 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
{ "fault": { "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]", "detail": { "errorcode": "steps.semanticcachelookup.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.