Inferencia local e híbrida

No todos los prompts necesitan un modelo de frontera en el centro de datos de otra persona. Bromure Agentic Coding puede ejecutar modelos de código de pesos abiertos directamente en la GPU de tu Mac con el framework MLX de Apple — sin ida y vuelta a la nube, sin factura por token y sin que el código salga de la máquina. Un espacio de trabajo puede ejecutarse íntegramente en el dispositivo, seguir usando la nube con una red de seguridad en el dispositivo, o mezclar ambos agente por agente.

La inferencia local es una elección por espacio de trabajo, ortogonal a Fusion: Fusion decide cuántos modelos responden a un prompt, mientras que el enrutamiento decide qué backend lo responde. Este capítulo explica dónde se ejecuta la inferencia, cómo funcionan el catálogo de modelos y las descargas, los tres modos de enrutamiento y el motor de políticas híbrido, cómo apuntar un agente individual a un modelo local, y cómo observar el comportamiento del motor. La referencia campo por campo de los ajustes de este panel está en Ajustes de Modelos locales.

Nota: Todo lo que se describe aquí se ejecuta en el anfitrión Mac, no dentro de la VM. Virtualization.framework no da al invitado Linux ningún acceso a la GPU, Metal o MLX, así que la inferencia en el dispositivo tiene que ocurrir en macOS y ser alcanzada desde el invitado a través del límite de red. Se requiere Apple Silicon (M1 o más reciente) — el mismo requisito que la propia app.

Dónde se ejecuta la inferencia

El motor está integrado en la app; no hay nada que instalar, ni entorno de Python, ni servidor externo como Ollama, LM Studio o una instancia de vLLM autoalojada a la que apuntar. Cuando una sesión necesita inferencia en el dispositivo, la app inicia un motor MLX privado y conecta el agente invitado con él.

El proceso hijo del motor

El motor MLX se ejecuta como un proceso hijo supervisado del propio binario de la app (bromure-cli model _mlx-engine), no dentro de la app en sí. Este aislamiento es deliberado: cargar un modelo demasiado grande para la memoria del Mac mata solo al proceso hijo del motor, nunca a la app ni a sus VM en ejecución. El padre reinicia automáticamente un motor caído, hasta tres veces; después se rinde con la línea de registro engine child crashed repeatedly — giving up (a model likely OOMs this Mac). El hijo se mata cuando la app se cierra, y cualquier huérfano dejado por un fallo grave se recolecta en el siguiente arranque.

Un solo motor sirve a todos los espacios de trabajo abiertos. Vincula un puerto de loopback asignado por el kernel en 127.0.0.1 — nunca 0.0.0.0, y nunca el convencional 11434 (ese puerto se deja libre para que una instalación separada de Ollama o LM Studio siga funcionando). Carga varios modelos en paralelo bajo un presupuesto de memoria igual a la memoria unificada del anfitrión menos 16 GB (con un mínimo de 8 GB), cargando cada modelo de forma diferida en su primer uso y desalojando el usado menos recientemente cuando el presupuesto está ajustado. Abrir o cerrar un espacio de trabajo reconfigura el motor en ejecución en caliente a través de un endpoint de administración — sin reinicio.

Mientras el motor se calienta, las ventanas de sesión muestran una pastilla de estado que dice Iniciando el motor local… que desaparece una vez que el motor responde a una sonda de disponibilidad.

Cómo el invitado alcanza el motor

Los agentes dentro de la VM nunca hablan directamente con el motor. Apuntan al anfitrión sintético https://bromure.llm — un nombre sin DNS real — y el proxy MITM del lado del anfitrión lo intercepta, aplica el mismo escaneo de inyección de prompts y la misma captura de trazas que aplica al tráfico de la nube, y reenvía la solicitud al motor del anfitrión. Por tanto, la inferencia local nunca es un punto ciego: cruza el mismo límite de red y aterriza en el mismo registro de auditoría que una llamada a Anthropic.

