pycoder-3b-GGUF

Versões quantizadas em GGUF de raporto/pycoder-3b, um fine-tuning QLoRA de 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:

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.

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

ollama create pycoder-3b -f Modelfile

Uso com llama.cpp

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:

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

{
  "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.

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
• Modelo base: Qwen/Qwen2.5-3B-Instruct
• Dataset: iamtarun/python_code_instructions_18k_alpaca
• Quantização: llama.cpp