Como executar o GLM-5.3-Flash em um MacBook Pro: O manual MLX 2bit-Lite

Executando GLM-5.3-Flash em um MacBook Pro significa exatamente uma máquina: um MacBook Pro de 128 GB M4/M5 Max executando a compilação 2bit-lite da nossa conversão MLX, com o limite de memória fixa do macOS elevado. Se o seu MacBook Pro tiver menos de 128 GB — um M4 Pro de 36 GB, um M4 Max de 48 GB — este manual não é para você; pule para a última seção e use a API hospedada z-ai/glm-5.3-flash em vez disso. GLM-5.3-Flash (pesos em zai-org/GLM-5.3-Flash) é o modelo de Mistura de Especialistas de 320 bilhões de parâmetros da Z.ai, com 18B ativos por token — lançado em 26 de agosto de 2026, o primeiro GLM-5 nativamente multimodal — e até mesmo a menor compilação do nosso port de MLX precisa de ~102 GB de pesos e ~112 GB de memória. Esse é o mercado inteiro, e não vamos amenizar isso.

Esta é uma documentação de primeira parte, não um texto de lançamento: os pesos abaixo são da compilação própria da OrcaRouter (orcarouter/GLM-5.3-Flash-MLX, MIT), produzida com nosso método de quantização OrcaSAQ sem calibração. Disponibilizamos essa versão em 26 de agosto e corrigimos publicamente o rumo no dia seguinte, porque a faixa de quantização original não tornava o uso em MacBook Pro prático para a maioria das pessoas — a compilação regular de 2 bits ainda exigia ~160 GB, o que nenhum laptop tem. Em 27 de agosto, reconstruímos a variante menor como 2bit-lite especificamente para caber em um MacBook Pro de 128 GB, e este texto é o relato honesto do que isso proporciona e do que custa. Cada número marcado como nota de campo abaixo foi medido em nossa execução de verificação em um único H200; nada aqui é um benchmark de fornecedor. Onde repetimos práticas da comunidade — o comando de memória fixa, o versionamento do mlx-vlm — nós os rotulamos como tal.

Qual versão se adequa a qual Mac (leia isto antes de baixar qualquer coisa)

Cada um dos cinco builds no repositório corresponde a um valor mínimo de RAM. Em um MacBook Pro, "qual build" tem exatamente uma resposta — tudo acima 2bit-lite é uma conversa sobre Mac Studio:

• 6-bit — ~296 GB de pesos / ~320 GB de RAM / quase sem perdas. Mac Studio apenas com 512 GB.

• 4-bit — ~204 GB / ~224 GB / nosso padrão recomendado. Mac Studio 256 GB. É isso que a raiz do repositório espelha.

• 3-bit — ~184 GB / ~200 GB. Mac Studio 256 GB.

• 2-bit — ~145 GB / ~160 GB. Mac Studio 192 GB. Esta foi a menor configuração que lançamos no primeiro dia, e foi o erro.

• 2bit-lite — ~102 GB / ~112 GB. A única versão que cabe numa máquina de 128 GB — um MacBook Pro M4/M5 Max de 128 GB, ou um Mac Studio ou Mac mini de 128 GB. Qualquer laptop Apple Silicon de 128 GB (M3 Max ou mais novo) é a mesma história, apenas mais lento.

A armadilha escondida nessa escada: o comando de download padrão do README baixa a build de 4 bits (~204 GB), que é o padrão certo para uma máquina de 256 GB e inútil em um laptop. Se você seguir o comando padrão em um MacBook Pro, acaba com um modelo que não vai alocar. O caminho 2bit-lite requer um explícito --include, abordado abaixo.

Há também um teto rígido que você encontrará antes mesmo de a matemática acima se aplicar. O macOS não permite que um processo use toda a memória unificada de um Mac de 128 GB; o teto padrão utilizável pela GPU é de aproximadamente 91–96 GB (engenharia reversa feita pela comunidade e corroborada em vários artigos sobre configurações de MLX com modelos grandes). Isso está abaixo dos ~102 GB apenas de pesos, então nem o 2bit-lite carregará até que você aumente o limite de memória fixa. Esse passo é obrigatório, e é a Seção 4.

