MiniMax M3.1 Flash GGUF: memória, configuração e custos de API

Para rodar MiniMax M3.1 Flash GGUF, comece com UD-Q2_K_XL e 160 GiB+ de memória. Prefira UD-Q4_K_XL com 256 GiB+ quando sua máquina tiver memória suficiente. Se precisar comprar hardware para programar ocasionalmente, calcule primeiro o custo de um teste pela API.

Estas estimativas da Unsloth, verificadas em 2026-11-06, consideram contexto de texto de 16K e um slot no servidor. A memória pode ser distribuída entre RAM e VRAM ou usar memória unificada. O procedimento abaixo disponibiliza uma API local e a conecta ao OpenCode 1.

De quanta memória o M3.1 Flash precisa?

Reserve espaço para todos os pesos quantizados e para a memória adicional necessária à execução. A ficha original do modelo MiniMax informa aproximadamente 428B parâmetros, com 23B ativos por token. Essa quantidade ativa reduz o processamento; ela não significa que você carregará apenas um modelo de 23B parâmetros.

A Unsloth publica os tamanhos e as metas de memória abaixo. Os downloads usam GB decimais; os valores de memória usam GiB.

Quantização	Tamanho do download	Tamanho dos pesos	Meta de memória
UD-IQ1_M	129.4 GB	120.5 GiB	Experimento com pouca memória; veja abaixo
UD-Q2_K_XL	143.9 GB	134.0 GiB	160 GiB+
UD-IQ3_XXS	160.0 GB	149.1 GiB	176 GiB+
UD-IQ3_S	175.5 GB	163.4 GiB	192 GiB+
UD-Q3_K_XL	194.0 GB	180.6 GiB	208 GiB+
UD-Q4_K_XL	249.4 GB	232.3 GiB	256 GiB+
UD-Q8_K_XL	259.1 GB	241.3 GiB	272 GiB+

A Unsloth reserva cerca de 20–32 GiB além dos pesos para o cache de chaves e valores, a execução e o sistema operacional. Esse cache armazena o estado da atenção para o contexto atual. Contextos maiores, slots adicionais, visão e decodificação especulativa exigem mais memória.

Só os pesos de 1-bit deixam apenas 7.5 GiB livres em uma máquina com 128 GiB. Isso fica abaixo da reserva adicional indicada. Para Q2, use a recomendação mais conservadora da Unsloth: 160 GiB.

Somar RAM e VRAM ajuda a planejar a distribuição dos pesos, mas essas memórias não são intercambiáveis. Ao transferir parte da execução para a CPU, deixe RAM suficiente para os pesos deslocados da GPU. Reserve também espaço em disco para o download escolhido.

O contexto anunciado de 1M não significa que essas estimativas cubram um contexto de 1M. Comece com 16K e aumente o limite depois de verificar o uso de memória.

Qual versão quantizada escolher?

Use Q2 para verificar primeiro se o modelo cabe na máquina. Depois, compare Q4 nas suas tarefas reais de programação, se houver memória. Escolha uma variante de 3-bit quando Q4 ultrapassar sua capacidade.

Os resultados gerais e os resultados por categoria da Unsloth têm escopos diferentes:

Concordância top-1 informada pela Unsloth	UD-Q2_K_XL	UD-Q4_K_XL
Resumo geral ponderado	91.5%	98.0%
Programação	91.2%	97.6%
Conversas gerais	88.5%	97.3%
Matemática	95.7%	99.0%

O resultado geral pondera sete categorias. As linhas de conversas e matemática representam categorias individuais. Isso explica por que Q2 aparece com valores de 91.5% e 88.5%.

A concordância top-1 mede se o modelo quantizado escolhe o mesmo token mais bem classificado que o modelo de referência. Ela não mede a taxa de aprovação em tarefas de programação. O resultado de 91.2% em programação não significa que 91.2% das alterações em repositórios passarão nos testes.

Trate 1-bit como um experimento para situações de pouca memória, apesar da concordância geral de aproximadamente 89.9%. Verifique edições de arquivos, argumentos das ferramentas e tarefas com várias etapas antes de confiar em qualquer versão quantizada.

Q8 acrescenta 9.7 GB em relação a Q4. A Unsloth o descreve como uma conversão sem perdas dos pesos publicados, que preserva a combinação de formatos NVFP4 e BF16. Portanto, o rótulo “8-bit” não indica uma precisão uniforme em todos os tensores.

Qual motor de inferência usar no seu hardware?

Escolha um conjunto de pesos e um procedimento preparados para o seu motor de inferência. Um resultado de memória obtido com EXL3 não comprova que o GGUF correspondente caberá na mesma máquina.

A documentação das opções abaixo foi verificada em 2026-11-06:

