Fine-tuning de LLMs: lo que el Capítulo 3 adelantó, ahora en serio

1. Chat templates, en serio

Ya los mencionamos en los Capítulos 2 y 6 como la pieza que reemplaza a token_type_ids para modelos de chat. Acá se formaliza: un modelo base (recién preentrenado) solo sabe completar texto; un modelo instruct fue afinado para seguir el formato de conversación de su chat template específico — y ese formato varía por familia de modelo (Llama, Mistral, Gemma, cada uno con sus propios tokens de rol y delimitadores).

El template no es cosmético: define dónde empieza y termina cada turno, qué texto es del sistema y cuál del usuario, y en los modelos más nuevos, cómo se representan llamadas a herramientas o inputs multimodales. Usar el template equivocado para un modelo — o concatenar strings a mano en vez de usar el que trae el tokenizer — es una de las formas más comunes de que un modelo instruct responda peor de lo que debería, sin ningún error visible.

Lo mejor que podés hacer para dejar de tratarlo como magia es mirar el string. El tokenizer guarda el template (una plantilla Jinja) y lo aplica sobre una lista de mensajes con role/content:

from transformers import AutoTokenizer

tok = AutoTokenizer.from_pretrained("google/gemma-4-E2B-it")
mensajes = [
    {"role": "system", "content": "Respondés en español, en una frase."},
    {"role": "user", "content": "¿Qué es un adapter LoRA?"},
]
print(tok.apply_chat_template(mensajes, tokenize=False, add_generation_prompt=True))

Tres cosas que se ven ahí y que importan para entrenar. Primero, los delimitadores (<|turn> y <turn|> en Gemma 4, que además escribe el rol model donde vos pusiste assistant y antepone <bos>; SmolLM2 y Qwen usan el formato "ChatML", <|im_start|> / <|im_end|>; Llama 3, <|start_header_id|>; Gemma 3, <start_of_turn>) son tokens especiales, uno solo cada uno en el vocabulario. El tokenizer los reconoce aunque los escribas vos como texto — el riesgo de concatenar a mano no es ese, sino reproducir el formato exacto: los saltos de línea, el orden, el mensaje de sistema por defecto que algunos templates insertan solos. Un espacio de diferencia y el modelo ve una secuencia que nunca vio en entrenamiento. Segundo, add_generation_prompt=True agrega el encabezado del turno del asistente vacío — es lo que se usa en inferencia para que el modelo empiece a responder; en entrenamiento no se usa, porque el turno del asistente ya viene completo en el dataset. Tercero, el turno del asistente en un ejemplo de entrenamiento tiene que terminar con el token de fin de turno (<|im_end|>): es lo que le enseña al modelo a parar. Un modelo que después de fine-tuning "no se calla" casi siempre fue entrenado con ejemplos sin ese token.

2. Fine-tuning supervisado con SFTTrainer

SFT es el sucesor natural del fine-tuning de tarea única del Capítulo 3: en vez de entrenar para una sola tarea (clasificar, traducir), entrenás sobre ejemplos de conversación completa — pares instrucción/respuesta — para que el modelo aprenda a seguir instrucciones en general. Es, literalmente, el paso que convierte un modelo base en algo parecido a ChatGPT o Claude.

Tiene sentido cuando necesitás controlar el formato exacto de salida, o adaptar el modelo a un dominio específico que un modelo instruct genérico no cubre bien — los mismos dos motivos del Capítulo 7, aplicados a instrucciones en vez de a una tarea puntual.

El formato del dataset

SFTTrainer (de la librería trl) espera uno de dos formatos. El conversacional es el que vas a usar casi siempre: una columna messages con la lista de turnos, cada uno un diccionario {"role": ..., "content": ...} — el mismo formato que le pasaste a apply_chat_template arriba. El otro es el estándar: columnas prompt y completion de texto plano (o una sola columna text ya formateada). Con el conversacional, el trainer aplica el chat template del tokenizer por vos — no tenés que formatear nada a mano, y esa es justamente la gracia: el formato que ve el modelo en entrenamiento es idéntico al de inferencia porque lo produce la misma función.

{"messages": [
    {"role": "system",    "content": "Sos un asistente que explica finanzas en español rioplatense."},
    {"role": "user",      "content": "¿Qué es el EBITDA?"},
    {"role": "assistant", "content": "Es la ganancia operativa antes de intereses, impuestos, depreciación y amortización..."}
]}

