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

Um gateway de IA que responde a partir do que já disse

Um assistente de suporte recebe as mesmas perguntas o dia todo, com palavras ligeiramente diferentes. O gateway na frente do seu modelo pode responder a uma pergunta a partir da resposta que deu a uma anterior próxima o bastante no significado, em vez de chamar o modelo de novo. Este workspace compila um gateway assim para manifestos Kubernetes, com o repositório em que ele guarda essas respostas.

A Feature que faz isso é core/semantic-caching. Quais respostas produzidas pela requisição de um chamador podem ser servidas a outro chamador é a questão à qual esta página dedica a maior parte do seu espaço, porque um cache compartilhado 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 arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.

O que ele 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 carregando como sua credential a chave que o gateway apresenta a esse modelo, e uma para o seu socket cache_store, carregando como sua credential a senha que o cache apresenta ao repositório. Duas vinculações de Feature no gateway: api_key, a sua chave administrativa, e answers, o cache; e uma no repositório, password, a senha que ele exige. As duas vinculações de senha leem um mesmo parâmetro, cache_password, e as duas credenciais dos modelos outro, openai_key; a Release preenche ambos. A vinculação answers nomeia o alias de embedding que transforma cada prompt em um vetor, o quanto dois prompts devem se parecer — 0.9, como similaridade de cosseno — e quanto tempo dura uma resposta armazenada, uma hora. Ela omite scope, então assume o padrão, end_user.

Gerar o exemplo

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd ai-gateway-semantic-cache

Build

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

Uma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:

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 registro padrão que .aggrega-config.yaml nomeia. A realização do cache executa um plugin que não vem nem no compilador nem no catálogo, a etapa de configuração do gateway pipeline-step/litellm-gateway-config, que a resolução obtém do registro que default_registry nomeia, hub.aggrega.ai.

