Fine-Tuning de Modelos Pequeños con LoRA: Guía DevOps para Sysadmins Linux

Por qué importa LoRA en 2026

Los modelos de lenguaje grandes (LLM) ya no son accesibles solo vía API: en 2026, modelos abiertos como Llama 3.1 8B, Qwen 2.5 7B o Gemma 2 9B corren en GPUs de consumo. Pero el full fine-tuning sigue siendo prohibitivo para quien no tenga un cluster: adaptar un modelo de 8B parámetros en fp16 requiere unos 80 GB de VRAM solo para los pesos, más activaciones, gradientes y estado del optimizador. Es la barrera que Low-Rank Adaptation (LoRA) vino a romper.

LoRA fue propuesto por Microsoft en 2021 (paper arXiv:2106.09685) y se ha convertido en el método por defecto para entrenar adaptadores sobre un modelo base congelado. En lugar de actualizar toda la matriz de pesos W, LoRA aprende una descomposición de bajo rango ΔW = A·B con A ∈ ℝ^d×r y B ∈ ℝ^r×k, donde r (el rango) es típicamente 8, 16 o 64. Esto reduce los parámetros entrenables entre 100 y 10 000 veces, manteniendo calidad comparable al full fine-tuning.

Para un sysadmin Linux esto se traduce en algo concreto: puedes tomar Llama 3.1 8B en su formato Q4_K_M de 4.7 GB y entrenarlo en tu RTX 4090 de 24 GB con cuantización de 4 bits (QLoRA), sin tocar el modelo base y produciendo un adaptador de apenas 30-80 MB que puedes versionar en Git como si fuera un config.

Por qué LoRA, no full fine-tuning

Antes de elegir una técnica, vale la pena entender qué la hace diferente. La tabla siguiente resume las opciones que tienes en 2026 desde una máquina Linux con una sola GPU:

Método	VRAM aprox. para 8B	Parámetros entrenables	Calidad vs full FT	Cuándo usarlo
Full fine-tuning	>80 GB	100 %	referencia	Cluster dedicado, datos masivos
LoRA estándar	~16-24 GB	0.1 – 1 %	≈95-99 %	Adaptación de tarea única, RTX 4090/5090
QLoRA (4-bit base)	~8-12 GB	0.1 – 1 %	≈90-97 %	GPU de 12-16 GB, edge inference
DoRA / rsLoRA	~16-24 GB	0.1 – 1 %	≥ LoRA	Cuando necesitas empuje extra sin más VRAM
Spectrum (SNR-based)	~30-50 GB	5-30 %	> QLoRA	8 GPU, máximo rendimiento

El factor decisivo para sysadmins no es la calidad máxima, sino el throughput por dólar. QLoRA (paper arXiv:2305.14314) habilita una 4090: entrenar Llama 3.1 8B con cuantización de 4 bits ocupa unos 10 GB de VRAM en su pico, dejando margen para context largos, gradient checkpointing y un batch decente.

Setup del entorno en Linux

El stack mínimo se reduce a cinco paquetes Python: transformers para cargar el modelo, peft para los adaptadores LoRA, trl para el SFTTrainer, bitsandbytes para la cuantización de 4 bits y accelerate para abstraer el device_map. Crea un venv limpio y nunca mezcles esto con tu sistema Python:

python3 -m venv ~/venvs/lora-trainer
source ~/venvs/lora-trainer/bin/activate
# Toolchain CUDA: en Ubuntu 24.04 / Debian 13 con driver 555+
pip install torch==2.4.1 --index-url https://download.pytorch.org/whl/cu124
# Stack Hugging Face (versiones fijadas a octubre 2025, compatibles entre sí)
pip install "transformers==4.46.3" 
            "datasets==3.1.0" 
            "accelerate==1.1.1" 
            "bitsandbytes==0.44.1" 
            "peft==0.13.2" 
            "trl==0.12.1"

