can-i-finetune-this — Guía práctica

Qué hace

Esta herramienta responde a la pregunta: “¿Puedo ajustar finamente este LLM en mi GPU de consumo?” — antes de descargar los pesos o perder tiempo con un error OOM. Proporciona:

• Estimación de memoria – modela el consumo de VRAM para un modelo, método (LoRA/QLoRA), longitud de secuencia, tamaño de lote y rango LoRA dados, incluyendo pesos, gradientes, estados del optimizador, activaciones y un margen de seguridad por fragmentación.
• Verificación de viabilidad – te dice si una configuración cabe en tu GPU, con un nivel de confianza.
• Recomendación – busca una configuración factible (por ejemplo, recomienda un rango más bajo o una longitud de secuencia más corta).
• Benchmarking – ejecuta un mini‑paso de entrenamiento real en un modelo pequeño (sshleifer/tiny-gpt2, ~5 MB) para medir el pico real de VRAM en tu máquina.
• Calibración – utiliza los resultados del benchmark para corregir las estimaciones estáticas, haciéndolas más precisas para tu GPU/controlador/stack de software específico.
• Generación de recetas – produce un script de entrenamiento listo para ejecutar de Hugging Face + PEFT + TRL adaptado a tu configuración elegida.
• Informes y comparación – genera informes en Markdown de los resultados del benchmark y compara múltiples ejecuciones.

La idea central es que las estimaciones estáticas simples (como accelerate estimate-memory) solo cubren la carga del modelo, no la sobrecarga de entrenamiento. Esta herramienta añade un modelo de memoria detallado y un bucle de retroalimentación de medición real.

Cómo empezar

Instalación

canifinetune tiene dos capas de instalación:

Importante: PyTorch generalmente debe instalarse con el wheel de CUDA que coincida con tu controlador. Por ejemplo, con uv:

uv pip install torch --index-url https://download.pytorch.org/pypi/cu121

Si estás usando uv para todo el entorno:

uv venv
uv pip install -e ".[dev,report]"
# Add training deps when you want to run benchmarks:
uv pip install -e ".[dev,train,report]"

Consulte docs/troubleshooting.md para obtener información específica sobre Windows / WSL / bitsandbytes.

Configuración mínima

1. Instale el paquete principal (o principal + entrenamiento si planea ejecutar pruebas comparativas).
2. (Opcional pero recomendado) Ejecute canifinetune doctor para verificar su entorno y la visibilidad de la GPU.
3. Ahora puede usar cualquiera de los comandos de la CLI.

Uso práctico

Todos los comandos se invocan a través de la CLI canifinetune. El README muestra los siguientes flujos de trabajo:

1. Verifique su máquina

canifinetune doctor

Muestra información del hardware (GPU, controlador, versión de CUDA) y verifica que las dependencias requeridas estén disponibles.

2. Estimar VRAM para una configuración específica

canifinetune estimate \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --method qlora \
  --gpu-vram-gb 16 \
  --seq-len 2048 \
  --micro-batch-size 1 \
  --lora-rank 16

La salida es una tabla con un veredicto de viabilidad (SÍ/NO) y un desglose de memoria por componente (modelo estático, sobrecarga de cuantización, parámetros entrenables, gradientes, estados del optimizador, activaciones, CUDA/fragmentación, margen de seguridad, total).

3. Deje que la herramienta recomiende una configuración viable

canifinetune recommend --model Qwen/Qwen2.5-1.5B-Instruct --gpu-vram-gb 16

Busca una configuración (rango, longitud de secuencia, método) que se adapte a su GPU.

4. Ejecutar un benchmark real (requiere extras [train])

canifinetune bench --model sshleifer/tiny-gpt2 --method lora --steps 3

Descarga un modelo pequeño y ejecuta algunos pasos de entrenamiento, midiendo el pico real de VRAM. Los resultados se guardan localmente para que puedan usarse posteriormente para la calibración.

5. Generar una receta de entrenamiento lista para ejecutar

canifinetune recipe \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --method qlora \
  --seq-len 2048 \
  --output recipes/qwen2.5-1.5b-qlora-4080

Genera una carpeta con un script de entrenamiento (run_qlora.py o similar) y un archivo de configuración, listos para ejecutarse con modificaciones mínimas.

6. Calibrar estimaciones usando resultados de benchmark

canifinetune calibrate --benchmarks benchmarks/results

Lee los archivos JSON de benchmark y actualiza los parámetros internos del estimador estático para adaptarse mejor a tu hardware.

