Hugging Face's logo

brunoconterato
/
Gemma-3-Gaia-PT-BR-4b-it-GGUF-F16

GGUF
Portuguese
conversational
Model card Files Community
Gemma-3-Gaia-PT-BR-4b-it-GGUF-F16 / instructions.md
brunoconterato's picture
brunoconterato
Add comprehensive instructions for converting, quantizing, and publishing LLMs in GGUF format for Ollama and Hugging Face
d7be2c3
preview code
|
raw
history blame contribute delete
7.77 kB

Guia Completo: Convertendo, Quantizando e Publicando LLMs em GGUF para Ollama e Hugging Face

Este guia detalha o processo para pegar um modelo de linguagem (LLM) do Hugging Face em seu formato original (como safetensors), convertê-lo para o formato GGUF usando o llama.cpp via Docker, otimizá-lo através de quantização (em diferentes níveis de precisão) e, finalmente, disponibilizá-lo para uso local com Ollama e para publicação pública no Hugging Face (ou na biblioteca oficial do Ollama).

Objetivos

  • Compreender a diferença entre conversão de formato, quantização FP16 e quantização de baixa precisão (Q4_K_M, etc.).
  • Converter um modelo LLM do Hugging Face para o formato GGUF em precisão FP16.
  • Quantizar o modelo GGUF FP16 para precisões mais baixas (ex: Q4_K_M) para otimização de desempenho e tamanho.
  • Rodar o modelo GGUF localmente usando Ollama.
  • Publicar o modelo GGUF no Hugging Face Model Hub para que possa ser baixado e usado por outros via Ollama.
  • Compreender e aplicar as exigências de licenciamento para modelos como o Gemma.

1. Pré-requisitos

Antes de começar, certifique-se de ter as seguintes ferramentas instaladas e configuradas no seu sistema:

  • Docker: Para rodar o ambiente llama.cpp isoladamente.
  • Git: Para clonar repositórios e gerenciar versões.
  • Git LFS (Large File Storage): Essencial para baixar e fazer upload de arquivos grandes (.safetensors, .gguf) no Git.
    sudo apt update && sudo apt install git-lfs     # Linux Mint/Ubuntu
git lfs install                                # configuração única

  • Python 3 e pip:

    sudo apt install python3 python3-pip           # Linux Mint/Ubuntu

  • huggingface_hub (CLI): Ferramentas de linha de comando para interagir com o Hugging Face.

    pip install huggingface_hub

  • Ollama: Para rodar os modelos GGUF localmente.

2. Preparação do Ambiente e Modelo

2.1. Instalação e Configuração do Ollama (Local)

  1. Baixe e instale conforme seu sistema operacional.

  2. Verifique a instalação executando:

    ollama

    Deve exibir a lista de comandos disponíveis.

2.2. Criar Diretórios e Baixar o Modelo

Estrutura recomendada:

~/Workspace/Models/
- meu_modelo_original/   # arquivos do Hugging Face
- saida_gguf/            # saída das conversões e quantizações

Crie com:

mkdir -p ~/Workspace/Models/meu_modelo_original
mkdir -p ~/Workspace/Models/saida_gguf

Clone o modelo:

cd ~/Workspace/Models/
git clone https://huggingface.co/CEIA-UFG/Gemma-3-Gaia-PT-BR-4b-it meu_modelo_original

Garanta que o Git LFS foi instalado antes de clonar, para baixar os arquivos grandes corretamente.

3. Conversão e Quantização (via Docker)

Usaremos a imagem ghcr.io/ggml-org/llama.cpp:full.

3.1. Pull da Imagem Docker 

docker pull ghcr.io/ggml-org/llama.cpp:full

3.2. Converter para GGUF + FP16 

docker run --rm -it \
  --entrypoint /bin/bash \
  -v ~/Workspace/Models/meu_modelo_original:/app/model_in:ro \
  -v ~/Workspace/Models/saida_gguf:/app/model_out \
  ghcr.io/ggml-org/llama.cpp:full \
  -c "cd /llama.cpp && python3 convert_hf_to_gguf.py /app/model_in \
      --outtype f16 \
      --outfile /app/model_out/gemma_3_gaia_f16.gguf"

3.3. Quantizar p/ Q4_K_M (4 bits) 

docker run --rm -it \
  --entrypoint /bin/bash \
  -v ~/Workspace/Models/saida_gguf:/app/model_out \
  ghcr.io/ggml-org/llama.cpp:full \
  -c "cd /llama.cpp && ./quantize \
      /app/model_out/gemma_3_gaia_f16.gguf \
      /app/model_out/gemma_3_gaia_q4_k_m.gguf \
      Q4_K_M"

4. Utilizando o Modelo no Ollama (Local)