El --index-url .../cu124 no es decorativo: por defecto pip install torch trae una build para CPU que no detecta tu GPU y torch.cuda.is_available() devuelve False. Si trabajas sobre WSL2 también necesitas asegurar que el módulo nvidia esté cargado dentro de la VM (nvidia-smi desde WSL debe listar la GPU antes de seguir).

Antes de continuar, verifica que el sistema ve el hardware correctamente. Tres líneas que confirman todo lo que necesitas:

python3 -c "import torch; print('CUDA:', torch.cuda.is_available(), torch.cuda.get_device_name(0))"
nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv
nvcc --version | grep release

Si la primera línea no dice True, no sigas: el resto del pipeline fallará en silencio cargando el modelo en CPU y tu entrenamiento tardará días en lugar de horas.

Preparar el dataset con formato conversacional

El formato {"messages": [{"role": "user", ...}, {"role": "assistant", ...}]} se ha vuelto estándar en SFTTrainer y es compatible con Llama 3.1, Mistral, Qwen y Gemma. Si tus datos viven en JSONL plano (cada línea un JSON), el siguiente snippet los normaliza al esquema del chat template del modelo en una sola pasada, manejando registros malformados sin abortar la conversión:

python3 -m pip install "transformers==4.46.3"
python3 - <<'PY'
import json
from pathlib import Path
from transformers import AutoTokenizer
tok = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B-Instruct")
out_path = Path("./dataset_chat.jsonl")
out_path.write_text("")
n_ok, n_skip = 0, 0
with open("./raw.jsonl") as f:
    for line in f:
        try:
            r = json.loads(line)
            messages = [
                {"role": "user", "content": r["instruction"]},
                {"role": "assistant", "content": r["output"]},
            ]
            text = tok.apply_chat_template(messages, tokenize=False)
            out_path.write_text(json.dumps({"text": text}, ensure_ascii=False) + "n")
            n_ok += 1
        except Exception:
            n_skip += 1
print(f"Conversiones OK: {n_ok}, saltadas: {n_skip}")
PY

El uso de apply_chat_template garantiza que el modelo vea exactamente el mismo formato que usó en su fine-tuning original. Si produces el texto a mano (concatenando <|begin_of_text|>...<|eot_id|>) cualquier token de control mal escapado degrada la calidad del adaptador sin que lo notes en la pérdida: el tokenizador reporta OK, el modelo aprende ruido.

Sobre el tamaño mínimo del dataset: la regla práctica es 1 000 ejemplos para un buen adaptador de estilo/tono y al menos 5 000 para conocimiento nuevo. Por debajo de 300 ejemplos el modelo sobreajusta y produce respuestas calcadas al dataset en lugar de generalizar.

Construir el adaptador LoRA

Aquí está el cambio de mentalidad: ya no tocas el modelo. La LoraConfig declara qué capas reciben adaptadores y con qué rango. Apuntar a las proyecciones q_proj y v_proj es la receta conservadora que sigue siendo válida; añadir k_proj, o_proj, y los MLP (gate_proj, up_proj, down_proj) mejora calidad a costa de VRAM:

python3 - <<'PY'
import torch, bitsandbytes as bnb
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
base_id = "meta-llama/Llama-3.1-8B-Instruct"
# Cuantización 4-bit (NF4) — el "Q" de QLoRA
bnb_cfg = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
)
model = AutoModelForCausalLM.from_pretrained(
    base_id,
    quantization_config=bnb_cfg,
    dtype=torch.bfloat16,
    device_map={"": 0},          # fuerza carga en GPU 0
    attn_implementation="sdpa",  # o "flash_attention_2" si compilaste FA
)
model = prepare_model_for_kbit_training(model)
lora_cfg = LoraConfig(
    r=16,
    lora_alpha=32,               # regla práctica: alpha = 2 * r
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
)
model = get_peft_model(model, lora_cfg)
model.print_trainable_parameters()
PY

