Llamafile: um LLM completo em um único arquivo executável

#Por que usar llamafile

A maioria das ferramentas de LLM locais exige uma instalação, um serviço em segundo plano e, depois, o download de um modelo. O Llamafile elimina todas essas etapas: o motor de inferência e os pesos do modelo ficam em um único arquivo. Você o torna executável, o inicia e seu navegador abre uma interface de chat. É o caminho mais curto entre um link de download e uma conversa com um modelo executado localmente.

Esse formato brilha em três situações. Para testar rapidamente um modelo sem poluir a máquina. Para distribuir um LLM para colegas ou usuários não técnicos: apenas um arquivo para enviar, nada para configurar. E para arquivamento: um llamafile continuará funcionando daqui a anos, sem depender de um runtime que precise ser instalado ou de um repositório online que continue acessível.

Sem instalação

Nenhum pacote, nenhum daemon, nenhuma variável de ambiente para configurar.

Um único arquivo

Motor + modelo unidos, fácil de copiar, salvar ou compartilhar.

Multi-OS

O mesmo binário roda em Windows, macOS, Linux, BSD (x86-64 e ARM64).

100 % local

Nenhum dado sai da máquina, nenhuma conexão de rede necessária após o download.

#Como funciona: o formato Mozilla

Llamafile combina dois componentes de código aberto. O primeiro é o llama.cpp, o motor de inferência em C/C++ que executa modelos no formato GGUF tanto em CPU quanto em GPU. O segundo é a Cosmopolitan Libc, uma biblioteca criada por Justine Tunney que permite compilar um executável “poliglota”: um mesmo arquivo binário reconhecido e executado nativamente por vários sistemas operacionais.

Na prática, um arquivo .llamafile é ao mesmo tempo um programa e um pacote de arquivos. Ele contém o código do servidor de inferência e, empacotado em seu interior, o arquivo GGUF dos pesos. Ao iniciar, ele detecta o sistema operacional e a arquitetura, carrega o modelo a partir de si mesmo e então inicia um servidor HTTP local com uma interface web de chat.

O próprio projeto llamafile está sob a licença Apache 2.0; as modificações feitas em llama.cpp e whisper.cpp para atender às necessidades do projeto permanecem sob a licença MIT, assim como os projetos originais, para manter a compatibilidade e permitir sua reintegração aos projetos de origem. Desde a versão 0.10.0, o llamafile utiliza um novo sistema de build alinhado às versões recentes do llama.cpp, o que amplia o suporte a modelos e funcionalidades mais recentes; as versões antigas continuam disponíveis para quem prefere a experiência “clássica”.

O projeto inclui também whisperfile, uma ferramenta complementar em um único arquivo, baseada em whisper.cpp e no mesmo empacotamento Cosmopolitan, para transcrição e tradução de áudio, sem instalação, nas mesmas plataformas que um llamafile tradicional.

#Pré-requisitos

Os requisitos são intencionalmente mínimos. O essencial é ter memória suficiente para o modelo escolhido; o tamanho do arquivo e a RAM necessária dependem diretamente da quantização.

OS

Windows 10+, macOS 11+, Linux recente ou BSD. x86-64 ou ARM64 (incluindo Apple Silicon).

RAM

Contar, aproximadamente, o tamanho do arquivo + uma margem. Um modelo 7B em Q4 (~5 GB) roda confortavelmente com 8 a 16 GB.

GPU (opcional)

Aceleração possível via NVIDIA (CUDA) ou Apple Metal. Sem GPU, a inferência é feita na CPU, de forma mais lenta, mas funcional.

Espaço em disco

De cerca de 500 MB para um modelo pequeno até dezenas de GB para um modelo grande não quantizado.

#Baixar e iniciar em segundos

O repositório oficial mozilla-ai/llamafile no GitHub lista llamafiles prontos para uso, e o Hugging Face hospeda muitos outros. O projeto, inicialmente lançado pela Mozilla Builders, foi assumido e hoje é mantido pela Mozilla.ai. Depois de obter o arquivo, o procedimento varia muito pouco conforme o sistema operacional.

1. 01
   Baixar o arquivo

   Baixe um .llamafile da página do GitHub do projeto ou do Hugging Face (busque “llamafile” na barra de pesquisa de modelos).
2. 02
   macOS e Linux: tornar executável

   Abra um terminal no diretório de download e permita a execução com chmod, depois execute o arquivo.
3. 03
   Windows: renomear para .exe

   Adicione a extensão .exe ao nome do arquivo e depois dê um clique duplo nele (ou execute-o pelo PowerShell).
4. 04
   Abrir a interface

   O programa inicia um servidor local e geralmente abre seu navegador automaticamente. Caso contrário, acesse http://localhost:8080.

# Rendre le fichier exécutable
chmod +x Llama-3.2-3B-Instruct.Q4_K_M.llamafile

# Lancer : ouvre l'interface web sur http://localhost:8080
./Llama-3.2-3B-Instruct.Q4_K_M.llamafile

# Renommer pour ajouter l'extension .exe
Rename-Item .\Llama-3.2-3B-Instruct.Q4_K_M.llamafile Llama-3.2-3B.exe

# Lancer
.\Llama-3.2-3B.exe

#O mesmo arquivo no Windows, no Mac e no Linux

