README.md

---
license: apache-2.0
base_model: Qwen/Qwen2.5-Coder-1.5B-Instruct
library_name: transformers
pipeline_tag: text-generation
tags:
  - code
  - python
  - sql
  - pyspark
  - qlora
  - ollama
  - gguf
---

# Model Card: qwen-python-slm

## Visão geral

`qwen-python-slm` é um modelo de linguagem pequeno (SLM) especializado em gerar código para o ecossistema de **Engenharia de Dados, Data Science, Machine Learning, Deep Learning, LLMs, Agentes de IA, DataOps e MLOps**.

O modelo é um ajuste fino (SFT com QLoRA) do [`Qwen/Qwen2.5-Coder-1.5B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct), mantendo a arquitetura de 1,5 bilhão de parâmetros e adicionando adaptadores LoRA treinados para responder a instruções técnicas de dados/IA em **Python**, **SQL** e **PySpark**.

- **Tipo de modelo:** Causal LM para geração de código
- **Idioma:** Português (instruções) + código multilíngue (Python/SQL/PySpark)
- **Licença:** Apache 2.0
- **Formatos disponíveis:**
  - Pesos completos (merged, FP16) no Hugging Face Hub
  - GGUF quantizado em Q4_K_M para uso local via Ollama / llama.cpp / Continue.dev

---

## Uso pretendido

- Geração de scripts Python para ETL/ELT, análise de dados e ML.
- Escrita de consultas SQL compatíveis com SQLite/PostgreSQL.
- Geração de código PySpark para processamento distribuído.
- Prototipagem de agentes de IA com LangChain, LlamaIndex, CrewAI etc.
- Automação de pipelines de MLOps/DataOps (Airflow, dbt, MLflow).
- Uso educacional e produtividade de desenvolvedores de dados.

> **Não recomendado para:** produção crítica sem revisão humana; geração de código com dados sensíveis sem validação de segurança; substituição de engenheiros especialistas.

---

## Comandos de linguagem

O modelo reconhece prefixos no prompt para forçar a linguagem/domínio desejado:

```text
/python   Código Python genérico
/sql      Consultas SQL
/pyspark  Código PySpark
/ml       Machine Learning (scikit-learn, PyTorch, etc.)
/llm      LLMs e fine-tuning (transformers, peft, vLLM, etc.)
/agent    Agentes de IA (LangChain, LlamaIndex, CrewAI, etc.)
/dataops  Pipelines/DataOps/MLOps (Airflow, dbt, MLflow, etc.)
```

Exemplo:

```bash
ollama run tel1980/qwen-python-slm "/sql Liste os 10 produtos mais vendidos no último trimestre."
```

---

## Detalhes do treinamento

- **Modelo base:** `Qwen/Qwen2.5-Coder-1.5B-Instruct`
- **Técnica:** Supervised Fine-Tuning (SFT) com QLoRA (4-bit NF4)
- **Tamanho de contexto:** 1024 tokens
- **Hardware de treino:** NVIDIA GeForce RTX 5050 (8 GB VRAM)
- **Hiperparâmetros LoRA:**
  - `r = 16`
  - `alpha = 32`
  - `dropout = 0.05`
  - Módulos alvo: `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj`
- **Hiperparâmetros de treino:**
  - Batch size efetivo: 16 (1 × 16 gradient accumulation)
  - Learning rate: 2e-4
  - Max steps: 500
  - Warmup steps: 30
  - Otimizador: `paged_adamw_8bit`
- **Resultado do treino:** ~1h10min de GPU, loss médio 0,578, loss final 0,508
- **Parâmetros treináveis:** 18,4M (1,18% do total)

---

## Dados de treino

Dataset final combinado: **98.180 amostras**.

- **Dataset principal:** `iamtarun/python_code_instructions_18k_alpaca` (Python, filtrado por keywords de dados/IA)
- **Datasets Python extras:** `flytech/python-codes-25k`, `m-a-p/CodeFeedback-Filtered-Instruction` (filtrado para Python, subamostrado para 30k)
- **Dataset SQL:** `b-mc2/sql-create-context` (subamostrado para 15k)
- **Dataset PySpark:** curadoria própria de 1.500 amostras no formato Alpaca (`datasets/pyspark_instructions.json`)
- **Filtro de domínio:** amostras são mantidas apenas se contiverem palavras-chave do ecossistema de dados/IA (pandas, sklearn, PyTorch, Spark, Airflow, MLflow, LangChain etc.)
- **Prompt de sistema:** engenheiro de dados/ML sênior, especializado em Python/SQL/PySpark para dados e IA.

---

## Métricas de avaliação

Avaliação executada com `src/evaluate.py` (Python) e `src/evaluate_extended.py` (SQL e PySpark), 30 amostras por linguagem.

> **Ressalva:** as amostras de avaliação vêm dos mesmos datasets usados no treino, então os números tendem a ser otimistas. Servem como sanity check de formato e gramática.

| Métrica | Valor |
|---|---|
| Taxa de compilação Python válida | 96,67% |
| Taxa de execução Python sem erros | 83,33% |
| Taxa de parse SQL válido | 100,00% |
| Taxa de sintaxe PySpark válida | 100,00% |
| BLEU médio — Python | 0,175 |
| BLEU médio — SQL | 0,917 |
| BLEU médio — PySpark | 0,353 |

Observações:
- Os erros de execução Python foram principalmente ambientais (biblioteca externa ausente, `input()` sem stdin, arquivo local inexistente), não falhas de sintaxe.
- BLEU alto em SQL reflete o forte padrão do dataset `sql-create-context`; BLEU mede similaridade com a referência, não correção semântica.

Futuramente, recomenda-se adicionar **pass@1** em benchmarks como HumanEval, MBPP e Spider/BIRD (SQL), com dados nunca vistos no treino.

---

## Limitações

- O modelo foi treinado com recursos limitados (RTX 5050 8 GB, 500 steps), então pode apresentar alucinações ou código não executável.
- SQL é validado sintaticamente, mas não executado contra um banco real — a semântica depende do schema fornecido.
- PySpark é tratado como Python; a execução real exige ambiente Spark configurado.
- O domínio é voltado para dados/IA; código fora desse escopo (frontend, mobile, etc.) pode ter qualidade inferior.
- O modelo pode reproduzir vieses presentes nos dados de treino.

---

## Como usar

### Ollama (GGUF)

```bash
ollama run tel1980/qwen-python-slm "/python Crie uma DAG do Airflow que baixe um CSV e salve no S3."
```

### Transformers (pesos merged)

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "tel1980/qwen-python-slm"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")

messages = [
    {"role": "system", "content": "Você é um engenheiro de dados e Machine Learning sênior."},
    {"role": "user", "content": "/sql Liste os clientes com mais de 5 pedidos."},
]
inputs = tokenizer.apply_chat_template(messages, return_tensors="pt", add_generation_prompt=True).to(model.device)
outputs = model.generate(inputs, max_new_tokens=512, temperature=0.2)
print(tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokens=True))
```

---

## Licença

Este modelo é distribuído sob a licença **Apache 2.0**, a mesma do modelo base Qwen2.5-Coder-1.5B-Instruct.

---

## Citação

Se você usar este modelo em trabalhos acadêmicos, cite o modelo base:

```bibtex
@article{qwen2.5,
  title={Qwen2.5 Technical Report},
  author={Qwen Team},
  journal={arXiv preprint arXiv:2409.12186},
  year={2024}
}
```

---

## Links

- Código-fonte: `https://github.com/tel1980/SLM_python`
- Pesos merged (FP16): `https://huggingface.co/tel1980/qwen-python-slm`
- GGUF quantizado: `https://huggingface.co/tel1980/qwen-python-slm-gguf`