Un gateway AI che risponde a partire da ciò che ha già detto
A un assistente di supporto vengono poste tutto il giorno le stesse domande con parole leggermente diverse. Il gateway davanti al suo modello può rispondere a una domanda con la risposta che ha dato a una precedente abbastanza vicina nel significato, anziché chiamare di nuovo il modello. Questo workspace compila un gateway di questo tipo in manifest Kubernetes, insieme allo store in cui conserva quelle risposte.
La Feature che lo fa è core/semantic-caching. Quali risposte prodotte dalla richiesta di un chiamante possano essere servite a un altro chiamante è la domanda a cui questa pagina dedica la maggior parte del suo spazio, perché una cache condivisa dai chiamanti sbagliati consegna a una persona una risposta generata per un’altra.
Questo workspace non scrive alcuna entità di catalogo propria. I tre file di entità qui presenti — un Aggregate, un Manifest e una Release — sono tutto ciò che chiunque scrive.
Che cosa costruisce
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
router | core/gateway/litellm | il gateway AI: un alias di chat, assistant, e un alias di embedding, embedder, ciascuno servito da un modello cablato al suo socket models |
chat | core/ai-model/openai | il modello di chat dietro assistant, l’API di OpenAI stessa, raggiunta come riferimento: per esso non viene eseguito nulla nel cluster |
embeddings | core/ai-model/openai-embedding | il modello di embedding dietro embedder, raggiunto allo stesso modo |
cache | core/datastore/redis | lo store in cui il gateway conserva le sue risposte |
Tre archi uses: due nel socket models del gateway, uno verso ciascun modello, ognuno dei quali porta come sua credential la chiave che il gateway presenta a quel modello, e uno nel suo socket cache_store, che porta come sua credential la password che la cache presenta allo store. Due associazioni di Feature sul gateway: api_key, la sua chiave amministrativa, e answers, la cache; e una sullo store, password, la password che richiede. Entrambe le associazioni di password leggono un solo parametro, cache_password, ed entrambe le credenziali dei modelli un altro, openai_key; la Release li soddisfa entrambi. L’associazione answers nomina l’alias di embedding che trasforma ogni prompt in un vettore, quanto devono somigliarsi due prompt — 0.9, come similarità del coseno — e quanto dura una risposta memorizzata, un’ora. Lascia fuori scope, quindi assume il valore predefinito, end_user.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example ai-gateway-semantic-cachePoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd ai-gateway-semantic-cacheBuild
aggrega build --release release.yaml --auto-pullUna release ha bisogno di un lockfile prima di eseguire il build, e i lockfile sono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno. Risolvine prima uno, oppure lascia che sia il build a crearlo:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildQuesto workspace risolve le entità del catalogo dal registry predefinito nominato da .aggrega-config.yaml. La realizzazione della cache esegue un plugin che non è incluso né nel compilatore né nel catalogo, il passo di configurazione del gateway pipeline-step/litellm-gateway-config, che la risoluzione scarica dal registry nominato da default_registry, hub.aggrega.ai.
Il build stampa, con <workspace> al posto della cartella di questo esempio:
[… 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>/distCon un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `ai-gateway-semantic-cache`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `ai-gateway-semantic-cache` e senza `dir`: scrive l’esempio in una nuova cartella `ai-gateway-semantic-cache`. Poi chiama lo strumento `build` con `workspace_root` impostato su `ai-gateway-semantic-cache`, `release` impostato su `release.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `ai-gateway-semantic-cache/dist/`.L’albero renderizzato
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.yamlL’associazione della cache non porta alcun file proprio. Ciò che fa è scritto nella configurazione del gateway. Ogni modello renderizza un solo file, un Service che mappa un nome interno al cluster sull’host dell’API di OpenAI, e ogni credenziale su una connessione di modello renderizza un proprio Secret, che prende il nome dal gateway e dall’alias della connessione.
I modelli che serve
La tabella di instradamento, l’inizio del corpo della configurazione del gateway, ha una voce per ogni connessione sul socket models, scritta a partire da ciò che ciascun modello pubblica — il suo endpoint, l’URL di base dell’API di OpenAI, e il suo nome di modello — e che nomina la variabile sotto cui la Recipe del gateway consegna la chiave di quella connessione:
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_KEYLa cache, come la legge il gateway
Ecco il corpo della configurazione del gateway, la chiave config.yaml di dist/helm/router/litellm-gateway-config/configmap.yaml, dal suo litellm_settings in poi:
[… 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-semanticCinque cose meritano di essere lette da esso.
L’indirizzo dello store non vi compare. host e port nominano due variabili d’ambiente tramite l’indirezione propria del gateway, e la Recipe del gateway le imposta a partire dall’arco cache_store. Da dist/helm/router-deployment.yaml, l’env del container del gateway:
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 è il Service che emette la Recipe propria dello store, letto da ciò che quella Recipe pubblica, e 6379 la porta che pubblica. La cache legge la password dello store da REDIS_PASSWORD, un riferimento al Secret che renderizza la credential sull’arco cache_store, router-replies.credential, e mai la password stessa. Lo store renderizza un proprio Secret dallo stesso parametro, cache-password, e si avvia con --requirepass letto da esso, quindi la password che la cache presenta e quella che lo store richiede sono un unico valore, scritto una volta sola. Senza un arco cache_store nessuna delle tre variabili sotto cui arrivano l’indirizzo e la password dello store viene renderizzata, e la cache, senza un posto in cui conservare le sue risposte, arresta il build, come si vede più sotto. La terza e la quarta voce sono le chiavi dei modelli, ciascuna referenziata dal Secret che renderizza la credenziale della sua connessione, sotto la variabile nominata dalla sua voce nella tabella di instradamento; il provider helm scrive ogni voce che legge da un Secret prima di quelle semplici.
Il modello di embedding è un alias della mappa propria del gateway. Il gateway invia ogni prompt a embedder attraverso la stessa mappa per cui passa la richiesta di un chiamante, quindi la cache non detiene alcun indirizzo né alcuna credenziale propria. Nomina un alias che la mappa non pubblica e il build si arresta, elencando quelli che pubblica.
La durata è quella dello store. Ogni risposta viene scritta con ttl come scadenza, quindi Redis la rimuove un’ora dopo che è stata memorizzata. La richiesta successiva per quel prompt riceve risposta dal modello, e la risposta viene memorizzata di nuovo.
Sono nominati solo i tipi di richiesta di cui la cache legge il prompt. Le richieste di chat, in streaming o no, e le API responses e messages vengono memorizzate nella cache. Una richiesta completions no, e nemmeno una richiesta di embeddings: lasciato al suo valore predefinito, il gateway memorizzerebbe la risposta a ogni richiesta di embeddings, calcolando per farlo una seconda volta l’embedding di ogni input, e non ne servirebbe nessuna.
L’indice prende il nome dal gateway e dall’associazione, router-answers, quindi due gateway di una stessa Release che condividono uno store conservano le loro risposte in indici separati.
Chi viene servito da una voce della cache
Una risposta memorizzata viene servita a una richiesta successiva solo quando tutto ciò che compone il suo bucket corrisponde, e il prompt ha una somiglianza di almeno 0.9 con quello a cui ha risposto:
- la chiave che la richiesta presenta, così come l’ha verificata il gateway, con il team e l’organizzazione di quella chiave;
- con
end_user, l’utente finale che la richiesta nomina; - il modello che la richiesta chiede, e gli altri parametri della richiesta — una temperatura diversa è un bucket diverso.
Il gateway scrive la chiave, il suo team e la sua organizzazione e l’utente finale nella richiesta stessa. Su una richiesta di chat li scrive nei metadata della richiesta, sopra qualunque valore il chiamante vi abbia inviato; su una richiesta responses o messages li tiene separati dai metadata del chiamante, ne rimuove ogni campo di team, organizzazione o utente finale scritto dal chiamante, e la guardia delle richieste che la sua Recipe fornisce rifiuta una richiesta che vi nomina la chiave, metadata.user_api_key, con un HTTP 400 che nomina il campo. Quindi nessuna richiesta può entrare nel bucket di un’altra chiave semplicemente nominandola.
I metadata propri di una richiesta possono comunque spostarla tra i bucket della chiave che presenta. Su una richiesta responses, model_group prende nel suo bucket il posto del modello che la richiesta chiede. Su una richiesta responses o messages, caching_groups consente alle richieste che nominano lo stesso gruppo di alias di modello di condividere le risposte tra di essi. Su una richiesta responses o di chat, redis_namespace tiene le richieste che nominano un namespace in bucket separati da quelle che non ne nominano nessuno. Nessuno di essi raggiunge il bucket di un’altra chiave.
La chiave di questo gateway è la sua chiave amministrativa, e ogni chiamante la detiene. Non ha alcun database di gestione associato, quindi non emette chiavi proprie: ogni chiamante presenta la chiave associata ad api_key, e una richiesta senza chiave, o con una chiave che il gateway non ha emesso, viene rifiutata prima di qualsiasi ricerca. Qui quindi la chiave non separa alcun chiamante da un altro, e con l’ambito predefinito ciò che tiene separati due chiamanti è l’utente finale che ciascuna richiesta nomina.
Con end_user, il valore predefinito, una voce viene servita alle richieste che nominano lo stesso utente finale. Il gateway legge l’utente finale dalla richiesta: un header x-litellm-end-user-id o x-litellm-customer-id, oppure il campo user, metadata.user_id, litellm_metadata.user o safety_identifier del corpo. Una risposta memorizzata per alice viene servita per la domanda formulata in modo simile di alice, e non per quella di bob.
Ne derivano due cose, ed entrambe sono comportamenti del gateway anziché configurazione:
- Il gateway non verifica nessuno di quei nomi. Chiunque detenga la chiave può nominare qualsiasi utente finale e riceve ciò che è stato memorizzato per quell’utente finale. Tieni la chiave presso l’applicazione che sa chi sono i suoi utenti finali, e lascia che sia lei a nominarli; non consegnare la chiave agli utenti finali stessi.
- Le richieste che non nominano alcun utente finale condividono un’unica cache. Ogni richiesta del genere che presenta la stessa chiave viene servita dalle stesse voci, chiunque l’abbia inviata.
Con key, ogni chiamante che presenta la chiave viene servito da un’unica cache. Aggiungi scope: key ai valori dell’associazione e rifai il build: il semantic_cache_scope della configurazione riporta key, e nient’altro cambia nell’output renderizzato. L’utente finale nominato da un header non fa allora parte del bucket, quindi una risposta memorizzata per l’utente alice, nominato in un header x-litellm-end-user-id, viene servita per la domanda formulata in modo simile di bob che lo nomina allo stesso modo, comprese le chiamate agli strumenti che contiene. Il campo user del corpo è però uno degli altri parametri della richiesta, quindi due richieste che vi nominano utenti finali diversi finiscono comunque in bucket diversi, come fanno due temperature. Questo si addice a una cache di risposte che sono le stesse per tutti, e a nient’altro.
Che cosa arresta il build
Ognuno di questi casi è una frase che il build stampa, e che nomina che cosa cambiare:
-
Nessuna chiave amministrativa. Rimuovi l’associazione
api_keye il build si arresta prima di renderizzare qualsiasi cosa:[… 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" -
Nessuno store. Rimuovi l’arco
cache_storee il build si arresta nominando il socket da cablare. -
Uno store che non pubblica alcun
vector_search. Il socket ammette gli store chiave-valore, e la Recipe del gateway si arresta su uno che non dichiara di servire la ricerca vettoriale del motore di query di Redis, con cui la cache cerca tra le sue risposte: un Redis precedente alla versione 8.0, o Valkey, non memorizzerebbe nulla mentre ogni richiesta continuerebbe a riuscire. -
Una seconda associazione
core/semantic-cachingsul gateway, che ha una sola cache. -
core/data-maskingsullo stesso gateway. Le due dichiarano un conflitto, perché una cache calcola la chiave di una richiesta dopo il mascheramento, quindi due richieste che differiscono solo in ciò che il mascheramento sostituisce condividerebbero un’unica risposta memorizzata.
Quando lo store non può essere usato
Il gateway si connette allo store quando serve la prima richiesta, non quando si avvia. Se non può usare lo store — lo store vuole una password che al gateway non è stata data, oppure rifiuta quella che gli è stata data — ogni ricerca va a vuoto e nulla viene memorizzato, mentre a ogni richiesta continua a rispondere il modello. Solo il log proprio del gateway lo segnala. Ecco perché i due capi della password leggono un solo parametro: lo slot password dello store e la credential sull’arco cache_store.
Dove il compilatore non interpreta
Il compilatore convoglia il nome del Service e la porta dello store dalla Recipe dello store nell’ambiente del gateway come stringhe, e l’alias e i numeri nella configurazione del gateway. Non si connette allo store, non sa se qualcosa risponda a cache-default:6379 e non sa che cosa sia un utente finale. Ogni arresto descritto sopra è dichiarato dalle entità stesse del catalogo, come asserzione nella realizzazione o nella Recipe del gateway o come il conflitto che le due Features dichiarano, e nessuno di essi si basa su una comprensione del traffico.
Adattarlo
- Condividi una cache per chiave. Aggiungi
scope: keyall’associazioneanswers, dove a ogni chiamante devono essere servite le stesse risposte. - Esegui lo store senza password. Rimuovi insieme l’associazione
passworddello store e lacredentialsull’arcocache_store, con il parametrocache_passwordnell’Aggregate e nella Release; ilREDIS_PASSWORDdel gateway viene allora renderizzato vuoto, il che porta a connettersi senza password. Rimuovere solo una delle due associazioni lascia la cache incapace di usare lo store. - Fai corrispondere più o meno prompt. Alza
similarity_thresholdper servire solo corrispondenze più vicine, o abbassalo per servirne di più; quale valore sia adatto dipende dal modello di embedding.