Mãos à obra

Chega de orçamento de RAM no papel. Esta é a lição dos comandos reais: clonar e compilar o cérebro, baixar os pesos, subir os servidores e plugar o seu cliente. Cada passo marcado com ✓ rodou neste M5 Max nesta sessão — não é "deveria funcionar", é "rodou, aqui está a saída". No fim você tem dois endpoints OpenAI-compatíveis na sua máquina: o cérebro em :8000 e a visão em :8081.

01 · O fluxo de ponta a ponta

São duas trilhas paralelas que terminam no mesmo lugar: o seu cliente. A trilha do cérebro (DS4 nativo, Metal) e a trilha da visão (MLX, em Python). Nenhuma depende da outra para subir — você pode ligar a visão enquanto os 81 GB do cérebro ainda baixam. O diagrama marca com ✓ o que já foi provado nesta sessão e com ⏳ o único passo demorado (o download).

02 · Anatomia de uma instalação (passo a passo)

A visão de cima mostrou o que roda. Agora o como, no detalhe: a instalação do cérebro é um pequeno fluxograma com um ponto de decisão (o teto de RAM) e um único passo lento (o download). O segredo é entender que cada caixa só faz sentido depois da anterior — e que a árvore de quant (seção 04) é o que muda qual arquivo você baixa.

E onde os comandos "moram" no terminal? Este mapa liga cada linha digitada ao que ela produz — o mesmo passo a passo, agora como uma sessão de terminal real:

O único passo lento — o download de 81 GB — é o que mais assusta, mas ele é resumível: se a rede cair (ou você der Ctrl-C), recomeça de onde parou. Visualmente, é baixar em pedaços e poder pausar a qualquer momento:

03 · Monte seu setup (interativo)

Antes de colar comandos a esmo, internalize a ordem. São cinco passos para o cérebro, e cada um só faz sentido depois do anterior. Clique em cada passo abaixo na sequência: ele marca ✓ e revela o comando exato que você roda. A barra de progresso à direita só completa quando os cinco estão feitos.

04 · Qual quant para minha RAM?

O losango do fluxograma — "a quant cabe na RAM?" — merece uma resposta sem chute. Esta árvore de decisão te leva da sua RAM ao formato certo em três perguntas. A regra de fundo é a da Lição 02: params × bits ÷ 8, sempre deixando 10–20% de folga para KV + sistema.

Agora inverta a pergunta: dada a sua RAM, qual o maior modelo que você consegue rodar em cada quant? Arraste — o número e as barras recalculam pela fórmula (com 80% de teto seguro):

05 · Escolha seu objetivo

Nem todo mundo precisa das duas trilhas no dia um. O que você liga primeiro depende do que você quer fazer hoje. Clique no seu objetivo — o setup recomendado, os comandos e o orçamento de RAM mudam junto:

# cérebro residente, contexto longo, KV em disco p/ folgar a RAM
./ds4-server --ctx 100000 --kv-disk-dir ~/.ds4/kv --kv-disk-space-mb 8192
# perf classe M5 Max (README do DS4): gen 25–34 t/s · prefill 87–463 t/s

# visão sozinha em :8081 — independe do cérebro
python -m mlx_vlm.server \
  --model mlx-community/Qwen3-VL-30B-A3B-Instruct-4bit \
  --port 8081
# ✓ medido nesta sessão: prompt 88 t/s · gen 62 t/s · pico 18,4 GB

# funil noturno offline = hermético, $0
alembic distill <corpus> --offline

# índice de visão sobre as imagens de cada pacote (append-only, dedupe)
alembic vision-index <family-root>
# offline determinístico por padrão; --online usa o MLX-VLM local desta lição

Uma diferença prática entre as trilhas: o cérebro é um binário nativo (compilado, sem dependências Python), enquanto a visão roda em Python — e por isso usa um uv venv, um ambiente isolado. Isso evita que o mlx-vlm conflite com o Python do sistema ou de outros projetos:

06 · Build → serve → query (e a saída real)

Agora a sequência completa, com os comandos exatos e — o que importa — a saída real capturada nesta sessão. Primeiro o diagrama animado do ciclo, depois os blocos de comando das duas trilhas.

Trilha do cérebro — clonar, compilar, baixar, servir

O DS4 (de antirez) compila nativo com Metal. Quatro comandos do zero ao endpoint:

# 1) clonar o repositório do cérebro (ou use seu ~/ds4 já clonado)
git clone https://github.com/antirez/ds4 && cd ds4

# 2) compilar com Metal — NUNCA `make cpu` num Apple Silicon
make
# ✓ provado nesta sessão: 5 binários Metal gerados, exit 0

# 3) baixar os pesos q2 (~81 GB; o download é resumível)
./download_model.sh q2-imatrix

# 4) servir — KV cache em disco para folgar a RAM
./ds4-server --ctx 100000 --kv-disk-dir ~/.ds4/kv --kv-disk-space-mb 8192
# perf medida (README do DS4, classe M5 Max): gen 25–34 t/s · prefill 87–463 t/s

Trilha da visão — venv, instalar, servir, chamar