É a promessa mais surpreendente do llamafile: o arquivo que você baixa no Linux é exatamente o mesmo que rodará em um Mac ou em um PC Windows. Não há versões 'Windows', 'Mac' ou 'Linux' para escolher. Essa portabilidade é possível graças ao Cosmopolitan Libc, que gera um executável compreendido por diversos sistemas ao mesmo tempo.

Na prática, isso significa que um mesmo llamafile colocado em um pendrive ou em um compartilhamento de rede funciona para toda a equipe, independentemente dos computadores de cada integrante. Você distribui um modelo sem se preocupar com o sistema operacional de cada um, nem pedir a ninguém para instalar nada.

#Opções úteis na linha de comando

A interface web é suficiente para conversar, mas algumas opções permitem ajustar o comportamento. Elas são passadas após o nome do arquivo ao iniciar.

-ngl N

Transfere N camadas do modelo para a GPU (por exemplo, -ngl 999 para colocar tudo na VRAM se ela for suficiente).

-c N

Define o tamanho da janela de contexto em tokens (ex. -c 4096).

--host / --port

Altera o endereço e a porta de escuta do servidor (por padrão, localhost:8080).

-m fichier.gguf

Utiliza um arquivo de pesos externo em vez do embutido — útil para contornar o limite de 4 GB do Windows.

--server --nobrowser

Inicia em modo de servidor sem abrir um navegador, prático para uso headless.

# Tout charger sur le GPU, contexte 8k, port personnalisé
./Llama-3.2-3B-Instruct.Q4_K_M.llamafile -ngl 999 -c 8192 --port 8090

# Serveur headless avec un GGUF externe (contourne la limite 4 Go)
./llava-v1.5-7b-q4.llamafile --server --nobrowser -m modele.gguf

O servidor também oferece uma API compatível com a OpenAI na rota /v1/chat/completions. Assim, você pode usar um llamafile como servidor para qualquer cliente que use o protocolo OpenAI, apenas apontando a URL base para http://localhost:8080/v1.

#Criar seu próprio llamafile

Você não está limitado aos arquivos preparados por outros: qualquer modelo GGUF pode ser empacotado. O projeto fornece um binário zipalign e um executável “vazio” (apenas o mecanismo de execução), ao qual se adicionam o arquivo de pesos e um arquivo de argumentos padrão.

1. 01
   Obter as ferramentas

   Baixe a versão mais recente do GitHub: ela contém o binário llamafile (apenas o motor) e o utilitário zipalign.
2. 02
   Ter um GGUF

   Obtenha o arquivo .gguf do modelo desejado no Hugging Face, com a quantização de sua escolha (Q4_K_M é um bom equilíbrio).
3. 03
   Escrever os argumentos padrão

   Crie um arquivo .args listando as opções a serem aplicadas na inicialização (modelo, interface web, etc.).
4. 04
   Empacotar com zipalign

   Copie o motor com um novo nome e depois insira nele o GGUF e o arquivo .args com zipalign.
5. 05
   Testar

   Torne o arquivo resultante executável e execute-o como qualquer llamafile.

# Fichier d'arguments par défaut
cat > .args <<'EOF'
-m
modele.Q4_K_M.gguf
--host
0.0.0.0
...
EOF

# Copier le moteur, puis y injecter poids + args
cp llamafile mon-modele.llamafile
zipalign -j0 mon-modele.llamafile modele.Q4_K_M.gguf .args

# Tester
chmod +x mon-modele.llamafile
./mon-modele.llamafile

#Llamafile vs Ollama: duas filosofias

Llamafile e Ollama atendem à mesma necessidade — executar um LLM localmente — mas com lógicas opostas. Ollama instala um daemon que escuta em http://localhost:11434 e gerencia uma biblioteca de modelos baixados conforme necessário. Llamafile não gerencia nada: cada modelo é um arquivo autônomo que você executa diretamente.

A divisão se resume assim: llamafile leva vantagem para testar pontualmente, distribuir a pessoas sem conhecimentos técnicos ou arquivar um modelo mantido em uma versão fixa; Ollama leva vantagem quando se trabalha com vários modelos no dia a dia ou se integra um LLM a uma stack duradoura com uma interface como Open WebUI ou LM Studio.

#Solução de problemas

« run-detectors » ou bloqueio da execução (Linux)

Um binutils/binfmt excessivamente rigoroso pode bloquear o formato poliglota. Solução: instalar o pacote APE loader ou executar via sh -c "./fichier.llamafile".

Arquivo muito grande no Windows

Acima de 4 GB, mantenha o GGUF separado e passe-o com -m para um pequeno llamafile "somente com o motor".

Sem aceleração por GPU

Verifique se os drivers CUDA (NVIDIA) estão presentes e adicione -ngl 999. No Mac, o Metal é usado automaticamente.

Porta já ocupada

Outro serviço está rodando na porta 8080: mude para --port 8090, por exemplo.

Respostas lentas

Usando apenas a CPU, isso é esperado para modelos grandes. Escolha uma quantização mais leve ou um modelo menor (3B em vez de 7B).

#Para se aprofundar

Llamafile é uma porta de entrada ideal. Para um uso local mais completo e duradouro, esses guias aprofundam o tema.

• Instalar um LLM localmente: guia passo a passo
• Ollama vs llama.cpp: qual escolher?
• Alternativas ao Ollama: um panorama
• Instalar Ollama em 5 minutos
• Fonte: repositório GitHub do llamafile
• Fonte: documentação oficial llamafile
• Fonte: post de anúncio original do llamafile

#FAQ