Règle SemanticCacheLookup

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Présentation

La stratégie SemanticCacheLookup est une stratégie de mise en cache avancée conçue pour optimiser les performances des charges de travail d'IA, en particulier celles impliquant des grands modèles de langage (LLM).

La règle utilise l' API Vertex AI d'embeddings de texte pour générer des embeddings pour le texte et Vector Search pour trouver des requêtes similaires en fonction de la similarité sémantique, plutôt que de correspondances exactes.

La règle SemanticCacheLookup peut réduire les temps de réponse des requêtes répétées et optimiser les coûts en réduisant le volume d'appels aux LLM.

Cette règle est utilisée avec la règle SemanticCachePopulate.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Avant de commencer

Avant d'utiliser la règle SemanticCacheLookup, vous devez effectuer les tâches suivantes :

• Créez un projet Vertex AI.
• Créez un index Vector Search.
• Créez un point de terminaison Vertex AI pour l'index.
• Créez une stratégie SemanticCachePopulate.

Pour en savoir plus sur la réalisation de ces tâches, consultez Premiers pas avec les règles de mise en cache sémantique.

Rôles requis

Pour obtenir les autorisations nécessaires pour appliquer et utiliser la règle SemanticCacheLookup, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur de la plate-forme AI (roles/aiplatform.user) sur le compte de service que vous utilisez pour déployer des proxys Apigee. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer les API

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

Enable the APIs

Élément <SemanticCacheLookup>

Définit une règle SemanticCacheLookup.

L'élément <SemanticCacheLookup> utilise la syntaxe suivante :

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

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Le tableau suivant fournit une description détaillée des éléments enfants de <SemanticCacheLookup> :

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

Référence d'élément enfant

Cette section décrit les éléments enfants de <SemanticCacheLookup>.

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

L'élément <DisplayName> utilise la syntaxe suivante :

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

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<IgnoreUnresolvedVariables>

Détermine si le traitement s'arrête lorsqu'une variable n'est pas résolue. Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement.

IgnoreUnresolvedVariables n'est pas applicable lorsque <DefaultValue> est fourni.

<UserPromptSource>

Emplacement de la charge utile pour le texte de l'invite utilisateur à extraire. Seules les valeurs de texte de chaîne sont acceptées.

Ce champ accepte la syntaxe du modèle de message Apigee, y compris l'utilisation de variables ou de fonctions de chemin JSON.

Exemple :

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

<Embeddings>

Cet élément contient les informations requises pour générer des représentations vectorielles continues de texte.

L'élément <Embeddings> utilise la syntaxe suivante :

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

<VertexAI> (enfant de <Embeddings>)

Contient l'élément <URL> pour les attributs spécifiques à Vertex AI.

L'élément VertexAI utilise la syntaxe suivante :

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

<URL> (enfant de <VertexAI>)

URL utilisée pour générer des embeddings textuels. Consultez la section Modèles compatibles pour obtenir la liste des modèles pouvant fournir des représentations vectorielles continues de texte pour la règle SemanticCacheLookup.

L'élément URL utilise la syntaxe suivante :

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

<SimilaritySearch>

Cet élément contient les informations requises pour effectuer des recherches de similarité.

Pour en savoir plus, consultez Interroger un index public pour obtenir les voisins les plus proches.

L'élément <SimilaritySearch> utilise la syntaxe suivante :

<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> (enfant de <SimilaritySearch>)

Contient l'élément <URL> pour les attributs spécifiques à Vertex AI.

L'élément VertexAI utilise la syntaxe suivante :

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

Le tableau suivant fournit une description détaillée des éléments enfants de <VertexAI>.

Variables de flux

Les variables de flux peuvent être utilisées pour configurer le comportement d'exécution dynamique des règles et des flux en fonction des en-têtes HTTP, du contenu des messages ou du contexte disponible dans le flux. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables de flux.

La règle peut définir ces variables en lecture seule lors de l'exécution.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Apigee spécifiques à la règle <SemanticCacheLookup>. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponse d'erreur

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

Exemple de règle de défaillance

<FaultRule name="SemanticCacheLookup Faults">
    <Step>
        <Name>SCL-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

Schémas

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.