Substrato de inferência: o que o Alembic deliberadamente delega
Quando a sua unidade de trabalho cruza a cintura estreita — o ModelAdapter → cliproxyapi → fetch — tudo o que acontece abaixo do fio (KV cache, batching, paged attention, prefill/decode, quantização) NÃO é código do Alembic. É do gateway e dos modelos MLX locais. Ao fim desta lição você entende cada uma dessas peças, o tradeoff de cada uma, e por que delegá-las é a decisão certa — não um buraco.
O mapa cita linha a linha: o adapter default é um proxy HTTP OpenAI-compatible puro — ModelRunInput → fetch → ModelRunResult, sem cache de token, sem scheduler de batch, sem kernel de atenção. Leitura conceitual de apoio que o founder indicou: walkinglabs · learn-harness-engineering (PT-BR) e ai-engineering-from-scratch — para os mecanismos de baixo nível que vivem do outro lado da cintura.
A grande ideia
- Você sabe que um LLM "gera texto token a token". Só isso.
- Você não precisa ter escrito um kernel de GPU, nem saber o que é VRAM.
- Você lembra da lição 0002: toda chamada de modelo passa pela cintura estreita (o
ModelAdapter+Result). Aqui a gente desce abaixo dessa cintura.
Pense no Alembic como um servidor de aplicação. Ele decide o que fazer, em que ordem, com que regras — mas não gerencia a memória física da máquina. Isso é trabalho do sistema operacional. Da mesma forma: o Alembic orquestra a unidade de trabalho (roteamento, gates, custo, observabilidade), mas a inferência de baixo nível — como os tokens são realmente computados na GPU — ele empurra para baixo da sua cintura.
- Explicar o que é o KV cache, por que ele cresce, e o que "eviction / memory-pressure" significa.
- Distinguir continuous batching de paged attention — e por que ambos são truques de throughput do servidor.
- Dizer por que prefill é compute-bound e decode é memory-bandwidth-bound — e o que isso muda.
- Ler uma tabela de quantização (INT8 / INT4 / FP8 / AWQ / GPTQ) e saber quando ela machuca a qualidade.
- Comparar speculative decoding × quantização × destilação como três caminhos para cortar custo/latência.
- Justificar a decisão do Alembic de delegar tudo isso — e apontar onde, no código, essa decisão aparece (ou some).
Existem três palavras que o curso inteiro usa para classificar cada peça de um harness: owned (o Alembic implementa), delegated (o Alembic empurra para baixo da cintura — o gateway cliproxyapi ou os modelos MLX locais) e gap (ainda não existe; vira roadmap). Esta lição é quase inteira sobre a coluna delegated. E delegar bem é uma virtude de engenharia, não uma omissão.
Pense como… a tomada da parede. Você liga o seu notebook sem saber (nem se importar com) como a usina gera os 127 V. A "interface" é o plugue. O Alembic faz o mesmo: a interface é a chamada OpenAI-compatible; a "usina" (KV cache, batching, quantização) fica do outro lado, e isso é de propósito. Onde a analogia quebra: você não escolhe a usina; o Alembic escolhe qual modelo/tier — só não gerencia os elétrons.
A cintura, em uma frase de código
O adapter default (cliproxyapi.ts:47-58) reduz toda a inferência a: callOpenAiCompatible({ baseUrl: 'http://127.0.0.1:8317', … }, input, Date.now()). Não há, em nenhum lugar dessa camada TypeScript, um cache de chave/valor, um agendador de lotes ou um kernel de atenção. Essa única escolha arquitetural é o que transforma ~7 dos 23 princípios do mapa em delegated em vez de gap: o Alembic não está "faltando" gerência de KV cache — ele a empurrou conscientemente para baixo do fio, do mesmo jeito que um servidor de aplicação empurra a gerência de page-cache para o kernel.
Por que isso é uma lição inteira
Porque a honestidade é o valor do curso. Um material desonesto fingiria que o Alembic "faz tudo". Este aqui diz: estas peças são reais, importantes, têm tradeoffs sérios — e o Alembic de propósito não as possui. Saber a fronteira é o que separa quem desenha um harness de quem só usa um.
A fronteira: o que fica acima e abaixo do fio
A imagem-moldura do curso é a dos "Self-Learning Agents": três camadas. Model (os pesos — o Alembic delega), Harness (o loop/gates/routing — o Alembic possui) e Context (memória/skills — o Alembic compõe). Tudo nesta lição mora na camada Model, abaixo da cintura. Leia o diagrama de cima (sua unidade de trabalho) para baixo (os elétrons).
Você abre cliproxyapi.ts inteiro (≈78 linhas). Quantas dessas peças da camada de baixo (KV cache, batching, paged attention, quantização) você espera encontrar implementadas ali?
fetch. O que ele tem é: o id do adapter, as capabilities (streaming/toolUse/vision), um healthCheck que dá um GET em /v1/models, e o run guardado. Nada de baixo nível. Essa "vacância" é a fronteira inteira da lição.KV cache: a memória que cresce a cada token
Para gerar o próximo token, o modelo precisa "olhar para trás" para todos os tokens anteriores (isso é a atenção). Recalcular esse olhar do zero a cada token seria absurdamente caro. Então o servidor guarda os resultados intermediários de cada token — duas matrizes por token, chamadas Key e Value. Esse armazenamento é o KV cache. Ele transforma a geração de "O(n²) toda vez" em "O(n) incremental".
Pense como… escrever uma redação sem reler o texto inteiro a cada palavra nova — você mantém um resumo na cabeça (o KV cache) e só acrescenta. Onde quebra: o seu "resumo mental" não cresce sem parar; o KV cache cresce linearmente com o tamanho do contexto e mora na memória da GPU (VRAM), que é finita.
Result voltar (ou um erro, se o servidor estourar).Onde isso vive (e onde NÃO vive)
No HARNESS-MAP.md (princípio #4): "Where Alembic does it: Nowhere in the TS layer — and correctly so. This lives in the inference server behind cliproxyapi (and in the local MLX runtime for LOCAL/offline models)." Status: delegated. Não é owned, não é gap — fora de escopo por design.
No setup local do founder (memória local-models-macbook): o KV cache de modelos como o DeepSeek-V4-Flash q2 (81 GB de pesos mmap'd, janela de até 1M tokens) ou o Qwen3-VL-30B-A3B é gerenciado pelo runtime MLX no M5 Max de 128 GB — o Alembic enxerga só a porta OpenAI-compat em :8000/:8317. [a verificar: os detalhes finos da política de eviction de cada runtime MLX/DS4 não foram inspecionados linha a linha — o que está verificado é apenas que o Alembic não tem código de KV cache.]
Continuous batching & paged attention
Duas ideias diferentes que vivem juntas no servidor:
Continuous batching — em vez de esperar um lote de requisições terminar para começar o próximo, o servidor intercala os passos de geração de várias requisições ao mesmo tempo. Assim que uma termina, outra entra no lugar imediatamente, sem deixar a GPU ociosa. É throughput: mais requisições por segundo no mesmo hardware.
Paged attention — gerencia o KV cache como a memória virtual de um sistema operacional: divide-o em "páginas" de tamanho fixo, em vez de exigir um bloco contíguo gigante por requisição. Isso elimina o desperdício (fragmentação) e deixa o servidor empacotar muito mais requisições na mesma VRAM.
Pense como… um restaurante. Continuous batching = assim que uma mesa termina, a próxima senta na hora (nunca deixa a mesa vazia). Paged attention = mesas modulares que você junta/separa conforme o grupo, em vez de reservar o salão inteiro para cada cliente. Onde quebra: num restaurante o garçom é o gargalo; aqui o gargalo é a largura de banda da memória da GPU.
O Alembic tem uma forma de "batching", mas é uma coisa completamente diferente: concorrência em nível de requisição no swarm (swarm/src/lead-dispatcher.ts · maxConcurrency, default 1, com rampa opcional). Isso é fan-out de orquestração — "rodar 3 unidades de trabalho em paralelo" — e não tem nada a ver com intercalar passos de decodificação de tokens dentro do servidor. Dois conceitos, dois andares. O HARNESS-MAP marca o cap de concorrência do swarm como owned, e o continuous batching como delegated.
Prefill vs decode: duas físicas diferentes
Gerar uma resposta tem duas fases, e elas têm naturezas opostas:
Prefill (processar o prompt inteiro de uma vez) é compute-bound: todos os tokens do prompt são processados em paralelo, então a GPU fica saturada de cálculo. É o que determina o time-to-first-token (quanto demora até a primeira palavra aparecer).
Decode (gerar os tokens de saída, um a um) é memory-bandwidth-bound: cada novo token precisa ler o KV cache inteiro da memória, e isso é serial (um token de cada vez). O gargalo não é o cálculo — é a velocidade de ler memória. É o que determina o inter-token-latency (a cadência da digitação).
Pense como… ler um livro e depois resumir em voz alta. Ler (prefill) você faz rápido com os olhos varrendo a página inteira; falar o resumo (decode) sai palavra por palavra, no ritmo da sua boca. Onde quebra: a "boca" aqui é a largura de banda da VRAM, e ela não acelera juntando mais núcleos de cálculo.
Demo: o orçamento de latência de uma resposta
Mexa nos controles e veja como o tamanho do prompt empurra o prefill (a espera até o 1º token) e o tamanho da saída empurra o decode (o tempo de digitação). Os ritmos (tok/s) usam os números reais medidos no M5 Max do founder como ponto de partida.
Modelo simplificado p/ ensino: prefill ~ entrada ÷ 40.500 tok/s; decode ~ saída ÷ 33,9 tok/s (ritmos reais do DeepSeek-V4-Flash q2). É didático, não um benchmark do seu hardware.
O que o Alembic enxerga (só o total)
O HARNESS-MAP #5 é explícito: "Not modeled in the TS layer. Alembic measures end-to-end latency only — the OTEL span's start_time/end_time are the event's own timestamp (harness/src/otel.ts:53-64); the funnel records wall-clock durationMs." Confirmado na leitura: em toOtelSpan, start_time e end_time são ambos event.at — o evento é um ponto no tempo, não tem fase de prefill vs decode.
Status: delegated (o split é do servidor). Vira gap só se o Alembic algum dia quisesse routing ciente de prefill/decode — ele não tem hoje nenhuma quebra de TTFT vs inter-token-latency.
Quantização: trocar precisão por memória e velocidade
Os pesos de um modelo são números. Por padrão eles são armazenados em alta precisão (16 bits cada). Quantização é guardar esses mesmos números com menos bits — 8, 4, até menos. Menos bits = o modelo ocupa menos memória e cada token lê menos dados (lembre: decode é memory-bandwidth-bound, então isso acelera de verdade). O preço: cada peso fica menos preciso, e em algum ponto a qualidade do raciocínio começa a degradar.
Pense como… salvar uma foto em JPEG com mais compressão. Arquivo menor, abre mais rápido — mas exagere e aparecem "artefatos". Quantizar demais um modelo é o "JPEG estourado" do raciocínio: ele começa a errar contas, perder o fio em contextos longos, alucinar mais. Onde quebra: diferente do JPEG, dá para ser esperto sobre QUAIS pesos comprimir (é o que AWQ e GPTQ fazem) e preservar quase toda a qualidade.
| Esquema | O que é | Quando brilha |
|---|---|---|
| FP16 / BF16 | 16 bits, ponto flutuante — a precisão "cheia" de referência. | Baseline de qualidade; o que você compara contra. |
| FP8 | 8 bits em ponto flutuante (mantém faixa dinâmica). | Hardware novo (ex.: H100); ótimo equilíbrio qualidade/velocidade. |
| INT8 | 8 bits inteiros. ~½ da memória do FP16. | Quase sem perda perceptível; o "padrão seguro". |
| INT4 | 4 bits inteiros. ~¼ da memória. | Couber-na-VRAM agressivo; aqui a qualidade começa a doer. |
| GPTQ | Método que quantiza pós-treino minimizando o erro camada a camada. | INT4/INT3 com perda muito menor que o corte ingênuo. |
| AWQ | "Activation-aware": protege os ~1% de pesos mais importantes. | INT4 preservando qualidade; popular por isso. |
Demo: o tradeoff tamanho × qualidade × velocidade
Escolha um esquema de quantização para um modelo de referência (≈30 B de pesos, partindo de 60 GB em FP16) e veja os três eixos se moverem ao mesmo tempo. Note como AWQ/GPTQ entregam o tamanho do INT4 com muito mais qualidade que o INT4 ingênuo.
Valores ilustrativos para ensinar o formato do tradeoff (não medições de um modelo específico). A lição real: a curva qualidade×tamanho não é reta — GPTQ/AWQ dobram a curva a seu favor.
O Alembic NÃO modela precisão — e isso aparece no schema
Esta é a evidência mais limpa da lição. O HARNESS-MAP #8 diz: "Model selection is by tier + price, not by quant level. The registry has maxOutputTokens and noImageSupport flags but no precision/quant metadata." Confirmado lendo contracts/src/registry.ts:8-30: o modelRegistryEntrySchema tem modelId, adapterId, tier, costPer1kInputUsd/OutputUsd, capabilities, e os opcionais provider/baseUrl/maxOutputTokens/noImageSupport — e o comentário do próprio código diz que esses quatro "feed the offline doctor --client-stack smoke check… never routing or pricing". Não existe campo de precisão. O Alembic trata cada modelId como uma tupla opaca capability+preço.
Status: delegated para quem serve os pesos. Vira gap só se um dia se quisesse routing ciente de quant — aí o schema do registry precisaria de um campo precision.
Três caminhos para cortar custo/latência
Quantização não é a única alavanca. Há três técnicas clássicas para deixar a inferência mais barata/rápida — e elas atacam ângulos diferentes. Duas são puramente do servidor; uma é treino. O Alembic delega todas as três — mas vale entender o que cada uma faz.
alembic distill destila um corpus de conhecimento (T0→T3 → LEARNINGS/SIGNALS), não um modelo. A palavra é a mesma; a técnica de ML não. No mapa: model-distillation = gap.Resumo de bolso: speculative = mais rápido sem perder qualidade (mas precisa de um modelo rascunho); quantização = menor e mais rápido, com risco de qualidade; destilação = um modelo novo, menor de vez, mas custa um treino. O Alembic não faz nenhum dos três — ele escolhe qual modelo chamar, e o gateway faz o resto.
O HARNESS-MAP #7 separa: speculative decoding + weight quantization → inteiramente a camada gateway/MLX (delegated). Model distillation = gap (não feito). E alerta para o overload do termo: a "distillation funnel" (@alembic/etl, alembic distill) destila um corpus em LEARNINGS+SIGNALS, não pesos. Confundir os dois é o erro clássico ao ler o repo.
Por que delegar é a decisão certa
Tudo nesta lição é a coluna delegated. A pergunta honesta é: isso não é uma falha? Não. É a mesma disciplina de um servidor de aplicação que não reescreve o kernel: você possui a sua camada de valor com excelência e confia na camada de baixo no contrato dela. O Alembic possui a cintura (o contrato) e o comportamento de falha no fio (Result, breaker, retry). O que está embaixo, ele não toca.
É literalmente um fetch. Olhe o coração do adapter default:
// O adapter default reduz TODA a inferência a uma chamada HTTP. const attempt = (input: ModelRunInput): Promise<ModelRunResult> => callOpenAiCompatible( { adapterId: CLIPROXYAPI_ID, baseUrl, /* http://127.0.0.1:8317 */ apiKey: options.apiKey, headers: options.headers, fetchImpl, }, input, Date.now(), ); // As capabilities que ele anuncia — repare no que NÃO está aqui: const CAPABILITIES: ModelCapabilities = { streaming: true, toolUse: true, vision: true, // sem precisão. sem quant. sem KV. sem batch. Tudo isso é do outro lado do fio. };
"That single architectural choice is what makes ~7 of the 23 principles below delegated rather than gap: Alembic isn't missing KV-cache management — it consciously pushed it below its waist, the same way an application server pushes page-cache management to the kernel." — HARNESS-MAP.md, "The one fact the whole map hinges on: the narrow waist".
adapterId), não dois caminhos de código. A complexidade de inferência inteira (KV, batch, quant) mora atrás do valor 'cliproxyapi' — invisível para a cintura.adapterId: 'local' (o caminho $0 determinístico) vs 'cliproxyapi' (o gateway). Não são dois códigos diferentes — é a mesma cintura apontando para substratos diferentes. Toda a complexidade de inferência mora atrás desse campo.
Recapitulando
Passe pelos slides para fixar a fronteira inteira — de cima (a cintura) para baixo (os elétrons).
- O adapter default do Alembic é um proxy HTTP puro —
ModelRunInput → fetch → ModelRunResult. - KV cache guarda K e V por token; troca O(n²) por O(n) incremental.
- O KV cache cresce linear com o contexto e mora na VRAM finita → daí eviction/paging.
- Continuous batching mantém a GPU sempre cheia (throughput); é do servidor.
- Paged attention gerencia o KV como memória virtual (densidade); também do servidor.
- Prefill é compute-bound (1º token); decode é memory-bandwidth-bound (tok/s).
- Quantizar reduz bits/peso → ajuda mais o decode; a curva qualidade×bits não é reta.
- AWQ/GPTQ protegem os pesos importantes → INT4 com qualidade quase de INT8.
- A degradação por quant aparece primeiro em raciocínio longo + tool-use — o que um agente mais usa.
- No registry não há campo de precisão: cada
modelIdé tupla opaca capability+preço. Tudo isso = delegated, por design.
Três perguntas. A pontuação corre sozinha embaixo.
fetch; KV cache é do gateway + MLX. Não é falha (gap) nem implementação própria (owned) — é uma delegação consciente, como um app server delega page-cache ao kernel.precision no modelRegistryEntrySchema; quant é delegated.Na próxima lição (0004 · Saída estruturada & ferramentas) subimos de volta para cima da cintura: como o Alembic valida o JSON que o modelo cospe com Zod nos boundaries, o GAP de auto-repair, e por que a superfície MCP é read-only por design.