Y el entrenamiento, con la configuración mínima:

from trl import SFTTrainer, SFTConfig

trainer = SFTTrainer(
    model="HuggingFaceTB/SmolLM2-1.7B",
    train_dataset=dataset,  # columna "messages" — el trainer aplica el chat template
    args=SFTConfig(
        max_length=2048,        # largo máximo en tokens; lo que sobra se trunca
        packing=True,
        learning_rate=2e-5,     # fine-tuning completo; con LoRA, ~10× más (§3)
        num_train_epochs=1,
        output_dir="sft-smollm2",
    ),
)
trainer.train()

packing=True concatena varios ejemplos cortos en una sola secuencia de longitud máxima — evita desperdiciar cómputo en padding cuando tus ejemplos son mucho más cortos que el límite del modelo. Todo lo del Capítulo 3 sobre leer curvas de aprendizaje aplica igual acá: loss que baja y se estabiliza es sano, un gap creciente entre train y validación es overfitting, sin importar que ahora el objetivo sea "seguir instrucciones" en vez de "clasificar una reseña".

¿Loss sobre toda la conversación o solo sobre el asistente?

Por defecto el modelo se entrena a predecir todos los tokens de la secuencia — incluido el prompt del sistema y lo que escribió el usuario. Eso tiene un costo: parte del gradiente se gasta en aprender a "escribir preguntas de usuario", que no es lo que querés, y si tus prompts son largos y tus respuestas cortas, la mayoría de la loss ni siquiera mide lo que te importa. La alternativa es enmascarar los tokens del prompt (ponerles etiqueta -100, que la loss ignora) y computar la loss solo sobre los turnos del asistente. En versiones recientes de TRL eso se pide con assistant_only_loss=True en SFTConfig, y requiere que el chat template del modelo marque dónde empiezan y terminan los turnos del asistente (los templates más nuevos lo traen; con uno que no, el trainer te lo va a decir). Para el formato prompt/completion, el equivalente es entrenar solo sobre la completion, que es el comportamiento por defecto para ese formato. Como regla: con respuestas largas y prompts cortos la diferencia es chica; con prompts largos (RAG, documentos pegados en el contexto) es grande y conviene enmascarar.

3. LoRA, con código real

El Capítulo 3 introdujo la idea; acá está la implementación real, vía peft integrado directo en SFTTrainer:

from peft import LoraConfig

peft_config = LoraConfig(
    r=16, lora_alpha=32, lora_dropout=0.05,
    target_modules=["q_proj", "v_proj"],   # o "all-linear" para cubrir todas las proyecciones
    task_type="CAUSAL_LM",
)
trainer = SFTTrainer(
    model=model, train_dataset=dataset, peft_config=peft_config,
    args=SFTConfig(learning_rate=2e-4, max_length=2048, output_dir="sft-lora"),
)
trainer.train()
trainer.save_model("sft-lora/adapter")   # guarda solo el adapter, unos pocos MB

Tres decisiones que la config deja en tus manos. r y lora_alpha: r es el rango de las matrices A/B (más rango, más capacidad y más parámetros), y la corrección se escala por lora_alpha / r — la convención de alpha = 2r del ejemplo es un punto de partida razonable, no una ley. target_modules: el ejemplo del curso toca solo las proyecciones de query y value de la atención; aplicar LoRA a todas las capas lineales (atención y MLP) suele rendir mejor a cambio de un adapter más grande — hoy es lo habitual. learning_rate: con LoRA se usa uno del orden de 1e-4 a 2e-4, unas diez veces más alto que en fine-tuning completo, porque las matrices del adapter arrancan en cero (B) y necesitan moverse rápido; usar el 2e-5 de un fine-tuning completo es la causa más común de un LoRA que "no aprendió nada". Y task_type="CAUSAL_LM" no es decorativo: le dice a peft qué tipo de modelo está envolviendo, y sin él el forward puede no propagar bien los argumentos (labels, cache) al modelo base.

El resultado de entrenar así no son pesos nuevos del modelo completo — es un adapter, un puñado de archivos chicos con las matrices A/B entrenadas. Podés servirlo separado (cargando el adapter sobre el modelo base en runtime) o fusionarlo — sumar A·B directamente a los pesos originales — para quedarte con un único checkpoint normal, sin dependencias extra de peft en producción.

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

