Add comprehensive instructions for converting, quantizing, and publishing LLMs in GGUF format for Ollama and Hugging Face

instructions.md

@@ -0,0 +1,279 @@
+# 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.