Inferência local e híbrida

Nem todos os prompts precisam de um modelo de fronteira no centro de dados de outra pessoa. O Bromure Agentic Coding pode executar modelos de código de pesos abertos diretamente na GPU do seu Mac com a framework MLX da Apple — sem ida e volta à cloud, sem faturação por token e sem código a sair da máquina. Um espaço de trabalho pode correr inteiramente no dispositivo, continuar a usar a cloud com uma rede de segurança no dispositivo, ou misturar os dois agente a agente.

A inferência local é uma escolha por espaço de trabalho, ortogonal ao Fusion: o Fusion decide quantos modelos respondem a um prompt, enquanto o encaminhamento decide qual backend o responde. Este capítulo explica onde a inferência corre, como funcionam o catálogo de modelos e as transferências, os três modos de encaminhamento e o motor de política híbrida, como apontar um agente individual para um modelo local e como observar o comportamento do motor. A referência campo a campo das definições do painel encontra-se em Definições de Modelos locais.

Nota: Tudo aqui corre no anfitrião Mac, não dentro da VM. O Virtualization.framework não dá ao convidado Linux qualquer acesso a GPU, Metal ou MLX, pelo que a inferência no dispositivo tem de acontecer no macOS e ser alcançada a partir do convidado através da fronteira de transmissão. É necessário Apple Silicon (M1 ou mais recente) — o mesmo requisito da própria aplicação.

Onde a inferência corre

O motor está incorporado na aplicação; não há nada a instalar, nenhum ambiente Python e nenhum servidor externo como o Ollama, o LM Studio ou uma instância vLLM auto-alojada para apontar. Quando uma sessão precisa de inferência no dispositivo, a aplicação inicia um motor MLX privado e liga o agente convidado a ele.

O processo-filho do motor

O motor MLX corre como um processo-filho supervisionado do próprio binário da aplicação (bromure-cli model _mlx-engine), não dentro da própria aplicação. Trata-se de um isolamento deliberado: carregar um modelo demasiado grande para a memória do Mac mata apenas o processo-filho do motor, nunca a aplicação nem as suas VMs em execução. O processo-pai reinicia automaticamente um motor que tenha falhado, até três vezes; a partir daí desiste com a linha de registo engine child crashed repeatedly — giving up (a model likely OOMs this Mac). O processo-filho é terminado quando a aplicação encerra, e qualquer órfão deixado por uma falha grave é recolhido no arranque seguinte.

Um único motor serve todos os espaços de trabalho abertos. Ele associa-se a uma porta de loopback atribuída pelo kernel em 127.0.0.1 — nunca 0.0.0.0 e nunca a convencional 11434 (essa porta é deixada livre para que uma instalação separada de Ollama ou LM Studio continue a funcionar). Carrega vários modelos em paralelo sob um orçamento de memória igual à memória unificada do anfitrião menos 16 GB (com um mínimo de 8 GB), carregando cada modelo de forma preguiçosa na primeira utilização e removendo o menos recentemente usado quando o orçamento aperta. Abrir ou fechar um espaço de trabalho reconfigura o motor em execução ao vivo através de um endpoint de administração — sem reinício.

Enquanto o motor aquece, as janelas de sessão mostram uma etiqueta de estado que diz A iniciar o motor local… e que desaparece assim que o motor responde a uma sonda de prontidão.

Como o convidado alcança o motor

Os agentes dentro da VM nunca falam diretamente com o motor. Eles têm como alvo o anfitrião sintético https://bromure.llm — um nome sem DNS real — e o proxy MITM do lado do anfitrião interceta-o, aplica a mesma análise de injeção de prompt e captura de rastreios que aplica ao tráfego de cloud, e encaminha o pedido para o motor no anfitrião. A inferência local nunca é, portanto, um ponto cego: cruza a mesma fronteira de transmissão e aterra na mesma trilha de auditoria que uma chamada à Anthropic.

Os agentes estão fixados a um nome de modelo sentinela, bromure-local, que o anfitrião remapeia para o modelo atualmente ativo do espaço de trabalho. Trocar o modelo ativo é um remapeamento do lado do anfitrião sem reinício do agente — o agente continua a pedir bromure-local e simplesmente obtém um modelo diferente por trás dele.

Nota: Um modelo cuja arquitetura o motor MLX ainda não suporta falha com um erro claro e permanente — "a sua arquitetura … ainda não é suportada pelo motor no dispositivo — escolha um modelo diferente" — devolvido como um erro de cliente para que o agente não o repita num ciclo.

O catálogo de modelos

