LlamaFactory: ajuste fino unificado de más de 100 modelos de lenguaje y visión

Introducción: la fragmentación del ajuste fino

El ecosistema de modelos de lenguaje grandes (LLM) ha evolucionado a un ritmo vertiginoso. Cada semana aparecen nuevos modelos con arquitecturas, tokenizadores y configuraciones de entrenamiento distintas. Para los equipos de inteligencia artificial aplicada, esto representa una oportunidad enorme, pero también un dolor de cabeza operativo: cada modelo exige scripts de ajuste fino específicos, dependencias particulares y formatos de datos propios. La consecuencia es clara: se dedica más tiempo a la fontanería que a la experimentación real.

LlamaFactory nace precisamente para resolver ese problema. Se trata de un framework unificado que permite ajustar más de 100 modelos de lenguaje y visión con una sola interfaz, ya sea mediante línea de comandos (CLI) o a través de una interfaz web (LLaMA Board). Su popularidad es indiscutible: casi 75 000 estrellas en GitHub y una adopción por parte de gigantes como Amazon, NVIDIA y Aliyun. En este artículo analizamos en profundidad qué ofrece, cómo funciona y por qué deberías considerarlo en tu flujo de trabajo.

Qué problema resuelve LlamaFactory

Antes de LlamaFactory, ajustar un modelo como Llama 3, Qwen o Mistral implicaba escribir código específico para cada familia. Si querías probar LoRA en lugar de ajuste completo, tenías que reescribir el script. Si además querías cambiar de QLoRA a DPO, el trabajo se multiplicaba. Esta fragmentación ralentiza la iteración y aumenta la probabilidad de errores.

LlamaFactory aborda este problema con una capa de abstracción que unifica:

• Más de 100 modelos: Llama, Qwen, Mistral, Gemma, DeepSeek, GPT, MoE, entre otros.
• Múltiples métodos de ajuste: ajuste completo, LoRA, QLoRA, RLHF, DPO, ORPO, SimPO, etc.
• Diversidad de datos: soporte para instrucciones, conversaciones, preferencias y datasets multimodales.
• Infraestructura variada: desde una GPU de consumo hasta clústeres con múltiples nodos, pasando por NPU y ROCm.

La promesa es simple: escribe una configuración una vez y ejecútala en cualquier modelo compatible. Esto reduce drásticamente el tiempo de puesta en marcha y permite a los equipos centrarse en lo que realmente importa: los datos y la evaluación.

Arquitectura de LlamaFactory

LlamaFactory está diseñado con un enfoque modular que separa la lógica de negocio de los detalles de implementación. A grandes rasgos, su arquitectura se compone de varias capas:

+---------------------+
|   Interfaz de usuario |
|  (CLI / Web UI)      |
+----------+----------+
           |
+----------v----------+
|   Capa de configuración |
|  (YAML, argumentos)    |
+----------+----------+
           |
+----------v----------+
|   Núcleo de LlamaFactory |
|  - Carga de modelos      |
|  - Tokenización          |
|  - Formateo de datos     |
|  - Entrenador unificado  |
+----------+----------+
           |
+----------v----------+
|   Backends de entrenamiento |
|  (Transformers, PEFT, TRL, |
|   DeepSpeed, FSDP, vLLM)   |
+----------+----------+
           |
+----------v----------+
|   Hardware (GPU, NPU, ROCm) |
+---------------------+

Esta separación permite que el mismo comando funcione con distintos backends sin cambiar la lógica del usuario. Además, la capa de configuración acepta tanto archivos YAML como argumentos de línea de comandos, lo que facilita la reproducibilidad y la integración en pipelines de MLOps.

Componentes clave

• Model Loader: se encarga de descargar y cargar el modelo base, aplicando cuantización si es necesario.
• Data Processor: convierte datasets en el formato esperado por cada modelo, gestionando plantillas de prompt y máscaras de atención.
• Trainer: orquesta el entrenamiento, ya sea ajuste completo, PEFT o RLHF, con soporte para aceleración distribuida.
• Inference Engine: permite desplegar el modelo ajustado con una API compatible con OpenAI, usando vLLM para alto rendimiento.

Cómo empezar con LlamaFactory

La instalación es sencilla y se puede realizar tanto desde PyPI como desde el repositorio. Recomendamos usar un entorno virtual para evitar conflictos de dependencias.

pip install llamafactory

Para aprovechar todas las funcionalidades, especialmente el entrenamiento distribuido, es aconsejable instalar los extras:

pip install "llamafactory[torch,metrics]"

Una vez instalado, puedes verificar la versión y los comandos disponibles:

llamafactory-cli version
llamafactory-cli help

Preparación de datos

LlamaFactory espera un formato JSON Lines (JSONL) con campos como instruction, input y output para tareas de instrucción. También admite conversaciones multi-turno con el campo conversations. Un ejemplo mínimo:

{"instruction": "¿Cuál es la capital de Francia?", "input": "", "output": "París"}
{"instruction": "Traduce al inglés", "input": "Hola mundo", "output": "Hello world"}

Para datasets de preferencias, se utilizan campos como chosen y rejected. LlamaFactory incluye utilidades para convertir y validar datos, lo que simplifica la integración con fuentes externas.

Ajuste fino con CLI

