Mise en cache sémantique avec un point de terminaison privé (Private Service Connect)

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 d'Apigee pour permettre la réutilisation intelligente des réponses en s'appuyant sur la similarité sémantique. Dans cet exemple, les règles exécutent leur recherche de similarité sur un index de recherche Vector Search déployé sur un point de terminaison privé (Private Service Connect). En utilisant ces règles dans votre proxy d'API Apigee, vous pouvez réduire les appels d'API backend redondants, abaisser la latence et diminuer les coûts opérationnels.

Ce guide s'applique à Apigee et à Apigee hybrid. La configuration de la règle est identique sur les deux plates-formes. Seule la manière dont l'environnement d'exécution atteint le point de terminaison privé diffère, comme décrit à l'étape 2 : Se connecter au rattachement de service. Sur Apigee Hybrid, la mise en cache sémantique sur un point de terminaison privé (Private Service Connect) est compatible avec la version 1.16.11 et les versions ultérieures, ainsi qu'avec la version 1.17.0 et les versions ultérieures. Pour en savoir plus, consultez Configurer sur Apigee hybrid.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Compute Engine, AI Platform, and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. Activez et configurez l' API d'embeddings textuels de Vertex AI dans votre projet Google Cloud .
  5. Créez (ou accédez à) un index Vector Search déployé sur un point de terminaison privé (Private Service Connect). Ce tutoriel ne duplique pas les étapes de configuration de Vector Search. Consultez Prérequis pour l'index de recherche Vector Search pour connaître les exigences spécifiques à SemanticCacheLookup et obtenir des liens vers la documentation de Vector Search.
  6. Vérifiez que vous disposez d'un environnement intermédiaire ou complet dans votre instance Apigee. Les règles de mise en cache sémantique ne peuvent être déployées que dans des environnements intermédiaires ou complets.
  7. Vérifiez que vous disposez d'un groupe d'environnements avec un nom d'hôte d'exécution que vous pouvez utiliser pour envoyer des requêtes à votre proxy d'API.

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 des proxys Apigee. Pour en savoir plus sur l'attribution de rôles, consultez 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 des variables d'environnement : 

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

Où :

  • PROJECT_ID est l'ID du projet avec 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érequis pour l'index Vector Search

Ce tutoriel suppose que vous disposez déjà (ou que vous allez créer) d'un index Vector Search déployé sur un point de terminaison privé (Private Service Connect). La création, la mise en forme et le déploiement d'un index Vector Search sont documentés dans les guides Vector Search. Ce tutoriel ne répète donc pas ces étapes. Suivez la documentation Vector Search pour :

Lorsque vous créez l'index, il doit répondre aux exigences spécifiques à SemanticCacheLookup suivantes :

  • L'index doit utiliser STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE") pour que les appels upsertDatapoints de la règle SemanticCachePopulate puissent être interrogés en temps quasi réel.
  • L'index dimensions doit correspondre à la dimensionnalité de sortie du modèle d'embeddings que vous utilisez dans la règle SemanticCacheLookup. Ce tutoriel utilise gemini-embedding-001, qui produit par défaut des embeddings à 3 072 dimensions. Si vous tronquez la sortie à une dimensionnalité inférieure (par exemple, 768 ou 1536), définissez dimensions sur la même valeur.
  • Créez l'index avec la mesure de distance (distanceMeasureType) qui correspond à la valeur <DistanceMeasureType> de votre stratégie. L'élément <SimilaritySearch><VertexAI><DistanceMeasureType> de la règle SemanticCacheLookup est facultatif et sa valeur par défaut est DOT_PRODUCT_DISTANCE. COSINE_DISTANCE est également accepté. La mesure de distance de l'index et la règle <DistanceMeasureType> doivent être identiques.

L'exemple minimal suivant crée un index compatible. Pour obtenir le corps de la requête complet et toutes les options disponibles, consultez Créer et gérer un index :

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl -X POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "semantic-cache-index",
    "metadata": {
      "config": {
        "dimensions": 3072,
        "distanceMeasureType": "DOT_PRODUCT_DISTANCE"
      }
    },
    "indexUpdateMethod": "STREAM_UPDATE"
  }'

