Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

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ânciaComponent do catálogoo que é aqui
routercore/gateway/litellmo 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
chatcore/ai-model/openaio 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
embeddingscore/ai-model/openai-embeddingo modelo de embedding por trás de embedder, alcançado da mesma forma
cachecore/datastore/rediso 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:

Terminal window
aggrega scaffold --example ai-gateway-semantic-cache

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd ai-gateway-semantic-cache

Compilação

Terminal window
aggrega build --release release.yaml --auto-pull

Uma 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:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Este 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>/dist

Com 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.yaml

O 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_KEY

A 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-semantic

Há 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_key e 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 assertions
    caused 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_store e 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-caching no gateway, que tem uma única cache.

  • core/data-masking no 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: key ao anexo answers, quando todos os chamadores devam receber as mesmas respostas.
  • Executar o repositório sem palavra-passe. Retirem-se em conjunto o anexo password do repositório e a credential na aresta cache_store, com o parâmetro cache_password no Aggregate e na Release; o REDIS_PASSWORD do 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_threshold para servir apenas correspondências mais próximas, ou diminua-se para servir mais; o valor adequado depende do modelo de embedding.