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