pycoder-3b

Fine-tuning QLoRA de 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.

Formato de prompt

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

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

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.

{
  "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
• Dataset: iamtarun/python_code_instructions_18k_alpaca
• Método: QLoRA (Dettmers et al., 2023) e LoRA (Hu et al., 2021)