Une passerelle d’IA qui répond à partir de ce qu’elle a déjà dit
Un assistant de support se voit poser les mêmes questions toute la journée en des termes légèrement différents. La passerelle placée devant son modèle peut répondre à une question à partir de la réponse qu’elle a donnée à une question antérieure suffisamment proche par le sens, plutôt que d’appeler à nouveau le modèle. Ce workspace compile une telle passerelle en manifestes Kubernetes, avec le magasin dans lequel elle conserve ces réponses.
La Feature qui s’en charge est core/semantic-caching. Quelles réponses produites par la requête d’un appelant peuvent être servies à un autre appelant, c’est la question à laquelle cette page consacre l’essentiel de sa place, car un cache partagé par les mauvais appelants remet à une personne une réponse générée pour une autre.
Ce workspace ne rédige aucune entité de catalogue qui lui soit propre. Les trois fichiers d’entité présents ici — un Aggregate, un Manifest et une Release — sont tout ce que quiconque écrit.
Ce qu’il construit
| instance | Component du catalogue | ce qu’il est ici |
|---|---|---|
router | core/gateway/litellm | la passerelle d’IA : un alias de chat, assistant, et un alias d’embedding, embedder, chacun servi par un modèle câblé à son socket models |
chat | core/ai-model/openai | le modèle de chat derrière assistant, l’API d’OpenAI elle-même, atteint en tant que référence : rien ne s’exécute pour lui dans le cluster |
embeddings | core/ai-model/openai-embedding | le modèle d’embedding derrière embedder, atteint de la même façon |
cache | core/datastore/redis | le magasin dans lequel la passerelle conserve ses réponses |
Trois arêtes uses : deux vers le socket models de la passerelle, une vers chaque modèle, chacune portant comme credential la clé que la passerelle présente à ce modèle, et une vers son socket cache_store, portant comme credential le mot de passe que le cache présente au magasin. Deux rattachements de Feature sur la passerelle : api_key, sa clé d’administration, et answers, le cache ; et un sur le magasin, password, le mot de passe qu’il exige. Les deux rattachements de mot de passe lisent un même paramètre, cache_password, et les deux informations d’identification des modèles un autre, openai_key ; la Release remplit les deux. Le rattachement answers nomme l’alias d’embedding qui transforme chaque prompt en vecteur, à quel point deux prompts doivent se ressembler — 0.9, en similarité cosinus — et combien de temps dure une réponse stockée, une heure. Il omet scope, donc il prend la valeur par défaut, end_user.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example ai-gateway-semantic-cacheElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd ai-gateway-semantic-cacheBuild
aggrega build --release release.yaml --auto-pullUne release a besoin d’un lockfile avant son build, et les lockfiles sont générés plutôt que livrés, de sorte qu’un clone neuf n’en contient aucun. Résolvez-en un d’abord, ou laissez le build le remplir :
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildCe workspace résout les entités du catalogue depuis le registre par défaut que nomme .aggrega-config.yaml. La réalisation du cache exécute un plugin qui n’est livré ni avec le compilateur ni avec le catalogue, l’étape de configuration de la passerelle pipeline-step/litellm-gateway-config, que la résolution récupère depuis le registre que nomme default_registry, hub.aggrega.ai.
Le build affiche, <workspace> désignant le dossier de cet exemple :
[… omitted: a line reporting on the gateway configuration step's plugin, five warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary and a total build time, which differ per run, and a notice that core/referenced-secret declares origin in both of its pillars]Build completed: 13 files written to <workspace>/distAvec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `ai-gateway-semantic-cache`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `ai-gateway-semantic-cache` et sans `dir` : il écrit l’exemple dans un nouveau dossier `ai-gateway-semantic-cache`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `ai-gateway-semantic-cache`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `ai-gateway-semantic-cache/dist/`.L’arborescence rendue
dist/helm/├── cache--password--cache-secret-cache-password.yaml├── cache-default-service.yaml├── cache-deployment.yaml├── chat-service.yaml├── embeddings-service.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--assistant-zdcredential--router-secret-router-assistant-credential.yaml├── router--embedder-zdcredential--router-secret-router-embedder-credential.yaml├── router--replies-zdcredential--router-secret-router-replies-credential.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlLe rattachement du cache n’apporte aucun fichier à lui. Ce qu’il fait est écrit dans la configuration de la passerelle. Chaque modèle rend un seul fichier, un Service qui fait correspondre un nom interne au cluster à l’hôte de l’API d’OpenAI, et chaque information d’identification sur une connexion de modèle rend un Secret qui lui est propre, nommé d’après la passerelle et l’alias de la connexion.
Les modèles qu’elle sert
La table de routage, le début du corps de configuration de la passerelle, a une entrée par connexion sur le socket models, écrite à partir de ce que publie chaque modèle — son endpoint, l’URL de base de l’API d’OpenAI, et son nom de modèle — et nommant la variable sous laquelle la Recipe de la passerelle livre la clé de cette connexion :
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY - model_name: "embedder" litellm_params: model: "openai/text-embedding-3-small" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_EMBEDDER_API_KEYLe cache, tel que la passerelle le lit
Voici le corps de configuration de la passerelle, la clé config.yaml de dist/helm/router/litellm-gateway-config/configmap.yaml, à partir de son litellm_settings :
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter cache: true cache_params: host: os.environ/SEMANTIC_CACHE_STORE_HOST port: os.environ/SEMANTIC_CACHE_STORE_PORT redis_semantic_cache_embedding_model: embedder redis_semantic_cache_index_name: router-answers semantic_cache_scope: end_user similarity_threshold: 0.9 supported_call_types: - acompletion - completion - aresponses - responses - aanthropic_messages - anthropic_messages ttl: 3600 type: redis-semanticCinq choses méritent d’y être lues.
L’adresse du magasin n’y figure pas. host et port nomment deux variables d’environnement par l’indirection propre à la passerelle, et la Recipe de la passerelle les définit à partir de l’arête cache_store. Extrait de dist/helm/router-deployment.yaml, l’env du conteneur de la passerelle :
env: - name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-key - name: REDIS_PASSWORD valueFrom: secretKeyRef: name: router-replies.credential key: password - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: router-assistant.credential key: api-key - name: LITELLM_MODEL_EMBEDDER_API_KEY valueFrom: secretKeyRef: name: router-embedder.credential key: api-key - name: SEMANTIC_CACHE_STORE_HOST value: cache-default - name: SEMANTIC_CACHE_STORE_PORT value: "6379"cache-default est le Service qu’émet la propre Recipe du magasin, lu dans ce que publie cette Recipe, et 6379 le port qu’elle publie. Le cache lit le mot de passe du magasin dans REDIS_PASSWORD, une référence au Secret que rend la credential sur l’arête cache_store, router-replies.credential, et jamais le mot de passe lui-même. Le magasin rend un Secret qui lui est propre à partir du même paramètre, cache-password, et démarre avec --requirepass lu dans celui-ci, de sorte que le mot de passe que présente le cache et celui qu’exige le magasin sont une seule valeur, écrite une fois. Sans arête cache_store, aucune des trois variables sous lesquelles arrivent l’adresse et le mot de passe du magasin n’est rendue, et le cache, faute d’endroit où conserver ses réponses, arrête le build, comme ci-dessous. Les troisième et quatrième entrées sont les clés des modèles, chacune référencée depuis le Secret que rendent les informations d’identification de sa propre connexion, sous la variable que nomme son entrée dans la table de routage ; le fournisseur helm écrit chaque entrée qu’il lit depuis un Secret avant les entrées simples.
Le modèle d’embedding est un alias de la propre table de la passerelle. La passerelle envoie chaque prompt à embedder via la même table que celle par laquelle passe la requête d’un appelant, si bien que le cache ne détient aucune adresse ni aucune information d’identification qui lui soit propre. Nommez un alias que la table ne publie pas et le build s’arrête, en listant ceux qu’elle publie.
La durée de vie est celle du magasin. Chaque réponse est écrite avec ttl comme expiration, si bien que Redis la supprime une heure après son stockage. La requête suivante pour ce prompt reçoit sa réponse du modèle, qui est stockée à nouveau.
Seules les sortes de requêtes dont le cache lit le prompt sont nommées. Les requêtes de chat, en streaming ou non, et les API responses et messages sont mises en cache. Une requête completions ne l’est pas, ni une requête d’embeddings : laissée à son propre défaut, la passerelle stockerait la réponse à chaque requête d’embeddings, en calculant pour cela une seconde fois l’embedding de chaque entrée, et n’en resservirait aucune.
L’index est nommé d’après la passerelle et le rattachement, router-answers, de sorte que deux passerelles d’une même Release partageant un magasin conservent leurs réponses dans des index distincts.
Qui est servi à partir d’une entrée du cache
Une réponse stockée n’est servie à une requête ultérieure que lorsque tout ce qui compose son compartiment correspond, et que le prompt a une similarité d’au moins 0.9 avec celui auquel elle a répondu :
- la clé que présente la requête, telle que la passerelle l’a vérifiée, avec l’équipe et l’organisation de cette clé ;
- sous
end_user, l’utilisateur final que nomme la requête ; - le modèle que demande la requête, et les autres paramètres de la requête — une température différente est un compartiment différent.
La passerelle écrit la clé, son équipe et son organisation ainsi que l’utilisateur final dans la requête elle-même. Sur une requête de chat, elle les écrit dans les metadata de la requête, par-dessus toute valeur que l’appelant y a envoyée ; sur une requête responses ou messages, elle les tient à l’écart des metadata de l’appelant, en retire tout champ d’équipe, d’organisation ou d’utilisateur final que l’appelant a écrit, et le garde de requêtes que livre sa Recipe refuse une requête qui y nomme la clé, metadata.user_api_key, avec un HTTP 400 nommant le champ. Ainsi, aucune requête ne peut entrer dans le compartiment d’une autre clé en la nommant.
Les propres metadata d’une requête peuvent encore la déplacer entre les compartiments de la clé qu’elle présente. Sur une requête responses, model_group prend dans son compartiment la place du modèle que demande la requête. Sur une requête responses ou messages, caching_groups permet aux requêtes nommant le même groupe d’alias de modèle de partager des réponses entre eux. Sur une requête responses ou de chat, redis_namespace tient les requêtes nommant un namespace dans des compartiments distincts de celles qui n’en nomment aucun. Aucun d’eux n’atteint le compartiment d’une autre clé.
La clé de cette passerelle est sa clé d’administration, et chaque appelant la détient. Aucune base de données de gestion ne lui est rattachée, donc elle n’émet aucune clé à elle : chaque appelant présente la clé rattachée à api_key, et une requête sans clé, ou avec une clé que la passerelle n’a pas émise, est refusée avant toute recherche. Ici, la clé ne sépare donc aucun appelant d’un autre, et dans la portée par défaut, ce qui tient deux appelants à l’écart l’un de l’autre est l’utilisateur final que nomme chaque requête.
Sous end_user, la valeur par défaut, une entrée est servie aux requêtes nommant le même utilisateur final. La passerelle lit l’utilisateur final dans la requête : un en-tête x-litellm-end-user-id ou x-litellm-customer-id, ou le champ user, metadata.user_id, litellm_metadata.user ou safety_identifier du corps. Une réponse stockée pour alice est servie pour la question formulée de manière semblable de alice, et non pour celle de bob.
Il en découle deux choses, et toutes deux relèvent du comportement de la passerelle plutôt que de la configuration :
- La passerelle ne vérifie aucun de ces noms. Quiconque détient la clé peut nommer n’importe quel utilisateur final et se voit servir ce qui a été stocké pour cet utilisateur final. Gardez la clé dans l’application qui sait qui sont ses utilisateurs finaux, et laissez-la les nommer ; ne remettez pas la clé aux utilisateurs finaux eux-mêmes.
- Les requêtes ne nommant aucun utilisateur final partagent un seul cache. Chacune de ces requêtes présentant la même clé est servie à partir des mêmes entrées, quel que soit son expéditeur.
Sous key, chaque appelant présentant la clé est servi à partir d’un seul cache. Ajoutez scope: key aux valeurs du rattachement et relancez le build : le semantic_cache_scope de la configuration indique key, et rien d’autre ne change dans la sortie rendue. L’utilisateur final que nomme un en-tête ne fait alors plus partie du compartiment, si bien qu’une réponse stockée pour alice, nommée dans un en-tête x-litellm-end-user-id, est servie pour la question formulée de manière semblable de bob le nommant de la même façon, appels d’outils qu’elle contient compris. Le champ user du corps est toutefois l’un des autres paramètres de la requête, donc deux requêtes y nommant des utilisateurs finaux différents tombent toujours dans des compartiments différents, comme le font deux températures. Cela convient à un cache de réponses identiques pour tout le monde, et à rien d’autre.
Ce qui arrête le build
Chacun de ces cas est une phrase qu’affiche le build, nommant ce qu’il faut changer :
-
Aucune clé d’administration. Retirez le rattachement
api_keyet le build s’arrête avant que quoi que ce soit ne soit rendu :[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "semantic-caching-litellm" instance "router" assertion "gateway_checks_the_caller": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "router" needs core/gateway/litellm to check every caller's key before a cached reply is served, but its api_key credential slot is not attached, so the gateway checks no caller and a cache bucket would be made only of what each caller claims. Attach a credential to the api_key slot of "router" -
Aucun magasin. Retirez l’arête
cache_storeet le build s’arrête en nommant le socket à câbler. -
Un magasin qui ne publie aucun
vector_search. Le socket admet les magasins clé-valeur, et la Recipe de la passerelle s’arrête sur un magasin qui n’indique pas servir la recherche vectorielle du moteur de requêtes de Redis, avec laquelle le cache recherche parmi ses réponses : un Redis antérieur à la version 8.0, ou Valkey, ne mettrait rien en cache tandis que chaque requête réussirait toujours. -
Un second rattachement
core/semantic-cachingsur la passerelle, qui n’a qu’un seul cache. -
core/data-maskingsur la même passerelle. Les deux déclarent un conflit, car un cache calcule la clé d’une requête après le masquage, si bien que deux requêtes ne différant que par ce que remplace le masquage partageraient une seule réponse stockée.
Lorsque le magasin ne peut pas être utilisé
La passerelle se connecte au magasin lorsqu’elle sert sa première requête, et non à son démarrage. Si elle ne peut pas utiliser le magasin — le magasin exige un mot de passe qui n’a pas été donné à la passerelle, ou refuse celui qui lui a été donné —, chaque recherche échoue et rien n’est stocké, tandis que chaque requête reçoit toujours une réponse du modèle. Seul le journal propre à la passerelle le signale. C’est pourquoi les deux extrémités du mot de passe lisent un même paramètre : l’emplacement password du magasin et la credential sur l’arête cache_store.
Là où le compilateur n’interprète pas
Le compilateur achemine le nom du Service et le port du magasin depuis la Recipe du magasin vers l’environnement de la passerelle sous forme de chaînes, et l’alias et les nombres vers la configuration de la passerelle. Il ne se connecte pas au magasin, ne sait pas si quelque chose répond à cache-default:6379, et ne sait pas ce qu’est un utilisateur final. Chaque arrêt ci-dessus est déclaré par les propres entités du catalogue, comme une assertion dans la réalisation ou dans la Recipe de la passerelle ou comme le conflit que déclarent les deux Features, et aucun d’eux ne repose sur une quelconque compréhension du trafic.
L’adapter
- Partager un cache par clé. Ajoutez
scope: keyau rattachementanswers, là où chaque appelant doit se voir servir les mêmes réponses. - Exécuter le magasin sans mot de passe. Retirez ensemble le rattachement
passworddu magasin et lacredentialsur l’arêtecache_store, avec le paramètrecache_passworddans l’Aggregate et la Release ; leREDIS_PASSWORDde la passerelle est alors rendu vide, ce qui permet de se connecter sans mot de passe. Ne retirer qu’un seul des deux rattachements laisse le cache incapable d’utiliser le magasin. - Faire correspondre plus ou moins de prompts. Augmentez
similarity_thresholdpour ne servir que des correspondances plus proches, ou baissez-le pour en servir davantage ; la valeur qui convient dépend du modèle d’embedding.