Instale mlx-vlm — e somente mlx-vlm

GLM-5.3-Flash é um modelo de visão-linguagem, portanto roda com mlx-vlm, não mlx-lm. Esta é a forma mais comum de as pessoas ficarem presas, então diga isso logo: mlx-lm é para modelos apenas de texto; executar um modelo multimodal por meio dele produz um erro de carregamento confuso. Instale o pacote VLM na versão 0.6.17 ou superior:

pip install -U "mlx-vlm>=0.6.17"

A fixação da versão não é decoração. glm5_next — a arquitetura híbrida de atenção esparsa mais linear por trás do GLM-5.3-Flash — só chegou ao mlx-vlm no mesmo dia em que o modelo foi lançado (26 de agosto de 2026), e qualquer versão mais antiga não reconhecerá a configuração. A arquitetura importa por um segundo motivo: esta é uma topologia totalmente nova, e os primeiros portes tiveram bugs reais de correção que uma saída fluente não revelaria. Uma auditoria de runtime da comunidade sobre o caminho MLX inicial do glm5_next encontrou e corrigiu quatro deles — um clamp SwiGLU não aplicado em todo bloco FFN, tensores de hiperconexão com restrição de manifold convertidos para o dtype errado (o que corrompia silenciosamente a matriz de mistura da atenção), duas incompatibilidades de épsilon nas normas de atenção e logits do router em bf16 onde a referência usa float32. Após as correções, os valores numéricos corresponderam à referência em aproximadamente 1e-7. A conclusão para você: mantenha o mlx-vlm atualizado e trate com desconfiança o primeiro lançamento de qualquer porte de arquitetura nova.

Baixe os pesos: os flags de exclusão e os de inclusão que você realmente precisa.

A raiz do repositório espelha a compilação de 4 bits, e todas as cinco variantes são distribuídas como subpastas. O comando padrão baixa a raiz e usa --exclude para que nenhuma das cinco pastas de variantes (que juntas têm cerca de 800 GB) seja incluída:

hf download orcarouter/GLM-5.3-Flash-MLX --local-dir ./GLM-5.3-Flash-MLX --exclude "2bit-lite/*" "2-bit/*" "3-bit/*" "4-bit/*" "6-bit/*"

Em um MacBook Pro, esse comando está errado para você — ele fornece a raiz de 4 bits. Para um laptop de 128 GB, baixe apenas a subpasta 2bit-lite:

hf download orcarouter/GLM-5.3-Flash-MLX --include "2bit-lite/*" --local-dir ./GLM-5.3-Flash-MLX

Esse é o download de ~102 GB, e ele é autocontido — a pasta 2bit-lite/ carrega seu próprio config.json, então você aponta o gerador direto para ela. Se o hf não estiver no seu PATH, instale-o: pip install -U huggingface_hub. Antes de começar, confirme que você tem ~110 GB de espaço livre em disco e que o armazenamento do seu Mac não esteja com apenas os últimos 100 GB livres — o MLX mapeia os pesos na memória, e um SSD quase cheio é como essas configurações morrem no meio do download.

Aumente o limite de memória fixa — a etapa que todos esquecem

Este é o passo decisivo em um MacBook Pro de 128 GB, e o cartão README presume que você já o conhece, em vez de explicar o comando. O limite padrão do working-set da Metal em um Mac de 128 GB é de aproximadamente 91–96 GB, o que fica abaixo dos ~102 GB dos pesos 2bit-lite — portanto, sem este passo, o modelo não consegue alocar memória e o carregamento falha. A correção padrão da comunidade é um sysctl que aumenta o teto de memória wireada da GPU em megabytes:

sudo sysctl iogpu.wired_limit_mb=114688