Los agentes están fijados a un nombre de modelo centinela, bromure-local, que el anfitrión reasigna al modelo actualmente activo del espacio de trabajo. Cambiar el modelo activo es una reasignación del lado del anfitrión sin reinicio del agente — el agente sigue pidiendo bromure-local y simplemente obtiene un modelo diferente detrás.

Nota: Un modelo cuya arquitectura el motor MLX aún no admite falla con un error claro y permanente — "its architecture … isn't supported by the on-device engine yet — pick a different model" — devuelto como error de cliente para que el agente no lo reintente en bucle.

El catálogo de modelos

El catálogo es una lista curada de modelos MLX preconvertidos, cada uno examinado para lo único que más importa en la codificación agéntica: los modelos cuantizados suelen romper las llamadas a herramientas, así que cada entrada del catálogo lleva una insignia de verificación de llamadas a herramientas. Las entradas también registran un tamaño de descarga y un requisito mínimo de memoria unificada, que el panel convierte en una comprobación de ajuste de RAM.

Un catálogo base viene incluido en la app para que el panel funcione sin conexión desde el primer día. Al arrancar, la app obtiene un catálogo actualizado de https://dl.bromure.io/mlx/catalog.json; un manifiesto más nuevo reemplaza por completo al base (no se fusiona). Un modelo retirado del catálogo publicado desaparece de la lista — a menos que ya lo tengas instalado, en cuyo caso sobrevive como un extra instalado.

Modelos que vienen en el catálogo base

El catálogo incluido es un conjunto de modelos de código Qwen3 en distintos niveles de memoria. Los cuatro están verificados para llamadas a herramientas:

El modelo de 8 mil millones de parámetros se ejecuta en cualquier Mac compatible; el modelo de mezcla de expertos de 480 mil millones de parámetros necesita una máquina de 512 GB (un M3 Ultra) y por esa razón no está marcado como recomendado. Un catálogo actualizado puede añadir compilaciones más nuevas o más grandes sin una actualización de la app.

Insignias y la comprobación de ajuste de RAM

Cada fila del panel (y cada línea de bromure-cli model catalog) lleva dos insignias:

• Un nivel de tamaño — S para modelos que necesitan 16 GB o menos, M hasta 32 GB, L hasta 64 GB, XL por encima de eso.
• Un veredicto de ajuste frente a la memoria unificada de tu Mac: Encaja, Ajustado o No encaja. "Encaja" requiere el mínimo del modelo más 16 GB de margen para el sistema operativo y todo lo demás; "Ajustado" significa que se carga con poco espacio de sobra; "No encaja" significa que el mínimo del modelo supera tu memoria. Las filas que no encajan aparecen atenuadas y no se pueden seleccionar ni descargar.

Por ejemplo, el modelo Qwen3 8B (mínimo de 16 GB) muestra Ajustado en un Mac de 16 GB y Encaja en 32 GB o más; Qwen3-Coder 30B-A3B (mínimo de 32 GB) muestra Encaja a partir de 48 GB.

Usar un modelo fuera del catálogo

El catálogo es un menú curado, no una valla. Cualquier repositorio de Hugging Face que ya esté en formato MLX se puede descargar por su nombre org/repo desde la línea de comandos (consulta Referencia de línea de comandos); un modelo así se trata como no probado — no lleva garantía de llamadas a herramientas ni certeza de ajuste de RAM. Los repositorios en formato GGUF se rechazan de plano, porque GGUF es la vía de Ollama y llama.cpp, no de MLX:

That's a GGUF (Ollama/llama.cpp) model — Bromure serves MLX weights only.

Descargar y almacenar modelos

Los pesos se descargan directamente desde huggingface.co mediante un descargador integrado y puramente en Swift — sin Python, sin mlx_lm.convert, sin conversión de ningún tipo. El descargador lee la lista de archivos del repositorio desde la API de Hugging Face, transmite cada archivo de pesos a un archivo temporal .partial y lo renombra atómicamente a su lugar; la documentación, las imágenes y cualquier archivo GGUF del repositorio se omiten. Antes de empezar, una comprobación previa de espacio en disco falla rápido en lugar de llenar tu disco:

