A Apple lançou a versão 0.32.3 da MLX a 29 de setembro de 2026, e o lançamento confirmou algo que já se via a chegar: a framework deixou de ser um projeto de nicho para programadores curiosos e tornou-se a forma mais rápida de correr modelos de linguagem num Mac com chip Apple Silicon. Com o M5 a trazer um acelerador neuronal dedicado na GPU e largura de banda de memória de 153 GB/s (contra 120 GB/s no M4), a diferença entre usar a MLX ou ficar pela alternativa genérica já não é cosmética.
Este tutorial mostra, passo a passo, como instalar a MLX, escolher o modelo certo, gerar texto, criar um servidor local, quantizar um modelo próprio e, no final, montar um mini-agente funcional que corre inteiramente na tua máquina. Vais precisar de cerca de 90 minutos, um Mac com Apple Silicon e paciência para o primeiro download do modelo.
Para quem trabalha em Portugal com dados sensíveis de clientes, contratos ou código fonte, correr um modelo localmente resolve um problema prático: nada do que escreves sai do portátil. Não há pedido de API a atravessar o Atlântico, não há registo num servidor de terceiros, e o custo por pergunta passa a ser zero depois da instalação. É esse argumento, mais do que a curiosidade técnica, que tem levado equipas de programação a testar a MLX em 2026.
O que é a MLX da Apple e porque interessa em 2026
A MLX é a framework de computação de arrays e aprendizagem automática da Apple, construída para tirar partido da memória unificada e da GPU Metal dos chips Apple Silicon. Tem interfaces em Python, C++ e Swift, mas é através do pacote mlx-lm que a maioria dos programadores a usa no dia a dia para carregar, correr, quantizar e afinar modelos de linguagem.
O repositório principal ml-explore/mlx soma hoje cerca de 28.700 estrelas no GitHub, e o pacote ml-explore/mlx-lm já passa das 7.300. Não são números que rivalizem com o Ollama, mas mostram uma comunidade que cresceu rápido depois da Apple ter dedicado duas sessões da WWDC26 ao tema: “Run local agentic AI on the Mac using MLX” e “Explore distributed inference and training with MLX”. A Apple deixou claro, nessas sessões, que quer a MLX como peça central de qualquer fluxo de trabalho de IA feito num Mac.
Quem já experimentou o Ollama ou o llama.cpp vai reconhecer a lógica, mas a MLX troca a portabilidade entre sistemas operativos por um desempenho mais afinado especificamente para Metal e para a memória partilhada entre CPU e GPU do Mac.
O código da MLX é aberto sob licença MIT, e os pesos de cada modelo mantêm a licença original do grupo que os treinou, seja a Apache 2.0 do Qwen3 ou licenças próprias de outras famílias. Isso significa que, antes de usar um modelo em produção ou de o redistribuíres, vale a pena abrir o model card no Hugging Face e confirmar o que a licença permite. Na camada técnica, a Apple também trouxe suporte ao Metal 4 e, nos chips M5, ao acelerador neuronal dedicado da GPU, dois componentes que explicam boa parte do salto de desempenho descrito mais adiante neste tutorial.
Este guia encaixa num tema maior que temos vindo a acompanhar na secção de Inteligência Artificial do shattered.io: a mudança de modelos de linguagem que só existiam numa cloud distante para modelos que cabem, literalmente, num portátil pousado numa mesa de cozinha. A MLX é apenas a versão mais recente e mais polida dessa mudança no ecossistema Apple.
MLX vs llama.cpp vs Ollama: as diferenças que importam
Antes de instalar nada, vale a pena entender onde a MLX se encaixa. O llama.cpp trabalha sobretudo com modelos em formato GGUF e corre em quase qualquer sistema, do Linux ao Windows, passando por telemóveis. O Ollama usa esse mesmo motor por debaixo, empacotado numa experiência simples de linha de comandos e, nas versões mais recentes, já consegue usar a MLX como motor por defeito em chips Apple Silicon quando a arquitetura do modelo é suportada. A MLX, por si só, fica um nível abaixo: é a camada que dá acesso direto a quantização, afinação (fine-tuning) e construção de aplicações Python personalizadas.
| Critério | MLX (mlx-lm) | llama.cpp | Ollama |
|---|---|---|---|
| Plataforma principal | Apenas Apple Silicon | Multiplataforma (CPU, GPU, Linux, Windows, macOS) | Multiplataforma, com backend MLX opcional no Mac |
| Formato de modelo | Pesos nativos MLX ou convertidos via mlx-lm.convert | GGUF | GGUF ou MLX, dependendo do modelo |
| Facilidade de uso | Linha de comandos e API Python | Linha de comandos, mais técnica | Muito simples, comandos de alto nível |
| Fine-tuning e quantização | Nativo, com LoRA incluído | Limitado, via scripts externos | Não suporta diretamente |
| Melhor cenário de uso | Desenvolvimento e experimentação em Mac | Portabilidade e hardware variado | Uso casual e servidores simples |
Na prática, a escolha não precisa de ser definitiva. Muita gente usa o Ollama para o dia a dia e recorre à MLX quando quer quantizar um modelo específico ou construir algo mais personalizado em Python. Este tutorial foca-se na MLX porque é a que dá mais controlo sobre o que corre, e sobre como corre, dentro do teu Mac.
Se o teu objetivo é apenas experimentar um modelo em cinco minutos sem tocar em código, o LM Studio continua a ser o caminho mais curto, porque embrulha tudo numa interface gráfica. Se precisas de produção, de scripts repetíveis ou de afinar um modelo para um caso de uso específico, a MLX justifica o tempo extra de aprendizagem. E se o teu trabalho passa por vários sistemas operativos, incluindo colegas em Windows ou Linux, o llama.cpp continua a ser a escolha mais segura para manter tudo compatível.
Pré-requisitos: o que precisas antes de começar
A lista de requisitos é curta, mas cada item conta. Um Mac com chip Intel não serve: a MLX depende da arquitetura unificada de memória que só existe a partir do M1.
| Requisito | Mínimo recomendado | Nota |
|---|---|---|
| Chip | Apple Silicon M1 ou mais recente | M4 ou M5 dão o melhor desempenho em 2026 |
| macOS | macOS 14 Sonoma ou mais recente | Recomendado macOS 15/16 para suporte total ao Metal mais recente |
| Memória unificada | 16 GB | Modelos de 8B em 4-bit cabem em 16 GB, mas 32 GB dá mais margem |
| Espaço em disco | 20 GB livres | Cada modelo descarregado ocupa entre 1 GB e 15 GB |
| Python | Python 3.10 ou mais recente | Instala via Homebrew ou python.org |
| Ferramentas de linha de comandos | Xcode Command Line Tools | Instala com xcode-select --install |
Com isto confirmado, passamos à parte prática. Os doze passos seguintes cobrem desde a instalação até à criação de um pequeno agente funcional, com paragens para medir desempenho e falar de segurança. Se não tiveres a certeza de quanta memória o teu Mac tem livre neste momento, abre o Monitor de Atividade, separador Memória, antes de avançares, isso evita escolher um modelo demasiado grande já no primeiro teste.
Passo 1: Confirmar o chip e a versão do macOS
Abre o Terminal e confirma que estás mesmo num Mac com Apple Silicon. Este primeiro passo evita um erro comum: tentar instalar a MLX numa máquina Intel, onde simplesmente não vai funcionar.
uname -m
sw_versO primeiro comando deve devolver arm64. Se devolver x86_64, estás num Mac Intel e a MLX não corre nesse hardware. O segundo comando mostra a versão do macOS: confirma que estás, no mínimo, no Sonoma.
Passo 2: Criar o ambiente Python e instalar o mlx-lm
Usar um ambiente virtual isolado evita conflitos com outras versões de Python que já tenhas instaladas, e é a prática recomendada pela própria documentação da Apple.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install mlx-lmA instalação demora entre 30 segundos e dois minutos, dependendo da ligação à internet. No final, confirma que tudo correu bem:
python -c "import mlx_lm; print(mlx_lm.__version__)"Resultado esperado: um número de versão impresso no terminal, sem mensagens de erro. Se vires um ModuleNotFoundError, o ambiente virtual provavelmente não está ativo, repete o comando source .venv/bin/activate.
Passo 3: Escolher o modelo certo para o teu Mac
O ecossistema mlx-lm já suporta versões convertidas das famílias Llama, Qwen3, Mistral, Mixtral, Gemma, DeepSeek, Phi, GLM, SmolLM, StarCoder e Cohere Aya. A maioria destes modelos está disponível pronta a usar na organização mlx-community do Hugging Face, já convertida e, em muitos casos, já quantizada.
| Modelo | Identificador no Hugging Face | Memória aproximada | Caso de uso |
|---|---|---|---|
| Qwen3 1.7B (bf16) | mlx-community/Qwen3-1.7B-MLX-bf16 | ~4 GB | Testes rápidos, Macs com 16 GB |
| Qwen3 8B (4-bit) | mlx-community/Qwen3-8B-MLX-4bit | ~5 GB | Equilíbrio entre qualidade e memória |
| Qwen3 8B (bf16) | mlx-community/Qwen3-8B-MLX-bf16 | ~16 GB | Qualidade máxima em Macs com 32 GB+ |
| Qwen3 14B (4-bit) | mlx-community/Qwen3-14B-MLX-4bit | ~8 GB | Mais capacidade sem exigir 32 GB |
Para quem está a começar, o Qwen3-8B em 4-bit é o ponto de partida mais equilibrado: cabe em Macs com 16 GB de memória unificada e já responde com qualidade suficiente para a maioria das tarefas de teste.
Como escolher entre bf16, 8-bit e 4-bit
O nome de cada modelo na tabela acima termina sempre numa indicação de precisão, e essa parte do nome não é só decoração. O bf16 guarda cada peso do modelo com 16 bits, o que preserva mais nuance nas respostas, mas exige o dobro da memória do 8-bit e cerca do quádruplo do 4-bit para o mesmo modelo. Na prática, isso traduz-se em três cenários distintos.
Em bf16, usa este nível quando tens 32 GB ou mais de memória unificada e queres a melhor qualidade possível para tarefas como resumos técnicos longos ou revisão de código complexo. Em 8-bit, fica o equilíbrio intermédio, uma opção pouco usada na prática porque o 4-bit já chega perto da mesma qualidade com metade do espaço. Em 4-bit, tens a opção mais comum em 2026: cabe em Macs com 16 GB, carrega mais rápido, e a perda de qualidade é pequena para conversação, programação e escrita geral.
A regra prática que vale a pena guardar: começa sempre pelo 4-bit. Só sobes para bf16 se notares erros concretos nas respostas, como confusão em tarefas de raciocínio em vários passos, e se o teu Mac tiver memória de sobra para aguentar a subida.
Passo 4: Gerar o primeiro texto com mlx_lm.generate
Chegou o momento de correr o primeiro modelo. O comando abaixo descarrega automaticamente o modelo do Hugging Face na primeira execução e guarda-o em cache local para as próximas vezes.
mlx_lm.generate \
--model mlx-community/Qwen3-8B-MLX-4bit \
--prompt "Explica em três frases como a memória unificada ajuda a correr modelos de IA num Mac." \
--max-tokens 300A primeira execução demora mais tempo porque está a descarregar o modelo, que pode ter entre 1 GB e 10 GB dependendo da escolha. Nas execuções seguintes, o arranque passa a ser quase instantâneo. O resultado típico no terminal é algo como:
==========
Prompt: Explica em três frases como a memória unificada ajuda...
A memória unificada permite que a CPU e a GPU acedam aos mesmos
dados sem cópias intermédias, o que reduz a latência...
==========
Prompt: 18 tokens, 612.4 tokens-per-sec
Generation: 142 tokens, 71.3 tokens-per-sec
Peak memory: 5.482 GBEstes três números, tokens de prompt por segundo, tokens gerados por segundo e memória de pico, vão ser os teus indicadores de referência em todo o resto deste tutorial.
Passo 5: Abrir uma sessão de chat interativa
Para conversas com várias trocas de mensagens, o comando mlx_lm.chat mantém o histórico da conversa sem precisares de repetir o contexto a cada pergunta.
mlx_lm.chat --model mlx-community/Qwen3-8B-MLX-4bitO terminal fica à espera de texto, e cada resposta aparece token a token, em tempo real. Escreve q ou usa Ctrl+C para saíres da sessão quando terminares.
Se preferires uma interface gráfica em vez da linha de comandos, vale lembrar que ferramentas como o LM Studio já conseguem carregar modelos no formato MLX por debaixo de uma janela de chat normal, o que dá o melhor dos dois mundos: o motor rápido da MLX com uma interface mais confortável para sessões longas de conversa.
Passo 6: Criar um servidor compatível com a API da OpenAI
Se já tens código que fala com a API da OpenAI, podes apontá-lo para o teu Mac em vez da cloud. O mlx_lm.server expõe um endpoint compatível, o que poupa reescrever integrações existentes.
mlx_lm.server \
--model mlx-community/Qwen3-8B-MLX-4bit \
--host 127.0.0.1 \
--port 8080Nota o --host 127.0.0.1: mantém o servidor acessível só na tua máquina. Mudar isto para 0.0.0.0 expõe o servidor à rede local, algo que só deves fazer se souberes exatamente quem tem acesso a essa rede. Para testar, numa segunda janela do terminal:
curl http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "mlx-community/Qwen3-8B-MLX-4bit", "messages": [{"role": "user", "content": "Olá!"}]}'A resposta chega em formato JSON, igual ao que receberias de qualquer API de chat comercial, só que processada inteiramente no teu hardware.
Para que serve a MLX no dia a dia: três casos de uso reais
Depois de teres o servidor a responder, a pergunta natural é o que fazer com ele além de perguntas de teste. Três cenários aparecem com frequência entre quem já usa a MLX em trabalho real.
O primeiro é a revisão de código sensível, contratos de clientes com cláusulas de confidencialidade ou bases de código proprietário, onde enviar trechos para uma API externa não é uma opção aceitável. Ligar um editor de código ao endpoint local criado no Passo 6 resolve isso sem sacrificar a conveniência de ter sugestões de IA.
O segundo é o processamento de documentos internos, como atas de reunião, relatórios financeiros ou dados de recursos humanos, que muitas empresas em Portugal preferem manter dentro das suas próprias máquinas por razões de conformidade com o RGPD. Resumir ou traduzir esses documentos com um modelo local evita que saiam da organização.
O terceiro é simplesmente custo: equipas pequenas que fazem centenas de pedidos por dia a uma API paga acabam a gastar valores consideráveis todos os meses. Trocar parte desse tráfego por um modelo local, mesmo que mais limitado, reduz a fatura sem exigir qualquer subscrição nova.
Passo 7: Quantizar um modelo para poupar memória
Nem todos os modelos que queres testar já têm uma versão quantizada publicada. O mlx_lm.convert resolve isso, transformando pesos originais num formato mais leve.
mlx_lm.convert \
--hf-path mistralai/Mistral-7B-Instruct-v0.3 \
-q \
--q-bits 4 \
--output-path ./modelos/mistral-7b-4bitA conversão reduz drasticamente o espaço ocupado em disco e a memória necessária durante a inferência, ao preço de uma perda pequena de qualidade nas respostas. Para a maioria das tarefas do dia a dia, essa perda é difícil de notar. Se já trabalhaste a quantização fora do ecossistema Apple, o processo lembra o que se faz com o Hugging Face, mas aqui fica tudo dentro do mesmo pacote.
Passo 8: Medir o desempenho real no teu Mac
Os números que a Apple divulga sobre o M5 referem-se sobretudo a ganhos relativos face ao M4, e não a um valor fixo de tokens por segundo válido para qualquer modelo. Segundo dados da própria Apple, o M5 traz entre 19% e 27% de melhoria na geração de texto face ao M4, em MacBooks Pro de 24 GB testados com a mesma configuração. Essa diferença vem, em grande parte, do salto na largura de banda de memória, de 120 GB/s para 153 GB/s.
No tempo até ao primeiro token, a diferença é ainda mais visível: a Apple reporta acelerações de 3,57x no Qwen3-1.7B-MLX-bf16, 3,62x no Qwen3-8B-MLX-bf16, 3,97x no Qwen3-8B-MLX-4bit e 4,06x no Qwen3-14B-MLX-4bit, sempre a comparar M5 com M4.
| Modelo | Chip testado | Tokens/s (geração) | Fonte |
|---|---|---|---|
| Qwen3-4B | M4 Max | ~134,5 tok/s | Teste independente |
| Qwen3.6-35B-A3B | M5 Max | ~120,4 tok/s | Teste independente |
| Gemma-4-E2B | M5 Max | ~204,9 tok/s | Teste independente |
Estes números não são diretamente comparáveis entre si, porque cada teste usou tamanhos de prompt, janelas de contexto e estados térmicos diferentes. Usa-os como referência de ordem de grandeza, não como garantia exata para a tua máquina. Para medir o teu próprio Mac, corre o mesmo prompt três vezes e olha para o valor de “tokens-per-sec” que o próprio mlx_lm.generate imprime no final.
Vale a pena comparar esse número com o que obténs numa API comercial para perceberes se a troca compensa para o teu caso. Uma API na cloud costuma responder a um ritmo constante, pago por token, e sem limite prático de contexto na maioria dos planos. Um Mac local responde sem custo por pedido, mas o ritmo cai conforme o modelo cresce e conforme a conversa acumula contexto. Para tarefas curtas e frequentes, como autocompletar código, o Mac local tende a ganhar. Para tarefas raras e muito exigentes, como analisar um documento de cem páginas de uma vez, a cloud ainda costuma ser mais previsível.
Passo 9: Construir um mini-agente local funcional
Com o modelo a correr e o servidor a responder, o passo seguinte é juntar tudo num pequeno projeto funcional: um agente de linha de comandos que lê uma pergunta, consulta o modelo local e guarda o histórico da conversa num ficheiro. É este o tipo de aplicação que a Apple destacou na sessão “Run local agentic AI on the Mac using MLX” da WWDC26.
from mlx_lm import load, generate
import json
from pathlib import Path
MODELO = "mlx-community/Qwen3-8B-MLX-4bit"
HISTORICO = Path("historico.json")
def carregar_historico():
if HISTORICO.exists():
return json.loads(HISTORICO.read_text())
return []
def guardar_historico(mensagens):
HISTORICO.write_text(json.dumps(mensagens, ensure_ascii=False, indent=2))
def main():
modelo, tokenizer = load(MODELO)
mensagens = carregar_historico()
print("Agente local pronto. Escreve 'sair' para terminar.")
while True:
pergunta = input("> ")
if pergunta.strip().lower() == "sair":
break
mensagens.append({"role": "user", "content": pergunta})
prompt = tokenizer.apply_chat_template(mensagens, add_generation_prompt=True)
resposta = generate(modelo, tokenizer, prompt=prompt, max_tokens=400)
print(resposta)
mensagens.append({"role": "assistant", "content": resposta})
guardar_historico(mensagens)
if __name__ == "__main__":
main()Guarda este código como agente.py e corre com python agente.py. Tens, neste momento, um projeto completo: ambiente isolado, modelo quantizado, histórico persistente e uma interface de conversação, tudo a correr sem depender de ligação à internet depois do primeiro download do modelo.
Este mini-agente ainda é simples de propósito, para que o código caiba num único ficheiro e seja fácil de seguir. A partir daqui, a extensão mais natural é dar-lhe acesso a ferramentas, por exemplo uma função que lê ficheiros locais ou que consulta uma base de dados, e deixar o modelo decidir quando chamar essa função dentro da própria conversa. É esse padrão, de modelo mais ferramentas, que a Apple chama de IA agêntica local, e que sustenta boa parte do interesse à volta da MLX em 2026.
Passo 10: Escalar para vários Macs com inferência distribuída
Para modelos maiores do que a memória de um único Mac consegue aguentar, a Apple apresentou na WWDC26 um caminho de treino e inferência distribuída entre várias máquinas, usando RDMA sobre Thunderbolt para reduzir a latência da comunicação entre Macs ligados fisicamente. Esta funcionalidade destina-se sobretudo a quem tem acesso a mais do que um Mac com Apple Silicon e quer juntar a memória de ambos para correr um modelo que, isolado, não caberia em nenhum dos dois.
Para a maioria dos leitores deste tutorial, com um único Mac, este passo serve mais como mapa do que vem a seguir do que como tarefa imediata. Vale a pena conhecer a opção antes de decidir comprar um Mac Studio topo de gama só para caber um modelo gigante.
Na prática, montar este tipo de cluster exige dois Macs ligados por um cabo Thunderbolt, ambos com a mesma versão da MLX instalada, e um processo de coordenação que distribui as camadas do modelo entre as duas máquinas. É um cenário pensado para quem já trabalha com modelos de dezenas de bilhões de parâmetros e tem acesso físico a mais do que um Mac Studio ou Mac Pro, não para o utilizador comum que só quer testar um modelo de 8B.
Passo 11: Proteger o servidor local e os dados
Correr um modelo localmente não elimina automaticamente todos os riscos de privacidade. Vale a pena fixar algumas regras antes de deixar o servidor a correr durante horas.
- Mantém o
mlx_lm.serverligado a127.0.0.1, nunca a0.0.0.0, a não ser que precises mesmo de acesso remoto e tenhas autenticação configurada. - Descarrega modelos apenas de fontes verificadas, como a organização mlx-community ou os repositórios oficiais das empresas que os treinaram.
- Evita repositórios que exijam
trust_remote_code=Truesem conseguires ler o código que isso executa. - Lembra-te que o histórico do terminal, notebooks e ficheiros de registo podem guardar as tuas conversas mesmo que a inferência seja inteiramente offline.
- Usa um volume de disco encriptado se guardares conversas sensíveis no ficheiro de histórico, como o
historico.jsoncriado no Passo 9.
Nenhuma destas medidas é exclusiva da MLX, aplicam-se a qualquer motor de inferência local, mas é fácil esquecê-las quando o foco está só em pôr o modelo a responder. Vale também confirmar a licença de cada modelo antes de o usares num produto comercial ou de partilhares as respostas publicamente, porque a licença “open source” do código da MLX não cobre automaticamente os pesos de todos os modelos que correm sobre ela.
Passo 12: Manter tudo atualizado e automatizar o arranque
A MLX evolui rápido, com lançamentos frequentes que trazem ganhos de desempenho sem mudares uma linha de código. Atualiza o pacote de vez em quando:
pip install --upgrade mlx-lmSe usas o servidor com frequência, cria um pequeno script de arranque que ativa o ambiente virtual e lança o mlx_lm.server automaticamente, em vez de repetires os comandos todos os dias. Isto fecha o ciclo: tens um ambiente instalado, um modelo escolhido, um servidor a correr, um projeto funcional e um processo de manutenção simples.
Onde Aprender Mais sobre a MLX
A documentação oficial, no repositório ml-explore/mlx-lm, mantém-se atualizada a cada lançamento e é a primeira paragem quando um comando deste tutorial mudar de sintaxe numa versão futura. A equipa de investigação da Apple publica também notas de desempenho e exemplos adicionais em machinelearning.apple.com, incluindo os números de M5 usados no Passo 8. Para quem quer ver a MLX aplicada a um modelo específico fora da família Qwen, a própria equipa do Qwen mantém um guia de integração com mlx-lm na sua documentação, e as gravações das sessões da WWDC26 da Apple sobre IA agêntica local e inferência distribuída continuam disponíveis no portal de vídeos para desenvolvedores da Apple.
Erros Comuns ao Instalar e Usar a MLX
A maior parte dos problemas que aparecem nos primeiros dias de uso da MLX repete-se com tanta frequência que vale a pena conhecê-los antes de os encontrares.
- Tentar instalar num Mac Intel. A MLX depende da arquitetura de memória unificada do Apple Silicon e simplesmente não corre em processadores Intel.
- Escolher um modelo demasiado grande para a memória disponível. Um Qwen3-14B em bf16 pode exceder a memória de um Mac com 16 GB e travar o sistema. Confirma sempre a coluna “memória aproximada” antes de descarregar.
- Esquecer de ativar o ambiente virtual. Sair e voltar a abrir o Terminal sem correr
source .venv/bin/activateé a causa mais comum de erros de “comando não encontrado” neste tutorial. - Expor o servidor à rede sem autenticação. Mudar
--hostpara0.0.0.0por curiosidade e esquecer de voltar atrás deixa o modelo acessível a qualquer dispositivo na mesma rede Wi-Fi. - Misturar versões antigas e novas do mlx-lm. Atualizações trazem mudanças na forma como alguns modelos são carregados, e um ambiente desatualizado pode falhar silenciosamente a carregar um modelo mais recente.
Resolução de Problemas: os Erros Mais Frequentes
Se algo correu mal a meio do tutorial, a tabela seguinte cobre os oito problemas que mais aparecem em fóruns e grupos de programadores a usar a MLX pela primeira vez.
| Problema | Causa provável | Solução |
|---|---|---|
| command not found: mlx_lm.generate | Ambiente virtual inativo | Corre source .venv/bin/activate antes de qualquer comando |
| Download do modelo trava a meio | Ligação à internet instável | Volta a correr o mesmo comando, o download retoma do ponto onde parou |
| Erro de memória insuficiente | Modelo demasiado grande para a RAM disponível | Escolhe uma versão em 4-bit ou um modelo mais pequeno |
| Respostas muito lentas | Outras aplicações a consumir memória unificada | Fecha apps pesadas (navegador com muitas abas, editores de vídeo) antes de correr |
| Servidor não responde ao curl | Porta errada ou servidor ainda a carregar o modelo | Confirma a porta no comando curl e espera a mensagem de “model loaded” |
| ModuleNotFoundError: mlx_lm | Instalação feita fora do ambiente virtual correto | Confirma com which python que estás dentro do .venv certo |
| Respostas em inglês quando pedes português | Modelo sem boa cobertura de português europeu | Reforça no prompt “responde em português de Portugal” e testa outro modelo da tabela |
| Conversão com mlx_lm.convert falha | Modelo de origem incompatível ou licença restrita | Confirma no model card do Hugging Face se o modelo é mesmo compatível com conversão |
Dicas Avançadas para Tirar Mais Partido da MLX
Depois de dominares os doze passos anteriores, há caminhos que valem o investimento extra de tempo. O primeiro é o fine-tuning com LoRA, já incluído no próprio mlx-lm, que permite afinar um modelo para um domínio específico, como respostas de suporte técnico ou um tom de escrita próprio, sem precisares de treinar do zero. O processo lembra o que se faz com o Unsloth fora do ecossistema Apple, mas corre inteiramente dentro da MLX.
O segundo caminho é combinar precisões diferentes no mesmo fluxo de trabalho: usar um modelo pequeno e rápido em bf16 para tarefas simples e reservar o 4-bit de um modelo maior só para perguntas mais complexas, trocando entre os dois programaticamente conforme a dificuldade da pergunta.
Um terceiro caminho, mais avançado, é correr vários modelos pequenos em paralelo, cada um especializado numa tarefa diferente, como um para código e outro para resumos, e deixar um script simples decidir qual chamar com base no tipo de pedido recebido. Isto exige mais memória do que correr um único modelo, mas em Macs com 32 GB ou mais torna-se perfeitamente viável, e evita o compromisso de escolher um único modelo generalista para tudo.
Por fim, vigia a memória de pico que o próprio mlx_lm.generate imprime no final de cada execução. Esse número sobe com o tamanho do contexto, por isso conversas muito longas acabam por consumir mais memória do que o modelo por si só, e é esse crescimento que normalmente explica quedas de desempenho a meio de uma sessão de chat prolongada.
Uma última dica, menos óbvia, é não assumires que o modelo mais recente é sempre a melhor escolha para a tua tarefa. Um Qwen3 mais antigo e mais pequeno, já bem testado, pode responder mais rápido e com menos surpresas do que a última novidade lançada há dias, ainda com conversões MLX pouco maduras. Antes de trocares de modelo em produção, corre os mesmos testes do Passo 8 e compara os números lado a lado.
Perguntas Frequentes sobre a MLX da Apple
A MLX funciona em qualquer Mac?
Não. Funciona apenas em Macs com chip Apple Silicon, do M1 ao M5. Macs com processador Intel não conseguem correr a framework, porque depende da arquitetura de memória unificada entre CPU e GPU.
Preciso de internet para usar os modelos depois de instalados?
Não. Depois do primeiro download do modelo, toda a geração de texto corre offline, sem enviar dados para nenhum servidor externo.
A MLX é mais rápida do que o Ollama?
Depende do modelo e do chip. Como motor de baixo nível otimizado para Metal, a MLX costuma ter vantagem em cenários de experimentação e quantização personalizada, mas o Ollama já usa a MLX como backend em muitos casos no Mac, o que reduz a diferença prática para quem só quer conversar com um modelo. A diferença torna-se mais visível quando precisas de controlo fino sobre o carregamento do modelo, sobre o formato exato dos pesos ou sobre scripts de afinação personalizados, áreas onde a MLX dá acesso direto que o Ollama não expõe.
Quanto espaço em disco um modelo típico ocupa?
Varia entre 1 GB, em modelos muito pequenos e fortemente quantizados, e mais de 15 GB em modelos maiores em precisão bf16. A tabela de modelos deste tutorial dá uma referência para as famílias Qwen3 mais usadas em 2026.
Posso usar a MLX para substituir a API da OpenAI no meu código?
Sim, em grande parte. O mlx_lm.server expõe um endpoint compatível com o formato de chat da OpenAI, por isso código já escrito para essa API costuma funcionar só trocando o endereço do servidor.
Vale a pena comprar um Mac novo só para correr modelos locais com MLX?
Só se já precisares de um Mac novo por outros motivos. Um M1 ou M2 com 16 GB já corre modelos de 7B a 8B em 4-bit com desempenho aceitável. O salto para M4 ou M5 nota-se sobretudo em tempo até à primeira resposta e em modelos maiores, não é indispensável para começar. Se o teu uso principal for programação do dia a dia ou conversas curtas, o ganho de um chip mais recente compensa menos do que parece à primeira vista, e o dinheiro talvez renda mais investido em memória extra do que em geração de chip.
A MLX suporta modelos em português?
A MLX corre qualquer modelo convertido para o seu formato, incluindo modelos multilingues como Qwen3, Gemma e Mistral, que têm cobertura razoável de português. A qualidade da resposta em português depende do modelo escolhido, não da framework em si.
É seguro correr um servidor MLX num portátil que uso em cafés ou aeroportos?
É seguro desde que o servidor fique ligado apenas a 127.0.0.1, como mostrado no Passo 6. Dessa forma, nenhum outro dispositivo na mesma rede Wi-Fi consegue aceder ao modelo ou às conversas, mesmo em redes públicas partilhadas com estranhos.