O catálogo é uma lista curada de modelos MLX pré-convertidos, cada um verificado quanto à única coisa que mais importa na programação agêntica: os modelos quantizados quebram frequentemente a chamada de ferramentas, por isso cada entrada do catálogo traz um crachá de verificação de chamada de ferramentas. As entradas também registam um tamanho de transferência e um requisito mínimo de memória unificada, que o painel transforma numa barreira de adequação de RAM.

Um catálogo de base é fornecido dentro da aplicação para que o painel funcione offline desde o primeiro dia. No arranque, a aplicação obtém um catálogo atualizado a partir de https://dl.bromure.io/mlx/catalog.json; um manifesto mais recente substitui totalmente o de base (não é fundido). Um modelo retirado do catálogo publicado desaparece da lista — a menos que já o tenha instalado, caso em que sobrevive como um extra instalado.

Modelos incluídos na base

O catálogo integrado é um conjunto de modelos de código Qwen3 em vários níveis de memória. Todos os quatro têm chamada de ferramentas verificada:

O modelo de 8 mil milhões de parâmetros corre em qualquer Mac suportado; o modelo de mistura de especialistas de 480 mil milhões de parâmetros precisa de uma máquina de 512 GB (um M3 Ultra) e, por essa razão, não está marcado como recomendado. Um catálogo atualizado pode adicionar builds mais recentes ou maiores sem uma atualização da aplicação.

Crachás e a barreira de adequação de RAM

Cada linha do painel (e cada linha de bromure-cli model catalog) traz dois crachás:

• Um nível de tamanho — S para modelos que precisam de 16 GB ou menos, M até 32 GB, L até 64 GB, XL acima disso.
• Um veredicto de adequação face à memória unificada do seu Mac: Cabe, Justo ou Não cabe. "Cabe" exige o mínimo do modelo mais 16 GB de folga para o SO e tudo o resto; "Justo" significa que carrega com pouca margem de sobra; "Não cabe" significa que o mínimo do modelo excede a sua memória. As linhas de "Não cabe" ficam esbatidas e não podem ser selecionadas nem transferidas.

Por exemplo, o modelo Qwen3 8B (mínimo de 16 GB) lê Justo num Mac de 16 GB e Cabe com 32 GB ou mais; o Qwen3-Coder 30B-A3B (mínimo de 32 GB) lê Cabe a partir de 48 GB.

Usar um modelo fora do catálogo

O catálogo é um menu curado, não uma cerca. Qualquer repositório da Hugging Face já em formato MLX pode ser puxado pelo seu nome org/repo a partir da linha de comandos (ver Referência da linha de comandos); tal modelo é tratado como não testado — não traz garantia de chamada de ferramentas nem garantia de adequação de RAM. Os repositórios em formato GGUF são rejeitados de imediato, porque o GGUF é o caminho do Ollama e do llama.cpp, não do MLX:

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

Transferir e armazenar modelos

Os pesos são puxados diretamente de huggingface.co por um transferidor integrado e em Swift puro — sem Python, sem mlx_lm.convert, sem conversão de qualquer tipo. O transferidor lê a lista de ficheiros do repositório a partir da API da Hugging Face, transmite cada ficheiro de pesos para um ficheiro temporário .partial e renomeia-o atomicamente para o lugar; documentação, imagens e quaisquer ficheiros GGUF no repositório são ignorados. Antes de começar, uma verificação prévia de espaço em disco falha rapidamente em vez de encher o seu disco:

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

Onde os modelos residem

Os pesos transferidos aterram numa disposição plana, por repositório, dentro do seu diretório Application Support:

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

Cada diretório contém o config.json do modelo, os seus fragmentos .safetensors e o seu tokenizador. As transferências são um efeito secundário global, partilhado por todos os espaços de trabalho — puxar um modelo uma vez torna-o disponível para todos eles. Os modelos previamente colocados em cache por outras ferramentas em ~/.cache/huggingface/hub são migrados para este diretório uma vez, através de hardlinks, para que nada seja transferido duas vezes.

Estados de transferência no painel

O controlo de ação em cada linha de modelo reflete o seu estado:

Como o transferidor é retomável ao nível do ficheiro, uma transferência interrompida nunca tem de começar do zero, e uma transferência parcial nunca é confundida com uma instalação funcional — um ficheiro sentinela em curso marca-a até o último byte aterrar.

Dica: O primeiro modelo que transferir é automaticamente definido como o modelo ativo do espaço de trabalho, para que um espaço de trabalho novo passe de "sem modelo local" a "pronto a servir" num único clique.

Ativar modelos locais para um espaço de trabalho