Not enough disk space: 40 GB free, but about 270 GB is needed.

Dónde viven los modelos

Los pesos descargados aterrizan en una estructura plana, por repositorio, bajo tu directorio de Application Support:

~/Library/Application Support/BromureAC/models/<org>--<name>/

Cada directorio contiene el config.json del modelo, sus fragmentos .safetensors y su tokenizador. Las descargas son un efecto secundario global, compartido entre todos los espacios de trabajo — descargar un modelo una vez lo hace disponible para todos ellos. Los modelos previamente almacenados en caché por otras herramientas en ~/.cache/huggingface/hub se migran a este directorio una sola vez, mediante enlaces duros, para que nada se descargue dos veces.

Estados de descarga en el panel

El control de acción de cada fila de modelo refleja su estado:

Como el descargador se puede reanudar a granularidad de archivo, una descarga interrumpida nunca tiene que empezar de nuevo, y una descarga parcial nunca se confunde con una instalación funcional — un archivo centinela en curso la marca hasta que aterriza el último byte.

Consejo: El primer modelo que descargas se establece automáticamente como el modelo activo del espacio de trabajo, de modo que un espacio de trabajo nuevo pasa de "sin modelo local" a "listo para servir" con un solo clic.

Habilitar modelos locales para un espacio de trabajo

Abre el espacio de trabajo en el explorador de espacios de trabajo, haz clic en Editar espacio de trabajo y selecciona el panel Modelos locales (el icono de CPU en verde menta). El panel comienza como un único interruptor; el selector de modo y la lista de modelos solo aparecen una vez que la inferencia local está activada.

1. Activa Habilitar modelos locales ("Ejecuta un modelo de código en este Mac en lugar de la nube."). Esto aleja el enrutamiento del espacio de trabajo de la nube; volver a desactivarlo restaura la nube.
2. Elige un Modo:
   • Local — siempre en el dispositivo mantiene cada solicitud en este Mac. Como señala el panel, las respuestas son privadas pero más lentas, y están limitadas por el modelo que puedas alojar en memoria.
   • Híbrido — nube, con respaldo local envía las solicitudes a la nube como de costumbre y recurre al modelo del dispositivo solo cuando la nube es inalcanzable — velocidad y calidad de la nube, con una red de seguridad local.
3. En la lista de modelos — encabezada Modelos · N GB de memoria unificada, donde N es la memoria de tu Mac — Descarga un modelo y luego selecciónalo como activo con el punto de radio a su izquierda. Las filas atenuadas necesitan más memoria de la que tiene tu Mac.
4. Haz clic en Guardar.

El modo de enrutamiento y la selección del modelo activo persisten al guardar; las descargas, al ser globales, ocurren de inmediato guardes o no. Si los modelos que seleccionas necesitaran juntos casi tanta o más memoria que la de tu Mac — el motor los sirve en paralelo, así que su memoria se suma — el panel muestra una advertencia y te pide que quites uno o elijas modelos más pequeños.

La lista completa de campos y valores por defecto está en Ajustes de Modelos locales.

Enrutamiento: Nube, Local e Híbrido

El enrutamiento es la elección de nivel superior, por espacio de trabajo, de qué backend sirve el tráfico LLM de un agente. Tiene tres valores:

Seleccionar Local o Híbrido activa automáticamente la vía de interceptación MITM — nunca accionas un interruptor separado para ello. Cada turno respondido se etiqueta en la traza con un marcador de servido-por que registra qué backend respondió: cloud o local-<model>. Puedes leerlo en el Inspector de trazas para confirmar, turno a turno, adónde fue realmente una sesión híbrida.

El enrutamiento es un valor por defecto por espacio de trabajo establecido en el panel, pero también se puede cambiar en una VM en ejecución desde la línea de comandos con bromure-cli vm routing (consulta Referencia de línea de comandos).

