← Atlas

Lección 5 — LoRA, QLoRA y adaptación agéntica: especializar sin confundir entrenamiento con evidencia

Descargar MP3 · Transcripción

# Lección 5 — LoRA, QLoRA y adaptación agéntica: especializar sin confundir entrenamiento con evidencia

**Duración objetivo:** 12 minutos  
**Nivel:** intermedio  
**Estado:** guion documental; no implica entrenamiento ni compatibilidad validada con Ornith

## Objetivos de aprendizaje

Al terminar esta lección podrás:

1. distinguir fine-tuning completo, LoRA y QLoRA;
2. explicar qué significa adaptar un modelo para tareas agénticas;
3. convertir una idea de entrenamiento en un experimento auditable;
4. revisar un manifiesto YAML que fija checkpoint, plantilla, datos, semilla, módulos objetivo y evaluación;
5. separar soporte de una familia arquitectónica, ejecución de un run y mejora demostrada.

## 1. El problema correcto: cambiar conducta, no sólo bajar la pérdida

Adaptar un modelo agéntico no consiste simplemente en enseñarle más respuestas. Buscamos una conducta observable: decidir si hace falta una herramienta, elegirla, producir argumentos válidos, esperar su resultado, recuperarse de un error y detenerse sin inventar éxito. Un conjunto de entrenamiento puede reforzar estas conductas, pero la pérdida de entrenamiento no certifica ninguna de ellas.

Antes de tocar pesos conviene formular el contrato. ¿Queremos mejorar llamadas simples, conversaciones multivuelta, abstención, aclaración de parámetros o recuperación ante errores? ¿Qué capacidades no deben retroceder: conversación general, código, español, seguridad o uso de herramientas ya conocido? Sin una línea base y un holdout separado, “adaptación agéntica” es una etiqueta, no un resultado.

También hay que distinguir datos de demostración y evaluación. Una trayectoria de entrenamiento puede contener mensajes de usuario, catálogo de herramientas, llamada estructurada, resultado simulado y respuesta final. El benchmark debe usar escenarios, plantillas o familias de API que no hayan cruzado al entrenamiento. Si una paráfrasis del mismo caso aparece a ambos lados, el modelo puede memorizar el patrón sin aprender a generalizar.

## 2. Tres rutas de ajuste

### Fine-tuning completo

Actualiza la mayor parte o la totalidad de los pesos. Ofrece máxima libertad, pero demanda más memoria, almacenamiento y disciplina operativa. Cada checkpoint especializado es grande y el riesgo de regresión también puede ser mayor. Es una referencia conceptual, no la primera opción automática.

### LoRA

LoRA mantiene congelado el modelo base e introduce matrices entrenables de bajo rango en componentes seleccionados. En lugar de aprender de nuevo una matriz completa, aprende una actualización compacta. El resultado suele ser un adaptador pequeño que puede conservarse separado, intercambiarse o fusionarse después.

La palabra clave es **seleccionados**. Los nombres de módulos dependen de la arquitectura. Copiar `q_proj` y `v_proj` desde una receta para Llama no demuestra que cubramos una arquitectura híbrida. La documentación de Axolotl para Qwen3.5 indica que esa familia intercala atención Transformer y Gated DeltaNet, y propone módulos específicos de atención lineal además de las proyecciones estándar. Eso documenta soporte para Qwen3.5 en Axolotl; no valida automáticamente un checkpoint Ornith, su revisión, su torre visual, MTP, plantilla ni exportación final.

### QLoRA

QLoRA conserva congelada una base cargada en baja precisión —típicamente cuatro bits— y entrena adaptadores LoRA. Su objetivo práctico es reducir la memoria del entrenamiento. No significa que el adaptador “sea de cuatro bits”, ni que el artefacto resultante sea ya un GGUF de serving. Entrenamiento, fusión y cuantización de despliegue son etapas distintas.

QLoRA tampoco es “LoRA gratis”. La memoria ahorrada puede habilitar un experimento, pero aparecen dependencias del cargador, tipo de cuantización, kernels, dtype de cómputo y arquitectura. Una receta que corre en Llama 2 o Qwen2.5 aporta aprendizaje procedural; no prueba calidad ni compatibilidad en Ornith.

## 3. Mapa del flujo experimental

```text
┌────────────────────┐      ┌────────────────────────┐
│ Checkpoint fijado  │      │ Datos con procedencia  │
│ revisión + hash    │      │ licencia + splits      │
└─────────┬──────────┘      └───────────┬────────────┘
          │                             │
          └──────────────┬──────────────┘
                         ▼
              ┌─────────────────────┐
              │ Plantilla + tokenizer│
              │ mensajes + tools     │
              └──────────┬──────────┘
                         ▼
        ┌─────────────────────────────────┐
        │ Brazo A: LoRA │ Brazo B: QLoRA │
        │ mismos datos, seed y targets    │
        └────────────────┬────────────────┘
                         ▼
              ┌──────────────────────┐
              │ Adaptadores + logs   │
              │ sin tocar el baseline│
              └──────────┬───────────┘
                         ▼
       ┌───────────────────────────────────┐
       │ Holdout: tools, abstención, error │
       │ más regresión general y seguridad │
       └────────────────┬──────────────────┘
                         ▼
             PROMOVER / ITERAR / DESCARTAR
```

