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