README.md

---
language:
- pt
- en
license: apache-2.0
tags:
- gguf
- nl2sql
- text-to-sql
- postgis
- geospatial
- cpu-inference
- qwen2.5-coder
base_model:
- Qwen/Qwen2.5-Coder-3B-Instruct
- Qwen/Qwen2.5-Coder-7B-Instruct
---

# TerraModel: SLMs Quantizados para Tradução NL2SQL Geoespacial

## 📌 Visão Geral do Modelo
O **TerraModel** é uma família de *Small Language Models* (SLMs) especializados na tradução de linguagem natural para consultas em bancos de dados relacionais espaciais (PostgreSQL/PostGIS). Este modelo foi otimizado para o domínio de monitoramento ambiental do bioma Amazônia, focado em superar o gargalo de largura de banda de memória (*Memory Bandwidth Wall*) em infraestruturas baseadas exclusivamente em processadores centrais (*CPU-only*).

Este repositório contém as versões quantizadas em formato **GGUF (4 bits e 8 bits)** dos modelos de 3B e 7B de parâmetros, permitindo inferência local de alta eficiência, com baixo consumo de RAM e garantia de privacidade na manipulação de dados governamentais sensíveis. Também disponibilizamos os pesos originais de alta precisão para inferência acelerada por GPU.

## 🛠️ Detalhes Técnicos
- **Modelo Base:** Qwen2.5-Coder-Instruct (3B e 7B)
- **Técnica de Fine-Tuning:** QLoRA (Parameter-Efficient Fine-Tuning)
- **Formatos de Inferência:** GGUF (via `llama.cpp` para CPU) e Safetensors (via `transformers` para GPU)
- **Quantizações Disponíveis:** Q4_K_M (INT4) e Q8_0 (INT8)
- **Domínio:** Geoespacial, PostGIS, Monitoramento Ambiental (Amazônia)
- **Idioma Principal:** Português (PT-BR) / SQL

## 📂 Arquivos do Repositório: Qual versão baixar?

### 1. Modelos Quantizados (CPU-Only)
Para ambientes restritos a processadores centrais, oferecemos formatos GGUF. Escolha a versão de acordo com a disponibilidade de memória RAM do seu servidor:

**Versões Q4 (INT4)**
Ideais para restrição severa de memória, oferecendo maior velocidade de geração (menor latência):
* `terramodel-7b-q4_k_m.gguf`: Requer **~4.68 GB** de RAM.
* `terramodel-3b-q4_k_m.gguf`: Requer apenas **~1.93 GB** de RAM (Versão mais leve, viável em praticamente qualquer dispositivo).

**Versões Q8 (INT8)**
Recomendadas se você possui maior folga na memória RAM e deseja priorizar a acurácia máxima e a integridade sintática nas consultas geradas:
* `terramodel-7b-q8_0.gguf`: Requer **~8.10 GB** de RAM (Melhor equilíbrio de desempenho empírico no benchmark).
* `terramodel-3b-q8_0.gguf`: Requer **~3.29 GB** de RAM.

### 2. Modelos em Alta Precisão (GPU)
Para infraestruturas que contam com aceleração gráfica, os pesos fundidos (*merged*) originais estão disponíveis nas seguintes pastas. O carregamento direto em VRAM (FP16) reflete o tamanho integral dos tensores:
* 📁 `terramodel-7b-bf16/` (Requer **~15.2 GB** de VRAM dedicada)
* 📁 `terramodel-3b-bf16/` (Requer **~6.18 GB** de VRAM dedicada)

## 💻 Como Utilizar (Inferência Local em Python via CPU)

Para rodar o formato GGUF localmente utilizando apenas o processador, recomendamos a biblioteca `llama-cpp-python`.

### Instalação
```bash
pip install llama-cpp-python
```



### Exemplo de Código (Python)

```bash

from llama_cpp import Llama

def generate_spatial_query(prompt: str, model_path: str) -> str:
    """
    Gera uma consulta PostGIS a partir de linguagem natural utilizando o TerraModel.
    
    Args:
        prompt (str): A pergunta em linguagem natural.
        model_path (str): O caminho local para o arquivo .gguf.
        
    Returns:
        str: A consulta SQL gerada pelo modelo.
    """
    # Instanciação do modelo otimizada para CPU
    llm = Llama(
        model_path=model_path,
        n_ctx=2048,          # Janela de contexto
        n_threads=8,         # Ajuste para a quantidade de núcleos físicos da sua CPU
        verbose=False
    )
    
    # System Prompt exato utilizado no fine-tuning do TerraModel
    system_prompt = """Você é o TerraModel, um especialista em análise geoespacial e PostgreSQL/PostGIS.
Sua tarefa é traduzir perguntas em linguagem natural para consultas SQL rigorosas e otimizadas.

Você deve basear sua sintaxe ESTRITAMENTE no seguinte esquema de banco de dados:
CREATE TABLE public.dados_deter (gid integer, fid varchar, classname varchar, quadrant varchar, path_row varchar, view_date date, sensor varchar, satellite varchar, areauckm numeric, uc varchar, areamunkm numeric, municipali varchar, geocodibge varchar, uf varchar, geom geometry);
Nota: Use unaccent() para buscar textos."""

    # Formatação ChatML requerida pela arquitetura Qwen2.5-Coder
    formatted_prompt = f"<|im_start|>system\n{system_prompt}<|im_end|>\n<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant\n"
    
    # Inferência
    response = llm(
        formatted_prompt,
        max_tokens=256,
        stop=["<|im_end|>"],
        temperature=0.1      # Temperatura baixa para garantir determinismo na sintaxe SQL
    )
    
    return response['choices'][0]['text'].strip()

# Exemplo de uso
if __name__ == "__main__":
    pergunta = "Calcule a área total em hectares dos polígonos que representam áreas de desmatamento e que estão dentro de um raio de 10 km de um ponto específico."
    caminho_gguf = "./terramodel-7b-q4_k_m.gguf"
    
    sql_gerado = generate_spatial_query(pergunta, caminho_gguf)
    print("Query Gerada:\n", sql_gerado)

```



## 📊 Avaliação e Desempenho

O modelo foi submetido a um rigoroso benchmark empírico. A versão TerraModel 7B Q8 atingiu uma Acurácia de Execução de 82,00% no PostGIS, superando APIs comerciais como o GPT-4o-mini em cenários de inferência zero-shot focados no esquema do projeto.

Para aprofundamento metodológico, métricas de taxa de transferência (throughput) e validação semântica sistêmica (RAGAS), consulte o artigo científico vinculado a este projeto.


## 🔗 Conjunto de Dados e Reprodutibilidade

O dataset sintético com as 3.000 amostras (pares NL-SQL) utilizadas para a injeção de conhecimento topológico e os scripts de benchmark estão disponíveis no repositório do GitHub:

👉 [Acesse o Repositório](https://github.com/thiagonishimura/terramodel)