Este diagrama incluye dos ideas esenciales. Primero, la comparación sólo es interpretable si cambia una variable principal. Segundo, el checkpoint base queda inmutable: los adaptadores y artefactos experimentales viven aparte y tienen rollback sencillo.

## 4. ¿Qué debe aprender un agente?

Un dataset agéntico útil no premia siempre “hacer una llamada”. Debe equilibrar al menos cinco clases:

- **llamada válida:** herramienta correcta y argumentos que cumplen el esquema;
- **abstención:** ninguna herramienta disponible resuelve la petición;
- **aclaración:** falta un dato obligatorio que no puede inferirse con seguridad;
- **rechazo:** la operación existe, pero viola política, autorización o alcance;
- **recuperación:** la herramienta devuelve timeout, límite de tasa, conflicto o salida malformada y el agente responde según un contrato.

Conviene entrenar trazas observables, no razonamiento privado. Los registros pueden guardar la llamada, el resultado, un código de decisión y el estado final. No hace falta incluir cadenas de pensamiento. Para operaciones con efectos laterales, los ejemplos deben representar idempotencia, límites de reintento y prohibición de duplicar una acción.

La procedencia es parte del dato. Cada lote debe registrar origen, licencia, transformaciones, generador si fue sintético y revisión. “Está en internet” no concede permiso de entrenamiento. Además, hay que eliminar secretos, PII y respuestas de herramientas que revelen más información de la necesaria.

## 5. Práctica: auditar un YAML sin ejecutarlo

El siguiente archivo es un **manifiesto didáctico de auditoría**, no una configuración confirmada de Axolotl ni una orden de entrenamiento. No lo ejecutes. Los campos `PENDIENTE_*` obligan a detenerse hasta validar la evidencia correspondiente.

```yaml
experimento:
  id: l5-agentic-lora-qlora-ab
  estado: diseño_no_ejecutar
  objetivo: mejorar tool_call, abstencion, aclaracion y recovery

modelo:
  repositorio: ornith-ai/Ornith-1.5-9B
  revision: PENDIENTE_SHA_INMUTABLE
  arquitectura_inspeccionada: false
  chat_template:
    origen: PENDIENTE_MODELCARD_O_TOKENIZER
    hash: PENDIENTE_HASH
  compatibilidad_ornith:
    axolotl: no_validada
    lora: no_validada
    qlora: no_validada

brazos:
  - nombre: control_base
    entrenamiento: ninguno
  - nombre: lora_bf16
    adapter: lora
    load_in_4bit: false
  - nombre: qlora_4bit
    adapter: qlora
    load_in_4bit: true
    quant_type: nf4_candidato_no_validado

adaptadores:
  rank: 16
  alpha: 32
  dropout: 0.05
  target_modules_candidatos:
    - q_proj
    - k_proj
    - v_proj
    - o_proj
    - linear_attn.in_proj_qkv
    - linear_attn.in_proj_z
    - linear_attn.out_proj
  regla: confirmar_nombres_formas_y_cobertura_en_el_modelo_real
  vision: congelada_hasta_validar
  mtp: excluido_hasta_validar

 datos:
  dataset: PENDIENTE_URI_Y_REVISION
  licencia: PENDIENTE_REVISION
  formato: mensajes_con_tools_y_resultados_observables
  prohibido: [secretos, pii_no_autorizada, razonamiento_privado]
  split_group_key: proveedor_repositorio_familia_api_escenario
  train_hash: PENDIENTE
  validation_hash: PENDIENTE
  holdout_hash: PENDIENTE

reproducibilidad:
  seed: 3407
  dependencias_lock: PENDIENTE
  hardware: PENDIENTE
  precision_compute: PENDIENTE
  longitud_secuencia: PENDIENTE
  batch_efectivo: PENDIENTE

 evaluacion:
  antes_y_despues: true
  metricas:
    - seleccion_herramienta
    - argumentos_validos_por_schema
    - abstencion_y_falsos_positivos
    - aclaracion_de_campos_faltantes
    - recovery_sin_duplicar_efectos
    - estado_final
  regresiones: [codigo, espanol, conversacion, seguridad]
  promocion: PENDIENTE_UMBRALES_Y_TOLERANCIAS

salidas:
  guardar_adapter: true
  merge: no_hasta_aprobar
  exportar_gguf: no_hasta_aprobar
  publicar: false
```

