Modelos Locais Hugging Face

Quando Usar

Use esta habilidade quando precisar selecionar modelos para rodar localmente com llama.cpp e GGUF em CPU, Mac Metal, CUDA ou ROCm. Abrange a busca por GGUFs, seleção de quantização, execução de servidores, busca exata de arquivos GGUF, conversão e serviço local compatível com OpenAI.

Pesquise no Hugging Face Hub por repositórios GGUF compatíveis com llama.cpp, escolha a quantização correta e inicie o modelo com llama-cli ou llama-server.

Fluxo de Trabalho Padrão

1. Pesquise no Hub com apps=llama.cpp.
2. Abra https://huggingface.co/<repo>?local-app=llama.cpp.
3. Prefira o snippet exato do aplicativo local HF e a recomendação de quantização quando visível.
4. Confirme os nomes exatos dos arquivos .gguf com https://huggingface.co/api/models/<repo>/tree/main?recursive=true.
5. Inicie com llama-cli -hf <repo>:<QUANT> ou llama-server -hf <repo>:<QUANT>.
6. Recorra a --hf-repo mais --hf-file quando o repositório usar nomenclatura de arquivo personalizada.
7. Converta de pesos Transformers apenas se o repositório já não expuser arquivos GGUF.

Início Rápido

Instalar llama.cpp

brew install llama.cpp
winget install llama.cpp

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
make

Autenticar para repositórios restritos

hf auth login

Pesquisar no Hub

https://huggingface.co/models?apps=llama.cpp&sort=trending
https://huggingface.co/models?search=Qwen3.6&apps=llama.cpp&sort=trending
https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending

Executar diretamente do Hub

llama-cli -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M
llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M

Executar um arquivo GGUF exato

llama-server \
    --hf-repo unsloth/Qwen3.6-35B-A3B-GGUF \
    --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \
    -c 4096

Converter apenas quando não houver GGUF disponível

hf download <repo-without-gguf> --local-dir ./model-src
python convert_hf_to_gguf.py ./model-src \
    --outfile model-f16.gguf \
    --outtype f16
llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M

Testar um servidor local rapidamente

llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "messages": [
      {"role": "user", "content": "Write a limerick about exception handling"}
    ]
  }'

Escolha da Quantização

• Prefira a quantização exata que o HF marca como compatível na página ?local-app=llama.cpp.
• Mantenha os rótulos nativos do repositório, como UD-Q4_K_M, em vez de normalizá-los.
• Use Q4_K_M como padrão, a menos que a página do repositório ou o perfil de hardware sugiram o contrário.
• Prefira Q5_K_M ou Q6_K para cargas de trabalho de código ou técnicas quando a memória permitir.
• Considere Q3_K_M, Q4_K_S ou variantes específicas do repositório IQ / UD-* para orçamentos mais apertados de RAM ou VRAM.
• Trate arquivos mmproj-*.gguf como pesos de projeção, não como o checkpoint principal.

Referências de Carregamento

• Leia hub-discovery.md para fluxos de trabalho baseados em URL, pesquisa de modelos, extração de API de árvore e reconstrução de comandos.
• Leia quantization.md para tabelas de formato, dimensionamento de modelos, compromissos de qualidade e imatrix.
• Leia hardware.md para detalhes de compilação e aceleração Metal, CUDA, ROCm ou CPU.

Recursos

• llama.cpp: https://github.com/ggml-org/llama.cpp
• Documentação Hugging Face GGUF + llama.cpp: https://huggingface.co/docs/hub/gguf-llamacpp
• Documentação Hugging Face Local Apps: https://huggingface.co/docs/hub/main/local-apps
• Documentação Hugging Face Local Agents: https://huggingface.co/docs/hub/agents-local
• Espaço do conversor GGUF: https://huggingface.co/spaces/ggml-org/gguf-my-repo

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo do produto ou API de origem.
• Verifique comandos, comportamento da API, preços, cotas, credenciais e efeitos de implantação contra a documentação oficial atual antes de fazer alterações.
• Não trate exemplos gerados como substitutos para testes específicos do ambiente, revisão de segurança ou aprovação do usuário para ações destrutivas ou custosas.