Abra o espaço de trabalho no navegador de espaços de trabalho, clique em Editar espaço de trabalho e selecione o painel Modelos locais (o ícone verde-menta de CPU). O painel começa como um único interruptor; o seletor de modo e a lista de modelos aparecem apenas depois de a inferência local estar ativa.

1. Ative Ativar modelos locais ("Executar um modelo de código neste Mac em vez da cloud."). Isto afasta o encaminhamento do espaço de trabalho da Cloud; voltar a desativá-lo restaura a Cloud.
2. Escolha um Modo:
   • Local — sempre no dispositivo mantém todos os pedidos neste Mac. Como o painel refere, as respostas são privadas mas mais lentas, e limitadas pelo modelo que consegue caber na memória.
   • Híbrido — cloud, recuar para local envia os pedidos para a cloud como habitualmente e recorre ao modelo no dispositivo apenas quando a cloud está inacessível — velocidade e qualidade da cloud, com uma rede de segurança local.
3. Na lista de modelos — intitulada Modelos · N GB de memória unificada, onde N é a memória do seu Mac — Transfira um modelo e, em seguida, selecione-o como ativo com o ponto de opção à sua esquerda. As linhas esbatidas precisam de mais memória do que o seu Mac tem.
4. Clique em Guardar.

O modo de encaminhamento e a seleção de modelo ativo persistem quando guarda; as transferências, sendo globais, acontecem imediatamente, quer guarde ou não. Se os modelos que selecionar precisarem em conjunto de perto ou mais do que a memória do seu Mac — o motor serve-os em paralelo, pelo que a sua memória se soma — o painel mostra um aviso e pede-lhe que descarte um ou escolha modelos menores.

A lista completa de campos e predefinições está em Definições de Modelos locais.

Encaminhamento: Cloud, Local e Híbrido

O encaminhamento é a escolha de topo, por espaço de trabalho, de qual backend serve o tráfego LLM de um agente. Tem três valores:

Selecionar Local ou Híbrido ativa automaticamente o caminho de interceção MITM — nunca aciona um interruptor separado para isso. Cada turno respondido é etiquetado no rastreio com um marcador de servido-por que regista qual backend respondeu: cloud ou local-<model>. Pode lê-lo no Inspetor de Rastreios para confirmar, turno a turno, para onde uma sessão híbrida foi de facto.

O encaminhamento é uma predefinição por espaço de trabalho definida no painel, mas também pode ser alterado numa VM em execução a partir da linha de comandos com bromure-cli vm routing (ver Referência da linha de comandos).

Nota: O encaminhamento local redireciona o tráfego de um agente para os anfitriões da Anthropic e da OpenAI (e o sentinela bromure.llm) para o motor. Não sequestra um agente que já esteja ele próprio fixado a uma credencial de cloud real — por exemplo, um agente Claude por subscrição a partilhar um espaço de trabalho mantém o seu tráfego de cloud real. Para forçar um agente específico a ser local independentemente do encaminhamento do espaço de trabalho, use o seu próprio modo de autenticação Modelo local, abaixo.

A política de recuo híbrido

O híbrido não é um único interruptor, mas um pequeno motor de política, afinado para nunca quebrar uma trajetória de programação ao trocar de modelos a meio do voo. Cada decisão é tomada numa fronteira de sessão e é depois fixa — uma vez encaminhada uma conversa para um backend, permanece lá durante o resto dessa sessão (a proteção de coerência).

O que desencadeia um recuo para local

Para uma nova sessão, a primeira regra que corresponde ganha, por esta ordem: uma sessão fixa já pinada, um orçamento de tokens de cloud esgotado, uma cloud não saudável (a barreira de saúde), uma atribuição por rácio de divisão e, caso contrário, a cloud. Durante um pedido já em voo para a cloud, duas coisas forçam uma repetição imediata no modelo local, fixando a sessão em local durante o seu ciclo de vida:

• Erros graves — uma ligação recusada ou expirada, ou um HTTP 429, 529 ou 5xx do fornecedor.
• Um prazo suave falhado — nenhum primeiro token dentro do orçamento de TTFT (5 segundos por predefinição).

Por baixo assenta uma barreira de saúde conservadora: a cloud é marcada como não saudável após pelo menos três falhas nos últimos cerca de dez pedidos, ou quando a média móvel ponderada exponencialmente do TTFT sobe além de 8 segundos, e só recupera após três sondas limpas e rápidas. Enquanto a cloud está não saudável, as novas sessões vão diretamente para local sem que cada uma pague primeiro a penalização do tempo limite suave. Os backends nunca são postos em corrida um contra o outro — não há cobertura especulativa nem gasto duplo; o recuo só dispara depois de um gatilho real.

Os botões ajustáveis

