--- license: apache-2.0 base_model: raporto/pycoder-3b library_name: gguf pipeline_tag: text-generation language: - pt - en - es tags: - gguf - ollama - llama.cpp - quantized - qwen2.5 - python - code - code-generation datasets: - iamtarun/python_code_instructions_18k_alpaca --- # pycoder-3b-GGUF Versões quantizadas em GGUF de [`raporto/pycoder-3b`](https://huggingface.co/raporto/pycoder-3b), um fine-tuning QLoRA de [`Qwen/Qwen2.5-3B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) para assistência em programação Python. Para executar com Transformers, vLLM ou continuar treinando, use o repositório de pesos em bf16. Este aqui é o formato de consumo: roda em llama.cpp, Ollama e LM Studio, inclusive em GPUs pequenas e em CPU. ## Arquivos | Arquivo | Quantização | Tamanho | Uso recomendado | |---|---|---|---| | `pycoder-3b-q4_k_m.gguf` | Q4_K_M (~4,5 bpw) | ~1,9 GB | Padrão. Menor pegada, cabe em GPUs de 4 GB. | | `pycoder-3b-q6_k.gguf` | Q6_K (~6,1 bpw) | ~2,6 GB | Qualidade quase idêntica ao original. Preferível quando há VRAM. | Ambos foram gerados a partir do mesmo GGUF F16, convertido direto dos pesos em bf16 — nenhum arquivo foi requantizado a partir de outro quantizado. Em um modelo de 3B, a degradação relativa da quantização tende a ser maior do que em modelos grandes. Se houver memória disponível, o Q6_K é a escolha mais segura. ## Uso com Ollama Direto do Hugging Face, sem Modelfile: ```bash ollama pull hf.co/raporto/pycoder-3b-GGUF:Q4_K_M ollama cp hf.co/raporto/pycoder-3b-GGUF:Q4_K_M pycoder-3b ollama run pycoder-3b ``` Para a versão de maior qualidade, troque a tag por `Q6_K`. Sem tag, o Ollama escolhe Q4_K_M quando o arquivo existe no repositório. ### Modelfile Ao importar o `.gguf` manualmente, o template é obrigatório. Sem ele, o Ollama aplica o padrão e o modelo responde fora de formato ou não interrompe a geração. ```dockerfile FROM ./pycoder-3b-q4_k_m.gguf TEMPLATE """{{- if .System }}<|im_start|>system {{ .System }}<|im_end|> {{ end }} {{- range .Messages }}<|im_start|>{{ .Role }} {{ .Content }}<|im_end|> {{ end }}<|im_start|>assistant """ SYSTEM """Você é um engenheiro de software sênior especializado em Python. Escreva código correto, idiomático e testável, explique decisões importantes em poucas linhas e sinalize casos de borda relevantes.""" PARAMETER stop "<|im_start|>" PARAMETER stop "<|im_end|>" PARAMETER temperature 0.2 PARAMETER top_p 0.9 PARAMETER repeat_penalty 1.05 PARAMETER num_ctx 8192 ``` ```bash ollama create pycoder-3b -f Modelfile ``` ## Uso com llama.cpp ```bash llama-cli -m pycoder-3b-q4_k_m.gguf -ngl 99 -c 8192 \ -p "Escreva uma função que valide um CPF." --temp 0.2 llama-server -m pycoder-3b-q4_k_m.gguf -ngl 99 -c 8192 --host 0.0.0.0 --port 8080 ``` `-ngl 99` descarrega todas as camadas na GPU. Com Q4_K_M, o modelo inteiro cabe em placas a partir de 4 GB; com Q6_K, a partir de 6 GB. ## 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 ``` ## Parâmetros recomendados | Parâmetro | Valor | Motivo | |---|---|---| | `temperature` | 0.15 – 0.3 | Geração de código pede determinismo. | | `top_p` | 0.9 | | | `repeat_penalty` | 1.05 | Evita loops sem penalizar repetição legítima em código. | | `num_ctx` | 8192 | Comporta um arquivo médio mais a conversa. | | `num_predict` | 1024 | Implementação acompanhada de testes. | ## Treinamento QLoRA em 4 bits sobre `Qwen/Qwen2.5-3B-Instruct`, com adapters LoRA em todas as projeções de atenção e MLP, perda calculada apenas sobre os tokens de resposta e sequence packing em blocos de 1024 tokens. ```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 } } ``` `train_samples` conta blocos empacotados, não exemplos: o dataset de 18.612 exemplos foi percorrido integralmente em 1 época. A perplexidade é medida apenas sobre tokens de resposta e não é comparável à de modelos de propósito geral. Detalhes completos no [repositório de pesos](https://huggingface.co/raporto/pycoder-3b). ## 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. ## 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**. Além das limitações do modelo original: - **Perda por quantização.** Estes arquivos não são numericamente idênticos aos pesos em bf16. Avalie a variante escolhida antes de adotá-la, em vez de assumir paridade com o repositório de origem. - **Alucinação de API.** Pode inventar parâmetros ou métodos de bibliotecas de terceiros. - **Contexto e raciocínio longos.** Refatorações amplas e cadeias longas de raciocínio estão acima do que essa faixa de tamanho entrega de forma confiável. - **Segurança.** O código gerado não passa por análise de segurança. 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. ## Créditos - Pesos de origem: [raporto/pycoder-3b](https://huggingface.co/raporto/pycoder-3b) - 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) - Quantização: [llama.cpp](https://github.com/ggml-org/llama.cpp)