Nota: El enrutamiento local redirige al motor el tráfico de un agente hacia los anfitriones de Anthropic y OpenAI (y el centinela bromure.llm). No secuestra un agente que ya esté fijado a una credencial de nube real — por ejemplo, un agente Claude por suscripción que comparte un espacio de trabajo conserva su tráfico de nube real. Para forzar un agente específico a ejecutarse localmente sin importar el enrutamiento del espacio de trabajo, usa su propio modo de autenticación Modelo local, más abajo.

La política de respaldo híbrido

Híbrido no es un solo interruptor, sino un pequeño motor de políticas, ajustado para no romper nunca una trayectoria de codificación cambiando de modelo a mitad de vuelo. Cada decisión se toma en un límite de sesión y luego es persistente — una vez que una conversación se enruta a un backend, se queda allí el resto de esa sesión (la salvaguarda de coherencia).

Qué desencadena un respaldo a local

Para una nueva sesión, gana la primera regla que coincide, en este orden: una sesión persistente ya fijada, un presupuesto de tokens de nube agotado, una nube en mal estado (la comprobación de salud), una asignación por ratio de reparto y, en caso contrario, la nube. Durante una solicitud que ya está en vuelo hacia la nube, dos cosas fuerzan una repetición inmediata en el modelo local, fijando la sesión a local durante toda su vida:

• Errores graves — una conexión rechazada o con tiempo de espera agotado, o un HTTP 429, 529 o 5xx del proveedor.
• Un plazo blando incumplido — ningún primer token dentro del presupuesto de TTFT (5 segundos por defecto).

Debajo hay una comprobación de salud conservadora: la nube se marca como en mal estado tras al menos tres fallos en las últimas aproximadamente diez solicitudes, o cuando la media móvil ponderada exponencialmente del TTFT sube por encima de 8 segundos, y solo se recupera tras tres sondas limpias y rápidas. Mientras la nube está en mal estado, las nuevas sesiones van directas a local sin que cada una pague primero la penalización del tiempo de espera blando. Los backends nunca se compiten entre sí — no hay cobertura especulativa ni doble gasto; el respaldo se dispara solo tras un desencadenante real.

Los ajustes configurables

Se exponen tres ajustes, y solo a través de la línea de comandos contra una VM en ejecución (consulta Referencia de línea de comandos). Persisten por espacio de trabajo pero se ignoran a menos que el enrutamiento sea Híbrido:

Los detalles internos de la comprobación de salud (el umbral de 8 segundos de la EWMA, la ventana de fallos y el número de sondas de recuperación) son fijos y no configurables por el usuario.

Modelos locales como backend de un agente

El enrutamiento es un eje que abarca todo el espacio de trabajo, pero también puedes apuntar un solo agente al motor local, dejando el resto del espacio de trabajo en la nube. En la pestaña Agentes del espacio de trabajo, cada agente — Claude Code, Codex o Grok — tiene un selector de modo de autenticación cuyas opciones incluyen Modelo local. Elígelo, escoge un modelo instalado, y ese agente se ejecuta íntegramente contra el motor del dispositivo con claves de nube ficticias que el motor ignora; el MITM aplica las mismas protecciones que aplica al tráfico de la nube.

Esto hace posibles los espacios de trabajo mixtos — por ejemplo, Claude Code con una suscripción junto a Codex en un modelo local. El enrutamiento Local de todo el perfil nunca secuestra el tráfico real de un agente de nube, y el modo Local por agente nunca se filtra a los demás. Cuando activas o desactivas la inferencia local en el panel Modelos locales, la app mantiene el modo de autenticación de cada agente en sincronía automáticamente.

Modelos locales en Fusion

Un modelo local también es un participante válido en Fusion, la función de síntesis multimodelo, y puede desempeñar allí cualquiera de dos roles:

• Como una rama. Marca Modelo local en Modelos a fusionar y elige un modelo instalado; su respuesta preliminar se une al panel junto a Claude, Codex y Grok. Como se ejecuta en tu Mac, es una rama adicional capaz a coste marginal cero.
• Como el juez. Elige Local como proveedor del juez de Fusion para ejecutar la etapa de análisis y síntesis íntegramente en el dispositivo, manteniendo todo el paso de juzgado fuera de la nube.