Notez la valeur numérique INDEX_ID renvoyée dans la réponse. Vous l'utiliserez dans la règle SemanticCachePopulate. Après avoir créé l'index, créez un point de terminaison d'index Private Service Connect et déployez-y l'index.

Lorsque vous créez le point de terminaison d'index Private Service Connect, il doit répondre aux exigences suivantes spécifiques à SemanticCacheLookup :

  • Le projectAllowlist doit inclure le projet Apigee qui lance la connexion :
    • Apigee : utilisez le projet locataire Apigee. Obtenez l'ID du projet locataire à partir de l'API Organizations (champ apigeeProjectId).
    Le projectAllowlist ne peut pas être modifié une fois le point de terminaison d'index créé. Si vous ajoutez le mauvais projet à la liste d'autorisation, vous devez supprimer et recréer le point de terminaison de l'index.

Notez l'INDEX_ENDPOINT_ID numérique du point de terminaison d'index.

Configurer le compte de service pour le proxy Apigee

Le proxy Apigee utilise un compte de service pour ses appels REST Vertex AI : l'API Embeddings dans la règle SemanticCacheLookup, upsertDatapoints dans la règle SemanticCachePopulate et la cible du modèle. Attribuez à ce compte de service le rôle AI Platform User (roles/aiplatform.user) :

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

Où SERVICE_ACCOUNT est l'adresse e-mail du compte de service utilisé par le proxy. Vous ferez référence à ce compte de service lorsque vous déploierez le proxy à l'étape 4 : Importer et déployer le proxy d'API.

Conditions préalables supplémentaires pour les déploiements Apigee hybrid

Pour les déploiements Apigee Hybrid, vérifiez les exigences supplémentaires suivantes :

  • Un environnement d'exécution hybride en version 1.16.11 ou ultérieure, ou 1.17.0 ou ultérieure, installé dans votre propre cluster Kubernetes. Consultez la documentation d'installation d'Apigee Hybrid. Cette fonctionnalité n'ajoute aucune exigence de cluster qui lui est propre. Tout cluster hybride compatible fonctionne.
  • Un environnement intermédiaire ou complet et un groupe d'environnements avec un nom d'hôte d'exécution, identique à celui d'Apigee. Les règles de mise en cache sémantique ne sont déployées que dans les environnements intermédiaires ou complets.
  • Joignabilité du réseau de l'environnement d'exécution au point de terminaison privé. Le processeur de messages doit pouvoir ouvrir une connexion gRPC en texte brut au point de terminaison Private Service Connect de Vector Search sur TARGET_HOST:10000.
  • Sortie pour les appels REST. Les appels Embeddings, Populate et model-target sont envoyés à la surface publique REGION-aiplatform.googleapis.com. L'environnement d'exécution a donc également besoin d'un chemin d'accès aux Google APIs, directement ou via un chemin privé si votre cluster n'a pas de sortie publique.

Configurer sur Apigee hybrid

La mise en cache sémantique sur un point de terminaison privé (Private Service Connect) est compatible avec Apigee Hybrid version 1.16.11 et ultérieures, et version 1.17.0 et ultérieures. La configuration de la règle et les étapes de Vector Search dans ce tutoriel sont identiques à celles d'Apigee. La différence est que, sur Apigee hybrid, vous exécutez l'environnement d'exécution et fournissez vous-même sa connectivité. Étant donné que les déploiements hybrides varient considérablement, cette section fournit des conseils généraux plutôt que des commandes exactes. La seule exigence ajoutée par cette fonctionnalité est que l'environnement d'exécution doit pouvoir atteindre le point de terminaison privé via gRPC en texte brut.

Fournir la joignabilité du réseau

Dans les déploiements hybrides, vous devez gérer la connectivité manuellement, car il n'existe pas de rattachement de point de terminaison géré par Apigee. Créez un point de terminaison Private Service Connect dans votre VPC client qui pointe vers le SERVICE_ATTACHMENT Vector Search, et utilisez son adresse IP interne comme TARGET_HOST dans le proxy. Pour en savoir plus, consultez Étape 2 : Se connecter au rattachement de service. Le routage spécifique (par exemple, VPC partagé ou GKE natif VPC) dépend de la configuration de votre cluster.

