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

Enable the APIs

Elemento <SemanticCacheLookup>

Definisce un criterio SemanticCacheLookup.

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>

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

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

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

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

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <SemanticCacheLookup>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

The <DisplayName> element uses the following syntax:

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

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

The <DisplayName> element has no attributes or child elements.

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

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

<Embeddings>

Questo elemento contiene le informazioni necessarie per generare gli embedding di testo.

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.

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.

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.

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.

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

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

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