El parámetro lora_alpha es el escalado de la actualización: la salida efectiva es W' = W + (alpha / r) * A·B. Con r=16, lora_alpha=32 la tasa de aprendizaje efectiva de los adaptadores duplica la magnitud que tendrían con alpha=r; es la combinación más usada en recetas de Hugging Face y la que mejor relación calidad/estabilidad da. Subir alpha sin tocar r es equivalente a subir la tasa de aprendizaje.

Después de print_trainable_parameters() deberías ver algo como trainable params: 13.6M / 8.03B (0.17%). Esa fracción de 0.17 % es exactamente lo que hace mágico al método: entrenas una porción minúscula de la red, guardas 13 MB en lugar de 16 GB y puedes tener un adaptador por cada dominio sin tocar el modelo base.

Entrenamiento real, paso a paso

El SFTTrainer de trl encapsula el ciclo de entrenamiento con todo lo que necesitas para un fine-tuning serio: packing de secuencias, gradient checkpointing, cosine schedule, logging a TensorBoard y push opcional al Hub. Esta es la receta mínima que sobrevive a datasets reales:

python3 - <<'PY'
from datasets import load_dataset
from transformers import AutoTokenizer
from trl import SFTTrainer, SFTConfig
tok = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B-Instruct")
tok.pad_token = tok.eos_token
tok.padding_side = "right"
ds = load_dataset("json", data_files="./dataset_chat.jsonl", split="train")
args = SFTConfig(
    output_dir="./lora-out",
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,         # batch efectivo = 16
    gradient_checkpointing=True,
    learning_rate=2e-4,
    lr_scheduler_type="cosine",
    warmup_ratio=0.03,
    bf16=True,
    logging_steps=10,
    save_strategy="epoch",
    packing=True,                          # concatena ejemplos cortos
    max_seq_length=2048,
    optim="paged_adamw_8bit",              # ahorra VRAM del optimizer
)
trainer = SFTTrainer(
    model=model,
    processing_class=tok,
    args=args,
    train_dataset=ds,
)
trainer.train()
PY

Detrás de bambalinas, paged_adamw_8bit mueve el estado del optimizador a memoria paginada cuando la VRAM se queda corta (usa nvidia-smi durante el primer paso para verlo: el uso fluctúa entre 12 y 18 GB). gradient_checkpointing=True recomputa activaciones a cambio de VRAM, así que tu batch efectivo se reduce; combínalo con gradient_accumulation_steps para mantener el throughput.

Si la curva de pérdida baja de 2.4 a ~1.1 en tres épocas, vas bien. Si oscila sin converger (picos hacia arriba repetidos), baja learning_rate a 5e-5 y revisa que tu dataset esté bien formateado (un escape mal hecho en JSON puede duplicar etiquetas y arruinar la señal).

Guardar y fusionar el adaptador

El adaptador entrenado es un directorio de safetensors pequeño (~30 MB). Puedes versionarlo en Git, subirlo al Hub, o fusionarlo con el modelo base para servirlo sin dependencias de PEFT. La fusión es irreversible, así que ten el adaptador a salvo antes de continuar:

python3 - <<'PY'
from peft import AutoPeftModelForCausalLM
from transformers import AutoTokenizer
# 1) Guardar adaptador + tokenizer
model.save_pretrained("./lora-out/adapter")
tok.save_pretrained("./lora-out/adapter")
# 2) Fusionar con el modelo base (para inferencia sin peft)
merged = AutoPeftModelForCausalLM.from_pretrained(
    "./lora-out/adapter",
    dtype=torch.bfloat16,
    device_map={"": 0},
)
merged = merged.merge_and_unload()
merged.save_pretrained("./lora-out/merged", safe_serialization=True)
tok.save_pretrained("./lora-out/merged")
PY

Después de fusionar, el modelo queda listo para llama.cpp, vLLM u Ollama. El directorio merged es lo que subes a tu registry privado o lo que importas vía la API GGUF. Si quieres mantener el modelo base limpio para combinar varios adaptadores (estilo multi-LoRA serving), conserva la versión sin fusionar y usa el backend de peft en inferencia.