Isso define um teto de aproximadamente 112 GB, deixando cerca de 14 GB como reserva do sistema. Em máquinas de 128 GB, os valores da comunidade na prática variam de ~114688 (112 GB) até ~122880 (120 GB); não coloque no máximo — o macOS precisa de folga, caso contrário você terá engasgos no window-server e travamentos do sistema sob pressão de memória. Após definir o valor, carregue o modelo e observe o Activity Monitor: se a pressão de memória ficar amarela, reduza o número.

Duas notas práticas, ambas da prática da comunidade, em vez de nossas notas de campo. Primeiro, o sysctl é redefinido ao reiniciar e se aplica à sessão de terminal em que você o definiu, portanto planeje executá-lo novamente (ou crie um script via LaunchAgent) — esquecê-lo depois de reiniciar é a clássica falha de "funcionou ontem". Segundo, o MLX também expõe um ajuste no processo, mlx.core.metal.set_wired_limit(bytes), no macOS 15.0 e versões mais recentes; ele deve permanecer abaixo do teto do sysctl, e é a opção mais portátil se você estiver criando scripts em um notebook. Não importa qual você use, o efeito é o mesmo: sem isso, nada aqui funciona.

Execute: texto, imagem e a API Python.

Com os pesos no lugar e o limite elevado, a geração é um único comando.

python -m mlx_vlm.generate --model ./GLM-5.3-Flash-MLX/2bit-lite --prompt "Explique o emaranhamento quântico em uma frase." --max-tokens 256

A entrada de imagem funciona da mesma forma com a flag --image — é aqui que o modelo multimodal mostra seu valor em um notebook, já que a torre de visão permanece com maior precisão no layout OrcaSAQ:

python -m mlx_vlm.generate --model ./GLM-5.3-Flash-MLX/2bit-lite --image photo.jpg --prompt "Descreva esta imagem." --max-tokens 256

Para um script, a API Python tem o mesmo formato que os usuários de mlx-vlm conhecem:

from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template model, processor = load("./GLM-5.3-Flash-MLX/2bit-lite") prompt = apply_chat_template(processor, model.config, "Descreva esta imagem.", num_images=1) print(generate(model, processor, prompt, ["photo.jpg"], max_tokens=256, verbose=True))

Mantenha --max-tokens modesto. Em nossa execução de notas de campo no H200, o 2bit-lite mantém aproximadamente 10 tok/s, então uma resposta de 1.024 tokens já é uma espera de dois minutos — e saídas longas são onde o orçamento de KV e o colapso de qualidade se fazem sentir (abaixo). Em um laptop, você deve esperar que pareça mais lento, não mais rápido, até que exista um número medido.

Que qualidade você está realmente obtendo (a escada medida)

Aqui está a parte honesta do manual, e não vamos encobrir isso. O OrcaSAQ degrada suavemente até 3 bits; depois, o custo sobe rapidamente. Em relação à referência FP8 (perplexidade 2,7797):

• 6-bit — perplexidade 2,7864 (+0,24%), concordância do token top-1 97,76%. Quase sem perdas, como anunciado.

• 4-bit — perplexidade 2.8620 (+2,96%), top-1 96,13%. O padrão recomendado.

• 3-bit — perplexidade 3.0566 (+9,96%), top-1 92,06%. Agressivo, mas utilizável.

• 2-bit — perplexidade 4.3622 (+56.9%), top-1 86.56%. Um custo real.

• 2bit-lite — perplexity 6.7018 (+141%), top-1 77.19%. A menor build, e a única que um MacBook Pro pode comportar.

Esses são números medidos do nosso próprio pipeline de conversão. O 2bit-lite representa uma regressão de perplexidade de 141% e uma concordância de token top-1 abaixo de 78% — você está executando um modelo visivelmente degradado, e os modos de falha abaixo são o que essa degradação parece na prática. É uma demonstração brilhante e um assistente razoável para respostas curtas; não é um substituto para o modelo de precisão total.