7. Generar un informe Markdown de los benchmarks

canifinetune report --benchmarks benchmarks/results --out report.md
canifinetune compare --benchmarks benchmarks/results --out compare.md

Configuración y opciones

Todos los parámetros clave se pasan como indicadores de CLI. No hay un archivo de configuración independiente (aunque el comando recipe genera scripts que contienen la configuración). Los parámetros principales son:

La estimación estática también usa suposiciones internas sobre target_modules (estándar para la arquitectura del modelo), gradient checkpointing (desactivado por defecto) y el optimizador (AdamW). Estas se enumeran en el bloque assumptions de la salida.

Limitaciones y restricciones conocidas

El README indica explícitamente el alcance actual y las brechas conocidas:

• Solo GPU de consumo única – sin múltiples GPU, sin DeepSpeed, sin soporte FSDP (aunque la hoja de ruta futura podría agregarlo).
• Nodo único – sin entrenamiento distribuido.
• Solo LoRA / QLoRA – no se considera el ajuste fino completo.
• Solo LM causal – no se modelan arquitecturas de clasificación o encoder‑decoder (la hoja de ruta podría extenderlo).
• Stack de Hugging Face – solo se admiten modelos/datasets/trainers del ecosistema HF.
• Las estimaciones estáticas tienen precisión limitada – la memoria de activación en particular es difícil de predecir. Cada estimación está etiquetada con un nivel de confidence y un bloque assumptions. La herramienta recomienda ejecutar bench y calibrate para fundamentar los números.
• El comando bench actualmente usa un modelo pequeño (sshleifer/tiny-gpt2) como proxy – esto puede no escalar perfectamente a modelos grandes, pero captura los overheads de tu entorno (desempaquetado de bitsandbytes, fragmentación, etc.).

La hoja de ruta del proyecto añade más contexto: el modelado de rendimiento (tokens/segundo), el ajuste automático de los pasos de acumulación de gradiente y una interfaz web aún no están implementados.

Mejores prácticas

Aunque el README no tiene una sección dedicada de “Mejores prácticas”, se pueden derivar los siguientes consejos:

• Ejecuta siempre canifinetune doctor primero para confirmar que tu GPU y las bibliotecas requeridas son visibles.
• Usa canifinetune recommend como punto de partida – encontrará una configuración factible sin prueba y error manual.
• Ejecuta canifinetune bench en tu máquina real, luego canifinetune calibrate para mejorar la precisión de estimaciones futuras. La diferencia entre la VRAM estática y la medida puede ser significativa (el README muestra 3.16 GB estático vs 7.10 GB real para un Qwen 1.5B QLoRA con seq_len=2048 en una RTX 4080).
• Instala PyTorch por separado con la rueda CUDA correcta – no confíes en la dependencia [train] para que elija la versión adecuada; usa la URL de índice que se muestra en la sección de instalación.
• Cuando uses uv, instala torch después de crear el venv, antes de agregar los extras de entrenamiento, para evitar conflictos de versiones.
• Consulta docs/troubleshooting.md si encuentras problemas en Windows o WSL, especialmente con bitsandbytes.

Procedimientos notables

Instalación de PyTorch con el backend CUDA correcto

El README da este patrón explícito (usando uv como ejemplo):

uv pip install torch --index-url https://download.pytorch.org/whl/cu121

Esto debe hacerse antes (o en lugar de) la resolución automática de dependencias desde [train]. El mismo principio aplica para pip.

Actualización desde una versión anterior

No se documentan pasos específicos de migración. Los comandos principales son retrocompatibles siempre que reinstales canifinetube desde PyPI. Si tienes resultados de benchmark almacenados localmente, permanecen en benchmarks/results/ y se pueden reutilizar.

Uso del resultado de la receta

El comando canifinetune recipe genera una carpeta que contiene un script de entrenamiento y un archivo de configuración. Este script está pensado para ejecutarse tal cual (con tu propio conjunto de datos y tokenizador), pero puede requerir ediciones menores para apuntar a tus datos. El README no detalla los internos del script, pero está basado en el entrenador TRL de Hugging Face.

Recopilación de líneas base para una nueva GPU

El directorio scripts/ del repositorio contiene scripts auxiliares para ejecutar benchmarks por lotes a través de muchas configuraciones. Las líneas base de la RTX 4080 en docs/rtx4080_baselines.md se produjeron con estos scripts. Puedes adaptarlos para generar tu propia tabla de referencia.