Premiers pas avec les règles de mise en cache sémantique

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

Consultez la documentation d' Apigee Edge.

Cette page explique comment configurer et utiliser les règles de mise en cache sémantique Apigee pour permettre la réutilisation intelligente des réponses en fonction de la similarité sémantique. L'utilisation de ces règles dans votre proxy d'API Apigee peut minimiser les appels d'API de backend redondants, réduire la latence et diminuer les coûts opérationnels.

Avant de commencer

Avant de commencer, veillez à effectuer les tâches suivantes :

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

   Enable the APIs

8. Configurez l' API Vertex AI Embeddings de texte et Vector Search dans votre projet Google Cloud .
9. Vérifiez qu'un environnement Comprehensive est disponible dans votre instance Apigee. Les règles de mise en cache sémantique ne peuvent être déployées que dans des environnements complets.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et utiliser les règles de mise en cache sémantique, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur AI Platform (roles/aiplatform.user) sur le compte de service que vous utilisez pour déployer les 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.

Définir des variables d'environnement

Dans le projet Google Cloud qui contient votre instance Apigee, utilisez la commande suivante pour définir les variables d'environnement :

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

Où :

• PROJECT_ID est l'ID du projet contenant votre instance Apigee.
• REGION est la région Google Cloud de votre instance Apigee.
• RUNTIME_HOSTNAME est le nom d'hôte de votre environnement d'exécution Apigee.

Pour vérifier que les variables d'environnement sont correctement définies, exécutez la commande suivante et examinez le résultat :

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Définir le projet

Définissez le projet Google Cloud dans votre environnement de développement :

    gcloud auth login
    gcloud config set project $PROJECT_ID

Présentation

Les règles de mise en cache sémantique sont conçues pour aider les utilisateurs d'Apigee avec les modèles LLM à diffuser intelligemment des requêtes identiques ou sémantiquement similaires de manière efficace, en minimisant les appels d'API de backend et en réduisant la consommation de ressources.

Les règles SemanticCacheLookup et SemanticCachePopulate sont associées respectivement aux flux de requête et de réponse d'un proxy d'API Apigee. Lorsque le proxy reçoit une requête, la règle SemanticCacheLookup extrait la requête utilisateur de la requête et la convertit en représentation numérique à l'aide de l'API Text Embeddings. Une recherche de similarité sémantique est effectuée à l'aide de Vector Search pour trouver des requêtes similaires. Si un point de données d'invite similaire est trouvé, une recherche dans le cache est effectuée. Si des données mises en cache sont trouvées, la réponse mise en cache est renvoyée au client.

Si la recherche de similarité ne renvoie pas de requête précédente similaire, le modèle LLM génère du contenu en réponse à la requête de l'utilisateur, et le cache Apigee est rempli avec la réponse. Une boucle de rétroaction est créée pour mettre à jour les entrées de l'index Vector Search en vue des futures requêtes.

Les sections suivantes décrivent les étapes requises pour créer et configurer les règles de mise en cache sémantique :

1. Configurez un compte de service pour l'index Vector Search.
2. Créez et déployez un index Vector Search.
3. Créez un proxy d'API pour activer la mise en cache sémantique.
4. Configurez les règles de mise en cache sémantique.
5. Testez les règles de mise en cache sémantique.

Configurer un compte de service pour l'index Vector Search

Pour configurer un compte de service pour l'index Vector Search, procédez comme suit :

1. Créez un compte de service à l'aide de la commande suivante :

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --description="DESCRIPTION" \
     --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

   Où :

   • SERVICE_ACCOUNT_NAME correspond au nom du compte de service.
   • DESCRIPTION est une description du compte de service.
   • SERVICE_ACCOUNT_DISPLAY_NAME est le nom à afficher du compte de service.

   Exemple :

   gcloud iam service-accounts create ai-client \
     --description="semantic cache client" \
     --display-name="ai-client"

2. Attribuez le rôle AI Platform User au compte de service à l'aide de la commande suivante :

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"

   Où SERVICE_ACCOUNT_NAME est le nom du compte de service créé à l'étape précédente.

3. Attribuez le rôle IAM Service Account User au compte de service à l'aide de la commande suivante :

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/iam.serviceAccountUser"

   Où SERVICE_ACCOUNT_NAME est le nom du compte de service créé à l'étape précédente.

Créer et déployer un index Vector Search

