Hiperparámetros

Qué controla cada hiperparámetro de LoRA y del entrenamiento, sus valores por defecto en AstrApp y cómo ajustarlos.

Teoría y producto, por separado

Las explicaciones de cada hiperparámetro son teoría general de fine-tuning. Los valores por defecto, los rangos y lo que dice En AstrApp salen del código del producto.

Qué es LoRA

La base para entender el rango y el alpha.

Un modelo guarda lo que sabe en matrices de pesos. LoRA no las modifica: les suma el producto de dos matrices delgadas, A y B, que son lo único que se entrena. Por eso el entrenamiento toca una fracción pequeña de los parámetros del modelo.

text

W' = W + (alpha / r) · B · A

W      pesos originales (congelados)
A, B   matrices entrenables de rango r
r      rango: qué tan "ancha" es la adaptación
alpha  escala: cuánto pesa la adaptación frente a W

Valores por defecto en AstrApp

Los de la tarjeta Hiperparámetros en Entrenar › Entrenar modelo. El botón Restaurar vuelve a estos valores.

Formulario es el rango del control deslizante. API es lo que acepta POST /api/v1/gpu/instances/training dentro de hyperparameters; fuera de ese rango, la petición se rechaza.

Hiperparámetro	Campo	Por defecto	Formulario	API
Vueltas al material (epochs)	`epochs`	3	1 – 20	1 – 20
Tamaño del paso (learning rate)	`learningRate`	2e-4	1e-6 – 1	1e-7 – 1
Ejemplos por lote (batch size)	`batchSize`	4	1 – 128	1 – 128
Lotes que junta antes de corregir	`gradientAccumulationSteps`	4	1 – 32	1 – 64
Largo máximo de conversación	`maxSeqLength`	2048	256 – 8192	128 – 131072
Espacio para lo tuyo (rango de LoRA)	`loraR`	16	4 – 64	1 – 256
Fuerza de lo aprendido (alpha)	`loraAlpha`	32	8 – 128	1 – 512
Olvido a propósito (dropout)	`loraDropout`	0.05	0 – 0.5	0 – 1
Arranque suave (warmup)	`warmupRatio`	0.03	0 – 0.5	0 – 1
Freno al exceso de confianza (weight decay)	`weightDecay`	0.001	0 – 0.1	0 – 1
Tope a las correcciones bruscas (gradient clipping)	`maxGradientNorm`	1	0 – 10	0 – 10
LR Scheduler	`lrSchedulerType`	cosine	cosine, linear, constant	cosine, linear, constant

Campos del formulario que el entrenamiento en GPU no usa

El formulario también muestra Copias intermedias (checkpoints), Revisiones durante el camino (evaluaciones), Hasta dónde baja el paso al final, Ciclos de subida y bajada del paso, LoRA Trainable Modules, Train on inputs. La ruta de entrenamiento en GPU los descarta al validar, así que moverlos no cambia nada:

Los checkpoints se guardan solos, más o menos cada 10% de los pasos.
LoRA se aplica siempre a los siete módulos de atención y MLP (ver abajo).
Para medir el modelo con datos que no vio, activa Evaluar el modelo tras entrenar.

Entrenamiento con Together AI

Si entrenas con Together AI en lugar de rentar una GPU, solo se usan epochs, batch size, learning rate y el rango, el alpha y el dropout de LoRA.

Hiperparámetros de entrenamiento

Controlan cuánto y qué tan rápido aprende el modelo.

Learning rate

Qué tanto se mueven los pesos con cada corrección. Muy alto y el entrenamiento se vuelve inestable: el loss sube de golpe o sale NaN. Muy bajo y necesitas más epochs para llegar al mismo lugar. 2e-4, el valor por defecto de AstrApp, es un punto de partida habitual para LoRA.

El scheduler cambia el learning rate durante el entrenamiento: cosine (por defecto) lo baja de forma suave, linear lo baja en línea recta y constant no lo cambia. El warmup es la fracción inicial de pasos en la que sube poco a poco: con 0.03, el primer 3%.

Epochs

Cuántas veces el modelo recorre tu dataset completo. Pocas y el modelo sigue sonando como el base; demasiadas y empieza a repetir tus ejemplos de memoria. El tiempo de GPU, y por lo tanto el costo, crece casi en proporción directa con las epochs. AstrApp usa 3 por defecto.

Batch size y acumulación de gradiente

El batch size es cuántos ejemplos procesa la GPU a la vez. La acumulación de gradiente junta las correcciones de varios lotes antes de aplicarlas. Lo que cuenta para el aprendizaje es el batch efectivo:

text

batch efectivo = batch size × acumulación de gradiente
Por defecto en AstrApp: 4 × 4 = 16

Estas configuraciones tienen el mismo batch efectivo (32) y distinto uso de memoria:

Batch × acumulación	Memoria de GPU	Velocidad
32 × 1	La más alta	La más rápida, si cabe en la GPU
8 × 4	Media	Intermedia
2 × 16	Baja	Más lenta
1 × 32	La mínima	La más lenta

En AstrApp

Si la GPU se queda sin memoria, train.py reintenta una vez con la mitad del batch size y el doble de acumulación, para conservar el batch efectivo. Si vuelve a fallar, el entrenamiento se detiene y te pide bajar el largo máximo de secuencia o usar una GPU con más VRAM.

Largo máximo de secuencia

Cuántos tokens de una conversación caben en un ejemplo. Lo que pase de ahí se corta y no se aprende. Subirlo cuesta bastante más memoria y hace cada paso más lento. AstrApp usa 2048 por defecto y, antes de entrenar, avisa en el log cuántas conversaciones lo superan.

Weight decay y gradient clipping

El weight decay empuja los pesos hacia valores pequeños para que el modelo no dependa de detalles sueltos de tus ejemplos. El gradient clipping (Max Gradient Norm) pone un tope a cada corrección, por si un ejemplo raro pide un cambio enorme.

Hiperparámetros de LoRA

Deciden cuánto espacio tiene el modelo para aprender lo tuyo.

Rango (r)

Más rango, más capacidad y un adapter más pesado. 16 alcanza para ajustar tono y formato; súbelo si enseñas algo que el modelo base no hace.

Alpha

Escala la adaptación. La regla habitual es el doble del rango: por eso AstrApp usa 32 con rango 16. Si cambias el rango, ajusta el alpha.

Dropout

Apaga al azar parte de la adaptación en cada paso para que el modelo no memorice. 0.05 por defecto.

Módulos de destino

Son las capas a las que se aplica LoRA. El artículo de QLoRA (Dettmers et al., 2023) encontró que aplicarlo a todas las capas lineales, no solo a las de atención, es necesario para igualar al fine-tuning completo.

En AstrApp

Los módulos están fijos en train.py: siempre son estos siete, sin importar lo que escribas en el formulario.

train.py

target_modules=[
    "q_proj", "k_proj", "v_proj", "o_proj",   # atención
    "gate_proj", "up_proj", "down_proj",      # MLP
]

QLoRA frente a LoRA

LoRA sobre un modelo base cuantizado a 4 bits.

QLoRA usa mucha menos memoria de GPU que LoRA en 16 bits, a cambio de pasos algo más lentos, y su calidad queda cerca de la de LoRA en 16 bits. En AstrApp no se elige: Entrenar modelo carga siempre el modelo base en 4 bits. La comparación completa está en la Guía de fine-tuning.

Overfitting y underfitting

Los dos problemas que se corrigen con hiperparámetros.

Overfitting

El modelo memoriza tus ejemplos y falla con preguntas nuevas. El loss de entrenamiento baja casi a cero mientras el de evaluación sube.

Baja las epochs.
Baja el learning rate.
Sube el dropout o el weight decay.
Agrega ejemplos más variados.

Underfitting

El modelo no capta tus patrones y responde genérico. El loss se queda alto y casi plano.

Sube las epochs.
Sube el learning rate con cuidado.
Sube el rango de LoRA (y el alpha con él).
Revisa que tus ejemplos muestren lo que quieres enseñar.

Mide con datos que el modelo no vio

AstrApp no tiene early stopping. Para ver el loss de evaluación, activa Evaluar el modelo tras entrenar en Entrenar modelo: mide el eval loss y la perplejidad con una parte apartada de tu dataset o con otro dataset.

Configuración inicial

Los valores por defecto de AstrApp, tal como los manda el formulario a la API.

hyperparameters (POST /api/v1/gpu/instances/training)

{
  "hyperparameters": {
    "epochs": 3,
    "learningRate": 0.0002,
    "batchSize": 4,
    "gradientAccumulationSteps": 4,
    "maxSeqLength": 2048,
    "loraR": 16,
    "loraAlpha": 32,
    "loraDropout": 0.05,
    "warmupRatio": 0.03,
    "weightDecay": 0.001,
    "maxGradientNorm": 1,
    "lrSchedulerType": "cosine"
  }
}

El resto del cuerpo de la petición está en Referencia API › Entrenamiento.