---
license: apache-2.0
base_model: Qwen/Qwen2.5-3B-Instruct
library_name: transformers
pipeline_tag: text-generation
language:
  - pt
  - en
  - es
tags:
  - qwen2.5
  - qlora
  - lora
  - peft
  - python
  - code
  - code-generation
datasets:
  - iamtarun/python_code_instructions_18k_alpaca
---

# pycoder-3b

Fine-tuning QLoRA de [`Qwen/Qwen2.5-3B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) para assistência em programação Python, com o adapter LoRA já mesclado nos pesos base.

O objetivo do ajuste é a **forma da resposta**, não conhecimento novo: entregar código completo e executável em vez de fragmentos, manter consistência de estilo e responder em português sem perder a capacidade original do modelo em inglês.

Versão quantizada para execução local: [`raporto/pycoder-3b-GGUF`](https://huggingface.co/raporto/pycoder-3b-GGUF).

## Formato de prompt

ChatML do Qwen2.5, com system prompt em português:

```text
<|im_start|>system
Você é um assistente especialista em programação Python.<|im_end|>
<|im_start|>user
Escreva uma função que...<|im_end|>
<|im_start|>assistant
```

O `apply_chat_template` do tokenizer já produz esse formato. Usar um template diferente do treino degrada bastante o resultado.

## Uso

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_id = "raporto/pycoder-3b"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, dtype=torch.bfloat16, device_map="auto")

messages = [
    {"role": "system", "content": "Você é um assistente especialista em programação Python."},
    {"role": "user", "content": "Escreva uma função que remova duplicados de uma lista preservando a ordem."},
]

inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_dict=True, return_tensors="pt"
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=768, temperature=0.2, top_p=0.9, do_sample=True)
print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))
```

Em versões do Transformers anteriores à 5, use `torch_dtype` no lugar de `dtype`.

### Parâmetros recomendados

| Parâmetro | Valor | Motivo |
|---|---|---|
| `temperature` | 0.15 – 0.3 | Geração de código pede determinismo. |
| `top_p` | 0.9 | |
| `repetition_penalty` | 1.05 | Evita loops sem penalizar repetição legítima em código. |
| `max_new_tokens` | 768 – 1024 | Implementação com testes cabe nessa faixa. |

## Treinamento

QLoRA em 4 bits (NF4 com double quantization), adapters LoRA sobre todas as projeções de atenção e MLP (`q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj`). Apenas os tokens da resposta do assistente entram na perda; os tokens de prompt recebem `label = -100`.

Os exemplos foram concatenados em blocos contíguos de 1024 tokens (sequence packing), com ~89% de aproveitamento. Exemplos acima do limite foram descartados em vez de truncados, para não ensinar o modelo a interromper código no meio.

```json
{
  "model": "Qwen/Qwen2.5-3B-Instruct",
  "dataset": "iamtarun/python_code_instructions_18k_alpaca",
  "dtype": "torch.bfloat16",
  "packing": true,
  "train_samples": 3431,
  "train_tokens": 3124347,
  "effective_batch": 16,
  "steps": 215,
  "train_loss": 0.48165738638057265,
  "eval_loss": 0.47419440746307373,
  "perplexity": 1.6067193148929226,
  "lora": {
    "r": 16,
    "alpha": 32,
    "dropout": 0.05
  }
}
```

| Item | Valor |
|---|---|
| Parâmetros treináveis | 29.933.568 de 3.115.872.256 (0,96%) |
| Blocos de treino | 3.431 (dataset completo, 18.612 exemplos) |
| Tokens de treino | 3.124.347 |
| Épocas | 1 |
| Batch efetivo | 16 |
| Learning rate | 2e-4, cosine, warmup 3% |
| Precisão | bf16 |
| Otimizador | paged AdamW 8-bit |

`train_samples` conta blocos empacotados, não exemplos: o dataset foi percorrido integralmente.

A perplexidade de 1,61 é calculada apenas sobre os tokens de resposta e não é comparável à perplexidade de modelos de linguagem de propósito geral.

## Avaliação

A perda de validação sozinha não diz se o código funciona. A avaliação deste modelo usa um benchmark de tarefas Python com testes executáveis, medindo em quatro camadas: presença de bloco de código, validade sintática (`ast.parse`), execução sem exceção e aprovação nos asserts da tarefa (pass@1 e pass@k).

Recomenda-se reexecutar o benchmark contra o modelo base antes de adotar este ajuste em qualquer fluxo, e novamente após quantizar, já que a perda de precisão pode alterar o resultado.

## Idiomas

Treinado com system prompt e instruções em português, sobre um dataset de código em inglês. Responde bem em **português** e **inglês**. O **espanhol** é herdado da capacidade multilíngue do Qwen2.5 e não foi alvo do ajuste, portanto não tem garantia de consistência de formato.

Código, nomes de identificadores e mensagens de erro permanecem em inglês, como é convenção em Python.

## Limitações

Modelo de 3B parâmetros treinado em ~18k exemplos de instrução. Serve como assistente de código do dia a dia, não como fonte autoritativa: **valide o código gerado antes de executar em produção**.

Limitações específicas:

- **Alucinação de API.** Pode inventar parâmetros ou métodos de bibliotecas de terceiros. Confira contra a documentação oficial.
- **Contexto e raciocínio longos.** Refatorações amplas, dependências entre múltiplos arquivos e cadeias longas de raciocínio estão acima do que essa faixa de tamanho entrega de forma confiável.
- **Contaminação.** O modelo base provavelmente já viu parte do dataset de treino. Avaliações feitas com tarefas derivadas desse dataset superestimam o desempenho.
- **Segurança.** O código gerado não passa por análise de segurança. Trate-o como código de terceiros: revise antes de executar, especialmente se manipular arquivos, rede ou entrada não confiável.
- **Escopo.** Ajustado para Python. Outras linguagens funcionam apenas na medida do modelo base.

## Licença

Apache 2.0, herdada do modelo base Qwen2.5-3B-Instruct. Verifique também os termos do dataset antes de redistribuir derivados.

## Créditos

- Modelo base: [Qwen/Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct)
- Dataset: [iamtarun/python_code_instructions_18k_alpaca](https://huggingface.co/datasets/iamtarun/python_code_instructions_18k_alpaca)
- Método: [QLoRA (Dettmers et al., 2023)](https://arxiv.org/abs/2305.14314) e [LoRA (Hu et al., 2021)](https://arxiv.org/abs/2106.09685)