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)