O build imprime, com <workspace> representando 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 este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace 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`: ela escreve o exemplo em uma 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 quais arquivos o build escreveu; eles ficam 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

A vinculação do cache não traz nenhum arquivo próprio. O que ela faz é escrito na configuração do gateway. Cada modelo renderiza um arquivo, um Service que mapeia um nome interno do cluster para o host da API da OpenAI, e cada credencial em uma conexão de modelo renderiza um Secret próprio, nomeado a partir do gateway e do alias da conexão.

Os modelos que ele serve

A tabela de roteamento, o início do corpo de configuração do gateway, tem uma entrada por conexão no socket models, escrita a partir do que cada modelo publica — o seu endpoint, a 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 conexã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

O cache, como o gateway o lê

Aqui está 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

Cinco coisas valem a pena ser lidas nele.

O endereço do repositório não está nele. host e port nomeiam duas variáveis de ambiente por meio da indireção própria do gateway, e a Recipe do gateway as define a partir da aresta cache_store. De dist/helm/router-deployment.yaml, o env do contêiner 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 ela publica. O cache lê a senha 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 senha. O repositório renderiza um Secret próprio a partir do mesmo parâmetro, cache-password, e inicia com --requirepass lido dele, então a senha que o 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 senha do repositório é renderizada, e o cache, sem onde guardar as suas respostas, interrompe o build, como mostrado 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 conexão renderiza, sob a variável que a sua entrada na tabela de roteamento nomeia; o provedor 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 a embedder pelo mesmo mapa pelo qual passa a requisição de um chamador, então o cache não detém nenhum endereço nem credencial própria. Nomeie um alias que o mapa não publica e o build é interrompido, listando os que ele publica.

O tempo de vida é o do repositório. Cada resposta é escrita com ttl como expiração, então o Redis a remove uma hora depois de ser armazenada. A próxima requisição para esse prompt é respondida pelo modelo, e a resposta é armazenada de novo.

Só são nomeados os tipos de requisição cujo prompt o cache lê. Requisições de chat, em streaming ou não, e as APIs responses e messages são armazenadas em cache. Uma requisição completions não é, e nem uma requisição de embeddings: deixado no seu próprio padrão, o gateway armazenaria a resposta a toda requisição de embeddings, gerando para isso uma segunda vez o embedding de cada entrada, e não serviria nenhuma delas de volta.

O índice é nomeado a partir do gateway e da vinculação, router-answers, então dois gateways de uma mesma Release que compartilham um repositório guardam as suas respostas em índices separados.

Quem é servido a partir de uma entrada do cache

Uma resposta armazenada é servida a uma requisição posterior somente quando tudo o que compõe o seu bucket corresponde, e o prompt tem similaridade de pelo menos 0.9 com aquele ao qual ela respondeu:

  • a chave que a requisição apresenta, como o gateway a verificou, com a equipe e a organização dessa chave;
  • com end_user, o usuário final que a requisição nomeia;
  • o modelo que a requisição pede, e os outros parâmetros da requisição — uma temperatura diferente é um bucket diferente.

O gateway escreve a chave, a sua equipe e organização e o usuário final na própria requisição. Em uma requisição de chat, ele os escreve nos metadata da requisição, por cima de qualquer valor que o chamador tenha enviado ali; em uma requisição responses ou messages, ele os mantém separados dos metadata do chamador, remove deles qualquer campo de equipe, organização ou usuário final que o chamador escreveu, e a guarda de requisições que a sua Recipe entrega recusa uma requisição que nomeie a chave ali, metadata.user_api_key, com HTTP 400 nomeando o campo. Então nenhuma requisição consegue entrar no bucket de outra chave apenas nomeando-a.

Os próprios metadata de uma requisição ainda podem movê-la entre os buckets da chave que ela apresenta. Em uma requisição responses, model_group toma no seu bucket o lugar do modelo que a requisição pede. Em uma requisição responses ou messages, caching_groups permite que requisições que nomeiam o mesmo grupo de aliases de modelo compartilhem respostas entre eles. Em uma requisição responses ou de chat, redis_namespace mantém as requisições que nomeiam um namespace em buckets separados das que não nomeiam nenhum. Nenhum deles alcança o bucket de outra chave.

A chave deste gateway é a sua chave administrativa, e todo chamador a detém. Ele não tem nenhum banco de dados de gestão vinculado, então não emite chaves próprias: todo chamador apresenta a chave vinculada a api_key, e uma requisição sem chave, ou com uma chave que o gateway não emitiu, é recusada antes de qualquer consulta. Então aqui a chave não separa nenhum chamador de outro, e sob o escopo padrão o que mantém dois chamadores separados é o usuário final que cada requisição nomeia.

Com end_user, o padrão, uma entrada é servida a requisições que nomeiam o mesmo usuário final. O gateway lê o usuário final da requisição: 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 armazenada para alice é servida para a pergunta de alice formulada de modo parecido, e não para a de bob.

Daí decorrem duas coisas, e ambas são comportamento do gateway, não configuração:

  • O gateway não verifica nenhum desses nomes. Quem detém a chave pode nomear qualquer usuário final e recebe o que foi armazenado para esse usuário final. Mantenha a chave com a aplicação que sabe quem são os seus usuários finais, e deixe que ela os nomeie; não entregue a chave aos próprios usuários finais.
  • Requisições que não nomeiam nenhum usuário final compartilham um único cache. Toda requisição desse tipo que apresenta a mesma chave é servida a partir das mesmas entradas, seja quem for que a enviou.

Com key, todo chamador que apresenta a chave é servido a partir de um único cache. Adicione scope: key aos valores da vinculação e faça o build de novo: o semantic_cache_scope da configuração passa a dizer key, e nada mais muda na saída renderizada. O usuário final que um cabeçalho nomeia deixa então de fazer parte do bucket, então uma resposta armazenada para alice, nomeada em um cabeçalho x-litellm-end-user-id, é servida para a pergunta de bob formulada de modo parecido que o nomeia da mesma forma, incluindo as chamadas de ferramentas que ela contém. O campo user do corpo, porém, é um dos outros parâmetros da requisição, então duas requisições que nomeiam ali usuários finais diferentes continuam caindo em buckets diferentes, como acontece com duas temperaturas. Isso serve para um cache de respostas que são as mesmas para todos, e para nada mais.

O que interrompe o build

Cada um destes casos é uma frase que o build imprime, nomeando o que mudar:

  • Nenhuma chave administrativa. Remova a vinculação api_key e o build é interrompido antes que qualquer coisa seja 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. Remova a aresta cache_store e o build é interrompido 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 em um que não declare servir a busca vetorial do mecanismo de consultas do Redis, com a qual o cache busca as suas respostas: um Redis anterior à versão 8.0, ou o Valkey, não armazenaria nada enquanto toda requisição continuaria tendo sucesso.

  • Uma segunda vinculação core/semantic-caching no gateway, que tem um único cache.

  • core/data-masking no mesmo gateway. As duas declaram um conflito, porque um cache calcula a chave de uma requisição depois do mascaramento, então duas requisições que diferem apenas no que o mascaramento substitui compartilhariam uma única resposta armazenada.

Quando o repositório não pode ser usado

O gateway se conecta ao repositório quando serve a primeira requisição, não quando inicia. Se ele não consegue usar o repositório — o repositório exige uma senha que não foi dada ao gateway, ou recusa a que foi dada —, toda busca falha e nada é armazenado, enquanto toda requisição continua sendo respondida pelo modelo. Só o log próprio do gateway informa isso. É por isso que as duas pontas da senha 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. Ele não se conecta ao repositório, não sabe se algo responde em cache-default:6379, e não sabe o que é um usuário 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 se apoia em qualquer compreensão do tráfego.

Adaptando-o

  • Compartilhar um cache por chave. Adicione scope: key à vinculação answers, quando todo chamador deve receber as mesmas respostas.
  • Executar o repositório sem senha. Remova juntas a vinculação 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 conecta sem senha. Remover apenas uma das duas vinculações deixa o cache sem conseguir usar o repositório.
  • Corresponder a mais ou menos prompts. Aumente similarity_threshold para servir apenas correspondências mais próximas, ou diminua-o para servir mais; o valor adequado depende do modelo de embedding.