README.md

---
language:
- pt
tags:
- gguf
- llama.cpp
- unsloth
- text-classification
- intent-detection
- gemma-3
- delivery
base_model: google/gemma-3-270m-it
license: gemma
datasets:
- RiosWesley/rango-router-BR
inference:
  parameters:
    temperature: 0.6
    top_p: 0.95
    top_k: 64
---

# Rango Router BR - Gemma 3 270M (GGUF)

**Rango Router BR** é um modelo *Tiny LLM* (baseado no Gemma 3 270M) finetunado para atuar como um classificador de intenções (router) extremamente rápido e leve para sistemas de atendimento de delivery no Brasil.

Este modelo foi treinado e convertido para o formato GGUF usando [Unsloth](https://github.com/unslothai/unsloth).

## Funcionalidade

O modelo lê a mensagem do usuário (que pode conter gírias, abreviações e linguagem informal brasileira) e classifica a intenção em um formato JSON.

### Intenções Suportadas (Output):
O modelo retorna um JSON com uma das três chaves:

1.  **`INFO_FLOW`**: O usuário quer informações (cardápio, horário, endereço, pix).
2.  **`ORDER_FLOW`**: O usuário quer fazer, alterar ou confirmar um pedido.
3.  **`HUMAN_HANDOFF`**: O usuário está irritado, teve problemas ou pediu um humano.

## Configurações de Inferência Recomendadas

Para garantir a melhor consistência no formato JSON e precisão na classificação, recomendamos os seguintes parâmetros:

| Parâmetro | Valor | Motivo |
| :--- | :--- | :--- |
| **Temperature** | `0.6` | Equilíbrio ideal para este modelo de 270M não "alucinar" o JSON, mas entender variações linguísticas. |
| **Top P** | `0.95` | Nucleus sampling padrão para evitar respostas de baixa probabilidade. |
| **Top K** | `64` | Limita o vocabulário de escolha, ajudando a manter o foco nas tags JSON. |

## Como rodar

### 1. Ollama (Recomendado)

Crie um arquivo chamado `Modelfile` com o seguinte conteúdo (as configurações já estão incluídas):

```dockerfile
FROM ./gemma-3-270m-it.Q8_0.gguf

# Template de chat padrão do Gemma 3
TEMPLATE "<start_of_turn>user\n{{ .Prompt }}<end_of_turn>\n<start_of_turn>model\n"

# Parâmetros recomendados para o Router
PARAMETER temperature 0.6
PARAMETER top_p 0.95
PARAMETER top_k 64
PARAMETER stop "<end_of_turn>"
```

Depois crie e rode o modelo:
```bash
ollama create rango-router -f Modelfile
ollama run rango-router "Manda o cardápio aí chefia"
```

### 2. Llama.cpp (CLI)

Ao rodar via linha de comando, passe as flags correspondentes:

```bash
llama-cli --hf RiosWesley/gemma-3-270m-router-br-gguf \
  --temp 0.6 \
  --top-p 0.95 \
  --top-k 64 \
  -p "<start_of_turn>user\nO motoboy sumiu, cadê meu lanche?<end_of_turn>\n<start_of_turn>model"
```

### 3. Python (Llama-cpp-python)

```python
from llama_cpp import Llama

llm = Llama(
    model_path="./gemma-3-270m-it.Q8_0.gguf",
    n_ctx=2048
)

output = llm(
    "<start_of_turn>user\nQuero pedir uma pizza meia a meia\n<end_of_turn>\n<start_of_turn>model",
    max_tokens=128,
    temperature=0.6,
    top_p=0.95,
    top_k=64,
    stop=["<end_of_turn>"]
)

print(output['choices'][0]['text'])
```

## Arquivos Disponíveis

*   `gemma-3-270m-it.Q8_0.gguf`: Versão quantizada em 8-bit (Recomendada).

## Dados de Treinamento

O modelo foi treinado no dataset **[RiosWesley/rango-router-BR](https://huggingface.co/datasets/RiosWesley/rango-router-BR)**, contendo frases coloquiais do português brasileiro focadas em contextos de alimentação e restaurantes.

---
*Model finetuned using [Unsloth](https://github.com/unslothai/unsloth).*
```