Hay dos errores deliberados de indentación antes de `datos` y `evaluacion`. La primera tarea es detectarlos sin ejecutar un parser. Después, marca todo campo pendiente como bloqueo, no como valor a improvisar. Verifica que los tres brazos usen el mismo checkpoint, plantilla, splits, semilla, longitud, batch efectivo y módulos objetivo cuando corresponda. Finalmente, exige inspeccionar el árbol real del modelo: los targets listados proceden de documentación de la familia Qwen3.5 y son candidatos, no una lista Ornith certificada.

## 6. Evaluación y criterio de promoción

Una comparación justa conserva datos, presupuesto de tokens, pasos, seed, plantilla y evaluación. LoRA BF16 y QLoRA deben producir adaptadores separados. Hay que registrar pérdida, memoria pico, tiempo y fallos, pero la decisión depende del holdout.

Para herramientas, mide selección, validez de esquema, exactitud de argumentos y estado final. Para abstención, mide también falsos positivos: un agente que llama siempre puede parecer activo y ser peligroso. Para aclaración, comprueba que pregunta sólo por lo indispensable. Para recovery, inyecta errores deterministas y verifica límites de reintento e idempotencia. Añade canarios de código, español, conversación y seguridad para detectar regresiones.

No promociones por una demo favorable ni porque el entrenamiento terminó. Promueve sólo si la mejora aparece frente al mismo baseline, se sostiene en varias ejecuciones o con incertidumbre reportada, no contamina el holdout y respeta tolerancias de regresión definidas antes del experimento. Si QLoRA usa menos memoria pero pierde calidad crítica, es una opción operativa fallida para ese objetivo.

## 7. Fuentes, vídeos y límites de evidencia

### Fuente primaria incluida en r3.2

- [Axolotl — Qwen 3.5](https://docs.axolotl.ai/docs/models/qwen3.5.html). Documenta la arquitectura híbrida, ejemplos LoRA/QLoRA y targets de Gated DeltaNet para Qwen3.5. **Límite:** soporte de familia y ejemplos de framework no equivalen a validación de Ornith.

### Vídeos canónicos de apoyo incluidos en r3.2

- [How to Fine-Tune LLMs for AI Agents: SFT and QLoRA Guide using Unsloth](https://www.youtube.com/watch?v=Jg0rT_fRvTg), Real World Devs. Flujo Qwen2.5-1.5B, SFT/QLoRA y exportación. **Límite:** no prueba Ornith y el registro r3.2 no fija todas las dependencias.
- [Steps By Step Tutorial To Fine Tune LLAMA 2 With Custom Dataset Using LoRA And QLoRA Techniques](https://www.youtube.com/watch?v=Vg3dS-NLUT4), Krish Naik. Procedimiento sobre Llama 2 con código. **Límite:** otra arquitectura, versiones y hardware no completamente fijados.
- [Mastering LLM Fine-Tuning with QLoRA: Quantization on a Single GPU + Code](https://www.youtube.com/watch?v=QzsjHUhZZLE), Analytics Camp. Útil para vocabulario y secuencia de trabajo. **Límite:** r3.2 lo clasifica como contexto anecdótico; no usar sus cifras para conclusiones.

Los vídeos enseñan procedimientos. La fuente primaria documenta soporte upstream. Ninguno demuestra que Ornith entrene, fusione, exporte o mejore con este YAML. Esa compatibilidad sólo puede afirmarse después de fijar una revisión, inspeccionar módulos, ejecutar un canario controlado y evaluar resultados reproducibles.

## Glosario

- **Adaptador:** conjunto pequeño de parámetros entrenados sobre una base congelada.
- **LoRA:** adaptación de bajo rango aplicada a matrices seleccionadas.
- **QLoRA:** entrenamiento LoRA con la base congelada cargada en baja precisión.
- **Módulo objetivo:** componente donde se inyecta el adaptador.
- **Chat template:** reglas que serializan roles, herramientas y mensajes en tokens.
- **Holdout:** conjunto reservado que no participa en entrenamiento ni decisiones iterativas.
- **Fuga:** solapamiento entre entrenamiento y evaluación que infla resultados.
- **Idempotencia:** propiedad que evita duplicar efectos al repetir una operación.
- **Rollback:** retorno al baseline inmutable retirando el adaptador experimental.
- **Compatibilidad sin validar:** soporte plausible o heredado, todavía no demostrado en el artefacto concreto.

## Recapitulación

LoRA reduce parámetros entrenables; QLoRA busca además reducir memoria de la base durante el ajuste. Ninguna técnica garantiza una mejor conducta agéntica. El trabajo real está en definir conductas observables, construir datos con procedencia, impedir fugas, fijar el experimento y evaluar llamadas, abstención, aclaración, recovery, estado final y regresiones.

Para Ornith, la postura correcta es conservadora: Qwen3.5 aporta pistas arquitectónicas y Axolotl documenta targets candidatos, pero la compatibilidad exacta permanece **no validada**. Primero se inspecciona; luego se ejecuta un canario aislado; finalmente se compara contra el baseline. Hasta entonces, tenemos un diseño auditable, no un logro.