MiniMax M3.1 Flash GGUF: memoria, ejecución local y API

Para ejecutar MiniMax M3.1 Flash GGUF en local, empieza con UD-Q2_K_XL y reserva 160 GiB+ de memoria. Si tu equipo dispone de 256 GiB+, prioriza UD-Q4_K_XL. Si tendrías que comprar hardware para programar de forma ocasional, calcula primero cuánto costaría una prueba con la API.

Estas estimaciones de Unsloth, consultadas el 2026-11-06, suponen un contexto de texto de 16K y un único slot del servidor. La memoria puede repartirse entre RAM y VRAM, o ser memoria unificada. El procedimiento completo permite servir una API local y conectarla a OpenCode 1.

¿Cuánta memoria necesita M3.1 Flash?

Reserva memoria para todos los pesos cuantizados, más el consumo adicional del motor de inferencia. La ficha original del modelo de MiniMax indica aproximadamente 428B parámetros, con 23B activos por token. Esa cantidad activa reduce el cálculo, pero no significa que solo debas cargar un modelo de 23B.

Unsloth publica los siguientes tamaños y objetivos de memoria. Las descargas se expresan en GB decimales; las cifras de memoria, en GiB.

Cuantización	Tamaño de descarga	Tamaño de los pesos	Memoria prevista
UD-IQ1_M	129.4 GB	120.5 GiB	Experimento con memoria limitada; consulta la explicación siguiente
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+

Unsloth reserva unos 20–32 GiB adicionales para la caché de claves y valores, el motor de inferencia y el sistema operativo. Esa caché conserva el estado de atención del contexto actual. Los contextos más largos, los slots adicionales, la visión y la decodificación especulativa necesitan más memoria.

Los pesos de 1-bit dejan solo 7.5 GiB libres en un equipo de 128 GiB. Esa cantidad está por debajo del margen adicional indicado. Para Q2, usa la recomendación más conservadora de Unsloth: 160 GiB.

La suma de RAM y VRAM indica dónde puedes distribuir los pesos; no forma una memoria totalmente intercambiable. Al trasladar parte del procesamiento a CPU, debe quedar suficiente RAM del sistema para los pesos correspondientes. Reserva también espacio en disco para la descarga elegida.

El contexto anunciado de 1M no convierte estas estimaciones en requisitos para un contexto de 1M. Empieza con 16K y aumenta el límite después de comprobar el consumo de memoria.

¿Qué cuantización conviene elegir?

Usa Q2 para comprobar primero si el modelo cabe y funciona. Después, compara Q4 en tus tareas reales de programación si tienes memoria suficiente. Elige una variante de 3-bit cuando Q4 supere tu capacidad.

Las cifras generales y por categoría de Unsloth tienen alcances distintos:

Coincidencia top-1 publicada por Unsloth	UD-Q2_K_XL	UD-Q4_K_XL
Resumen general ponderado	91.5%	98.0%
Programación	91.2%	97.6%
Conversación general	88.5%	97.3%
Matemáticas	95.7%	99.0%

El resumen general pondera siete categorías. Las filas de conversación y matemáticas corresponden a categorías individuales. Esto explica por qué Q2 tiene tanto una cifra de 91.5% como otra de 88.5%.

La coincidencia top-1 mide si el modelo cuantizado elige el mismo token de mayor probabilidad que el modelo de referencia. No mide la proporción de tareas de programación resueltas. Un resultado de 91.2% en programación no significa que el 91.2% de los cambios en un repositorio superen sus pruebas.

Considera 1-bit una opción experimental para equipos con poca memoria, aunque su coincidencia general ronde el 89.9%. Comprueba las modificaciones de archivos, los argumentos de las herramientas y el comportamiento en varios pasos antes de confiar en cualquier cuantización.

Q8 añade 9.7 GB frente a Q4. Unsloth lo describe como una conversión sin pérdida de los pesos publicados, que conserva una combinación de formatos NVFP4 y BF16. Por tanto, la etiqueta «8-bit» no indica una precisión uniforme para todos los tensores.

