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

pip install llama-cpp-python

Exemplo de Código (Python)

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