Questa pagina si applica ad Apigee e ad Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
La policy SemanticCachePopulate è una policy di memorizzazione nella cache avanzata progettata per ottimizzare le prestazioni dei workload di AI, in particolare quelli che coinvolgono i modelli linguistici di grandi dimensioni (LLM).
La policy 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.
La policy SemanticCachePopulate può ridurre i tempi di risposta per le query ripetute e ottimizzare i costi riducendo il volume delle chiamate agli LLM.
Questa policy funziona in combinazione con la policy SemanticCacheLookup.
Questa policy è una policy estensibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.
Prima di iniziare
Prima di utilizzare il criterio SemanticCachePopulate, completa 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 saperne di più sul completamento di queste attività, consulta Inizia a utilizzare le policy di memorizzazione nella cache semantica.
Ruoli e autorizzazioni
Per ottenere le autorizzazioni necessarie per applicare e utilizzare la policy SemanticCachePopulate, chiedi all'amministratore di concederti il ruolo IAM AI Platform User (roles/aiplatform.user) sul 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
Abilita le API Compute Engine, Vertex AI e Cloud Storage, se non sono già abilitate.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.
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>Policy predefinita
Il seguente esempio mostra le impostazioni predefinite quando aggiungi una policy 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 una nuova policy SemanticCachePopulate nell'interfaccia utente di Apigee, il modello contiene stub per tutte le possibili operazioni. Consulta di seguito 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 <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 saperne di più, consulta Applica l'upsert ai 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 è |
Esempio
Questa sezione fornisce un esempio di 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 dell'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 maggiori informazioni, vedi Inserisci/aggiorna punti dati.
La data di scadenza dei punti dati è <TTLInSeconds> dalla data di 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> (elemento secondario 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>L'elemento URL supporta l'utilizzo di modelli di URL. Se vuoi, fornisci una variabile in questo elemento
per contenere il valore dell'URL, come mostrato nell'esempio seguente:
<URL>https://{URL_VARIABLE}</URL><TTLInSeconds>
Elemento che specifica la durata (TTL) delle risposte memorizzate nella cache, in secondi. Il valore predefinito è 60.
Per saperne di più, consulta Aggiorna e ricrea un indice attivo.
| Valore predefinito | N/D |
| Obbligatorio? | Facoltativo |
| Tipo | Stringa |
| Elemento principale |
<SemanticCachePopulate>
|
| Elementi secondari |
Nessuno |
Variabili di flusso
Le variabili di flusso configurano il comportamento dinamico di runtime per policy e flussi, in base alle intestazioni HTTP o ai contenuti dei messaggi oppure al contesto disponibile nel flusso. Per saperne di più sulle variabili di flusso, consulta Riferimento alle variabili di flusso.
Questa policy fornisce il seguente insieme di variabili di flusso di sola lettura durante l'esecuzione. Puoi utilizzare queste variabili di flusso con la policy DataCapture per creare report di analisi personalizzati. Per saperne di più, consulta Raccolta dei dati dei clienti con la policy di acquisizione dei dati.
| Nome variabile | Descrizione |
|---|---|
response.content |
Contiene i contenuti completi della risposta dell'API. |
SemanticCachePopulate.policy_name.upsert_index_request |
Contiene il payload della richiesta inviato all'API Vertex AI Vector Search per aggiornare l'indice vettoriale con nuovi embedding e metadati. |
SemanticCachePopulate.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 la policy <SemanticCachePopulate>.
Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per saperne di più, consulta Cosa devi sapere
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 è riuscita. |
steps.semanticcache.populate.InternalError |
500 |
Questo errore si verifica in caso di errore imprevisto all'interno delle norme |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questa policy.
| Nome dell'errore | Causa |
|---|---|
The SimilaritySearch/VertexAI/PrivateServiceConnect element is not supported in SemanticCachePopulate. |
Si verifica se l'elemento <PrivateServiceConnect> viene utilizzato in <SemanticCachePopulate>. |
The SimilaritySearch/VertexAI/URL element is required. |
Si verifica se l'elemento <URL> in <SimilaritySearch> è vuoto. |
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 SimilaritySearch<URL> 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 policy genera un errore in fase di runtime. Per saperne di più, consulta Informazioni 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 dell'errore è l'ultima parte del codice di errore. | fault.name Matches "UnresolvedVariable" |
semanticcachepopulate.POLICY_NAME.failed |
POLICY_NAME è il nome specificato dall'utente della policy 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" } } }
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 policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.