¿Qué motor de inferencia encaja con tu hardware?

Elige un conjunto de pesos y unas instrucciones preparados para tu motor de inferencia. Que una configuración EXL3 quepa en memoria no demuestra que la GGUF correspondiente también quepa.

Las siguientes opciones reflejan la documentación verificada a fecha de 2026-11-06:

Hardware	Opción que conviene revisar	Límite práctico
Apple Silicon	Pesos oQ3e de MLX-community con oMLX	El conjunto ocupa 196.152 GB / 182.681 GiB, incluidos los componentes de borrador y visión. Añade memoria para el motor de inferencia y el contexto.
Un DGX Spark	Configuración SAGE-EXL3 de vcruz305	Está destinada a un sistema GB10 de 128 GB, con versiones fijadas de los componentes y acceso a los pesos sujeto a autorización. Solo sirve texto y admite un flujo de decodificación.
AMD Instinct	Pesos Quark MXFP4 de AMD	La configuración documentada indica MI350/MI355, Linux y ROCm 7.2.3. Incluye un ejemplo de paralelismo tensorial con cuatro GPU; no es una receta genérica para Radeon.
Cuatro tarjetas RTX 3090	Inferencia personalizada reconocida en la publicación de MiniMax del 1 de noviembre sobre la comunidad	MiniMax atribuye a @superalesha una combinación de pesos cuantizados, caché de expertos y RAM del sistema. Ese reconocimiento no garantiza el mismo rendimiento en otras configuraciones.

Para tu primera instalación GGUF, sigue el procedimiento explícito con llama.cpp que aparece a continuación. Antes de un despliegue comercial, revisa la MiniMax Community License, incluidas sus condiciones de atribución y notificación.

Compila llama.cpp e inicia un servidor de 16K

Usa la rama de compatibilidad con MiniMax enlazada por Unsloth. A fecha de 2026-11-06, la PR #31192 de llama.cpp seguía abierta y sin integrar. Este ejemplo fija el commit observado en la cabecera de esa PR.

Compilación y descarga

Usa Bash en Ubuntu o WSL, con el NVIDIA CUDA toolkit ya instalado. Instala los requisitos restantes y compila el 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

En macOS, instala las herramientas de línea de comandos de Xcode, CMake, Python y jq. Omite los comandos apt-get y cambia -DGGML_CUDA=ON por -DGGML_CUDA=OFF. La documentación de compilación indica que Metal está activado de forma predeterminada en macOS.