El comando principal es llamafactory-cli train, que acepta un archivo YAML con toda la configuración. Por ejemplo, para ajustar un modelo Qwen2.5 con LoRA:

### config/lora_qwen.yaml
model_name_or_path: Qwen/Qwen2.5-7B-Instruct
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
dataset: alpaca_es
template: qwen
dataset_dir: data
output_dir: outputs/qwen2.5-lora
per_device_train_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 1e-4
num_train_epochs: 3
logging_steps: 10
save_steps: 100

Y se ejecuta con:

llamafactory-cli train config/lora_qwen.yaml

Para ajuste completo, basta con cambiar finetuning_type a full y ajustar los hiperparámetros. La misma configuración sirve para otros modelos cambiando model_name_or_path y template.

Interfaz web: LLaMA Board

Si prefieres una experiencia visual, LlamaFactory ofrece LLaMA Board, una interfaz basada en Gradio que permite configurar y lanzar entrenamientos sin escribir código. Se inicia con:

llamafactory-cli webui

Esto abre una interfaz en el navegador donde puedes seleccionar el modelo, el dataset, los hiperparámetros y monitorizar el progreso en tiempo real. Es ideal para experimentación rápida y para equipos con perfiles menos técnicos.

Despliegue con API compatible con OpenAI

Una vez ajustado el modelo, puedes servirlo con vLLM para obtener inferencia de alto rendimiento:

llamafactory-cli api --model_name_or_path outputs/qwen2.5-lora --template qwen --infer_backend vllm

Esto levanta un servidor que expone endpoints compatibles con la API de OpenAI, facilitando la integración con aplicaciones existentes.

Casos de uso prácticos

LlamaFactory brilla en escenarios donde la experimentación rápida y la variedad de modelos son clave. Algunos casos concretos:

• Atención al cliente: ajustar un modelo pequeño (7B) con datos de conversaciones para respuestas automáticas, reduciendo costes frente a modelos propietarios.
• Generación de código: especializar un modelo en un lenguaje de programación concreto usando datasets de repositorios.
• Análisis de documentos: combinar modelos de visión y lenguaje para extraer información de facturas o informes, como hace Apoidea Group con Amazon SageMaker.
• Investigación en RLHF: probar algoritmos como DPO o ORPO con distintos modelos base sin reescribir el pipeline.
• Prototipado rápido: evaluar múltiples modelos y métodos en cuestión de horas gracias a la configuración unificada.

Un ejemplo real: un equipo de soporte técnico necesita un asistente que responda en español con terminología específica. Con LlamaFactory, pueden tomar un modelo Qwen2.5, aplicar LoRA con un dataset de tickets históricos y desplegarlo con vLLM en menos de un día.

Comparativa con alternativas

Existen otras herramientas de ajuste fino, como Axolotl, Unsloth o Torchtune. Cada una tiene sus fortalezas. La siguiente tabla resume las diferencias clave:

LlamaFactory destaca por su amplitud de modelos, la interfaz web y la integración de despliegue. Axolotl es más flexible para configuraciones avanzadas, mientras que Unsloth optimiza la velocidad en un subconjunto de modelos. Torchtune es una opción más cercana a PyTorch puro, pero requiere más conocimiento técnico.

Preguntas frecuentes (FAQ)

¿Qué requisitos de hardware necesito para usar LlamaFactory?

Depende del modelo y del método. Para un modelo de 7B con QLoRA, una GPU con 8 GB de VRAM es suficiente. Para ajuste completo de un 7B, se recomiendan al menos 24 GB. LlamaFactory soporta múltiples GPUs, DeepSpeed y FSDP para escalar.

¿Puedo usar LlamaFactory con modelos que no estén en la lista oficial?

Sí, siempre que el modelo sea compatible con Hugging Face Transformers. Puedes especificar la ruta local o el identificador del Hub. La lista oficial se actualiza constantemente, pero la arquitectura subyacente permite adaptar otros modelos.

¿Cómo maneja LlamaFactory los datasets en español?

El formato es independiente del idioma. Puedes usar cualquier dataset en español siguiendo la estructura JSONL. Además, LlamaFactory incluye plantillas de prompt que puedes personalizar para adaptar el formato a tus necesidades.

¿Es compatible con entornos sin GPU, como CPU o NPU?

Sí. LlamaFactory soporta entrenamiento en CPU (aunque lento) y en NPU de Ascend, así como en GPUs AMD con ROCm. La documentación oficial proporciona guías específicas para cada backend.

¿Qué diferencia hay entre LoRA y QLoRA en LlamaFactory?

LoRA añade adaptadores de bajo rango al modelo base, reduciendo el número de parámetros entrenables. QLoRA además cuantiza el modelo base a 4 bits, lo que disminuye aún más el uso de memoria. En LlamaFactory, se seleccionan con finetuning_type: lora o qlora respectivamente.

Conclusión

LlamaFactory se ha consolidado como una herramienta esencial para cualquier equipo que trabaje con LLM. Su enfoque unificado elimina la fricción del ajuste fino y permite iterar rápidamente sobre una amplia gama de modelos y métodos. Ya sea que prefieras la línea de comandos o una interfaz web, LlamaFactory ofrece un camino accesible y potente hacia la personalización de modelos. Si aún no lo has probado, este es el momento de incorporarlo a tu caja de herramientas.