Si votre cluster ne dispose pas d'une sortie Internet publique, assurez-vous que l'environnement d'exécution dispose d'un chemin d'accès privé aux Google APIs, tel que l'accès privé à Google, pour gérer les communications REST.

Après avoir établi la connectivité à grpc://TARGET_HOST:10000, suivez les étapes suivantes (création et déploiement de l'index, création du proxy et test), qui sont identiques pour Apigee et Apigee hybrid.

Présentation

Les règles de mise en cache sémantique aident les utilisateurs d'Apigee avec des modèles LLM à traiter de manière intelligente et efficace les prompts identiques ou présentant une similarité sémantique. Cela permet de minimiser les appels d'API backend et de réduire la consommation de ressources.

Les règles SemanticCacheLookup et SemanticCachePopulate sont rattaché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 le prompt utilisateur de la requête et le 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 prompts similaires. Si un point de données de requête 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 prompt précédent similaire, le modèle LLM génère du contenu en réponse au prompt de l'utilisateur et remplit le cache Apigee avec la réponse. Une boucle de rétroaction est créée pour mettre à jour les entrées de l'index de recherche Vector Search en vue des futures requêtes.

Dans ce scénario, l'index Vector Search est déployé sur un point de terminaison privé (Private Service Connect) via gRPC. Pour en savoir plus sur la compatibilité de Private Service Connect avec Vector Search, consultez Interroger des index d'accès aux services privés ou Private Service Connect.

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

  1. Vérifiez vos ressources et obtenez les valeurs dont Apigee a besoin.
  2. Connectez-vous au rattachement de service.
  3. Créez le groupe de proxys d'API.
  4. Importez et déployez le proxy d'API.
  5. Tester les règles de mise en cache sémantique

Étape 1 : Vérifiez vos ressources et obtenez les valeurs dont Apigee a besoin

Avant de configurer Apigee, vérifiez que le point de terminaison de votre index Vector Search est compatible avec Private Service Connect et que votre index est déployé. Ensuite, lisez les deux valeurs utilisées par le proxy Apigee : le rattachement de service et le DEPLOYED_INDEX_ID.

Vérifiez que l'index est déployé et que le point de terminaison expose un rattachement de service Private Service Connect :

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"

La commande renvoie un nom de ressource de rattachement de service au format projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME. Dans ce guide, cette valeur est appelée SERVICE_ATTACHMENT. Si la commande renvoie une valeur vide, l'index n'est pas encore déployé sur un point de terminaison Private Service Connect. Revenez à la section Prérequis pour l'index Vector Search et terminez le déploiement de l'index avant de continuer.

Lisez le DEPLOYED_INDEX_ID de l'index déployé sur le point de terminaison :

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.id)"

Dans ce guide, cette valeur est appelée DEPLOYED_INDEX_ID. Vous l'utiliserez dans la règle SemanticCacheLookup à l'étape 3 : Créer le bundle de proxy d'API.

Pour en savoir plus sur le déploiement et l'interrogation de points de terminaison d'index privés, consultez Déployer un index sur un point de terminaison Private Service Connect et Interroger des index d'accès aux services privés ou Private Service Connect.

Étape 2 : Se connecter au rattachement de service

Cette étape vous donne l'hôte privé que le <GrpcEndpoint> du proxy appelle. La méthode de création dépend de votre plate-forme. La configuration du proxy dans les étapes ultérieures est identique dans les deux cas.

Apigee : créer un rattachement de point de terminaison

Sur Apigee, créez un rattachement de point de terminaison Apigee. Le rattachement de point de terminaison est le côté client Private Service Connect d'Apigee. Il se connecte au rattachement de service Vector Search et vous fournit un hôte privé que le proxy appelle.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "'"$REGION"'",
        "serviceAttachment": "SERVICE_ATTACHMENT"
      }' \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT"

Interrogez jusqu'à ce que l'état (state) du rattachement soit ACTIVE et que son état d'appairage (connectionState) soit ACCEPTED, puis notez l'hôte : 

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments/ENDPOINT_ATTACHMENT"