Sobre velocidade, devemos a você a mesma honestidade. A nota de campo publicada é H200: ~10 tok/s, multi-turn estável, Q&A do dia a dia e texto curto funcionam bem. Ainda não temos um número medido em MacBook Pro para o 2bit-lite e não vamos inventar um — a vazão em Apple Silicon aqui depende da largura de banda da memória, das condições térmicas e da cobertura de kernels MLX para a atenção híbrida, nenhum dos quais medimos para esta compilação neste laptop. O ponto de dados Apple Silicon publicado mais próximo que podemos indicar é um ~450 tok/s independente para uma compilação GLM-5.3-Flash de 4 bits em um Mac de 512 GB sob um runtime MLX diferente — uma compilação diferente, uma precisão diferente e uma máquina desktop, então também não o leia como o seu número. Planeje para a lentidão; surpreenda-se agradavelmente se ela não vier.

Cache KV e contexto longo: atenção ao espaço livre

GLM-5.3-Flash anuncia uma janela de contexto de 1 milhão de tokens. Esse número é irrelevante neste hardware, e um guia que afirmasse o contrário estaria prestando um desserviço a você. A nota de campo tem uma linha: dê ao runtime orçamento de KV suficiente para o comprimento alvo. Em um único H200, o 2bit-lite deixa cerca de 39 GB de folga para o cache KV após o carregamento dos pesos. Em um MacBook Pro de 128 GB, a aritmética é mais severa: ~102 GB de pesos contra um teto de ~112 GB deixa cerca de 26 GB antes do próprio conjunto de trabalho do macOS — e as camadas híbridas de atenção linear tornam a pegada de KV deste modelo pequena em relação a um modelo denso deste tamanho, mas ela ainda cresce linearmente com o contexto.

Orientações do lado do servidor vindas da comunidade em geral corroboram o ponto: uma configuração que carrega bem em um contexto de 8K pode ficar sem memória em 128K. No laptop, mantenha contextos curtos — alguns milhares de tokens de perguntas e respostas ou uma única imagem — e não tente alimentá-lo com um livro. No momento em que uma carga de trabalho realmente precisa de contexto longo, você está na última seção deste artigo.

A geração de código longo não é confiável em 2bit-lite (leia isto duas vezes)

Esta é a seção sem a qual um guia que esconde seus modos de falha não teria valor, então ela ganha seu próprio título. As notas de campo do H200 são inequívocas: perguntas e respostas cotidianas e textos curtos saem bem, e a geração de código longo não é confiável nessa precisão. Três modos de falha reproduzidos em nossa execução de verificação:

• Laços de repetição — o modelo começa a repetir as mesmas linhas ou blocos em vez de progredir, geralmente após algumas centenas de tokens.

• Código de cola ausente — imports, conexões e tratamento de erros silenciosamente descartados. A função gerada parece correta isoladamente, mas não é executada, porque o arcabouço circundante simplesmente está ausente.

• Churn de reescrita — em vez de uma edição mínima, o modelo reescreve grandes partes de um arquivo, e as saídas de turnos sucessivos discordam entre si.

Essas coisas são reproduzíveis em 2bit-lite, e são precisamente as coisas que uma concordância top-1 de 77% prevê. O que os profissionais que mantêm a compilação do laptop por perto realmente fazem:

• Use-o para explicação, sumarização, Q&A e compreensão de imagens — trabalho de formato curto em que ele é genuinamente bom.

• Se você precisar pedir código, peça uma pequena função de cada vez com uma assinatura explícita, e verifique cada uma antes de continuar. Não entregue a ele um arquivo inteiro e peça uma funcionalidade.

• Para qualquer coisa longa — um módulo completo, uma refatoração, uma longa sessão de agente — roteie para a API de precisão total. Isso não é uma solução alternativa; é a arquitetura correta, e é a última seção.

Quando não fazer isso de forma alguma: use z-ai/glm-5.3-flash em vez disso.

A regra de decisão honesta: execute o 2bit-lite em um MacBook Pro M4/M5 Max de 128 GB somente quando você quiser especificamente um modelo multimodal de 320B em um laptop que você pode carregar — perguntas e respostas offline, documentos privados, compreensão de imagens sem que nada saia da máquina. Escolha a API para todo o resto:

• Qualquer MacBook Pro com menos de 128 GB — não há versão para você. Não tente carregá-la; use a API.