Hardware	Opção a avaliar	Limite prático
Apple Silicon	Pesos oQ3e da MLX-community com oMLX	O conjunto totaliza 196.152 GB / 182.681 GiB, incluindo o modelo auxiliar e os componentes de visão. Some a memória de execução e de contexto.
Um DGX Spark	Procedimento SAGE-EXL3 de vcruz305	Destina-se a um sistema GB10 com 128 GB, versões fixadas dos componentes, acesso aos pesos mediante solicitação, atendimento apenas de texto e um fluxo de decodificação.
AMD Instinct	Pesos Quark MXFP4 da AMD	A configuração documentada especifica MI350/MI355, Linux, ROCm 7.2.3 e um exemplo de paralelismo de tensores com quatro GPUs. Não é um procedimento genérico para Radeon.
Quatro placas RTX 3090	Inferência personalizada reconhecida na publicação da MiniMax para a comunidade em 1 de novembro	A MiniMax atribui a abordagem de @superalesha a pesos quantizados, cache de especialistas e RAM do sistema. Esse reconhecimento não garante o mesmo desempenho em outras configurações.

Para a primeira implantação de GGUF, siga o procedimento explícito com llama.cpp abaixo. Antes do uso comercial, consulte a MiniMax Community License, incluindo suas condições de atribuição e notificação.

Compile o llama.cpp e inicie um servidor com contexto de 16K

Use a branch com suporte ao MiniMax indicada pela Unsloth. Em 2026-11-06, o PR #31192 do llama.cpp continuava aberto e não havia sido integrado. Este exemplo fixa o commit mais recente observado nessa branch.

Compile e baixe os pesos

Use Bash no Ubuntu ou WSL, com o toolkit NVIDIA CUDA já instalado. Instale os demais pré-requisitos e compile o servidor:

sudo apt-get update
sudo apt-get install -y build-essential cmake git libssl-dev python3-venv curl jq

git clone https://github.com/ggml-org/llama.cpp
git -C llama.cpp fetch origin pull/31192/head:minimax-m31
git -C llama.cpp checkout --detach 6b95a9908d2c7b242817a447708aec38e937e2c0

cmake llama.cpp -B llama.cpp/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --target llama-server

No macOS, instale as ferramentas de linha de comando do Xcode, CMake, Python e jq; pule os comandos apt-get. Troque -DGGML_CUDA=ON por -DGGML_CUDA=OFF. A documentação de compilação informa que Metal fica habilitado por padrão no macOS.

Baixe todas as quatro partes dos pesos Q2 pela CLI do Hugging Face:

python3 -m venv .venv-m31
source .venv-m31/bin/activate
python -m pip install -U huggingface_hub

hf download unsloth/MiniMax-M3.1-Flash-GGUF \
  --local-dir unsloth/MiniMax-M3.1-Flash-GGUF \
  --include "UD-Q2_K_XL/*"

Mantenha as partes juntas. Ao indicar a primeira parte, o servidor carrega o conjunto completo.

Inicie o servidor e verifique a resposta

Comece com um slot, contexto explícito de 16K e decodificação comum de texto:

./llama.cpp/build/bin/llama-server \
  --model unsloth/MiniMax-M3.1-Flash-GGUF/UD-Q2_K_XL/MiniMax-M3.1-Flash-UD-Q2_K_XL-00001-of-00004.gguf \
  --alias m31-local \
  --ctx-size 16384 \
  --parallel 1 \
  --n-gpu-layers auto \
  --jinja \
  --flash-attn on \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 0 \
  --min-p 0.0 \
  --chat-template-kwargs '{"reasoning_effort":"high"}' \
  --host 127.0.0.1 \
  --port 8080

O PR especifica Jinja, Flash Attention e um slot para essa configuração com atenção esparsa. As opções de llama-server permitem alocar automaticamente as camadas na GPU.

Esse comando não adiciona um projetor de visão nem um modelo auxiliar DSpark. Nenhuma chave de API está configurada, e o servidor aceita conexões apenas pelo endereço de loopback local.

Se a alocação de VRAM falhar, reduza o número de camadas na GPU e verifique a RAM disponível no sistema. Se a memória total for insuficiente, escolha uma quantização menor ou adicione memória. Transferir pesos para a CPU não elimina a necessidade de armazená-los.

Em um segundo terminal Bash, verifique se o servidor está pronto:

curl -sS -i http://127.0.0.1:8080/health

Prossiga quando receber HTTP 200 com {"status":"ok"}. HTTP 503 com Loading model indica que a inicialização ainda está em andamento.

Depois, consulte o modelo disponível e solicite uma resposta:

curl -sS http://127.0.0.1:8080/v1/models | jq '.data[].id'