La réponse contient l'hôte dans le champ host. Dans ce guide, cette valeur est appelée TARGET_HOST.

Pour vous connecter au rattachement de service Vector Search à partir de votre proxy, vous pouvez utiliser :

  • Adresse IP : utilisez l'adresse IP renvoyée dans le champ host directement en tant que TARGET_HOST (par exemple, 7.0.3.4).
  • Un enregistrement DNS privé : si vous avez configuré une zone Cloud DNS privée dans votre projet Google Cloud avec l'appairage DNS vers Apigee, vous pouvez créer un enregistrement A dans votre zone privée pointant vers l'adresse IP du rattachement de point de terminaison et utiliser ce nom de domaine (par exemple, vectorsearch.example.com) comme TARGET_HOST. Pour en savoir plus, consultez Utiliser un enregistrement DNS et Se connecter avec des zones d'appairage DNS privées.

Point de terminaison Private Service Connect pour Apigee Hybrid

Dans Apigee, Google fournit une ressource de "rattachement de point de terminaison" qui gère la connexion Private Service Connect. Toutefois, dans Apigee hybrid, vous gérez l'environnement d'exécution et l'environnement réseau. Quel que soit l'emplacement d'exécution de votre cluster, il doit pouvoir atteindre le point de terminaison Private Service Connect de Vector Search via une connexion gRPC en texte brut vers host:10000.

Pour Apigee Hybrid, créez un point de terminaison Private Service Connect dans un VPC client Google Cloud qui pointe vers le SERVICE_ATTACHMENT Vector Search. Utilisez l'adresse IP interne du point de terminaison comme TARGET_HOST dans votre configuration de proxy. Assurez-vous que le projet Google Cloud hébergeant ce point de terminaison est inclus dans leprojectAllowlistde l'index de recherche Vector Search. Pour en savoir plus, consultez Prérequis pour l'index Vector Search.

Étape 3 : Créez le groupe de proxys d'API

Créer le bundle de proxys

Créez la structure de répertoires suivante : 

apiproxy/
├── PROXY_NAME.xml
├── proxies/default.xml
├── targets/default.xml
└── policies/
    ├── SCL-1.xml
    └── SCP-1.xml

policies/SCL-1.xml : la règle SemanticCacheLookup. Le bloc <SimilaritySearch> utilise <PrivateServiceConnect><GrpcEndpoint> (pas de <URL>).