Ambos roles necesitan al menos un modelo local descargado; hasta entonces, las filas correspondientes en el panel de Fusion aparecen atenuadas con una indicación para descargar uno aquí primero. Consulta Fusion para el flujo de trabajo completo del panel.

Reparación de llamadas a herramientas

El modo de fallo predominante de los modelos cuantizados en uso agéntico es emitir una llamada a herramienta como texto plano en lugar de una llamada estructurada que el agente pueda ejecutar. Un proxy de reparación se sitúa frente al motor — tanto el invitado como la ruta local del MITM apuntan a él, no al motor desnudo — y rescata estos casos de forma transparente.

Para cada respuesta almacena en búfer la salida y vuelve a analizar las muchas formas ad-hoc en que un modelo podría filtrar una llamada, entre ellas:

<function name="write_file" arguments='{…}'>
<tool_call>{…}</tool_call>
[{"name": "…", "parameters": {…}}]

así como el formato nativo <function=Name><parameter=k>v</parameter></function> de Qwen3-Coder y el formato de canales de Gemma. Sintetiza bloques de uso de herramientas apropiados a partir de lo que encuentre y vuelve a emitir el mensaje como SSE correcto según el protocolo, en la forma de red nativa del agente. También detecta un preámbulo atascado — donde el modelo narra una acción ("Now I'll create the file:") y luego termina su turno sin llegar a llamar a la herramienta — y vuelve a preguntar hasta dos veces para recuperar la llamada faltante. Se añade un recordatorio de formato de herramienta al prompt del sistema siempre que se declaran herramientas.

La reparación siempre está activada para la inferencia local y no necesita configuración. Los problemas del motor se convierten en cuerpos de error nativos de la red, para que el agente muestre el motivo real en lugar de un fallo genérico, por ejemplo:

Local inference engine unreachable (starting up, reloading a model, or stopped) — retry in a moment.

Monitorizar el motor

Dos ventanas bajo el menú Ventana te permiten observar la inferencia en el dispositivo sin abrir Console.app.

Métricas de inferencia

Ventana → Métricas de inferencia… abre un panel de telemetría en vivo (título de ventana Métricas de inferencia), encabezado con la etiqueta Inferencia local y la dirección de loopback del motor. Analiza las métricas Prometheus del motor y las convierte en tarjetas — Decode tok/s, Prefill tok/s, En ejecución, En espera, En vuelo, Latencia media, Aciertos de caché, Memoria Metal, Tokens generados y Tokens de prompt — más una lista de Modelos cargados y un desplegable Todas las métricas con la tabla en bruto.

La ventana sondea cada 5 segundos, y solo mientras está abierta. Las tasas de decodificación y prellenado son, por diseño, ratios acumulativos de por vida, así que se leen como promedios estables en lugar de deltas por segundo bruscos. Cuando el motor está caído el panel muestra engine not reachable, y durante una generación larga puede mostrar brevemente engine busy (timed out).

Registro del motor de inferencia

Ventana → Registro del motor de inferencia… abre un seguimiento en vivo (título de ventana Registro del motor de inferencia) de la salida del proceso hijo del motor más los eventos de ciclo de vida del padre — cargas de modelos, "serving", estadísticas por solicitud, y cualquier OOM, fallo, reinicio o error de carga. Las líneas están codificadas por color (rojo para fallos, verde para eventos sanos, naranja para advertencias, azul para trabajo en curso). La barra de herramientas ofrece un campo Filtrar…, una casilla Desplazamiento automático, Copiar y Limpiar; cuando aún no ha pasado nada, muestra No inference-engine activity yet. El búfer es un anillo en memoria limitado a 5.000 líneas, y cada línea también se refleja en la salida de errores estándar de la app, así que lanzar bromure-cli desde una terminal te da una copia duradera.

Referencia de línea de comandos