curl -sS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "m31-local",
    "messages": [
      {"role": "user", "content": "Reply with LOCAL_OK."}
    ],
    "reasoning_effort": "low",
    "max_tokens": 4096,
    "stream": false
  }' | jq '{message: .choices[0].message, finish_reason: .choices[0].finish_reason}'

Verifique se a lista inclui m31-local e se message.content contém a resposta solicitada. Neste teste básico, o esforço low da requisição substitui o padrão high do servidor.

Se finish_reason for length, a resposta atingiu seu limite de saída. Aumente esse limite dentro do orçamento total de contexto antes de atribuir a ausência do texto final a uma falha no carregamento.

Conecte o OpenCode 1 e verifique uma chamada de ferramenta

Use a integração documentada de provedor personalizado do OpenCode para conectar o cliente de programação. O OpenCode executa as ferramentas de arquivos; o llama-server gera as respostas do modelo.

Esta configuração segue a documentação do OpenCode 1. OpenCode 1 e OpenCode 2 usam o mesmo comando opencode. Se você já usa V2, configure um ambiente separado.

Para uma nova instalação de V1, com Node.js e npm disponíveis:

npm install -g opencode-ai
opencode --version

Mescle a configuração abaixo com o arquivo opencode.json na raiz do projeto. Ela segue o exemplo oficial de provedor llama.cpp:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MiniMax local",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "m31-local": {
          "name": "MiniMax M3.1 Flash Q2",
          "limit": {
            "context": 16384,
            "output": 4096
          }
        }
      }
    }
  }
}

Essa configuração local dispensa uma chave de API fictícia. O limite de contexto corresponde ao servidor em execução. O limite de saída define um orçamento para a resposta; ele não representa o máximo do modelo.

Em um projeto Node que contenha package.json, execute:

opencode run --model local/m31-local \
  "Read package.json with a file tool. Report scripts.test, or say it is missing. Do not edit files or run commands."

Procure uma etapa real de leitura de arquivo por ferramenta e compare a resposta com o arquivo. A afirmação do modelo de que leu o arquivo não basta.

Se o cliente não conectar, confira a URL base com /v1 e o alias do modelo. Verifique também se o servidor está em execução. Se o texto funcionar, mas as ferramentas falharem, confira --jinja. Repita essa verificação limitada antes de tentar editar o repositório.

Mantenha a primeira sessão pequena. Se as definições das ferramentas consumirem muito contexto, siga o método do guia de custo de contexto do MCP antes de ampliar a janela do servidor.

Quando usar a API?

Comece pela API se precisar comprar hardware para uso ocasional. Considere a execução local quando já tiver capacidade suficiente ou precisar manter a execução do modelo na sua máquina.

Em 2026-11-06, a tabela padrão de preços da API MiniMax informa:

Item cobrado	USD por 1 milhão de tokens
Entrada sem cache	$0.15
Leitura de entrada em cache	$0.015
Saída	$0.60

São cobranças por uso da API, descontadas do saldo da conta. A MiniMax também descreve as tarifas do Flash como uniformes. Sua fórmula de cobrança do cache inclui entrada nova, acertos de cache e saída, sem acrescentar um item separado de gravação no cache.

Considere uma carga mensal ilustrativa de 20 milhões de tokens de entrada sem cache e 2 milhões de tokens de saída faturados:

API token charge = 20 × $0.15 + 2 × $0.60
                 = $4.20 per month

O exemplo considera apenas chamadas de texto, sem acertos de cache e sem ferramentas pagas no servidor. Impostos e taxas de pagamento ficam de fora.

Para comparar, considere este orçamento local ilustrativo:

Hardware allocation = $3,000 ÷ 36 months
                    = $83.33 per month

Active electricity  = 0.15 kW × 60 hours × $0.20/kWh
                    = $1.80 per month

Local subtotal      = $85.13 per month

Todos os valores usados no cálculo local são suposições. O cálculo não é uma cotação de uma máquina verificada nem comprova que ela concluirá essa carga em 60 horas. Antes de comprar, acrescente energia em repouso, configuração, manutenção e eventuais atualizações de equipamento.

Use o mesmo esforço de raciocínio ao comparar execuções reais. A API MiniMax usa max por padrão, enquanto este servidor local usa high. Considere os tokens de saída faturados e avalie o custo por tarefa de programação concluída, incluindo novas tentativas e falhas nas ferramentas.

A BetterToken também lista MiniMax-M3.1-Flash para acesso com pagamento por uso em 2026-11-06. Sua URL base documentada, compatível com OpenAI, é https://www.bettertoken.ai/v1. Use os preços atuais ao calcular o custo dessa opção.

Se você já tiver o hardware, substitua a parcela ilustrativa de aquisição pelos seus custos incrementais reais. Depois, meça tarefas representativas. A execução local só atende ao objetivo quando a capacidade de memória, o tempo de conclusão e os resultados aceitos correspondem às suas necessidades.