Agora você terá, por exemplo, gemma_3_gaia_f16.gguf e/ou gemma_3_gaia_q4_k_m.gguf dentro de ~/Workspace/Models/saida_gguf.

4.1. Criar um Modelfile

No diretório da saída:

cd ~/Workspace/Models/saida_gguf
nano Modelfile

Conteúdo:

# Modelfile
FROM gemma_3_gaia_q4_k_m.gguf

# Exemplo de SYSTEM prompt
SYSTEM """Você é um assistente de IA prestativo e amigável."""

# Exemplos de parâmetros (ajuste conforme sua RAM/VRAM)
# PARAMETER temperature 0.7
# PARAMETER top_k 40
# PARAMETER top_p 0.9
# PARAMETER num_ctx 4096

4.2. Importar para Ollama 

ollama create brunoconterato/Gemma-3-Gaia-PT-BR-4b-it:q4_k_m -f Modelfile
# (ou para F16):
# ollama create brunoconterato/Gemma-3-Gaia-PT-BR-4b-it:f16 -f Modelfile

4.3. Rodar o Modelo 

ollama run brunoconterato/Gemma-3-Gaia-PT-BR-4b-it:q4_k_m

5. Publicando o Modelo para Compartilhamento

Temos duas formas principais de publicar: via Hugging Face ou via biblioteca oficial do Ollama.

5.1. No Hugging Face Model Hub

5.1.1. Criar Repositório

  • Vá ao Hugging Face e crie um repositório público (ex: Gemma-3-Gaia-PT-BR-4b-it-GGUF-F16), escolhendo a licença adequada.

5.1.2. Preparar Repositório Local 

cd ~/Workspace/Models/saida_gguf
git init
git lfs install
git lfs track "*.gguf"

5.1.3. Adicionar arquivos essenciais

Crie ou atualize:

---
license: gemma
language:
  - pt
base_model:
  - CEIA-UFG/Gemma-3-Gaia-PT-BR-4b-it
  - google/gemma-3-4b-it
---

# Gemma-3-Gaia-PT-BR-4b-it – GGUF Quantizado por brunoconterato (F16)

Este repositório contém uma versão quantizada (16‑bit) do modelo **Gemma‑3‑Gaia‑PT‑BR‑4b‑it**, otimizada para uso com [Ollama](https://ollama.com/).

**Detalhes do modelo:**

- **Base model:** Gemma‑3‑Gaia‑PT‑BR‑4b‑it
- **Quantização:** F16
- **Origem:** https://huggingface.co/CEIA-UFG/Gemma-3-Gaia-PT-BR-4b-it
- **Desenvolvedor:** brunoconterato

## Licença

Este modelo está disponível sob os **Gemma Terms of Use**. Ao baixar ou usar, você concorda com:

- Políticas de uso proibido (Prohibited Use Policy) conforme exigido.
- Inclusão dos termos completos da licença.
- Aviso de modificação (quantização).

Arquivos adicionais:

- `Gemma_Terms_of_Use.txt` – texto completo da licença oficial.
- `NOTICE.txt` – aviso exigido pela licença (veja abaixo).

## Uso com Ollama

```bash
ollama run hf.co/brunoconterato/Gemma-3-Gaia-PT-BR-4b-it-GGUF-F16
```


Crie também:
```bash
echo "Gemma is provided under and subject to the Gemma Terms of Use found at ai.google.dev/gemma/terms" > NOTICE.txt

Adicione tudo:

git add README.md Gemma_Terms_of_Use.txt NOTICE.txt gemma_3_gaia_f16.gguf
git commit -m "Initial commit: Gemma‑3‑Gaia‑PT‑BR‑4b‑it GGUF (F16) model + documentação e licença"

5.1.4. Conectar e Enviar 

huggingface-cli login
huggingface-cli lfs-enable-largefiles .
git remote add origin https://huggingface.co/brunoconterato/Gemma-3-Gaia-PT-BR-4b-it-GGUF-F16
git push -u origin main

5.2. Biblioteca oficial do Ollama

  1. Configure sua chave pública SSH (~/.ollama/id_ed25519.pub ou equivalente).

  2. Copie o modelo local para o namespace de publicação:

    ollama cp brunoconterato/Gemma-3-Gaia-PT-BR-4b-it:q4_k_m brunoconterato/Gemma-3-Gaia-PT-BR-4b-it:q4_k_m

  3. Publique:

    ollama push brunoconterato/Gemma-3-Gaia-PT-BR-4b-it:q4_k_m

6. Considerações Finais

  • Licenciamento Gemma: exige atribuição, redistribuição dos termos de uso e aviso de modificação mesmo em derivados.
  • Hardware: mesmo quantizados, LLMs exigem memória RAM/VRAM suficiente—verifique seu sistema antes de rodar.