Descarga los cuatro fragmentos de Q2 mediante la CLI de 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/*"

Mantén los fragmentos juntos. Al indicar el primero, el servidor carga el conjunto completo.

Inicio y comprobación

Empieza con un slot, un contexto explícito de 16K y decodificación de texto normal:

./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

La PR requiere Jinja, Flash Attention y un único slot para esta implementación de atención dispersa. Las opciones de llama-server permiten asignar automáticamente las capas a la GPU.

Este comando no añade un proyector de visión ni un modelo de borrador DSpark. No configura una clave de API y solo escucha en la dirección de bucle local.

Si falla la asignación de VRAM, reduce el número de capas en GPU y comprueba la RAM disponible del sistema. Si falta memoria total, elige una cuantización más pequeña o añade memoria. Trasladar trabajo a la CPU no elimina la necesidad de almacenar los pesos.

Comprueba que el servidor esté listo desde una segunda terminal Bash:

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

Continúa cuando recibas HTTP 200 con {"status":"ok"}. HTTP 503 con Loading model significa que la inicialización sigue en curso.

Después, consulta el modelo disponible y solicita una respuesta:

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}'

Comprueba que la lista de modelos incluya m31-local y que message.content contenga la respuesta solicitada. En esta prueba básica, el esfuerzo low de la solicitud sustituye al valor predeterminado high del servidor.

Si finish_reason es length, la respuesta ha agotado su límite de salida. Aumenta ese límite sin superar el contexto total antes de interpretar la falta de texto final como un fallo de carga del modelo.

Conecta OpenCode 1 y verifica una llamada a una herramienta

Conecta el cliente de programación mediante la integración documentada de OpenCode para proveedores personalizados. OpenCode ejecuta las herramientas de archivos; llama-server genera las respuestas del modelo.

Esta configuración sigue la documentación de OpenCode 1. OpenCode 1 y OpenCode 2 usan el mismo comando opencode. Si ya utilizas V2, prepara un entorno separado.

Para instalar V1 desde cero, con Node.js y npm disponibles:

npm install -g opencode-ai
opencode --version

Incorpora esta configuración a opencode.json en la raíz del proyecto. Sigue el ejemplo oficial del proveedor 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
          }
        }
      }
    }
  }
}

Esta configuración local no necesita una clave de API ficticia. El límite de contexto coincide con el del servidor. El límite de salida es un presupuesto elegido para las respuestas, no el máximo del modelo.

En un proyecto de Node que contenga package.json, ejecuta:

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."

Busca un paso real de lectura mediante una herramienta y compara la respuesta con el archivo. No basta con que el modelo afirme haberlo leído.

Si el cliente no se conecta, comprueba la URL base con /v1, el alias del modelo y que el servidor siga activo. Si el texto funciona pero las herramientas fallan, confirma --jinja y repite esta comprobación acotada antes de intentar editar el repositorio.

Mantén pequeña la primera sesión. Si las definiciones de herramientas ocupan demasiado contexto, aplica el método de la guía sobre el costo de contexto de MCP antes de ampliar la ventana del servidor.

¿Cuándo conviene usar la API en su lugar?

Empieza con la API si necesitarías comprar hardware para un uso ocasional. Considera la ejecución local si ya tienes capacidad suficiente o necesitas que el modelo se ejecute en tu equipo.

A fecha de 2026-11-06, la tarifa estándar de la API de MiniMax indica:

Concepto facturado	USD por 1 millón de tokens
Entrada sin caché	$0.15
Lectura de entrada desde la caché	$0.015
Salida	$0.60

Estos cargos por consumo de API se descuentan del saldo de la cuenta. MiniMax también describe como uniformes las tarifas por token de Flash. Su fórmula de facturación de la caché incluye entrada nueva, aciertos de caché y salida, sin añadir un cargo separado por escritura en caché.

Considera una carga mensual ilustrativa de 20 millones de tokens de entrada sin caché y 2 millones de tokens de salida facturados:

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

Este cálculo supone solicitudes solo de texto, sin aciertos de caché ni herramientas de servidor de pago. Excluye impuestos y comisiones aplicadas al pagar.

Como comparación, considera este presupuesto 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 los valores del cálculo local son supuestos. No representan una oferta de un equipo verificado ni demuestran que complete esa carga de trabajo en 60 horas. Añade el consumo en reposo, la instalación, el mantenimiento y las ampliaciones necesarias antes de decidir una compra.

Usa el mismo esfuerzo de razonamiento al comparar ejecuciones reales. La API de MiniMax usa max de forma predeterminada, mientras que este servidor local usa high. Calcula con los tokens de salida facturados y evalúa el costo por tarea de programación completada, incluidos los reintentos y los pasos fallidos con herramientas.

BetterToken también incluye MiniMax-M3.1-Flash con pago por uso a fecha de 2026-11-06. Su URL base documentada compatible con OpenAI es https://www.bettertoken.ai/v1. Usa sus precios actuales para calcular el costo de esa opción.

Si ya tienes el hardware, sustituye la asignación ilustrativa por tus costos adicionales reales. Después, mide tareas representativas. La ejecución local será útil cuando la memoria disponible, el tiempo de finalización y los resultados aceptados cumplan tus necesidades.