DS4 / DwarfStar

As lições anteriores deram o vocabulário — MoE, memória unificada, quantização, KV cache. O DS4 é onde tudo isso vira um binário que roda. Não é mais um carregador genérico de GGUF: é um engine nativo em C escrito por antirez com um único alvo em mente — rodar o DeepSeek-V4 num Mac. Esta lição abre a caixa: a arquitetura, o build que já provamos neste Mac, o streaming de SSD que dissolve o limite de RAM, e como ligar um cliente.

01 · O que é o DS4 — e por que ele é diferente

O DS4 — apelidado de "DwarfStar" — é um engine de inferência pequeno, nativo e autocontido, escrito em C. Ele não tenta rodar qualquer modelo: foi otimizado primeiro para o DeepSeek-V4-Flash (284 B de parâmetros totais, 13 B ativos por token, contexto de 1M). A variante Pro (1,6 T totais / 49 B ativos) existe para máquinas de memória gigante. Pense nele como um motor de corrida construído para uma pista — não um carro de passeio que vai a qualquer lugar.

A diferença em relação a um llama.cpp da vida é o foco: em vez de suportar centenas de arquiteturas, o DS4 conhece uma família a fundo e gasta toda a engenharia nela — quantização sob medida (seção 02), streaming de SSD desenhado para o MoE (seção 04) e um servidor que já fala os protocolos comerciais (seção 05). É o que permite a um modelo de 284 B parecer de fronteira num laptop.

É a primeira vez que uso um modelo local para coisa séria que eu normalmente pediria pro Claude ou pro GPT... o DS4 é muito mais B [fronteira] do que A [modelo local pequeno].— antirez, antirez.com/news/165

01b · DS4 vs llama.cpp — a aposta estreita

A melhor forma de entender o DS4 é contrastá-lo com o carregador genérico que todo mundo conhece. Não é "melhor" em abstrato — é uma troca deliberada: ele abre mão da generalidade para ganhar profundidade numa família só. (O próprio README agradece ao llama.cpp: o DS4 herda formatos GGUF, kernels e tabelas de quant daquele ecossistema.)

Repare que metade da tabela são coisas que só fazem sentido quando você fixa o modelo: o quant assimétrico, o streaming do MoE e o agente vertical dependem de conhecer a arquitetura exata. É o preço e o prêmio da aposta estreita.

02 · A arquitetura do engine

O DS4 é uma pilha curta e direta: um GGUF com quantização assimétrica no disco, um núcleo C com kernels Metal que faz a matemática, um KV cache que vive entre RAM e disco, e um servidor que fala os protocolos das APIs comerciais. Os clientes (Claude Code, Codex, seu app) nem percebem que estão falando com algo local. Veja a pilha se montar, camada por camada:

A quantização assimétrica 2/8-bit

Aqui está a sacada que faz 284 B caber em 81 GB sem virar lixo. O DS4 não quantiza tudo no mesmo nível. Os especialistas roteados — a maior parte dos parâmetros, mas só um punhado ativo por token — vão para 2-bit. Todo o resto (atenção, embeddings, roteador, camadas densas) fica em Q8. A precisão é gasta onde importa para a fidelidade, e a economia é feita onde há volume. É a tese da Lição 04 aplicada com bisturi, não com martelo.

Os quants de 2-bit não são brincadeira; ele chama ferramentas de forma confiável.— antirez, DS4 MODEL_CARD

02b · O fluxo de um token, do prompt ao próximo token

Camadas empilhadas é o mapa estático. Agora siga um token pelo engine — é aqui que MoE, atenção comprimida e streaming aparecem em movimento. Cada token novo refaz este caminho. Repare no losango de decisão: é o ponto onde o roteador escolhe os experts, e onde o streaming de SSD pode ou não custar um acesso a disco.

Por que 1M de contexto cabe: atenção comprimida (CSA + HCA)

A pergunta óbvia: como um modelo expõe 1 milhão de tokens de contexto sem um KV cache gigante para cada token em cada camada? A resposta está no design de atenção do DeepSeek-V4, que o DS4 implementa fielmente. Cada camada guarda uma janela crua dos últimos 128 tokens (alta resolução, recente) e, além dela, linhas comprimidas no eixo do tempo — várias posições agrupadas numa só linha de KV.

03 · Quanto baixar — escolha pela sua RAM

O download não é tamanho único. Cada quant casa com uma faixa de memória: quanto mais RAM, mais experts cabem residentes e maior a qualidade que você pode pagar (a seção 04 explica o porquê). Todos vêm de hf.co/antirez/deepseek-v4-gguf. Escolha o alvo de download e arraste a RAM — o painel diz, ao vivo, se cabe:

Todos de hf.co/antirez/deepseek-v4-gguf. O q2-imatrix é o ponto de entrada para os Macs de coding/agente — é o que cabe nos 128 GB com folga e o que vamos servir na seção 05. O streaming de SSD (abaixo) suaviza as bordas, mas a tabela é o ponto de partida.

03b · Conta na ponta do lápis — de onde saem os 81 GB