Remarque : Règles <GrpcEndpoint> :

  • Le format est grpc://TARGET_HOST:PORT ; le schéma doit être grpc://. grpcs:// (TLS) n'est pas compatible avec cette version.
  • Le port est 10000 pour Vector Search. Les points de terminaison du plan de données Private Service Connect diffusent gRPC sur le port 10000. Le point de terminaison est donc toujours grpc://TARGET_HOST:10000.
  • TARGET_HOST peut être l'adresse IP du rattachement de point de terminaison (à l'étape 2) ou un enregistrement DNS personnalisé créé dans votre zone DNS privée.
  • Le saut gRPC est en texte brut et non authentifié (sécurisé par l'isolation du réseau).
<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-1">
  <DisplayName>SCL-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-embedding-001:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <PrivateServiceConnect>
        <GrpcEndpoint>grpc://TARGET_HOST:10000</GrpcEndpoint>
      </PrivateServiceConnect>
      <DeployedIndexID>DEPLOYED_INDEX_ID</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

policies/SCP-1.xml : la règle SemanticCachePopulate. La méthode Populate est réservée à REST et doit utiliser <URL> (elle rejette <PrivateServiceConnect> au moment du déploiement) : 

<SemanticCachePopulate async="false" continueOnError="true" enabled="true" name="SCP-1">
  <DisplayName>SCP-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>3600</TTLInSeconds>
</SemanticCachePopulate>

targets/default.xml : cible du modèle. La cible appelle une API Google. Elle a donc besoin d'un jeton. <GoogleAccessToken> utilise le compte de service du déploiement : 

<TargetEndpoint name="default">
  <PreFlow name="PreFlow"><Request/><Response/></PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

proxies/default.xml : exécutez la règle SemanticCacheLookup sur la requête et la règle SemanticCachePopulate sur la réponse : 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request><Step><Name>SCL-1</Name></Step></Request>
    <Response><Step><Name>SCP-1</Name></Step></Response>
  </PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPProxyConnection>
    <BasePath>/PROXY_NAME</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

PROXY_NAME.xml : descripteur du bundle : 

<APIProxy name="PROXY_NAME">
  <BasePaths>/PROXY_NAME</BasePaths>
  <Policies><Policy>SCL-1</Policy><Policy>SCP-1</Policy></Policies>
  <ProxyEndpoints><ProxyEndpoint>default</ProxyEndpoint></ProxyEndpoints>
  <TargetEndpoints><TargetEndpoint>default</TargetEndpoint></TargetEndpoints>
</APIProxy>

Étape 4 : Importer et déployer le proxy d'API

Compressez le bundle, importez-le pour créer une révision, puis déployez la révision avec votre compte de service : 

TOKEN=$(gcloud auth print-access-token)
(cd BUNDLE_DIR && zip -r ../PROXY_NAME.zip apiproxy)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@PROXY_NAME.zip" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?action=import&name=PROXY_NAME"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments?override=true&serviceAccount=SERVICE_ACCOUNT"

Où :

  • BUNDLE_DIR est le répertoire contenant le dossier apiproxy/. L'archive doit contenir le dossier apiproxy/ à la racine.
  • ENV est l'environnement Apigee dans lequel vous déployez le proxy. L'environnement doit être un environnement intermédiaire ou complet.
  • REVISION est le numéro de révision renvoyé par l'appel d'importation.
  • SERVICE_ACCOUNT est l'adresse e-mail du compte de service que vous utilisez pour déployer le proxy.

Attendez que le déploiement indique READY : 

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments" | jq .state

Étape 5 : Testez les règles de mise en cache sémantique

Envoyez une nouvelle requête. Il s'agit d'un défaut de cache (miss) : le modèle est appelé et la réponse est mise en cache. 

curl -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

Envoyez à nouveau le même prompt. Il s'agit d'un succès de cache (hit) : la réponse est diffusée à partir du cache et le modèle n'est pas appelé. 

curl -i -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

En cas de succès, la réponse inclut l'en-tête Cached-content: true, la même réponse et une latence nettement inférieure.

Vous pouvez également vérifier la mise en cache à l'aide d'une session de débogage. En cas de correspondance, la règle SemanticCacheLookup définit les variables de flux suivantes :

Variable Valeur d'un hit
SemanticCacheLookup.SCL-1.dense_embeddings Vecteur d'embedding de la requête.
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response La réponse mise en cache.

En cas de succès, la cible du modèle n'est pas appelée : le flux est court-circuité et renvoie la réponse mise en cache.

Dépannage

Pour obtenir la documentation de référence complète sur les erreurs, consultez la règle SemanticCacheLookup.

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 ignore tous les en-têtes de contrôle du cache 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 différencier les entrées ayant des significations très similaires, la réponse peut renvoyer des informations obsolètes ou incorrectes.
  • La fonctionnalité Vector Search n'est pas disponible dans toutes les régions. Pour obtenir la liste des régions prises en charge, consultez la section Disponibilité des fonctionnalités de la page "Emplacements Vertex AI". Si votre organisation Apigee se trouve dans une région non compatible, 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 le streaming continu des réponses des événements envoyés par le serveur (SSE).
  • Les règles de mise en cache sémantique utilisent des API LLM, ce qui peut entraîner des latences plus élevées, de l'ordre de quelques centaines de millisecondes.
  • Dans les installations Apigee hybrid, la compatibilité avec les règles de mise en cache sémantique est limitée aux installations sur Google Cloud Platform.
  • Lorsque la règle SemanticCacheLookup est configurée pour utiliser un point de terminaison Vector Search privé via Private Service Connect (PSC), l'appel de recherche de similarité est envoyé via une connexion gRPC directe au point de terminaison privé et ne passe pas par un proxy de transfert configuré.

Étapes suivantes