README.md

---
license: apache-2.0
base_model: unsloth/Qwen2.5-Coder-3B-Instruct
tags:
  - unsloth
  - qwen2
  - lora
  - gguf
  - code
  - coding-assistant
language:
  - en
  - es
---

# Qwen2.5-SuperCoder-3B-Instruct

> ⚠️ **Aviso:** este modelo fue entrenado por un aficionado, como proyecto personal de fine-tuning.

Fine-tune de **Qwen2.5-Coder-3B-Instruct**, orientado a asistencia de código ("vibe coding"), corrección de errores, y generación de interfaces, manteniendo coherencia conversacional multi-turno.

## Tecnología usada

- **Modelo base:** [Qwen2.5-Coder-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-3B-Instruct), arquitectura Qwen2 clásica (atención GQA + RoPE).
- **Framework de entrenamiento:** [Unsloth](https://github.com/unslothai/unsloth), con `FastLanguageModel` y checkpointing optimizado (`use_gradient_checkpointing="unsloth"`).
- **Método:** LoRA 16-bit (rank 32, alpha 32, dropout 0), aplicado a `q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj`.
- **Hardware:** entrenado en una RTX 5090 (32GB VRAM) alquilada en vast.ai.
- **Hiperparámetros clave:** learning rate 2e-4, scheduler coseno, optimizer AdamW 8-bit, 2 épocas, context length 2048, weight decay 0.01, entrenamiento con `assistant completions only` (el loss solo se calcula sobre los tokens de la respuesta del asistente, no sobre el prompt ni el system message).
- **Exportación:** cuantizado a GGUF (Q4_K_M) para inferencia en llama.cpp / Ollama / LM Studio.

## Dataset de entrenamiento

Mezcla de ~46,600 filas (tras deduplicación) de 13 fuentes públicas, normalizadas a conversaciones multi-turno (formato `messages`, no solo pares instrucción/respuesta aplanados) para preservar coherencia conversacional. Proporciones aproximadas por fuente:

| Dataset | % de la mezcla | Propósito |
|---|---|---|
| CodeAlpaca-20k | ~42% | Código general, instrucciones cortas |
| teknium/OpenHermes-2.5 | ~7% | Conversación general multi-turno |
| CodeDevX/Vibe-Coding-Instruct-V2 | ~7% | Código orientado a "vibe coding" |
| ise-uiuc/Magicoder-Evol-Instruct-110K | ~6% | Instrucciones de código evolucionadas (Evol-Instruct) |
| m-a-p/CodeFeedback-Filtered-Instruction | ~6% | Debug con feedback de ejecución real |
| angrygiraffe/claude-opus-4.6-4.7-reasoning-8.7k | ~5% | Razonamiento paso a paso (destilado) |
| HuggingFaceH4/ultrachat_200k | ~5% | Conversación general, retención de contexto |
| Vezora/Tested-143k-Python-Alpaca | ~4% | Python verificado/ejecutado |
| nohurry/Opus-4.6-Reasoning-3000x-filtered | ~4% | Razonamiento paso a paso (destilado, filtrado) |
| cfahlgren1/react-code-instructions | ~3% | Componentes React / diseño de interfaces |
| iamdyeus/ui-instruct-4k | ~3% | Componentes UI (Next.js / Tailwind / ShadCN) |
| garage-bAInd/Open-Platypus | ~3% | Lógica y razonamiento general |
| meta-math/MetaMathQA | ~2% | Matemática/lógica, sin saturar la mezcla |

## La filosofía "ponytail"

Un subconjunto de las fuentes con razonamiento visible (angrygiraffe, nohurry, CodeFeedback) fue entrenado con un system prompt fijo que le pide al modelo, antes de escribir código, evaluar en orden: **(1)** si el código necesita existir (YAGNI), **(2)** si la librería estándar ya lo resuelve, **(3)** si una función nativa de la plataforma lo resuelve, **(4)** si una dependencia ya instalada lo resuelve, **(5)** si se puede resolver en una línea — y solo entonces escribir el mínimo código necesario, sin recortar validación de inputs, seguridad, manejo de errores o accesibilidad.

Ese system prompt **no se aplicó a toda la mezcla**: solo se inyectó en las fuentes donde la respuesta demuestra ese razonamiento explícitamente. En datasets de instrucciones cortas y directas (CodeAlpaca, Magicoder, etc.) no tendría sentido pedir ese checklist si la respuesta nunca lo refleja — habría sido una señal de entrenamiento contradictoria (el system prompt pidiendo algo que la respuesta objetivo no demuestra).

## Limitaciones conocidas

- Al ser un fine-tune LoRA sobre un modelo de 3B, no espera igualar la calidad de modelos de código mucho más grandes.
- La mezcla de datasets incluye entre 13 fuentes de calidad y curación variable (algunas generadas sintéticamente por terceros vía API, no verificadas manualmente por sus autores).
- No se descarta cierta interferencia entre lenguajes de programación dado el desbalance de la mezcla (fuerte peso en Python, menor en JavaScript/TypeScript) — revisa el output generado en lenguajes menos representados antes de confiar en él ciegamente.

## Uso

Formato de prompt ChatML (heredado de Qwen2.5):

```
<|im_start|>system
{system_prompt}<|im_end|>
<|im_start|>user
{prompt}<|im_end|>
<|im_start|>assistant
```