Como converter um modelo para GGUF com o llama.cpp?
Resposta rápida
Execute o script de conversão do llama.cpp em um diretório de modelo no formato Hugging Face, especificando um tipo de saída como f16 (precisão total) ou um formato quantizado como q4_k_m. O script lê os pesos e a configuração do modelo, grava-os em um único arquivo .gguf, e esse arquivo pode ser carregado diretamente pelo llama.cpp, Ollama ou LM Studio.
- ▸O modelo de origem precisa estar no formato Hugging Face (safetensors ou checkpoint do PyTorch) antes da conversão
- ▸Escolha um tipo de saída: f16/f32 para precisão total, ou um tipo quantizado para converter e reduzir o tamanho em uma única etapa
- ▸Quantizar separadamente após uma conversão para f16 dá mais controle do que quantizar durante a conversão
Atualizado: 15 de julho de 2026
Technique & Concept ExplainersIntermediário
Pontos principais
- ✓A conversão para GGUF lê os pesos e metadados de um modelo no formato Hugging Face e os grava em um único arquivo .gguf portátil
- ✓Converta primeiro para f16/f32 se planeja testar vários níveis de quantização — quantizar a partir de uma conversão já quantizada perde mais qualidade do que quantizar a partir da precisão total
- ✓O tipo de saída escolhido no momento da conversão determina tanto o tamanho do arquivo quanto a qualidade da inferência — não existe almoço grátis entre os dois
- ✓A maioria dos erros de conversão está relacionada a um diretório de modelo de origem incompatível ou incompleto, não ao script de conversão em si
O processo de conversão
A conversão tem três etapas práticas: preparar o modelo de origem, executar o script de conversão com um tipo de saída e — se você converteu para precisão total — quantizar depois.
- ▸**1. Preparar o modelo de origem:** o script de conversão espera um diretório no formato Hugging Face contendo os arquivos de pesos do modelo (safetensors é preferido em relação aos checkpoints legados do PyTorch em `.bin`), além dos arquivos de configuração e de tokenizer. Um diretório baixado parcialmente ou montado manualmente que não tenha os arquivos de tokenizer é a causa mais comum de falhas de conversão.
- ▸**2. Executar o script de conversão com um tipo de saída:** `python convert_hf_to_gguf.py
--outtype f16` gera um arquivo GGUF em precisão total. Passar um `--outtype` quantizado (por exemplo, `q8_0`) quantiza durante a conversão em uma única etapa, mas dá menos controle do que converter primeiro para f16 e quantizar separadamente depois com uma ferramenta de quantização dedicada. - ▸**3. Quantizar separadamente para mais controle (opcional, mas recomendado):** partindo de um arquivo GGUF em f16, execute a ferramenta de quantização do llama.cpp para produzir várias variantes quantizadas (por exemplo, q4_k_m, q5_k_m) a partir da mesma fonte em precisão total, permitindo comparar os trade-offs de qualidade e tamanho sem repetir a conversão a cada vez.
Erros comuns de conversão
A maioria das falhas de conversão se encaixa em poucas categorias, quase sempre relacionadas ao modelo de origem, e não ao script em si.
- ▸**Arquitetura não reconhecida:** o script de conversão mantém uma lista interna de arquiteturas de modelo suportadas. Uma arquitetura muito nova ou incomum pode ainda não ser suportada — verifique a lista de arquiteturas atual da ferramenta antes de supor que os arquivos do modelo estão corrompidos.
- ▸**Arquivos de tokenizer ausentes:** a conversão precisa da configuração do tokenizer além dos pesos. Um diretório de modelo com apenas arquivos de pesos e sem arquivos de tokenizer falhará no meio da conversão.
- ▸**Expectativas de formato de arquivo incompatíveis:** checkpoints legados do PyTorch em `.bin` às vezes precisam de uma etapa extra de conversão para safetensors, dependendo da versão da ferramenta — prefira baixar modelos que já venham no formato safetensors para evitar isso completamente.
- ▸**Espaço em disco ou RAM insuficientes durante a conversão:** a conversão carrega o modelo em precisão total na memória antes de gravá-lo, portanto precisa de aproximadamente a mesma quantidade de RAM que o tamanho do modelo em precisão total, além do espaço em disco para os arquivos de origem e o arquivo GGUF de saída simultaneamente.
Perguntas frequentes
Devo quantizar durante a conversão ou converter primeiro para precisão total?▾
Converta primeiro para precisão total (f16) se planeja comparar vários níveis de quantização — quantizar separadamente depois a partir da mesma fonte f16 dá resultados mais precisos do que quantizar diretamente a partir de um modelo de origem durante a conversão, e permite produzir várias variantes quantizadas sem repetir a etapa de conversão.
Por que meu arquivo GGUF convertido não carrega no Ollama ou no LM Studio mesmo com a conversão bem-sucedida?▾
Uma conversão bem-sucedida não garante que a ferramenta de carregamento suporte aquela arquitetura ou versão específica do GGUF. Verifique se a versão da sua ferramenta de carregamento está atualizada — tanto o formato GGUF quanto o suporte a arquiteturas evoluem, e uma versão mais antiga da ferramenta pode não reconhecer um arquivo produzido por um script de conversão mais recente.
Quanto espaço em disco a conversão precisa?▾
Reserve o tamanho total do modelo de origem mais o tamanho do arquivo GGUF de saída simultaneamente — para uma conversão em precisão total, isso praticamente dobra o espaço ocupado pelo modelo durante o processo. Os arquivos de saída quantizados são menores, mas os arquivos de origem precisam permanecer presentes até a conversão terminar.
Posso converter um modelo que já passou por fine-tuning?▾
Sim — o processo de conversão funciona da mesma forma em um modelo ajustado (fine-tuned) e em um modelo base, desde que os pesos ajustados estejam salvos em um formato padrão compatível com o Hugging Face. Se o fine-tuning usou pesos de adaptador (como LoRA) em vez de pesos completos, mescle primeiro o adaptador ao modelo base e depois converta o resultado mesclado.