Règle SemanticCachePopulate

Présentation

La stratégie SemanticCachePopulate 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 stratégie utilise l'API d'embeddings textuels Vertex AI pour générer des embeddings pour le texte et la recherche vectorielle pour mettre en cache les réponses de l'API en fonction de la similarité sémantique, plutôt que des correspondances exactes.

La règle SemanticCachePopulate 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 SemanticCacheLookup.

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 stratégie SemanticCachePopulate, 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 et autorisations

Pour obtenir les autorisations nécessaires pour appliquer et utiliser la règle SemanticCachePopulate, 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 <SemanticCachePopulate>

Définit une règle SemanticCachePopulate.

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

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

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

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

Exemple

Cette section fournit un exemple utilisant <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>

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

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

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

<SimilaritySearch>

Élément contenant les informations requises pour mettre à jour l'index vectoriel.

Pour en savoir plus, consultez Insérer des points de données.

Le délai d'expiration des points de données est de <TTLInSeconds> à compter de la date d'entrée.

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

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </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://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (enfant de <VertexAI>)

URL utilisée pour effectuer une opération upsert sur des points de données dans l'index vectoriel.

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

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

Élément spécifiant la valeur TTL (Time To Live) des réponses mises en cache, en secondes. La valeur par défaut est 60.

Pour en savoir plus, consultez la section Mettre à jour et recompiler un index actif.

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 <SemanticCachePopulate>. 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-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.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.