Problemas conocidos y troubleshooting

El primer error que verás en producción es RuntimeError: element 0 of tensors does not require grad and does not have a grad_fn. La causa es que no llamaste a prepare_model_for_kbit_training y los pesos cuantizados quedaron congelados sin requires_grad=True. La solución es estructural: ese paso pone las capas en float32 donde hace falta y descongela las entradas de los adapters LoRA.

El segundo bug típico es OutOfMemoryError en el segundo o tercer paso, no en el primero. Esto casi siempre significa que gradient_checkpointing está desactivado o que max_seq_length excede lo planificado. Baja la secuencia a 1024 si tu VRAM es ajustada, o sube gradient_accumulation_steps para compensar el batch más chico.

El tercer síntoma es el peor: la pérdida baja, el modelo responde coherentemente, pero produce pequeñas regresiones en comportamiento general (pierde un poco de capacidad de seguir instrucciones en inglés cuando fue entrenado en español). Esto es el catastrophic forgetting. Dos mitigaciones prácticas sin reentrenar el modelo base:

• Usa neftune_noise_alpha=5 en SFTConfig para añadir ruido a los embeddings durante el entrenamiento: la técnica NEFTune reduce olvido catastrófico sin coste de cómputo.
• Limita el learning rate (5e-5 en lugar de 2e-4) y entrena menos épocas (2 en lugar de 4). El sobreajuste es la causa del olvido, no la falta de datos.

Si quieres ir más allá, la librería peft en su versión 0.14+ incluye intruder dimension mitigation (do_intruder_dim_mitigation=True), basado en el paper arXiv:2410.21228, que detecta dimensiones del adaptador que se solapan con conocimiento previo y las reescala. Es trabajo post-entrenamiento y no toca el modelo base.

Cuándo NO vale la pena LoRA

LoRA no es bala de plata. Tres escenarios donde te conviene otra cosa:

• Tu modelo no encaja en GPU ni cuantizado a 4 bits. Llama 70B en Q4 ocupa 40 GB; incluso con offloading a CPU el ciclo de entrenamiento se vuelve inviable en hardware de consumo. Si necesitas ese tamaño, mejor evalúa in-context learning o prefix tuning sobre un modelo cuantizado en CPU.
• Tienes menos de 200 ejemplos de calidad. El adaptador aprenderá a repetir el dataset, no a generalizar. Mejor invierte el tiempo en curar datos o usa técnicas de prompting avanzado hasta tener material suficiente.
• El cambio de comportamiento es estructural. Si quieres que el modelo razone de forma muy distinta o que cambie de arquitectura mental, LoRA no lo logrará: solo modifica la superficie, no el fondo. Para esos casos, RLHF/DPO sobre el modelo base sigue siendo el camino correcto.

Resumen

LoRA en 2026 se ha vuelto la opción por defecto para adaptar LLMs abiertos desde una workstation Linux. Con una RTX 4090 y unos 16 GB de VRAM libres puedes entrenar un adaptador específico de dominio en pocas horas y fusionarlo con el modelo base para servirlo vía vLLM u Ollama. El flujo completo se reduce a: instalar el stack Hugging Face, preparar datos con apply_chat_template, declarar LoraConfig, entrenar con SFTTrainer y guardar. La parte interesante es iterar: cada adaptador es de 30 MB, así que versionar y comparar versiones no cuesta nada.

Preguntas frecuentes

Lee también

• Desafíos y Requisitos de Ejecutar AI en el Borde para Sysadmins Linux
• Contribuciones a Debian: Trabajos patrocinados por Freexian y opciones de apoyo
• Sysadmins Linux: por qué un chatbot no es la herramienta correcta para middleware en tiempo real
• Ataque de Malspam en Agosto: Cómo los Sysadmins Linux Pueden Proteger su Correo
• OCI mínimas y seguras para ISVs: rocks de Canonical