A visão usa o uv para um venv isolado e instala o mlx-vlm direto do Git. O servidor sobe um endpoint OpenAI em :8081:

# 1) venv isolado e ativado (uv é rápido e reprodutível)
uv venv ~/.venv-mlxvlm && source ~/.venv-mlxvlm/bin/activate

# 2) instalar o mlx-vlm a partir do main
uv pip install "git+https://github.com/Blaizzy/mlx-vlm"

# 3) subir o servidor de visão (OpenAI-compatível) em :8081
python -m mlx_vlm.server \
  --model mlx-community/Qwen3-VL-30B-A3B-Instruct-4bit \
  --port 8081
# ✓ rodando nesta sessão

Por que a visão é tão rápida e leve para um modelo de 30 B? O segredo está no "A3B" do nome: é um MoE (mixture-of-experts) que guarda 30 B de pesos mas só ativa ~3 B por token. Memória paga o total; velocidade paga só os ativos — daí 62 t/s a 18,4 GB:

E a prova: a chamada real e a resposta medida, capturadas agora nesta máquina.

# chamada real ao endpoint OpenAI-compatível da visão
curl -s 127.0.0.1:8081/v1/chat/completions -d '{
  "model":"mlx-community/Qwen3-VL-30B-A3B-Instruct-4bit",
  "messages":[{"role":"user","content":"Descreva o conceito de memória unificada."}]
}'
# resposta real (medida nesta sessão):
"A memória unificada é uma arquitetura em que CPU e GPU compartilham o mesmo
 pool físico de memória, eliminando cópias entre dispositivos e permitindo que
 modelos grandes sejam acessados diretamente pela GPU com baixa latência."
# timings reais:
prompt 88 t/s · gen 62 t/s · peak 18,4 GB

07 · CPU vs Metal — por que o make certo importa

Você viu duas vezes o aviso "nunca make cpu". Aqui está o porquê, lado a lado. No Apple Silicon a memória é unificada: CPU e GPU compartilham o mesmo pool. Compilar para CPU ignora a GPU (Metal) e trata a máquina como um PC comum — exatamente o que torna inviável rodar um modelo de 284 B. O make padrão do DS4 já mira o Metal.

É a mesma lição que a Lição 03 (banda = velocidade) e a Lição 05 (engines): o que decide a velocidade local é o caminho até a memória. Em números, o contraste entre os alvos de build e entre as duas trilhas desta lição:

E como o comando de servir muda conforme a engine? As duas trilhas desta lição usam engines diferentes — clique para ver o comando de cada uma lado a lado:

./ds4-server --ctx 100000 --kv-disk-dir ~/.ds4/kv --kv-disk-space-mb 8192
# 127.0.0.1:8000 · gen 25–34 t/s · prefill 87–463 t/s (README, classe M5 Max)

python -m mlx_vlm.server \
  --model mlx-community/Qwen3-VL-30B-A3B-Instruct-4bit \
  --port 8081
# ✓ medido nesta sessão: prompt 88 t/s · gen 62 t/s · pico 18,4 GB

curl -s 127.0.0.1:8000/v1/models        # cérebro
curl -s 127.0.0.1:8081/v1/models        # visão
# 200 + JSON com o id do modelo = no ar. Recusou? servidor não subiu (não é a api-key).

08 · Referência de comandos

A parte mais simples e mais satisfatória: plugar o cliente. Como ambos os servidores falam OpenAI, qualquer cliente que aceite uma base-URL aponta para o 127.0.0.1. A api-key pode ser qualquer string — não há autenticação num servidor local.

# cérebro (DeepSeek) — para coding/agente
base-url  = http://127.0.0.1:8000
model     = deepseek-v4-flash          # o id que o ds4-server expõe
api-key   = qualquer-coisa            # local não valida a chave

# visão (Qwen3-VL) — para imagens/screenshots
base-url  = http://127.0.0.1:8081/v1
model     = mlx-community/Qwen3-VL-30B-A3B-Instruct-4bit
api-key   = qualquer-coisa

# exemplo: variáveis que o Claude Code / Codex / opencode entendem
export OPENAI_BASE_URL=http://127.0.0.1:8000
export OPENAI_API_KEY=local

Repare no endereço: 127.0.0.1 é o loopback — a sua própria máquina falando consigo mesma. Nenhum byte do prompt ou da resposta sai do Mac. É a diferença concreta entre IA local e uma API na nuvem:

E uma nota sobre aquele flag --kv-disk-dir no comando do cérebro: ele move o KV cache (a memória de trabalho da conversa, da Lição 06) para o disco em vez da RAM. Com os pesos já ocupando 81 GB, é o que dá folga para contextos longos sem estourar:

E o cartão de referência — cada comando desta lição num lugar só, com o estado verificado nesta sessão:

E quando algo dá errado? Os três tropeços mais comuns desta lição têm cada um uma causa única e uma correção direta. Este mapa de diagnóstico vai do sintoma que você vê à causa real e à correção — antes de você abrir uma busca:

Fixe os comandos (flashcards)

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