base = AutoModelForCausalLM.from_pretrained("HuggingFaceTB/SmolLM2-1.7B")
model = PeftModel.from_pretrained(base, "sft-lora/adapter")   # base + adapter, separados
model = model.merge_and_unload()                              # W ← W + (alpha/r)·B·A ; devuelve el modelo "plano"
model.save_pretrained("sft-fusionado")
AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM2-1.7B").save_pretrained("sft-fusionado")  # ¡con el chat template!

Fusionar es reversible solo si guardaste el adapter aparte — el modelo fusionado ya no distingue qué parte de cada peso vino de dónde. Lo cargás después con AutoModelForCausalLM.from_pretrained("sft-fusionado") como cualquier otro checkpoint, y lo servís con vLLM sin flags especiales.

4. Evaluación: benchmarks y sus límites

Un LLM instruction-tuned se evalúa contra baterías de benchmarks estandarizados — útiles para comparar modelos entre sí, con la salvedad de que un buen score no garantiza que sirva para tu caso de uso específico. Cada uno mide algo distinto y cada uno tiene una forma conocida de mentir:

La herramienta del curso para correr esto es lighteval, de Hugging Face. Una tarea se nombra con cuatro partes separadas por |: la suite, la tarea, la cantidad de ejemplos few-shot, y si se permite truncar esos ejemplos cuando no entran en el contexto. Un comando típico, evaluando un modelo local con accelerate:

pip install lighteval

lighteval accelerate \
    "model_name=./sft-fusionado" \
    "lighteval|gsm8k|0|0" \
    --output-dir resultados

El resultado es un JSON por corrida con la métrica de cada tarea (para GSM8K, la exactitud de la respuesta final) más los detalles por ejemplo si los pedís — que son los que te interesan: leer veinte fallos concretos enseña más que el número agregado. En versiones anteriores de lighteval el argumento del modelo se escribía pretrained=... y las tareas del leaderboard iban con el prefijo leaderboard|; si un comando copiado de un tutorial falla, es casi seguro eso. La misma herramienta permite definir tareas propias — un archivo de Python con tu dataset y tu métrica — que es la forma de meter tu set de evaluación custom en el mismo pipeline que los benchmarks públicos.

Cuando el benchmark genérico no alcanza, dos alternativas: LLM-as-judge (otro LLM evalúa la respuesta contra un criterio) o arenas (comparación humana entre respuestas de distintos modelos) — y para lo más específico, un set de evaluación propio, hecho a medida. Las dos primeras tienen sus propias trampas: un juez LLM prefiere respuestas largas y con formato, y tiende a preferir las de su propia familia; una arena mide qué respuesta gusta, no cuál es correcta.

5. Errores comunes

Casi ninguno tira una excepción. El síntoma es un modelo que entrena "bien" según la loss y responde mal.

6. Resumen

1. Un chat template no es cosmético — define el contrato de formato entre vos y el modelo, distinto por familia. Mirá el string con apply_chat_template(tokenize=False); los delimitadores son tokens especiales y el turno del asistente tiene que cerrar con el token de fin.
2. SFT es fine-tuning para seguir instrucciones en general, no para una sola tarea — el paso que convierte un modelo base en algo usable como asistente. SFTTrainer toma una columna messages, aplica el template solo, y con assistant_only_loss entrena solo sobre lo que dijo el asistente. El largo se fija con max_length (antes max_seq_length).
3. LoRA con peft + SFTTrainer entrena un adapter chico — con learning rate de 1e-4–2e-4, no el de fine-tuning completo — que podés servir separado o fusionar con merge_and_unload(); fusionar solo funciona sobre pesos en punto flotante, no sobre pesos ya cuantizados.
4. Después de SFT viene la alineación por preferencias (DPO sobre pares chosen/rejected) o RL con reward functions (GRPO, Capítulo 12).
5. Los benchmarks estandarizados sirven para comparar modelos entre sí, cada uno mide una cosa y cada uno tiene una trampa (casi siempre contaminación); lighteval los corre con un comando. LLM-as-judge y evaluación custom son lo que realmente te dice si el modelo sirve para tu caso — y ya construiste ambos.

7. Ponete a prueba

Respondé antes de abrir cada respuesta. Si fallás una, volvé a la sección indicada.

8. Para practicar

from transformers import AutoTokenizer

tok = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM2-135M-Instruct")
msgs = [{"role": "user", "content": "Hola"},
        {"role": "assistant", "content": "Hola, ¿en qué te ayudo?"}]

