Gemma-3-Gaia-PT-BR-4b-it-GGUF-F16/instructions.md

# 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.
  - [Instalação do Docker](https://docs.docker.com/get-docker/)
- **Git:** Para clonar repositórios e gerenciar versões.
  - [Instalação do Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- **Git LFS (Large File Storage):** Essencial para baixar e fazer upload de arquivos grandes (`.safetensors`, `.gguf`) no Git.
  ```bash
  sudo apt update && sudo apt install git-lfs     # Linux Mint/Ubuntu
  git lfs install                                # configuração única
  ```

* **Python 3 e `pip`:**

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

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

  ```bash
  pip install huggingface_hub
  ```

* **Ollama:** Para rodar os modelos GGUF localmente.

  - [Instalação do Ollama](https://ollama.com/download)

---

## 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:

   ```bash
   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:

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

Clone o modelo:

```bash
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

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

### 3.2. Converter para GGUF + FP16

```bash
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)

```bash
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:

```bash
cd ~/Workspace/Models/saida_gguf
nano Modelfile
```

Conteúdo:

```text
# 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

```bash
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

```bash
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

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

#### 5.1.3. Adicionar arquivos essenciais

Crie ou atualize:

````markdown
---
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:

```bash
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

```bash
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:

   ```bash
   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:

   ```bash
   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.