Pour créer et déployer un index Vector Search :

1. Créez un index Vector Search qui autorise les mises à jour en streaming :

   ACCESS_TOKEN=$(gcloud auth print-access-token) && curl --location --request POST \
     "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
       --header "Authorization: Bearer $ACCESS_TOKEN" \
       --header 'Content-Type: application/json' \
       --data-raw \
       '{
         "displayName": "semantic-cache-index",
         "description": "semantic-cache-index",
         "metadata": {
           "config": {
             "dimensions": "768",
             "approximateNeighborsCount": 150,
             "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
             "featureNormType": "NONE",
             "algorithmConfig": {
               "treeAhConfig": {
                 "leafNodeEmbeddingCount": "10000",
                 "fractionLeafNodesToSearch": 0.05
                 }
               },
             "shardSize": "SHARD_SIZE_MEDIUM"
             },
           },
         "indexUpdateMethod": "STREAM_UPDATE"
       }'

   $REGION définit la région dans laquelle l'index Vector Search est déployé. Nous vous recommandons d'utiliser la même région que celle de votre instance Apigee. Cette variable d'environnement a été définie lors d'une étape précédente.

   Une fois cette opération terminée, une réponse semblable à la suivante devrait s'afficher :

   {
     "name": "projects/976063410430/locations/us-west1/indexes/5695338290484346880/operations/9084564741162008576",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata",
       "genericMetadata": {
         "createTime": "2025-04-25T18:45:27.996136Z",
         "updateTime": "2025-04-25T18:45:27.996136Z"
       }
     }
   }

   Pour en savoir plus sur la création d'index Vector Search, consultez Créer un index.

2. Créez un IndexEndpoint à l'aide de la commande suivante :

   gcloud ai index-endpoints create \
     --display-name=semantic-cache-index-endpoint \
     --public-endpoint-enabled \
     --region=$REGION \
     --project=$PROJECT_ID

   Cette étape peut prendre plusieurs minutes. Une fois l'opération terminée, un résultat semblable à celui-ci doit s'afficher :

   Waiting for operation [8278420407862689792]...done.
     Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

   Pour en savoir plus sur la création d'un IndexEndpoint, consultez Créer un IndexEndpoint.

3. Déployez l'index sur le point de terminaison à l'aide de la commande suivante :

   INDEX_ENDPOINT_ID=$(gcloud ai index-endpoints list \
     --project=$PROJECT_ID \
     --region=$REGION \
     --format="json" | jq -c -r \
     '.[] | select(.displayName=="semantic-cache-index-endpoint") | .name | split("/") | .[5]' \
     ) && INDEX_ID=$(gcloud ai indexes list \
     --project=$PROJECT_ID \
     --region=$REGION \
     --format="json" | jq -c -r \
     '.[] | select(.displayName=="semantic-cache-index") | .name | split("/") | .[5]' \
     ) && gcloud ai index-endpoints deploy-index \
     $INDEX_ENDPOINT_ID \
     --deployed-index-id=semantic_cache \
     --display-name=semantic-cache \
     --index=$INDEX_ID \
     --region=$REGION \
     --project=$PROJECT_ID

Le déploiement initial d'un index sur un point de terminaison peut prendre entre 20 et 30 minutes. Pour vérifier l'état de l'opération, utilisez la commande suivante :

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

Vérifiez que l'index a été déployé :

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

La commande doit renvoyer $ done: true.

Créer un proxy d'API pour activer la mise en cache sémantique

Dans cette étape, vous allez créer un proxy d'API à l'aide du modèle Proxy avec cache sémantique, si vous ne l'avez pas déjà fait.

Avant de créer le proxy d'API, définissez la variable d'environnement suivante :

export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

Pour créer un proxy à utiliser avec la mise en cache sémantique :

1. Accédez à la page Proxys d'API dans la console Google Cloud .

   Accéder aux proxys d'API

2. Cliquez sur + Créer pour ouvrir le volet Créer un proxy d'API.
3. Dans la zone Modèle de proxy, sélectionnez Proxy avec cache sémantique.
4. Saisissez les informations suivantes :
   • Nom du proxy : saisissez le nom du proxy.
   • Description : (facultatif) saisissez une description du proxy.
   • Target (Existing API) (Cible (API existante)) : saisissez l'URL du service de backend que le proxy appelle. Il s'agit du point de terminaison du modèle LLM utilisé pour générer du contenu.

     Pour ce tutoriel, la cible (API existante) peut être définie sur :

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent

5. Saisissez les URL du cache sémantique suivantes :
   • URL de génération d'embeddings : ce service Vertex AI convertit les entrées de texte en une forme numérique pour l'analyse sémantique.

     Pour ce tutoriel, cette URL peut être définie sur la valeur suivante :

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict

   • URL de requête des voisins les plus proches : ce service Vertex AI recherche des entrées de texte similaires à partir des requêtes précédentes dans l'index Vector Search pour éviter le retraitement.

     Pour ce tutoriel, cette URL peut être définie sur la valeur suivante :

     PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors

     Les valeurs PUBLIC_DOMAIN_NAME et INDEX_ENDPOINT_ID ont été définies à une étape précédente. Pour obtenir ces valeurs, vous pouvez utiliser les commandes suivantes :

       echo $PUBLIC_DOMAIN_NAME
       echo $INDEX_ENDPOINT_ID

   • URL d'insertion/mise à jour de l'index : ce service Vertex AI met à jour l'index avec les entrées nouvelles ou modifiées.

     Pour ce tutoriel, cette URL peut être définie sur la valeur suivante :

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints

6. Cliquez sur Suivant.
7. Cliquez sur Créer.

La configuration XML du proxy d'API est visible dans l'onglet Développer. Les règles SemanticCacheLookup et SemanticCachePopulate contenant des valeurs par défaut sont déjà associées aux flux de requête et de réponse du proxy.

Configurer les règles de mise en cache sémantique

Vous pouvez afficher la configuration XML de chaque règle en cliquant sur son nom dans la vue Détails de l'onglet Développer du proxy d'API. Vous pouvez modifier le code XML de la règle directement dans la vue Code de l'onglet Développer.

Modifiez les règles :

• Règle SemanticCacheLookup :
  • Supprimez l'élément <UserPromptSource> pour utiliser la valeur par défaut.
  • Mettez à jour l'élément <DeployedIndexId> pour utiliser la valeur semantic_cache.
  • Configurez la valeur <Threshold> de similarité sémantique pour déterminer quand deux requêtes sont considérées comme correspondantes. La valeur par défaut est 0,9, mais vous pouvez l'ajuster en fonction de la sensibilité de votre application. Plus le nombre est élevé, plus les requêtes doivent être étroitement liées pour être considérées comme un succès de cache (hit). Pour ce tutoriel, nous vous recommandons de définir cette valeur sur 0,95.
  • Cliquez sur Enregistrer.
• Règle SemanticCachePopulate :
  • Définissez l'élément <TTLInSeconds> pour spécifier le nombre de secondes avant l'expiration du cache. La valeur par défaut est 60 s. Notez qu'Apigee ignorera tous les en-têtes cache-control qu'il recevra du modèle LLM.
  • Cliquez sur Enregistrer.

Ajouter l'authentification Google au proxy d'API

Vous devez également ajouter l'authentification Google au point de terminaison cible du proxy d'API pour permettre les appels de proxy à la cible.

Pour ajouter le jeton d'accès Google :

1. Dans l'onglet Développer, cliquez sur par défaut sous le dossier Points de terminaison cibles. La vue Code affiche la configuration XML de l'élément <TargetEndpoint>.
2. Modifiez le code XML pour ajouter la configuration suivante sous <HTTPTargetConnection> :

   <Authentication>
     <GoogleAccessToken>
       <Scopes>
         <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
       </Scopes>
     </GoogleAccessToken>
   </Authentication>

3. Cliquez sur Enregistrer.

Déployer le proxy d'API

Pour déployer le proxy d'API :

1. Cliquez sur Déployer pour ouvrir le volet Déployer le proxy d'API.
2. Le champ Révision doit être défini sur 1. Si ce n'est pas le cas, cliquez sur 1 pour le sélectionner.
3. Dans la liste Environnement, sélectionnez l'environnement dans lequel vous souhaitez déployer le proxy. L'environnement doit être un environnement complet.
4. Saisissez le compte de service que vous avez créé lors d'une étape précédente.
5. Cliquez sur Déployer.

Tester les règles de mise en cache sémantique

Pour tester les règles de mise en cache sémantique :

