Ein KI-Gateway, das aus dem antwortet, was es bereits gesagt hat
Einem Support-Assistenten werden den ganzen Tag dieselben Fragen in leicht abgewandelten Worten gestellt. Das Gateway vor seinem Modell kann eine Frage aus der Antwort beantworten, die es auf eine frühere, in der Bedeutung hinreichend ähnliche gegeben hat, statt das Modell erneut aufzurufen. Dieser Workspace kompiliert ein solches Gateway zu Kubernetes-Manifesten, mit dem Store, in dem es diese Antworten aufbewahrt.
Das Feature, das dies tut, ist core/semantic-caching. Welche Antworten, die die Anfrage eines Aufrufers erzeugt hat, einem anderen Aufrufer ausgeliefert werden können, ist die Frage, der diese Seite den größten Teil ihres Raums widmet, denn ein von den falschen Aufrufern geteilter Cache gibt einer Person eine Antwort, die für eine andere erzeugt wurde.
Dieser Workspace schreibt keine eigene Katalogentität. Die drei Entitätsdateien hier — ein Aggregate, ein Manifest und ein Release — sind alles, was irgendjemand schreibt.
Was es baut
| Instanz | Katalog-Component | was es hier ist |
|---|---|---|
router | core/gateway/litellm | das KI-Gateway: ein Chat-Alias, assistant, und ein Embedding-Alias, embedder, jeder bereitgestellt von einem Modell, das mit seinem Socket models verdrahtet ist |
chat | core/ai-model/openai | das Chat-Modell hinter assistant, die eigene API von OpenAI, als Referenz erreicht: Dafür läuft nichts im Cluster |
embeddings | core/ai-model/openai-embedding | das Embedding-Modell hinter embedder, auf dieselbe Weise erreicht |
cache | core/datastore/redis | der Store, in dem das Gateway seine Antworten aufbewahrt |
Drei uses-Kanten: zwei in den Socket models des Gateways, eine zu jedem Modell, die jeweils als ihre credential den Schlüssel tragen, den das Gateway diesem Modell vorlegt, und eine in seinen Socket cache_store, die als ihre credential das Passwort trägt, das der Cache dem Store vorlegt. Zwei Feature-Anbindungen am Gateway: api_key, sein Administrationsschlüssel, und answers, der Cache; und eine am Store, password, das Passwort, das er verlangt. Beide Passwort-Anbindungen lesen einen Parameter, cache_password, und beide Modell-Zugangsdaten einen anderen, openai_key; das Release erfüllt beide. Die Anbindung answers nennt den Embedding-Alias, der jeden Prompt in einen Vektor umwandelt, wie ähnlich sich zwei Prompts sein müssen — 0.9, als Kosinusähnlichkeit — und wie lange eine gespeicherte Antwort gültig bleibt, eine Stunde. Sie lässt scope weg und erhält daher die Voreinstellung, end_user.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example ai-gateway-semantic-cacheDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd ai-gateway-semantic-cacheBuild
aggrega build --release release.yaml --auto-pullEin Release braucht ein Lockfile, bevor es baut, und Lockfiles werden erzeugt statt mitgeliefert, daher hat ein frischer Klon keines. Lösen Sie zuerst eines auf, oder lassen Sie den Build es füllen:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildDieser Workspace löst die Katalogentitäten aus der Standard-Registry auf, die .aggrega-config.yaml nennt. Die Realisierung des Caches führt ein Plugin aus, das weder im Compiler noch im Katalog mitgeliefert wird, den Gateway-Konfigurationsschritt pipeline-step/litellm-gateway-config, den die Auflösung aus der Registry abruft, die default_registry nennt, hub.aggrega.ai.
Der Build gibt aus, wobei <workspace> für den Ordner dieses Beispiels steht:
[… 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>/distMit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `ai-gateway-semantic-cache` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `ai-gateway-semantic-cache` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `ai-gateway-semantic-cache`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `ai-gateway-semantic-cache`, `release` auf `release.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `ai-gateway-semantic-cache/dist/`.Der gerenderte Baum
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.yamlDie Cache-Anbindung bringt keine eigene Datei mit. Was sie tut, wird in die Konfiguration des Gateways geschrieben. Jedes Modell rendert eine Datei, einen Service, der einen clusterinternen Namen auf den API-Host von OpenAI abbildet, und jeder Satz Zugangsdaten an einer Modellverbindung rendert ein eigenes Secret, benannt nach dem Gateway und dem Alias der Verbindung.
Die Modelle, die es bedient
Die Routing-Tabelle, der Anfang des Konfigurationsinhalts des Gateways, hat einen Eintrag je Verbindung am Socket models, geschrieben aus dem, was jedes Modell veröffentlicht — seinem Endpunkt, der API-Basis-URL von OpenAI, und seinem Modellnamen —, und nennt die Variable, unter der das Recipe des Gateways den Schlüssel dieser Verbindung zustellt:
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_KEYDer Cache, wie das Gateway ihn liest
Hier ist der Konfigurationsinhalt des Gateways, der Schlüssel config.yaml von dist/helm/router/litellm-gateway-config/configmap.yaml, ab seinem 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-semanticFünf Dinge lohnt es sich daraus abzulesen.
Die Adresse des Stores steht nicht darin. host und port nennen über die eigene Indirektion des Gateways zwei Umgebungsvariablen, und das Recipe des Gateways setzt diese aus der Kante cache_store. Aus dist/helm/router-deployment.yaml, die env des Containers des Gateways:
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 ist der Service, den das eigene Recipe des Stores emittiert, abgelesen aus dem, was dieses Recipe veröffentlicht, und 6379 der Port, den es veröffentlicht. Der Cache liest das Passwort des Stores aus REDIS_PASSWORD, einer Referenz auf das Secret, das die credential an der Kante cache_store rendert, router-replies.credential, und nie das Passwort selbst. Der Store rendert aus demselben Parameter ein eigenes Secret, cache-password, und startet mit --requirepass, das daraus gelesen wird, sodass das Passwort, das der Cache vorlegt, und das, das der Store verlangt, ein einziger Wert sind, einmal geschrieben. Ohne eine Kante cache_store wird keine der drei Variablen gerendert, unter denen Adresse und Passwort des Stores ankommen, und der Cache, der seine Antworten nirgends aufbewahren kann, bricht den Build ab, wie unten gezeigt. Der dritte und der vierte Eintrag sind die Schlüssel der Modelle, jeder referenziert aus dem Secret, das die Zugangsdaten seiner eigenen Verbindung rendern, unter der Variable, die sein Eintrag in der Routing-Tabelle nennt; der Provider helm schreibt jeden Eintrag, den er aus einem Secret liest, vor die einfachen.
Das Embedding-Modell ist ein Alias der eigenen Map des Gateways. Das Gateway sendet jeden Prompt über dieselbe Map an embedder, die auch die Anfrage eines Aufrufers durchläuft, daher hält der Cache weder eine eigene Adresse noch eigene Zugangsdaten. Nennen Sie einen Alias, den die Map nicht veröffentlicht, und der Build bricht ab und listet die auf, die sie veröffentlicht.
Die Lebensdauer ist die des Stores. Jede Antwort wird mit ttl als Ablaufzeit geschrieben, daher entfernt Redis sie eine Stunde nach dem Speichern. Die nächste Anfrage für diesen Prompt wird vom Modell beantwortet und neu gespeichert.
Nur die Arten von Anfragen, deren Prompt der Cache liest, werden genannt. Chat-Anfragen, gestreamt oder nicht, sowie die APIs responses und messages werden zwischengespeichert. Eine completions-Anfrage nicht, und ebenso wenig eine Embeddings-Anfrage: Bei seiner eigenen Voreinstellung würde das Gateway die Antwort auf jede Embeddings-Anfrage speichern, dafür jede Eingabe ein zweites Mal einbetten und keine davon wieder ausliefern.
Der Index ist nach dem Gateway und der Anbindung benannt, router-answers, sodass zwei Gateways eines Release, die sich einen Store teilen, ihre Antworten in getrennten Indizes aufbewahren.
Wer aus einem Cache-Eintrag bedient wird
Eine gespeicherte Antwort wird einer späteren Anfrage nur ausgeliefert, wenn alles, was ihren Bucket ausmacht, übereinstimmt und der Prompt dem, den sie beantwortet hat, zu mindestens 0.9 ähnlich ist:
- der Schlüssel, den die Anfrage vorlegt, so wie das Gateway ihn geprüft hat, mit Team und Organisation dieses Schlüssels;
- unter
end_userder Endbenutzer, den die Anfrage nennt; - das Modell, das die Anfrage anfordert, und die übrigen Parameter der Anfrage — eine andere Temperatur ist ein anderer Bucket.
Das Gateway schreibt den Schlüssel, sein Team und seine Organisation sowie den Endbenutzer in die Anfrage selbst. Bei einer Chat-Anfrage schreibt es sie in die metadata der Anfrage, über jeden Wert, den der Aufrufer dort gesendet hat; bei einer responses- oder messages-Anfrage hält es sie von den metadata des Aufrufers getrennt, entfernt daraus jedes Feld für Team, Organisation oder Endbenutzer, das der Aufrufer geschrieben hat, und der Anfragewächter, den sein Recipe zustellt, weist eine Anfrage, die dort den Schlüssel nennt, metadata.user_api_key, mit HTTP 400 zurück und nennt dabei das Feld. So kann sich keine Anfrage per Namensangabe in den Bucket eines anderen Schlüssels bringen.
Die eigenen metadata einer Anfrage können sie trotzdem zwischen den Buckets des Schlüssels verschieben, den sie vorlegt. Bei einer responses-Anfrage tritt model_group in ihrem Bucket an die Stelle des Modells, das die Anfrage anfordert. Bei einer responses- oder messages-Anfrage lässt caching_groups Anfragen, die dieselbe Gruppe von Modell-Aliasen nennen, Antworten über diese hinweg teilen. Bei einer responses- oder Chat-Anfrage hält redis_namespace Anfragen, die einen Namespace nennen, in anderen Buckets als die, die keinen nennen. Keines davon erreicht den Bucket eines anderen Schlüssels.
Der Schlüssel dieses Gateways ist sein Administrationsschlüssel, und jeder Aufrufer hält ihn. Es ist keine Verwaltungsdatenbank angebunden, daher gibt es keine eigenen Schlüssel aus: Jeder Aufrufer legt den an api_key angebundenen Schlüssel vor, und eine Anfrage ohne Schlüssel oder mit einem Schlüssel, den das Gateway nicht ausgegeben hat, wird zurückgewiesen, bevor irgendetwas nachgeschlagen wird. Der Schlüssel trennt hier also keinen Aufrufer vom anderen, und unter dem Standardbereich ist es der Endbenutzer, den jede Anfrage nennt, der zwei Aufrufer auseinanderhält.
Unter end_user, der Voreinstellung, wird ein Eintrag an Anfragen ausgeliefert, die denselben Endbenutzer nennen. Das Gateway liest den Endbenutzer aus der Anfrage: einen Header x-litellm-end-user-id oder x-litellm-customer-id oder das Feld user, metadata.user_id, litellm_metadata.user oder safety_identifier des Körpers. Eine für alice gespeicherte Antwort wird für die ähnlich formulierte Frage von alice ausgeliefert, nicht für die von bob.
Daraus folgen zwei Dinge, und beide sind Verhalten des Gateways, nicht Konfiguration:
- Das Gateway prüft keinen dieser Namen. Wer den Schlüssel hält, kann jeden beliebigen Endbenutzer nennen und erhält, was für diesen Endbenutzer gespeichert wurde. Belassen Sie den Schlüssel bei der Anwendung, die weiß, wer ihre Endbenutzer sind, und lassen Sie sie diese nennen; geben Sie den Schlüssel nicht an die Endbenutzer selbst weiter.
- Anfragen, die keinen Endbenutzer nennen, teilen sich einen Cache. Jede solche Anfrage, die denselben Schlüssel vorlegt, wird aus denselben Einträgen bedient, wer auch immer sie gesendet hat.
Unter key wird jeder Aufrufer, der den Schlüssel vorlegt, aus einem Cache bedient. Fügen Sie scope: key den Werten der Anbindung hinzu und bauen Sie neu: semantic_cache_scope der Konfiguration lautet key, und sonst ändert sich nichts in der gerenderten Ausgabe. Der Endbenutzer, den ein Header nennt, ist dann kein Teil des Buckets, sodass eine für alice gespeicherte Antwort, in einem Header x-litellm-end-user-id genannt, für die ähnlich formulierte Frage von bob ausgeliefert wird, die ihn auf dieselbe Weise nennt, einschließlich der Tool-Calls darin. Das Feld user des Körpers ist allerdings einer der übrigen Parameter der Anfrage, sodass zwei Anfragen, die dort verschiedene Endbenutzer nennen, weiterhin in verschiedene Buckets fallen, wie es zwei Temperaturen tun. Das passt zu einem Cache von Antworten, die für alle gleich sind, und zu nichts anderem.
Was den Build abbricht
Jeder dieser Fälle ist ein Satz, den der Build ausgibt und der nennt, was zu ändern ist:
-
Kein Administrationsschlüssel. Entfernen Sie die Anbindung
api_key, und der Build bricht ab, bevor irgendetwas gerendert wird:[… 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" -
Kein Store. Entfernen Sie die Kante
cache_store, und der Build bricht ab und nennt den Socket, der zu verdrahten ist. -
Ein Store, der kein
vector_searchveröffentlicht. Der Socket lässt die Key-Value-Stores zu, und das Recipe des Gateways bricht bei einem ab, der nicht angibt, dass er die Vektorsuche der Redis-Query-Engine bedient, mit der der Cache seine Antworten durchsucht: Ein Redis vor Version 8.0 oder Valkey würde nichts zwischenspeichern, während jede Anfrage weiterhin gelänge. -
Eine zweite Anbindung
core/semantic-cachingam Gateway, das einen einzigen Cache hat. -
core/data-maskingam selben Gateway. Die beiden deklarieren einen Konflikt, weil ein Cache den Schlüssel einer Anfrage nach der Maskierung bildet, sodass zwei Anfragen, die sich nur in dem unterscheiden, was die Maskierung ersetzt, eine gespeicherte Antwort teilen würden.
Wenn der Store nicht nutzbar ist
Das Gateway verbindet sich mit dem Store, wenn es die erste Anfrage bedient, nicht beim Start. Kann es den Store nicht nutzen — der Store verlangt ein Passwort, das das Gateway nicht erhalten hat, oder weist das zurück, das es erhalten hat —, geht jede Suche ins Leere und nichts wird gespeichert, während jede Anfrage weiterhin vom Modell beantwortet wird. Nur das eigene Log des Gateways sagt das. Deshalb lesen die beiden Enden des Passworts einen Parameter: der Slot password des Stores und die credential an der Kante cache_store.
Wo der Compiler nicht interpretiert
Der Compiler leitet den Service-Namen und den Port des Stores aus dem Recipe des Stores als Strings in die Umgebung des Gateways weiter, und den Alias und die Zahlen in die Konfiguration des Gateways. Er verbindet sich nicht mit dem Store, weiß nicht, ob unter cache-default:6379 etwas antwortet, und weiß nicht, was ein Endbenutzer ist. Jeder Abbruch oben wird von den eigenen Entitäten des Katalogs deklariert, als Assertion in der Realisierung oder im Recipe des Gateways oder als der Konflikt, den die beiden Features deklarieren, und keiner davon beruht auf irgendeinem Verständnis des Datenverkehrs.
Anpassen
- Einen Cache pro Schlüssel teilen. Fügen Sie
scope: keyzur Anbindunganswershinzu, wo jeder Aufrufer dieselben Antworten erhalten soll. - Den Store ohne Passwort betreiben. Entfernen Sie die Anbindung
passworddes Stores und diecredentialan der Kantecache_storegemeinsam, zusammen mit dem Parametercache_passwordim Aggregate und im Release;REDIS_PASSWORDdes Gateways wird dann leer gerendert, womit die Verbindung ohne Passwort hergestellt wird. Entfernt man nur eine der beiden Anbindungen, kann der Cache den Store nicht nutzen. - Mehr oder weniger Prompts treffen. Erhöhen Sie
similarity_threshold, um nur nähere Treffer auszuliefern, oder senken Sie ihn, um mehr auszuliefern; welcher Wert passt, hängt vom Embedding-Modell ab.