Três botões estão expostos, e apenas através da linha de comandos contra uma VM em execução (ver Referência da linha de comandos). Persistem por espaço de trabalho, mas são ignorados a menos que o encaminhamento seja Híbrido:

Os detalhes internos da barreira de saúde (o limiar EWMA de 8 segundos, a janela de falhas e a contagem de sondas de recuperação) são fixos e não ajustáveis pelo utilizador.

Modelos locais como backend de um agente

O encaminhamento é um eixo de todo o espaço de trabalho, mas também pode apontar um único agente para o motor local, deixando o resto do espaço de trabalho na cloud. No separador Agentes do espaço de trabalho, cada agente — Claude Code, Codex ou Grok — tem um seletor de modo de autenticação cujas opções incluem Modelo local. Escolha-o, selecione um modelo instalado, e esse agente corre inteiramente contra o motor no dispositivo com chaves de cloud fictícias que o motor ignora; o MITM aplica as mesmas proteções que aplica ao tráfego de cloud.

Isto torna possíveis espaços de trabalho mistos — por exemplo, o Claude Code numa subscrição a par do Codex num modelo local. O encaminhamento Local de todo o perfil nunca sequestra o tráfego real de um agente de cloud, e o modo Local por agente nunca vaza para os outros. Quando ativa ou desativa a inferência local no painel Modelos locais, a aplicação mantém automaticamente o modo de autenticação de cada agente em sincronia.

Modelos locais no Fusion

Um modelo local é também um participante válido no Fusion, a funcionalidade de síntese multimodelo, e pode desempenhar qualquer um de dois papéis:

• Como perna. Assinale Modelo local em Modelos a fundir e escolha um modelo instalado; a sua resposta preliminar junta-se ao painel a par do Claude, do Codex e do Grok. Como corre no seu Mac, é uma perna extra capaz a custo marginal zero.
• Como juiz. Escolha Local como fornecedor de juiz do Fusion para executar a fase de análise e síntese inteiramente no dispositivo, mantendo todo o passo de julgamento fora da cloud.

Ambos os papéis precisam de pelo menos um modelo local transferido; até lá, as linhas correspondentes no painel do Fusion ficam esbatidas com uma sugestão para transferir um aqui primeiro. Consulte Fusion para o fluxo de trabalho completo do painel.

Reparação de chamadas de ferramentas

O modo de falha dominante dos modelos quantizados em uso agêntico é emitir uma chamada de ferramenta como texto simples em vez de uma chamada estruturada que o agente possa executar. Um proxy de reparação fica à frente do motor — o convidado e a rota local do MITM apontam ambos para ele, não para o motor nu — e resgata estes casos de forma transparente.

Para cada resposta, ele armazena a saída em buffer e volta a analisar as muitas formas ad-hoc em que um modelo poderia vazar uma chamada, incluindo:

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

bem como o formato nativo <function=Name><parameter=k>v</parameter></function> do Qwen3-Coder e o formato de canais do Gemma. Ele sintetiza blocos de uso de ferramentas adequados a partir do que quer que encontre e volta a emitir a mensagem como SSE correto ao protocolo na forma de transmissão nativa do agente. Também deteta um preâmbulo encravado — em que o modelo narra uma ação ("Agora vou criar o ficheiro:") e depois termina o seu turno sem nunca chamar a ferramenta — e volta a solicitar até duas vezes para recuperar a chamada em falta. Um lembrete de formato de ferramenta é anexado ao prompt de sistema sempre que são declaradas ferramentas.

A reparação está sempre ativa para a inferência local e não precisa de configuração. Os problemas do motor são convertidos em corpos de erro nativos à transmissão, para que o agente mostre a razão real em vez de uma falha genérica, por exemplo:

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

Monitorizar o motor

Duas janelas no menu Janela permitem-lhe observar a inferência no dispositivo sem abrir a Console.app.

Métricas de inferência

Janela → Métricas de inferência… abre um painel de telemetria ao vivo (título da janela Métricas de inferência), encabeçado com a etiqueta Inferência local e o endereço de loopback do motor. Ele analisa as métricas Prometheus do motor em cartões — Decode tok/s, Prefill tok/s, Em execução, Em espera, Em voo, Latência média, Acerto de cache, Mem Metal, Tokens gerados e Tokens de prompt — mais uma lista de Modelos carregados e uma divulgação Todas as métricas com a tabela em bruto.

A janela sonda a cada 5 segundos, e apenas enquanto está aberta. As taxas de decode e prefill são rácios acumulados ao longo do tempo de vida por conceção, pelo que se leem como médias estáveis em vez de deltas por segundo instáveis. Quando o motor está inativo, o painel mostra motor inacessível, e durante uma geração longa pode brevemente mostrar motor ocupado (tempo limite excedido).