• Geração de código extenso ou raciocínio de contexto longo — 2bit-lite falha exatamente nisso, de forma confiável. Use a API.

• Trabalho sensível à qualidade — Concordância top-1 de 77,19% e perplexidade +141% representam uma queda real, não um erro de arredondamento. Use a API.

• Taxa de transferência garantida ou latência previsível — ainda não existe um número medido para laptop, e o valor registrado em campo é de 10 tok/s. Use a API.

O modelo hospedado é z-ai/glm-5.3-flash, servido com precisão total no OrcaRouter ao preço atual da Z.ai — $0.07 por milhão de tokens de entrada e $0.25 por milhão de tokens de saída no momento em que escrevo (preço de lançamento; a tabela publicada da Z.ai é de $0.15 / $0.50). Esse é o preço informado pelo fornecedor, repassado com margem de 0%, então uma redução de preço da Z.ai se reflete do nosso lado no mesmo dia. Você recebe uma única chave de API que também dá acesso aos outros mais de 200 modelos que roteamos, e o failover automático significa que um experimento com esse novo modelo não coloca o seu caminho de produção nas mãos de um único provedor. No mesmo tempo que se leva para baixar 102 GB e esperar a primeira geração a frio, a API já respondeu a uma semana inteira de perguntas — e ela as responde com precisão total.

A inferência local vale a pena quando o motivo é local — privacidade, trabalho offline, sem limites de requisições, uma demo que roda na bateria. Não vale a pena do ponto de vista de custo ou qualidade por qualquer outro motivo, e não vale a pena de forma alguma em uma máquina com menos de 128 GB.

Perguntas Frequentes

Um Mac de 64 GB ou 96 GB consegue executar o GLM-5.3-Flash localmente?Não. A menor versão, a 2bit-lite, exige cerca de 112 GB no mínimo após a sobrecarga do macOS, e até uma máquina de 128 GB precisa aumentar o limite de memória fixa para carregá-lo. Se o seu Mac tiver menos de 128 GB, o caminho local não existe; encaminhe o z-ai/glm-5.3-flash pela API.

Instalei o mlx-vlm e o modelo não carrega — o que está errado? As duas causas usuais, em ordem: uma versão anterior a 0.6.17, que antecede o suporte a glm5_next e não reconhecerá a arquitetura; e o limite de memória fixa não ter sido elevado, porque a compilação de ~102 GB não consegue alocar sob o teto padrão de ~91–96 GB da Metal em um Mac de 128 GB. Corrija ambos (atualize o pacote, execute o sysctl) e ele carrega.

O build local 2bit-lite é o mesmo modelo que a API z-ai/glm-5.3-flash? Mesmos pesos subjacentes do GLM-5.3-Flash, mas não a mesma qualidade. O 2bit-lite é uma quantização de 2 bits com concordância de token top-1 de 77,19% contra a referência FP8, e a geração de código longo não é confiável. A API oferece precisão total. Eles são intercambiáveis apenas para trabalhos de formato curto e tolerantes à qualidade.

A versão de 30 segundos

Uma máquina, uma build, um sysctl obrigatório. Se você tiver um MacBook Pro M4/M5 Max de 128 GB: instale mlx-vlm>=0.6.17, baixe apenas 2bit-lite/ (~102 GB), aumente o limite de memória fixa com sudo sysctl iogpu.wired_limit_mb=114688 e execute mlx_vlm.generate — para perguntas e respostas, textos curtos e imagens. Aceite que a geração de código longo não é confiável nessa precisão, que ainda não há throughput medido em laptops e que um Mac de 128 GB é o mínimo, não o padrão. Se qualquer uma dessas ressalvas for um impeditivo — ou se o seu Mac tiver menos de 128 GB — o mesmo modelo em precisão total está a uma chamada de API de distância no z-ai/glm-5.3-flash.

Não está em um Mac de 128 GB? z-ai/glm-5.3-flash serve o mesmo modelo com precisão total no OrcaRouter — uma chave de API, preços do provedor repassados com margem de 0% e sem download de 102 GB.