Los comandos de modelos y enrutamiento hablan con la API de control de la app en ejecución, así que la app (o su agente) debe estar en ejecución. Los comandos que actúan sobre una VM específica toman un argumento final <vm>, que es un id de VM o un nombre de espacio de trabajo. Los valores por defecto persistentes por espacio de trabajo se editan en los paneles de la GUI descritos arriba; estos comandos actúan sobre una sesión en vivo. Consulta Automatización y CLI para el conjunto de comandos circundante.

Gestión de modelos:

bromure-cli model catalog [--all] [--offline]
bromure-cli model pull <catalog-id | org/repo>
bromure-cli model ls
bromure-cli model use <catalog-id | org/repo> <vm>
bromure-cli model rm <catalog-id | org/repo>

Enrutamiento y política híbrida para una VM en ejecución:

bromure-cli vm routing cloud|local|hybrid <vm>
bromure-cli vm hybrid budget <tokens> <vm>
bromure-cli vm hybrid ttft <seconds> <vm>
bromure-cli vm hybrid split <0-100> <vm>
bromure-cli vm fusion enable|disable <vm>

vm routing establece el modo de backend; los tres ajustes vm hybrid afinan la política de respaldo (y solo tienen efecto cuando el enrutamiento es Híbrido). vm fusion activa el panel multimodelo ortogonal y está documentado en Fusion.

Comandos de diagnóstico internos

Estos subcomandos ocultos existen para el desarrollo y la solución de problemas y no forman parte del flujo de trabajo cotidiano. El propio proceso hijo del motor es generado por la app como bromure-cli model _mlx-engine --config <path>.

Comando	Propósito
bromure-cli model _mlx-serve <repo>	Inicia el servidor MLX en proceso para un modelo y se bloquea, imprimiendo su puerto y clave para pruebas con curl.
bromure-cli model _mlx-selftest <repo>	Carga un modelo, genera una vez e imprime el TTFT y los tok/s de decodificación.
bromure-cli model _repair-serve --engine-port <port>	Ejecuta el proxy de reparación de llamadas a herramientas de forma independiente contra un motor en ejecución.
bromure-cli model _tc-test <path>	Ejecuta el rescate de llamadas a herramientas sobre un archivo de texto guardado para comprobar la extracción de llamadas filtradas.
bromure-cli model _spec-bench <main-repo> --draft <draft-repo>	Compara el rendimiento de la decodificación especulativa desactivada frente a activada para un par de modelos.

Expectativas de rendimiento

La inferencia en el dispositivo intercambia velocidad por privacidad y coste, y el intercambio es real — ajusta tus expectativas en consecuencia:

• El rendimiento escala con el modelo y el chip. Un modelo pequeño como Qwen3 8B es ágil en cualquier Mac compatible; las grandes compilaciones de mezcla de expertos son más lentas y necesitan mucha más memoria. La ventana Métricas de inferencia muestra las tasas reales de decodificación y prellenado en tu hardware — el número honesto sobre el que planificar.
• La primera solicitud paga por la carga de un modelo. Un motor frío muestra Iniciando el motor local… mientras se calienta; los pesos grandes tardan un tiempo real en cargarse en memoria antes de que aparezca el primer token. Las solicitudes posteriores se saltan esto.
• Los bucles de agente multiturno se abaratan tras el primer turno. El motor mantiene una caché KV de prefijo por conversación (hasta cuatro ranuras de sesión por modelo), así que cada turno del agente prellena solo los nuevos tokens en lugar de toda la transcripción — y una cadena lateral no desaloja la caché de la conversación principal.
• La generación está serializada. El motor ejecuta una generación a la vez, así que varias sesiones ocupadas comparten la GPU en lugar de ejecutarse verdaderamente en paralelo.
• Los modelos de razonamiento piensan en silencio. Para los modelos que emiten un bloque <think>, el bloque siempre se elimina antes de que la respuesta llegue al agente — obtienes la calidad sin el inflado de la transcripción.

Consejo: Si un modelo local se siente lento o se atasca, abre primero la ventana Registro del motor de inferencia: las cargas de modelos, los desalojos, los reinicios por OOM y los errores de arquitectura no admitida aparecen todos allí en texto plano, lo cual es más rápido que adivinar desde el lado del agente.