Um gateway de IA que responde a partir do que já disse
A um assistente de apoio são feitas as mesmas perguntas durante todo o dia, com palavras ligeiramente diferentes. O gateway à frente do seu modelo pode responder a uma pergunta a partir da resposta que deu a uma anterior suficientemente próxima no significado, em vez de voltar a chamar o modelo. Este workspace compila um gateway deste tipo para manifestos Kubernetes, com o repositório em que guarda essas respostas.
A Feature que o faz é core/semantic-caching. Que respostas produzidas pelo pedido de um chamador podem ser servidas a outro chamador é a questão a que esta página dedica a maior parte do seu espaço, porque uma cache partilhada pelos chamadores errados entrega a uma pessoa uma resposta gerada para outra.
Este workspace não cria nenhuma entidade de catálogo própria. Os três ficheiros de entidade aqui presentes — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
router | core/gateway/litellm | o gateway de IA: um alias de chat, assistant, e um alias de embedding, embedder, cada um servido a partir de um modelo ligado ao seu socket models |
chat | core/ai-model/openai | o modelo de chat por trás de assistant, a própria API da OpenAI, alcançado como referência: nada é executado para ele no cluster |
embeddings | core/ai-model/openai-embedding | o modelo de embedding por trás de embedder, alcançado da mesma forma |
cache | core/datastore/redis | o repositório em que o gateway guarda as suas respostas |
Três arestas uses: duas para o socket models do gateway, uma para cada modelo, cada uma a transportar como sua credential a chave que o gateway apresenta a esse modelo, e uma para o seu socket cache_store, que transporta como sua credential a palavra-passe que a cache apresenta ao repositório. Dois anexos de Feature no gateway: api_key, a sua chave administrativa, e answers, a cache; e um no repositório, password, a palavra-passe que este exige. Os dois anexos de palavra-passe leem um mesmo parâmetro, cache_password, e as duas credenciais dos modelos outro, openai_key; a Release satisfaz ambos. O anexo answers nomeia o alias de embedding que transforma cada prompt num vetor, quão semelhantes têm de ser dois prompts — 0.9, como semelhança de cosseno — e quanto tempo dura uma resposta guardada, uma hora. Omite scope, pelo que assume a predefinição, end_user.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example ai-gateway-semantic-cacheDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd ai-gateway-semantic-cacheCompilação
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de ser compilada, e os lockfiles são gerados em vez de distribuídos, pelo que um clone novo não tem nenhum. Resolva-se um primeiro, ou deixe-se que a compilação o preencha:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resolve as entidades do catálogo a partir do registo predefinido que .aggrega-config.yaml nomeia. A realização da cache executa um plugin que não vem nem no compilador nem no catálogo, o passo de configuração do gateway pipeline-step/litellm-gateway-config, que a resolução obtém do registo que default_registry nomeia, hub.aggrega.ai.
A compilação imprime, com <workspace> a representar a pasta deste exemplo:
[… 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>/distCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho ainda não contiver uma pasta `ai-gateway-semantic-cache`, chame a ferramenta `scaffold` uma única vez com `example` definido como `ai-gateway-semantic-cache` e sem `dir`: esta escreve o exemplo numa nova pasta `ai-gateway-semantic-cache`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `ai-gateway-semantic-cache`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me que ficheiros a compilação escreveu; encontram-se em `ai-gateway-semantic-cache/dist/`.A árvore renderizada
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.yamlO anexo da cache não traz nenhum ficheiro próprio. O que faz é escrito na configuração do gateway. Cada modelo renderiza um único ficheiro, um Service que mapeia um nome interno do cluster para o anfitrião da API da OpenAI, e cada credencial numa ligação de modelo renderiza um Secret próprio, com o nome do gateway e do alias da ligação.
Os modelos que serve
A tabela de encaminhamento, o início do corpo de configuração do gateway, tem uma entrada por ligação no socket models, escrita a partir do que cada modelo publica — o seu endpoint, o URL base da API da OpenAI, e o seu nome de modelo — e que nomeia a variável sob a qual a Recipe do gateway entrega a chave dessa ligação:
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_KEYA cache, tal como o gateway a lê
Eis o corpo de configuração do gateway, a chave config.yaml de dist/helm/router/litellm-gateway-config/configmap.yaml, a partir do seu 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-semanticHá cinco coisas que vale a pena ler nele.
O endereço do repositório não está nele. host e port nomeiam duas variáveis de ambiente através da indireção própria do gateway, e a Recipe do gateway define-as a partir da aresta cache_store. De dist/helm/router-deployment.yaml, o env do contentor do 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 é o Service que a própria Recipe do repositório emite, lido do que essa Recipe publica, e 6379 a porta que publica. A cache lê a palavra-passe do repositório de REDIS_PASSWORD, uma referência ao Secret que a credential na aresta cache_store renderiza, router-replies.credential, e nunca a própria palavra-passe. O repositório renderiza um Secret próprio a partir do mesmo parâmetro, cache-password, e arranca com --requirepass lido dele, pelo que a palavra-passe que a cache apresenta e a que o repositório exige são um único valor, escrito uma só vez. Sem uma aresta cache_store, nenhuma das três variáveis sob as quais chegam o endereço e a palavra-passe do repositório é renderizada, e a cache, sem onde guardar as suas respostas, interrompe a compilação, como se vê abaixo. A terceira e a quarta entradas são as chaves dos modelos, cada uma referenciada a partir do Secret que a credencial da sua própria ligação renderiza, sob a variável que a sua entrada na tabela de encaminhamento nomeia; o fornecedor helm escreve cada entrada que lê de um Secret antes das simples.
O modelo de embedding é um alias do próprio mapa do gateway. O gateway envia cada prompt para embedder através do mesmo mapa por onde passa o pedido de um chamador, pelo que a cache não detém nenhum endereço nem credencial própria. Ao nomear um alias que o mapa não publica, a compilação é interrompida, listando os que publica.
O tempo de vida é o do repositório. Cada resposta é escrita com ttl como expiração, pelo que o Redis a remove uma hora depois de ter sido guardada. O pedido seguinte para esse prompt é respondido pelo modelo, e a resposta é guardada de novo.
Só são nomeados os tipos de pedido cujo prompt a cache lê. Os pedidos de chat, em streaming ou não, e as APIs responses e messages são guardados em cache. Um pedido completions não é, nem um pedido de embeddings: deixado na sua própria predefinição, o gateway guardaria a resposta a todos os pedidos de embeddings, gerando para isso uma segunda vez o embedding de cada entrada, e não serviria nenhuma delas de volta.
O índice tem o nome do gateway e do anexo, router-answers, pelo que dois gateways de uma mesma Release que partilhem um repositório guardam as suas respostas em índices separados.
Quem é servido a partir de uma entrada da cache
Uma resposta guardada só é servida a um pedido posterior quando tudo o que compõe o seu compartimento corresponde, e o prompt tem uma semelhança de pelo menos 0.9 com aquele a que respondeu:
- a chave que o pedido apresenta, tal como o gateway a verificou, com a equipa e a organização dessa chave;
- com
end_user, o utilizador final que o pedido nomeia; - o modelo que o pedido solicita, e os outros parâmetros do pedido — uma temperatura diferente é um compartimento diferente.
O gateway escreve a chave, a sua equipa e organização e o utilizador final no próprio pedido. Num pedido de chat, escreve-os nos metadata do pedido, por cima de qualquer valor que o chamador lá tenha enviado; num pedido responses ou messages, mantém-nos separados dos metadata do chamador, remove deles qualquer campo de equipa, organização ou utilizador final que o chamador tenha escrito, e a guarda de pedidos que a sua Recipe entrega recusa um pedido que nomeie lá a chave, metadata.user_api_key, com HTTP 400 a nomear o campo. Assim, nenhum pedido consegue entrar no compartimento de outra chave apenas por a nomear.
Os próprios metadata de um pedido podem ainda movê-lo entre os compartimentos da chave que apresenta. Num pedido responses, model_group ocupa no seu compartimento o lugar do modelo que o pedido solicita. Num pedido responses ou messages, caching_groups permite que pedidos que nomeiam o mesmo grupo de aliases de modelo partilhem respostas entre eles. Num pedido responses ou de chat, redis_namespace mantém os pedidos que nomeiam um namespace em compartimentos separados dos que não nomeiam nenhum. Nenhum deles chega ao compartimento de outra chave.
A chave deste gateway é a sua chave administrativa, e todos os chamadores a detêm. Não tem nenhuma base de dados de gestão anexada, pelo que não emite chaves próprias: todos os chamadores apresentam a chave anexada a api_key, e um pedido sem chave, ou com uma chave que o gateway não emitiu, é recusado antes de qualquer consulta. Aqui, portanto, a chave não separa nenhum chamador de outro, e com o âmbito predefinido o que mantém dois chamadores separados é o utilizador final que cada pedido nomeia.
Com end_user, a predefinição, uma entrada é servida a pedidos que nomeiam o mesmo utilizador final. O gateway lê o utilizador final do pedido: um cabeçalho x-litellm-end-user-id ou x-litellm-customer-id, ou o campo user, metadata.user_id, litellm_metadata.user ou safety_identifier do corpo. Uma resposta guardada para alice é servida para a pergunta de alice formulada de modo semelhante, e não para a de bob.
Daí decorrem duas coisas, e ambas são comportamento do gateway e não configuração:
- O gateway não verifica nenhum desses nomes. Quem detiver a chave pode nomear qualquer utilizador final e recebe o que foi guardado para esse utilizador final. Mantenha-se a chave na aplicação que sabe quem são os seus utilizadores finais, e deixe-se que seja ela a nomeá-los; não se entregue a chave aos próprios utilizadores finais.
- Os pedidos que não nomeiam nenhum utilizador final partilham uma única cache. Todos esses pedidos que apresentem a mesma chave são servidos a partir das mesmas entradas, seja quem for que os enviou.
Com key, todos os chamadores que apresentam a chave são servidos a partir de uma única cache. Acrescente-se scope: key aos valores do anexo e volte-se a compilar: o semantic_cache_scope da configuração passa a indicar key, e nada mais muda na saída renderizada. O utilizador final que um cabeçalho nomeia deixa então de fazer parte do compartimento, pelo que uma resposta guardada para alice, nomeada num cabeçalho x-litellm-end-user-id, é servida para a pergunta de bob formulada de modo semelhante que o nomeie da mesma forma, incluindo as chamadas a ferramentas que contenha. O campo user do corpo é, no entanto, um dos outros parâmetros do pedido, pelo que dois pedidos que aí nomeiem utilizadores finais diferentes continuam a cair em compartimentos diferentes, como acontece com duas temperaturas. Isso convém a uma cache de respostas que são as mesmas para todos, e a nada mais.
O que interrompe a compilação
Cada um destes casos é uma frase que a compilação imprime, a nomear o que alterar:
-
Nenhuma chave administrativa. Retire-se o anexo
api_keye a compilação é interrompida antes de qualquer coisa ser renderizada:[… 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" -
Nenhum repositório. Retire-se a aresta
cache_storee a compilação é interrompida, nomeando o socket a ligar. -
Um repositório que não publica nenhum
vector_search. O socket admite os repositórios chave-valor, e a Recipe do gateway é interrompida perante um que não declare servir a pesquisa vetorial do motor de consultas do Redis, com a qual a cache pesquisa as suas respostas: um Redis anterior à versão 8.0, ou o Valkey, não guardaria nada enquanto todos os pedidos continuariam a ter êxito. -
Um segundo anexo
core/semantic-cachingno gateway, que tem uma única cache. -
core/data-maskingno mesmo gateway. As duas declaram um conflito, porque uma cache calcula a chave de um pedido depois do mascaramento, pelo que dois pedidos que difiram apenas no que o mascaramento substitui partilhariam uma única resposta guardada.
Quando o repositório não pode ser utilizado
O gateway liga-se ao repositório quando serve o primeiro pedido, e não quando arranca. Se não conseguir utilizar o repositório — o repositório exige uma palavra-passe que não foi dada ao gateway, ou recusa a que foi dada —, todas as pesquisas falham e nada é guardado, enquanto todos os pedidos continuam a ser respondidos pelo modelo. Só o registo próprio do gateway o indica. É por isso que as duas pontas da palavra-passe leem um mesmo parâmetro: o slot password do repositório e a credential na aresta cache_store.
Onde o compilador não interpreta
O compilador canaliza o nome do Service e a porta do repositório da Recipe do repositório para o ambiente do gateway como strings, e o alias e os números para a configuração do gateway. Não se liga ao repositório, não sabe se algo responde em cache-default:6379, e não sabe o que é um utilizador final. Cada interrupção acima é declarada pelas próprias entidades do catálogo, como uma asserção na realização ou na Recipe do gateway ou como o conflito que as duas Features declaram, e nenhuma delas assenta em qualquer compreensão do tráfego.
Adaptá-lo
- Partilhar uma cache por chave. Acrescente-se
scope: keyao anexoanswers, quando todos os chamadores devam receber as mesmas respostas. - Executar o repositório sem palavra-passe. Retirem-se em conjunto o anexo
passworddo repositório e acredentialna arestacache_store, com o parâmetrocache_passwordno Aggregate e na Release; oREDIS_PASSWORDdo gateway é então renderizado vazio, o que faz a ligação sem palavra-passe. Retirar apenas um dos dois anexos deixa a cache sem conseguir utilizar o repositório. - Corresponder a mais ou menos prompts. Aumente-se
similarity_thresholdpara servir apenas correspondências mais próximas, ou diminua-se para servir mais; o valor adequado depende do modelo de embedding.