llamafile: Execute qualquer LLM como um único executável portátil

O llamafile é um único arquivo executável que contém tanto um modelo de linguagem quanto o runtime de inferência. Construído sobre o llama.cpp e o Cosmopolitan Libc, o mesmo arquivo executa nativamente no Linux, macOS, Windows, FreeBSD e outros sistemas — sem contêineres, sem ambiente Python e sem gerenciador de pacotes necessário.

Como um único arquivo roda em todos os sistemas operacionais

O llamafile depende de duas tecnologias. llama.cpp fornece o mecanismo de inferência em C++ para modelos no formato GGUF. Cosmopolitan Libc gera um binário poliglota: um único conjunto de bytes que satisfaz simultaneamente o formato PE/COFF esperado pelo Windows, o formato ELF esperado pelo Linux e o cabeçalho Mach-O esperado pelo macOS. Ao executar o arquivo, o carregador de cada sistema operacional encontra seu próprio cabeçalho válido e executa o binário nativamente — sem emulação nem camada de tradução envolvida.

Os pesos do modelo são anexados a esse binário usando um contêiner compatível com ZIP. O ZIP permite dados arbitrários antes do registro do diretório central, de modo que o arquivo GGUF fica posicionado no final sem corromper o executável. O runtime localiza os pesos buscando o final do arquivo na inicialização. Um efeito colateral prático: você pode inspecionar ou extrair os pesos de qualquer llamafile usando qualquer utilitário padrão de ZIP.

Baixando e executando um llamafile

llamafiles pré-construídos são publicados no Hugging Face pelos autores dos modelos e vinculados ao repositório GitHub Mozilla-Ocho/llamafile. Os arquivos usam a extensão .llamafile .

Linux e macOS

# Tornar executável — arquivos baixados não possuem, por padrão, o bit de execução
chmod +x mistral-7b-instruct.llamafile

# Iniciar o servidor e a interface web (navegador abre automaticamente)
./mistral-7b-instruct.llamafile

# Inferência CLI pontual sem iniciar o servidor
./mistral-7b-instruct.llamafile -p "Explique o llamafile em um parágrafo"

O servidor escuta por padrão em 127.0.0.1:8080 . Para alterar a porta, passe o argumento --port 9000 ou use --host 0.0.0.0 --host 0.0.0.0para escutar em todas as interfaces de rede — útil ao servir de uma máquina headless em uma rede local. Execute ./model.llamafile --help

Windows

para ver todas as opções disponíveis, incluindo flags para suprimir a abertura automática da guia do navegador ao executar em modo headless. .exeO Windows exige que os executáveis terminem em

ren mistral-7b-instruct.llamafile mistral-7b-instruct.llamafile.exe

Em seguida, clique duas vezes no arquivo no Explorador ou execute-o a partir do Prompt de Comando. Uma guia do navegador será aberta automaticamente.

Limite de 4 GB. O carregador PE do Windows não consegue lidar com executáveis maiores que 4 GB. A maioria dos modelos de 7B em quantização Q8 ou superior, bem como todos os modelos de 13B ou maiores, ultrapassam esse limite. Se o arquivo tiver mais de 4 GB, o Windows se recusará a executá-lo. Suas opções são: baixar uma variante com quantização mais leve (normalmente entre 4–5 GB para um modelo de 7B, frequentemente logo abaixo do limite) ou baixar o binário independente do runtime llamafile e passar o GGUF como argumento separado. Antes de escolher um modelo e sua quantização, consulte os Q4_K_M requisitos de VRAM e tamanho de arquivo para principais LLMs para selecionar a quantização ideal para seu hardware. Executar um llamafile sem a flag

Interface web integrada

-p inicia um servidor HTTP e abre seu navegador padrão em http://localhost:8080 . A interface é uma aplicação de página única totalmente autônoma, sem dependências externas de CDN — funciona integralmente offline. Ela oferece:Configuração do prompt do sistema

• Parâmetros de amostragem: temperatura, top-p, top-k e penalidade por repetição
• Exibição da contagem de tokens
• Histórico de conversa persistente dentro da sessão
• Qualquer dispositivo em sua rede local (LAN) pode acessar a interface, desde que o servidor tenha sido iniciado com

--host 0.0.0.0 --host 0.0.0.0.

API compatível com OpenAI

Enquanto o servidor estiver em execução, o llamafile expõe uma API REST compatível com OpenAI em http://localhost:8080/v1. Qualquer cliente SDK OpenAI, integração LangChain ou LlamaIndex pode direcionar-se a ela simplesmente sobrescrevendo a URL base:

curl http://localhost:8080/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{
    "model": "local",
    "messages": [{"role": "user", "content": "Olá"}]
  }'

No Python, defina base_url="http://localhost:8080/v1" e qualquer string não vazia como chave de API ao construir o cliente openai.OpenAI . O modelo o campo nas solicitações é ignorado — o modelo carregado é sempre utilizado.

Criando um llamafile a partir de um GGUF existente

Se você já possui um modelo GGUF — do ecossistema llama.cpp, do cache local do Ollama ou de um download do Hugging Face — pode empacotá-lo em um llamafile autocontido. Esse processo utiliza a llamafile-zipalign , uma ferramenta incluída no conjunto de ferramentas llamafile:

1. Baixe o pacote de versão do llamafile para sua plataforma na página de lançamentos no GitHub.
2. Extraia o binário autônomollamafile (apenas o tempo de execução, sem modelo embutido).
3. O melhor editor completo llamafile-zipalign para anexar seu GGUF a uma cópia do binário de tempo de execução.
4. Marque o resultado como executável e execute-o.

A sintaxe exata das opções mudou entre versões. Consulte a seção oficial do README sobre criação de llamafiles para obter a sintaxe atual. A saída é um único arquivo portátil que pode ser distribuído como qualquer outro binário.

llamafile vs Ollama: quando usar cada um

Ambas as ferramentas executam modelos GGUF localmente e expõem APIs compatíveis com OpenAI. Elas resolvem problemas distintos. Veja o Guia completo do Ollama para uma análise mais detalhada do outro lado dessa comparação.

Escolha o llamafile quando for distribuir para uma máquina que você não controla, executar em um ambiente isolado (air-gapped) ou incorporar um modelo em um projeto que deve funcionar sem dependências de nível de sistema. Escolha o Ollama quando você gerencia uma biblioteca de modelos, deseja atualizações automáticas ou alterna frequentemente entre modelos na mesma sessão.

Se você está avaliando se a inferência local faz sentido econômico para sua carga de trabalho, o calculadora de ponto de equilíbrio entre hospedagem local e uso de API pode quantificar a relação de custo-benefício em comparação com os custos das APIs em nuvem.

Requisitos de hardware

O llamafile adiciona sobrecarga desprezível além do llama.cpp. O gargalo é sempre o tamanho do modelo e sua quantização. O llamafile detecta aceleradores disponíveis na inicialização — CUDA para GPUs NVIDIA, Metal para Apple Silicon e ROCm para AMD — e os utiliza automaticamente. Caso nenhuma GPU seja encontrada, ele recorre à inferência na CPU, utilizando instruções AVX2 ou AVX-512, quando disponíveis.

Um modelo de 7 bilhões de parâmetros na quantização Q4_K_M requer aproximadamente 4–5 GB de VRAM para execução integral na GPU. Use o Calculadora de VRAM para estimar os requisitos de qualquer modelo e quantização específicos antes do download. Para decisões de compra de hardware, o melhor Placas de vídeo para LLMs locais guia aborda as opções atuais em diferentes faixas de preço.

Perguntas frequentes

Posso executar o llamafile em Apple Silicon?

Sim. O llamafile gera um binário nativo Mach-O no Apple Silicon e usa automaticamente a aceleração por GPU Metal. O desempenho é sólido para modelos de 7B e 13B; modelos maiores são limitados pela memória unificada disponível. Um M2 Max ou M3 Pro com 36 GB de memória unificada consegue executar confortavelmente modelos da classe 30B.

O llamafile suporta modelos multimodais (visão)?

O llamafile é construído sobre o llama.cpp, que suporta modelos de visão no estilo LLaVA. Se um llamafile específico suporta entrada de imagens depende de o modelo embutido ser, de fato, multimodal. Verifique o cartão do modelo do arquivo que você baixou — essa capacidade reside nos pesos, não no tempo de execução.

Como interrompo o servidor?

Imprensa Ctrl+C no terminal onde o llamafile está sendo executado. Se você o iniciou clicando duas vezes no Windows ou macOS, feche a janela do terminal que apareceu ou encerre o processo pelo Gerenciador de Tarefas ou pelo Monitor de Atividade.

Posso executar o llamafile como um serviço em segundo plano?

Sim. No Linux, envolva-o em um arquivo de unidade systemd. No macOS, crie um arquivo plist para launchd. O llamafile aceita sinais Unix padrão e funciona com qualquer supervisor de processos. Execute para escutar em todas as interfaces de rede — útil ao servir de uma máquina headless em uma rede local. Execute para encontrar a opção que suprime a abertura automática da guia do navegador ao executar em um ambiente headless.

O llamafile é o mesmo que um arquivo GGUF?

Não. Um arquivo GGUF contém apenas os pesos do modelo e exige um tempo de execução separado — como o llama.cpp, o Ollama, LM Studio, ou similar — para ser executado. Um arquivo llamafile empacota os pesos e de execução em um único arquivo. Como os pesos são anexados no formato ZIP, é possível extrair o arquivo GGUF bruto de qualquer arquivo llamafile com qualquer utilitário ZIP padrão e usá-lo em outro lugar.

Como o llamafile se compara ao LM Studio?

O LM Studio é um aplicativo desktop com interface gráfica (GUI) para descoberta e inferência de modelos — requer instalação e gerencia uma biblioteca de modelos, tornando-o mais semelhante ao Ollama do que ao llamafile. O llamafile é um formato de implantação: sem interface gráfica, sem biblioteca de modelos, apenas um arquivo que você executa. O LM Studio é adequado para usuários que desejam uma interface visual; o llamafile é ideal para implantações automatizadas, sem interface (headless) ou portáteis. Consulte o Guia completo do LM Studio para uma análise detalhada.