Registo do motor de inferência

Janela → Registo do motor de inferência… abre um acompanhamento ao vivo (título da janela Registo do motor de inferência) da saída do processo-filho do motor mais os eventos de ciclo de vida do processo-pai — carregamentos de modelos, "serving", estatísticas por pedido e qualquer OOM, falha, reinício ou erro de carregamento. As linhas são codificadas por cores (vermelho para falhas, verde para eventos saudáveis, laranja para avisos, azul para trabalho em curso). A barra de ferramentas oferece um campo Filtrar…, uma caixa de verificação Deslocamento automático, Copiar e Limpar; quando ainda nada aconteceu, lê-se Ainda sem atividade do motor de inferência. O buffer é um anel em memória limitado a 5.000 linhas, e cada linha é também espelhada para a stderr da aplicação, pelo que iniciar o bromure-cli a partir de um terminal dá-lhe uma cópia durável.

Referência da linha de comandos

Os comandos de modelo e de encaminhamento falam com a API de controlo da aplicação em execução, pelo que a aplicação (ou o seu agente) tem de estar em execução. Os comandos que atuam sobre uma VM específica recebem um argumento <vm> no final, que é um id de VM ou um nome de espaço de trabalho. As predefinições persistentes por espaço de trabalho são editadas nos painéis GUI descritos acima; estes comandos atuam sobre uma sessão ao vivo. Consulte Automatização e CLI para o conjunto de comandos circundante.

Gestão 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>

Encaminhamento e política híbrida para uma VM em execução:

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 define o modo de backend; os três botões vm hybrid afinam a política de recuo (e só têm efeito quando o encaminhamento é Híbrido). vm fusion ativa o painel multimodelo ortogonal e está documentado em Fusion.

Comandos de diagnóstico internos

Estes subcomandos ocultos existem para desenvolvimento e resolução de problemas e não fazem parte do fluxo de trabalho diário. O próprio processo-filho do motor é gerado pela aplicação como bromure-cli model _mlx-engine --config <path>.

Comando	Finalidade
bromure-cli model _mlx-serve <repo>	Inicia o servidor MLX em processo para um modelo e bloqueia, imprimindo a sua porta e chave para testes com curl.
bromure-cli model _mlx-selftest <repo>	Carrega um modelo, gera uma vez e imprime o TTFT e o decode tok/s.
bromure-cli model _repair-serve --engine-port <port>	Executa o proxy de reparação de chamadas de ferramentas de forma autónoma contra um motor em execução.
bromure-cli model _tc-test <path>	Executa o resgate de chamadas de ferramentas num ficheiro de texto guardado para verificar a extração de chamadas vazadas.
bromure-cli model _spec-bench <main-repo> --draft <draft-repo>	Faz benchmark da descodificação especulativa desligada versus ligada para um par de modelos.

Expectativas de desempenho

A inferência no dispositivo troca velocidade por privacidade e custo, e a troca é real — defina as expectativas em conformidade:

• O débito escala com o modelo e o chip. Um modelo pequeno como o Qwen3 8B é ágil em qualquer Mac suportado; as grandes builds de mistura de especialistas são mais lentas e precisam de muito mais memória. A janela Métricas de inferência mostra as taxas reais de decode e prefill no seu hardware — o número honesto por onde planear.
• O primeiro pedido paga por um carregamento de modelo. Um motor frio mostra A iniciar o motor local… enquanto aquece; os grandes pesos levam tempo real a carregar na memória antes de aparecer o primeiro token. Os pedidos seguintes saltam isto.
• Os ciclos de agente multi-turno ficam mais baratos após o primeiro turno. O motor mantém uma cache KV de prefixo por conversa (até quatro ranhuras de sessão por modelo), pelo que cada turno do agente só pré-carrega os novos tokens em vez de toda a transcrição — e uma cadeia lateral não remove a cache da conversa principal.
• A geração é serializada. O motor executa uma geração de cada vez, pelo que várias sessões ocupadas partilham a GPU em vez de correrem verdadeiramente em paralelo.
• Os modelos de raciocínio pensam em silêncio. Para os modelos que emitem um bloco <think>, o bloco é sempre removido antes de a resposta chegar ao agente — obtém a qualidade sem o inchaço da transcrição.

Dica: Se um modelo local parecer lento ou encravar, abra primeiro a janela Registo do motor de inferência: carregamentos de modelos, remoções, reinícios por OOM e erros de arquitetura não suportada surgem todos aí em texto simples, o que é mais rápido do que adivinhar pelo lado do agente.