Contrôle du cache rapide dans une passerelle API multimodèle : préfixes stables, isolation des locataires et analyse des accès au cache
Une architecture de passerelle pratique pour protéger les taux de réussite du cache d'invite sur les API de style OpenAI, Anthropic et Gemini : régions d'invite stables, normalisation des métriques du fournisseur, isolation des locataires, attribution de facturation et contrôles de déploiement.
La mise en cache des invites est facile à gaspiller. Une équipe peut disposer d'une invite système de 40 000 jetons, d'un schéma d'outil, d'un bloc de stratégie, d'une carte de référentiel ou d'une mémoire d'agent qui devrait être réutilisable, puis placer accidentellement un horodatage, un ID de demande, un nom d'utilisateur, un extrait de récupération ou un ordre aléatoire d'outils en haut de l'invite. Le fournisseur voit un préfixe différent, le cache est manqué, la latence augmente et la facture semble déroutante.
Dans une application à fournisseur unique, vous pouvez résoudre ce problème dans le modèle d'application. Dans une passerelle multimodèle, le problème est plus important : chaque fournisseur expose différents contrôles de cache, seuils de jetons, comportement de durée de vie, champs d'utilisation et sémantique de facturation. La passerelle a besoin d'un modèle de plan de contrôle portable pour assembler des invites sécurisées pour le cache, mesurer le comportement du cache, isoler les locataires et attribuer les coûts.
Cet article décrit une architecture de référence. Il ne s’agit pas d’une étude de cas client et ne revendique pas de résultats de référence. Les faits ci-dessous proviennent de la documentation du fournisseur et de recherches publiques ; les recommandations de conception sont des conseils d'exploitation au niveau de la passerelle.
Le mode d'échec : assemblage d'invites de rupture de cache
La mise en cache des invites récompense généralement les préfixes d'invite répétés. Les mécanismes exacts varient selon le fournisseur, mais l'implication pratique est la même : si le début de l'invite change, la réutilisation en souffre.
Les disjoncteurs de cache courants incluent :
- Métadonnées par requête en haut : horodatages, ID de trace, ID de session, ID de déploiement ou étiquettes de requête générées.
- Données spécifiques à l'utilisateur dans le préfixe : noms, attributs de compte, autorisations ou préférences privées placés avant les blocs de stratégie ou d'outils réutilisables.
- Sérialisation des outils instables : schémas d'outils émis dans un ordre non déterministe, avec des espaces changeants ou des ID générés.
- Extraits de récupération trop tôt : contexte RAG inséré avant les instructions système stables ou le contexte du référentiel partagé.
- Dérive du modèle : petites modifications de formulation publiées fréquemment sans gestion des versions ni diagnostic du cache.
Une passerelle ne peut pas comme par magie rendre un préfixe instable pouvant être mis en cache, mais elle peut appliquer un contrat d'assemblage rapide et rendre visibles les échecs de cache.
Informations sur le fournisseur autour desquelles concevoir
Les détails sont importants car une passerelle doit normaliser le comportement sans prétendre que les fournisseurs sont identiques.
- OpenAI : OpenAI a documenté la mise en cache des invites pour le préfixe d'invite le plus long calculé précédemment. Il commence à 1 024 jetons, augmente par incréments de 128 jetons et expose le nombre de jetons mis en cache dans les champs d'utilisation. OpenAI indique également que les caches d'invites sont généralement effacés après 5 à 10 minutes d'inactivité et sont toujours supprimés dans l'heure suivant la dernière utilisation du cache.
- Anthropic : la mise en cache des invites Anthropic peut être demandée avec
cache_control. Sa documentation décrit la correspondance du cache sur les composants d'invite tels que les outils, le contenu du système et les messages jusqu'au bloc marqué avec contrôle du cache. Anthropic documente une cache éphémère, comprenant une durée de 5 minutes et une option d'1 heure moyennant un coût supplémentaire. - Gemini : la mise en cache contextuelle de Google Gemini expose le nombre de jetons d'accès au cache via des métadonnées d'utilisation telles que
total_cached_tokens, et sa documentation répertorie le nombre minimum de jetons d'entrée par modèle. - Implication sur le contrôle des données : la documentation sur le contrôle des données de l'API d'OpenAI indique que la mise en cache étendue des invites nécessite le stockage des tenseurs clé/valeur en tant qu'état de l'application dans le stockage local du GPU. Même lorsque les fournisseurs maintiennent des garanties d'isolation, les passerelles doivent traiter le comportement du cache comme une infrastructure sensible, et non comme une banque de données d'application partagée.
- Indicateur de recherche : des recherches publiques ont examiné si les architectures de type passerelle pouvaient introduire des vulnérabilités de mise en cache rapide qui contournent les hypothèses d'isolation du cache au niveau du fournisseur. Cela ne prouve pas qu'une passerelle spécifique est vulnérable, mais cela prend en charge une conception conservatrice d'isolation des locataires.
Recommandation : implémentez le contrôle du cache en tant que fonctionnalité de passerelle avec des politiques explicites, et non comme un effet secondaire accidentel de demandes répétées.
Un contrat d'assemblage rapide sur trois régions
La décision de conception la plus importante consiste à séparer le contenu stable et volatile avant que la requête n'atteigne un adaptateur de fournisseur.
Région 1 : préfixe stable
Le préfixe stable est un contenu censé rester identique dans de nombreuses requêtes pour la même application, la même route de modèle et la même version de modèle d'invite. Exemples :
- instructions du système de base ;
- blocages de sécurité et de stratégie ;
- schémas d'outils ;
- documentation produit statique ;
- Cartes de référentiel pour les agents de codage ;
- instructions de format de sortie corrigées.
Cette région doit être déterministe. La passerelle doit la construire à partir de modèles versionnés, de JSON canonique et de règles de classement stables. Si un registre d'outils est inclus, triez les outils par ID d'outil stable. Si des schémas JSON sont inclus, sérialisez-les avec un ordre de clé déterministe et aucun horodatage généré.
Région 2 : locataire semi-stable ou contexte d'espace de travail
La région semi-stable change moins souvent que les demandes individuelles mais n'est pas partagée globalement. Exemples :
- Remplacements de stratégie spécifiques au locataire ;
- listes autorisées d'outils au niveau de l'espace de travail ;
- terminologie spécifique au client ;
- Conventions de codage d'équipe ;
- Contexte de projet de longue durée.
Cette région doit être limitée à un locataire, un espace de travail ou une limite d'application. Il peut toujours être mis en cache, mais la passerelle ne doit jamais supposer qu'un autre locataire peut le réutiliser en toute sécurité.
Région 3 : suffixe volatile
Le suffixe volatile est la partie par requête :
- message de l'utilisateur ;
- extraits récupérés pour cette requête ;
- horodatage actuel, si cela est vraiment nécessaire ;
- demander des métadonnées d'ID et de trace, si elles sont incluses dans l'invite ;
- la conversation à court terme tourne ;
- Résultats de l'outil d'exécution.
La plupart des échecs de cache causés par la conception de l'application se produisent parce que des données de suffixe volatiles sont accidentellement placées dans le préfixe. Un constructeur côté passerelle devrait rendre cela difficile.
Modèle d'implémentation : générateurs de préfixes stables
Une implémentation pratique de passerelle peut exposer une interface d'assemblage d'invites plutôt que d'accepter une chaîne d'invite opaque de chaque application.
{
"template_id": "code-agent-v3",
"tenant_id": "tenant_123",
"route": "codage-long-contexte",
"stable_prefix": {
"system_policy_version": "01/08/2026",
"toolset_version": "outils-v12",
"repo_context_version": "repo-map-8491"
},
"semi_stable_context": {
"workspace_policy_version": "workspace-44-v6"
},
"volatile_suffix": {
"user_message": "Expliquez pourquoi ce test échoue...",
"retrieval_context_ids": ["chunk_7", "chunk_19"],
"trace_id": "not_inserted_into_prompt"
}
La passerelle restitue ensuite la requête spécifique au fournisseur. Cela donne à la passerelle un endroit pour appliquer les règles :
- rejeter les horodatages dans les champs de préfixe stable ;
- canoniser les schémas d'outils ;
- hacher chaque région séparément ;
- attacher des contrôles de cache là où un fournisseur les prend en charge ;
- préserver la sémantique des invites lors du déplacement ultérieur de données volatiles ;
- enregistrer le modèle et les empreintes digitales du préfixe pour les diagnostics.
Pour les applications existantes qui envoient uniquement des messages bruts, la passerelle peut toujours fournir un mode lint : inspecter l'ordre des messages, calculer les empreintes digitales des préfixes et signaler les disjoncteurs de cache probables sans réécrire l'invite initialement.
Couche d'adaptateur du fournisseur : normaliser l'utilisation du cache sans masquer les différences
Une passerelle multimodèle ne doit pas exposer aux développeurs trois rapports de cache non liés. Il ne faut pas non plus aplatir les données économiques spécifiques aux fournisseurs de manière si agressive que les factures deviennent impossibles à expliquer.
Créez un registre de cache normalisé avec des champs tels que :
{
"request_id": "req_abc",
"tenant_id": "tenant_123",
"app_id": "code-agent",
"route": "codage-long-contexte",
"provider": "nom_fournisseur",
"model": "id_modèle",
"template_id": "code-agent-v3",
"stable_prefix_hash": "sha256:...",
"semi_stable_hash": "sha256:...",
"input_tokens_total": 58200,
"input_tokens_uncached": 8200,
"cache_write_tokens": 50 000,
"cache_read_tokens": 0,
"output_tokens": 1300,
"cache_ttl_class": "ephemeral_5m",
"provider_cache_fields": {
"raw_field_names": "stored_or_redacted_provider_usage"
}
L'adaptateur mappe l'utilisation du fournisseur en catégories normalisées :
- Jetons d'entrée non mis en cache : jetons traités sans remise de lecture du cache ni comptabilité de lecture du cache.
- Jetons d'écriture du cache : jetons qui ont créé ou actualisé une entrée de cache côté fournisseur lorsque le fournisseur signale cette distinction.
- Jetons de lecture du cache : jetons servis à partir du cache ou comptés comme mis en cache par les métadonnées d'utilisation du fournisseur.
- Jetons de sortie : jetons générés, qui doivent rester distincts des aspects économiques du cache rapide.
- Option TTL : la classe de durée de cache sélectionnée dans laquelle un fournisseur expose un choix.
Recommandation : stockez l'utilisation brute du fournisseur dans un formulaire rédigé et versionné par un schéma, à côté des champs normalisés. La normalisation est utile pour les tableaux de bord ; les champs bruts sont nécessaires pour la réconciliation lorsque la sémantique du fournisseur change.
Observabilité du cache : tableaux de bord qui expliquent les échecs
Un tableau de bord de cache utile fait bien plus qu'afficher le nombre total de jetons mis en cache. Cela devrait aider les équipes à répondre : « Quelle charge de travail brise le préfixe et qu'est-ce qui a changé ? »
Suivez les métriques du cache par :
- locataire ;
- espace de travail ou application ;
- modèle d'itinéraire ;
- fournisseur et modèle ;
- version du modèle d'invite ;
- hachage de préfixe stable ;
- hachage de contexte semi-stable ;
- Clé API ou compte de service, le cas échéant ;
- fenêtre temporelle, en particulier parce que les durées de vie du cache sont courtes pour de nombreuses charges de travail.
Les métriques dérivées utiles incluent :
- Taux de lecture du cache : jetons d'entrée mis en cache divisés par le nombre total de jetons d'entrée éligibles pour la mise en cache.
- Désabonnement des préfixes : nombre de hachages de préfixes stables distincts par version de modèle et par heure.
- Dérive du modèle : modifications de l'accès au cache après la publication d'un modèle.
- Coût de démarrage à froid : dépenses en écriture en cache ou en entrées non mises en cache pour la première requête d'une rafale.
- Comparaison des itinéraires : taux de réussite sur les itinéraires des fournisseurs pour la même charge de travail logique.
Ne stockez pas par défaut les invites brutes pour le débogage. Préférez les hachages, les longueurs de région, les ID de modèle, les avertissements de canonisation et les différences expurgées. Si une équipe a besoin d'un débogage plus approfondi, exigez des contrôles d'accès et des limites de conservation explicites.
Politique d'isolation des locataires : ne pas concevoir pour une réutilisation entre locataires
L'hypothèse de passerelle la plus sûre est simple : le comportement pouvant être mis en cache doit être limité au client. Même si deux locataires partagent un bloc de politique publique identique, la passerelle ne doit pas intentionnellement acheminer ou façonner le trafic pour exploiter la réutilisation du cache entre locataires.
Une politique conservatrice comprend :
- Routage adapté aux locataires : acheminez le trafic pouvant être mis en cache en utilisant les limites du locataire, de l'espace de travail et des applications.
- Aucun préfixe partagé contenant des secrets : ne placez jamais les secrets de locataire, les informations d'identification, les documents privés ou les données spécifiques à l'utilisateur dans un préfixe partagé réutilisable.
- Empreintes digitales de préfixe séparées : calculez les empreintes digitales avec la portée du locataire incluse dans le grand livre de la passerelle, même si le texte rendu est identique.
- Contrôles au niveau de l'organisation : permettent aux administrateurs de désactiver les fonctionnalités de cache du fournisseur pour les charges de travail sensibles.
- L'isolation du fournisseur n'est pas une fonctionnalité de produit à revendre : traitez l'isolation du cache du fournisseur comme une protection de base, et non comme une autorisation de créer un pool de cache entre clients.
Prédiction : à mesure que les agents à contexte long deviennent plus courants, le comportement du cache fera partie des évaluations de sécurité, et pas seulement des évaluations de coûts. Les passerelles capables de prouver la politique de cache au niveau du locataire seront plus faciles à gouverner.
Attribution de facturation : lectures, écritures et jetons normaux du cache distincts
La mise en cache des invites peut rendre les factures plus difficiles à comprendre si tous les jetons d'entrée sont affichés sous la forme d'un seul chiffre. Le grand livre de facturation doit conserver au moins cinq catégories :
- Jetons d'entrée non mis en cache ;
- mettre en cache les jetons d'écriture ;
- mettre en cache les jetons de lecture ;
- jetons de sortie ;
- Frais de durée de vie ou de contrôle du cache spécifiques au fournisseur.
Cela est important lorsqu'un fournisseur réduit les lectures en cache, qu'un autre facture différemment les écritures en cache et qu'un autre propose une option TTL plus longue. Une facture client doit être en mesure d'expliquer pourquoi deux demandes avec un total similaire de jetons d'entrée ont eu des coûts différents.
Pour la rétrofacturation interne, attribuez les effets de cache au locataire et à l'application qui ont effectué la demande. Évitez d’attribuer un avantage de lecture du cache d’un locataire à un autre. Si une équipe de plate-forme interne partagée possède le modèle d'invite stable, signalez les performances du cache au niveau du modèle séparément des factures des locataires.
Liste de contrôle du cache-linting
Avant d'activer l'application du cache, exécutez les modèles d'invite via une liste de contrôle Lint :
- Les instructions système stables s'affichent avant les entrées volatiles de l'utilisateur.
- Les schémas d'outils sont triés par ID ou nom stable.
- JSON est sérialisé de manière déterministe.
- Aucun horodatage, ID aléatoire, ID de demande ou ID de trace n'apparaît dans le préfixe stable.
- Aucun secret spécifique à l'utilisateur n'apparaît dans les blocs réutilisables partagés.
- Les extraits RAG sont placés après les sections de règles et d'outils réutilisables, sauf s'il existe une raison délibérée de ne pas le faire.
- Les modèles d'invite ont des versions explicites.
- Les versions de modèles peuvent être corrélées aux modifications du taux d'accès au cache.
- Les contrôles du cache du fournisseur sont utilisés uniquement via le code de l'adaptateur, et non via une logique d'application dispersée.
- La journalisation brute des invites est désactivée par défaut ou protégée par des règles strictes de conservation et d'accès.
Plan de déploiement
1. Observez avant de modifier les invites
Commencez par collecter les champs d'utilisation du fournisseur et les métriques de cache normalisées pour le trafic existant. Calculez les empreintes digitales du préfixe pour les N premiers jetons ou pour les régions d'invite définies par la passerelle. L'objectif est de trouver des routes à grand volume et à long contexte avec un taux de désabonnement élevé des préfixes.
2. Classer les charges de travail
Regroupez le trafic en catégories : sessions d'agent, assistants de codage, RAG, automatisation du support, analyse de documents, tâches par lots et chat court. Le travail de cache rapide accorde généralement plus d’attention aux charges de travail à contexte long et à préfixes répétés. Les invites courtes inférieures aux seuils du fournisseur peuvent ne pas en bénéficier.
3. Présenter les générateurs de préfixes stables
Déplacez une charge de travail de la construction d'invites brutes vers un assemblage basé sur une région. Gardez la demande du fournisseur rendue sémantiquement équivalente. Ne combinez pas cette modification avec une migration de modèle, une refonte des outils ou des réécritures majeures des invites, sinon vous ne saurez pas ce qui a provoqué les modifications des métriques.
4. Canaries un itinéraire
Activez les contrôles de cache pour une petite partie d'un client ou d'une application interne. Comparez le taux de lecture du cache, le taux de désabonnement des préfixes, le délai d'obtention du premier jeton, le taux d'erreur et les catégories de coûts. Évitez de réclamer des économies jusqu'à ce que les factures des fournisseurs soient rapprochées des grands livres de la passerelle.
5. Appliquer progressivement
Après le canari, transformez les avertissements liés aux peluches en contrôles de politique. Par exemple, avertissez d'abord en cas d'ordre d'outils instable, puis rejetez les nouvelles versions de modèles qui incluent des métadonnées volatiles dans le préfixe stable.
Compromis
- Taux de réussite du cache plus élevé par rapport à la flexibilité des invites : les préfixes stables améliorent la réutilisation, mais les équipes devront peut-être déplacer des instructions dynamiques ultérieurement ou reconcevoir les modèles.
- Mise en cache native du fournisseur ou portabilité : l'utilisation des contrôles de cache de chaque fournisseur peut améliorer la rentabilité, mais les seuils, les durées de vie, les champs et la sémantique de tarification diffèrent.
- Observabilité versus journalisation sensible : les différences d'invite facilitent le débogage, mais les hachages et les diagnostics expurgés sont des valeurs par défaut plus sûres.
- Isolement des locataires ou réutilisation maximale : une réutilisation à grande échelle peut sembler attrayante, mais le comportement à l'échelle du locataire est plus sûr et plus facile à expliquer.
- Rétention plus longue par rapport au coût et à la complexité des règles : des options de durée de vie plus longue peuvent faciliter les sessions d'agent, mais peuvent introduire des considérations différentes en matière de tarification et de contrôle des données.
Conclusion exploitable
Traitez la mise en cache des invites comme un problème de plan de contrôle de passerelle, et non comme une case à cocher du fournisseur. Le modèle pratique est le suivant : définir des régions d'invite stables, semi-stables et volatiles ; les rendre de manière déterministe ; adapter les contrôles de cache spécifiques au fournisseur derrière une seule interface ; normaliser l'utilisation du cache dans un grand livre ; exposer les diagnostics d'accès au cache par locataire, application, itinéraire et version de modèle ; et appliquer les hypothèses relatives aux locataires.
La première étape utile n'est pas une réécriture. Ajoutez l'observabilité du cache à vos invites les plus longues, identifiez le taux de désabonnement des préfixes et lintez les modèles à l'origine du plus grand nombre d'échecs. Une fois que vous pouvez expliquer le comportement du cache, vous pouvez l'optimiser en toute sécurité.