entrenamiento = tok.apply_chat_template(msgs, tokenize=False)
inferencia    = tok.apply_chat_template(msgs[:1], tokenize=False, add_generation_prompt=True)
print(repr(entrenamiento)); print(repr(inferencia))

ids = tok(entrenamiento, add_special_tokens=False)["input_ids"]
print([tok.decode([i]) for i in ids][:12])          # ¿"<|im_start|>" es UN token?
print(len(tok("<|im_start|>", add_special_tokens=False)["input_ids"]))    # 1: lo reconoce dentro del texto
print(len(tok("<|im_start|", add_special_tokens=False)["input_ids"]))     # un carácter menos: ya no es especial

from datasets import Dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig

pares = [("¿Capital de Francia?", "Dato: París."), ("¿Cuánto es 2+2?", "Dato: 4."),
         ("¿Color del cielo?", "Dato: azul."), ("¿Autor del Quijote?", "Dato: Cervantes."),
         ("¿Planeta más grande?", "Dato: Júpiter."), ("¿Idioma de Brasil?", "Dato: portugués."),
         ("¿Símbolo del oro?", "Dato: Au."), ("¿Año de la Revolución de Mayo?", "Dato: 1810."),
         ("¿Océano más grande?", "Dato: Pacífico."), ("¿Moneda de Japón?", "Dato: yen.")]
ds = Dataset.from_list([{"messages": [{"role": "user", "content": q}, {"role": "assistant", "content": a}]}
                        for q, a in pares])

trainer = SFTTrainer(
    model="HuggingFaceTB/SmolLM2-135M-Instruct",
    train_dataset=ds,
    peft_config=LoraConfig(r=8, lora_alpha=16, target_modules="all-linear", task_type="CAUSAL_LM"),
    args=SFTConfig(output_dir="mini-sft", max_length=128, learning_rate=2e-4,
                   max_steps=30, per_device_train_batch_size=2, logging_steps=5,
                   use_cpu=True, report_to="none"),
)
trainer.train()
trainer.save_model("mini-sft/adapter")

tok = trainer.processing_class
prompt = tok.apply_chat_template([{"role": "user", "content": "¿Capital de Italia?"}],
                                 tokenize=False, add_generation_prompt=True)
out = trainer.model.generate(**tok(prompt, return_tensors="pt"), max_new_tokens=12, do_sample=False)
print(tok.decode(out[0], skip_special_tokens=True))

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

tok  = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM2-135M-Instruct")
base = AutoModelForCausalLM.from_pretrained("HuggingFaceTB/SmolLM2-135M-Instruct")
con_adapter = PeftModel.from_pretrained(base, "mini-sft/adapter")
x = tok("¿Capital de Italia?", return_tensors="pt")
with torch.no_grad():
    logits_adapter = con_adapter(**x).logits.clone()

fusionado = con_adapter.merge_and_unload()
fusionado.save_pretrained("mini-sft/fusionado"); tok.save_pretrained("mini-sft/fusionado")

plano = AutoModelForCausalLM.from_pretrained("mini-sft/fusionado")   # sin peft
with torch.no_grad():
    logits_plano = plano(**x).logits
print("diferencia máxima:", (logits_adapter - logits_plano).abs().max().item())
print("parámetros:", sum(p.numel() for p in plano.parameters()))

9. Fuentes y para seguir

• LLM Course, Chapter 11 — Fine-tuning large language models — el capítulo original: chat templates, SFT, LoRA y evaluación con lighteval, con el ejemplo de SmolLM2.
• Transformers — Chat templates — cómo se escriben y aplican los templates, add_generation_prompt, y cómo fijar uno en un modelo base.
• TRL — SFTTrainer — los formatos de dataset aceptados, max_length, packing, assistant_only_loss y la integración con peft; es la referencia contra la que verificar cualquier nombre de parámetro.
• LoRA: Low-Rank Adaptation of Large Language Models (arXiv 2106.09685) — el paper original: por qué una corrección de rango bajo alcanza, y de dónde sale el escalado por alpha/r.
• Direct Preference Optimization (arXiv 2305.18290) — el paso siguiente a SFT del callout de §3: optimizar preferencias sin reward model.
• lighteval — el evaluador de §4: cómo se nombran las tareas, qué backends soporta y cómo definir una tarea propia.