A tabela diz "81 GB"; aqui está por que. O quant de 2-bit do DS4 é cirúrgico: ele só comprime os experts roteados do MoE — que são a maioria do espaço do modelo — e ainda assim em dois níveis: up/gate em IQ2_XXS e down em Q2_K. Todo o resto (experts compartilhados, projeções, roteamento) fica intacto em Q8. Veja a divisão real:

E quando o modelo NÃO cabe? O orçamento de cache de experts

Aqui mora a alavanca prática do streaming (seção 04). Quando você liga --ssd-streaming, os pesos não-roteados ficam residentes e o resto da RAM vira um cache de experts. O orçamento automático do DS4 faz a conta sozinho: pega 80% do working set recomendado pelo Metal, subtrai os pesos não-roteados, e o que sobra vira cache de experts. Arraste a RAM e veja o orçamento se formar (no M5 Max de 128 GB, o automático escolheu ~59 GB — número medido no README):

04 · Streaming de SSD: a RAM vira um espectro

Este é o mecanismo mais original do DS4. Em vez de tratar a RAM como um corte rígido — "cabe ou não cabe" — o DS4 trata o SSD como uma extensão contínua. Os pesos não-roteados (atenção, roteador, densas) ficam residentes na memória. Os especialistas roteados são lidos do GGUF sob demanda: quando o roteador pede um especialista que não está no cache, ele é trazido do SSD (cache-miss). E o KV cache é, nas palavras de antirez, "um cidadão de disco de primeira classe".

O KV cache é um cidadão de disco de primeira classe. O streaming de SSD transforma a RAM disponível de um corte rígido num espectro contínuo de níveis de velocidade.— antirez, DS4 README

É isso que reconcilia a tabela da seção 03 com a vida real: o q4 (153 GB) "não cabe" num corte rígido de 128 GB, mas com streaming a borda fica macia — os experts mais frios apenas custam um pouco de latência quando são chamados. A RAM deixa de ser um sim/não e vira um botão de velocidade.

04b · Cache-hit → velocidade (e prefill ≠ geração)

O streaming não é grátis: cada cache-miss paga uma leitura de SSD. Mas há uma assimetria importante que o README destaca — o prefill (ler o prompt) tolera misses muito melhor que a geração (produzir tokens), porque cada token novo re-roteia pelos experts. Daí a regra: contexto longo entra rápido; é a geração token-a-token que sente o disco.

Comparativo: o mesmo q2, em três máquinas

O DS4 publica números reais de velocidade. Compare o nosso M5 Max com o M3 Max anterior e com um Mac Studio M3 Ultra — tudo no mesmo quant (q2), prompt curto, decode guloso. É a prova de que "mais banda/mais máquina = mais tok/s" (a tese da Lição 03):

Sinta o efeito: taxa de acerto → tok/s efetivo

Modelo mental simples: se um cache-hit gera a 34 t/s (o número do M5 Max) e um miss custa uma leitura de SSD, então o tok/s efetivo da geração depende de quantos tokens acertam o cache. Mais RAM ⇒ mais experts residentes ⇒ taxa de acerto maior. Arraste a taxa de acerto e veja:

05 · Do clone ao cliente: o fluxo

Quatro passos te levam de zero a um endpoint local servindo. Os dois primeiros — clone e make — já estão provados neste Mac. Os outros dois dependem só de disco e de apontar o cliente. Repare no badge verde de prova nas duas primeiras caixas:

O comando, na prática

# 1+2 — clone e build (provado neste Mac: 5 binários Metal, exit 0)
git clone <repo-do-ds4> && cd ds4 && make
# → ds4  ds4-server  ds4-bench  ds4-eval  ds4-agent

# 3 — baixar o quant que cabe nos 128 GB (≈ 81 GB)
./download_model.sh q2-imatrix

# 4 — servir (NUNCA make cpu no macOS: kernel panic; Metal é o default)
./ds4-server   # OpenAI + Anthropic + Responses + completions em 127.0.0.1:8000

# 5 — plugar um cliente (ex.: chamada Anthropic-compatível)
curl -s 127.0.0.1:8000/v1/messages -d '{"model":"deepseek-v4-flash","messages":[...]}'

O que "single-stream" significa

O ds4-server aceita os quatro protocolos, mas tem uma propriedade que define como você o opera: ele é single-stream — uma única requisição em voo por vez. Não há paralelismo de requisições; o servidor processa um grafo de cada vez e serializa o resto. Consequência prática: um cliente sério por vez. Para visão concorrente, separe o endpoint (assunto da Lição 08).

05b · As quatro APIs lado a lado — e por que single-stream

O ds4-server fala quatro famílias de protocolo de uma vez. Isso é o que faz um cliente comercial (Claude Code, Codex) "não perceber" que está falando com algo local: cada um usa o endpoint que já conhece. Veja qual cliente casa com qual rota:

A propriedade que define a operação: o parsing roda em threads, mas a inferência é serializada por um único graph worker — o servidor não junta requisições independentes em lote. É o "single-stream". Veja a fila:

Comparativo extra: os três modos de raciocínio

O DeepSeek-V4-Flash tem três "marchas" de esforço de raciocínio — e a diferença em tarefas de código/matemática é enorme. Isso importa porque o mesmo modelo local pode ser rápido-e-direto ou lento-e-profundo. Clique para comparar (números do MODEL_CARD oficial):

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.