1. Envoyez une requête au proxy à l'aide de la commande suivante :

   curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
     "contents": [
         {
             "role": "user",
             "parts": [
                 {
                     "text": "Why is the sky blue?"
                 }
             ]
         }
     ]
   }'

   Où PROXY_NAME correspond au chemin de base du proxy d'API que vous avez déployé à l'étape précédente.

Répétez l'appel d'API en remplaçant la chaîne d'invite par les chaînes d'invite sémantiquement similaires suivantes :
• Pourquoi le ciel est-il bleu ?
• Pourquoi le ciel est-il bleu ?
• Pourquoi le ciel est-il bleu ?
• Peux-tu m'expliquer pourquoi le ciel est bleu ?
• Pourquoi le ciel est-il bleu ?
2. Comparez le temps de réponse pour chaque appel une fois qu'une requête similaire a été mise en cache.

Pour vérifier que vos appels sont diffusés à partir du cache, consultez les en-têtes de réponse. Un en-tête Cached-Content: true doit être associé.

Bonnes pratiques

Nous vous recommandons d'intégrer les bonnes pratiques suivantes à votre programme de gestion des API lorsque vous utilisez les règles de mise en cache sémantique :

• Empêchez la mise en cache des données sensibles avec Model Armor.

  Pour éviter la mise en cache des données sensibles, nous vous recommandons d'utiliser Model Armor pour le filtrage de contenu. Model Armor peut signaler les réponses comme non mises en cache s'il détecte des informations sensibles. Pour en savoir plus, consultez la présentation de Model Armor.

• Gérez la fraîcheur des données avec l'invalidation des points de données Vertex AI et la valeur TTL (Time-to-Live).

  Nous vous recommandons d'implémenter des stratégies d'invalidation des points de données appropriées pour vous assurer que les réponses mises en cache sont à jour et reflètent les dernières informations de vos systèmes de backend. Pour en savoir plus, consultez Mettre à jour et recompiler un index actif.

  Vous pouvez également ajuster le TTL des réponses mises en cache en fonction de la volatilité des données et de la fréquence des mises à jour. Pour en savoir plus sur l'utilisation du TTL dans la règle SemanticCachePopulate, consultez <TTLInSeconds>.

• Utilisez des stratégies de mise en cache prédéfinies pour garantir l'exactitude des données de réponse.

  Nous vous recommandons d'implémenter des stratégies de mise en cache prédéfinies semblables à celles ci-dessous :

  • Réponses génériques de l'IA : configurez une valeur TTL longue (par exemple, une heure) pour les réponses non spécifiques à l'utilisateur.
  • Réponses spécifiques à l'utilisateur : n'implémentez pas la mise en cache ou définissez une valeur TTL courte (par exemple, cinq minutes) pour les réponses qui contiennent des informations spécifiques à l'utilisateur.
  • Réponses urgentes : configurez une valeur TTL courte (cinq minutes, par exemple) pour les réponses qui nécessitent des mises à jour en temps réel ou fréquentes.

Limites

Les limites suivantes s'appliquent aux règles de mise en cache sémantique :

• La taille maximale du texte pouvant être mis en cache est de 256 Ko. Pour en savoir plus, consultez la section Taille de la valeur du cache sur la page Limites d'Apigee.
• Apigee ignorera tous les en-têtes cache-control qu'il reçoit du modèle LLM.
• Si le cache n'est pas invalidé correctement ou si l'algorithme de similarité sémantique n'est pas suffisamment précis pour faire la différence entre des entrées ayant des significations très similaires, la réponse peut renvoyer des informations obsolètes ou incorrectes.
• La fonctionnalité de recherche vectorielle n'est pas disponible dans toutes les régions. Pour obtenir la liste des régions disponibles, consultez la section Disponibilité des fonctionnalités de la page "Emplacements Vertex AI". Si votre organisation Apigee se trouve dans une région non prise en charge, vous devrez créer des points de terminaison d'index dans une région différente de celle de votre organisation Apigee.
• Les règles de mise en cache sémantique ne sont pas compatibles avec les proxys d'API utilisant des EventFlows pour la diffusion en continu des réponses des événements envoyés par le serveur (SSE).
• La fonction JsonPath dans <UserPromptSource> n'est pas compatible avec la fonctionnalité ignoreUnresolvedVariables. Par défaut, les valeurs nulles ou vides sont ignorées lors de l'application du modèle de message.

Étapes suivantes

Découvrez comment faire vos premiers pas avec les règles Model Armor.