Cómo pedir ayuda (y cómo no necesitarla)

1. Leer un error de abajo hacia arriba

Un traceback de Python se lee al revés de como uno lo mira instintivamente: la línea de más abajo es la causa real, todo lo de arriba es la cadena de llamadas que llevó hasta ahí. El error más común al arrancar con el Hub — un identificador de modelo mal escrito, o un archivo config.json faltante en el repo — se diagnostica en segundos si vas directo a la última línea en vez de leer todo de arriba para abajo.

Un ejemplo real, del tipo que el curso usa: el nombre del checkpoint tiene una letra de más ("distillbert" con dos eles) y el pipeline explota. Esto es lo que ves:

Traceback (most recent call last):
  File "demo.py", line 4, in <module>
    reader = pipeline("question-answering", model=model_checkpoint)
  File ".../site-packages/transformers/pipelines/__init__.py", line ..., in pipeline
    config = AutoConfig.from_pretrained(model, _from_pipeline=task, **hub_kwargs, **model_kwargs)
  File ".../site-packages/transformers/models/auto/configuration_auto.py", line ..., in from_pretrained
    config_dict, unused_kwargs = PretrainedConfig.get_config_dict(pretrained_model_name_or_path, **kwargs)
  File ".../site-packages/transformers/configuration_utils.py", line ..., in get_config_dict
    config_dict, kwargs = cls._get_config_dict(pretrained_model_name_or_path, **kwargs)
  File ".../site-packages/transformers/configuration_utils.py", line ..., in _get_config_dict
    resolved_config_file = cached_file(...)
  File ".../site-packages/transformers/utils/hub.py", line ..., in cached_file
    raise EnvironmentError(
OSError: lewtun/distillbert-base-uncased-finetuned-squad-d5716d28 is not a local folder and is not a valid model identifier listed on 'https://huggingface.co/models'
If this is a private repository, make sure to pass a token having permission to this repo either by logging in with `huggingface-cli login` or by passing `token=<your_token>`

Leído de abajo hacia arriba, línea por línea:

1. Última línea (el mensaje): OSError: ... is not a local folder and is not a valid model identifier. Ya está el diagnóstico completo: lo que le pasaste no es ni una carpeta local ni un repo del Hub. La frase sobre repos privados es la segunda hipótesis que la librería te ofrece — no la ignores si el repo es tuyo y no hiciste login.
2. Justo arriba (raise EnvironmentError( en utils/hub.py): es el lugar donde transformers decidió rendirse. No es tu código, es la librería explicándote que no encontró el archivo. Todo lo que está en site-packages es "de ellos".
3. Las cuatro líneas siguientes hacia arriba (configuration_utils.py, configuration_auto.py, pipelines/__init__.py): la cadena interna. Te dicen qué estaba buscando: el config.json. Útil para confirmar que el problema es "no existe el repo" y no "existe pero le falta un archivo" — si fuera esto último, el mensaje diría que falta config.json, no que el identificador es inválido.
4. La primera línea con un archivo tuyo (demo.py, línea 4): la línea de tu código que disparó todo. Es el único lugar donde vas a tocar algo. Acá miramos el valor de model_checkpoint y aparece la doble ele.

La regla que sale de esto: el mensaje final te dice qué falló; el primer archivo tuyo (contando desde abajo) te dice dónde lo provocaste; todo lo del medio te dice por qué camino, y casi nunca hace falta leerlo entero — salvo cuando el error viene de una librería que llama a otra y el mensaje final es genérico (un KeyError: 'labels', por ejemplo, no dice nada sin ver quién pidió esa clave).

Antes de asumir que el bug es tuyo: huggingface_hub.list_repo_files() te dice qué archivos tiene realmente un repo, y pegar el mensaje de error tal cual en un buscador casi siempre te lleva a alguien que ya lo resolvió — la mayoría de los errores que vas a ver ya los vio otra persona antes.

from huggingface_hub import list_repo_files
print(list_repo_files("lewtun/distilbert-base-uncased-finetuned-squad-d5716d28"))

Si en esa lista no aparece config.json, el error que vas a ver es otro (la librería lo dice explícitamente), y la solución es que el dueño del repo lo suba — o que lo cargues vos con AutoConfig.from_pretrained("distilbert-base-uncased") y se lo pases al modelo a mano, como hace el curso.

2. Pedir ayuda bien

Un buen post de foro (o de cualquier canal de soporte) tiene cuatro ingredientes, siempre en este orden de importancia:

El último punto es, con diferencia, el que más tiempo ahorra — a vos y a quien te ayuda. Reducir el problema a un ejemplo mínimo casi siempre te hace encontrar la causa antes incluso de terminar de escribir la pregunta.

Hay un quinto ingrediente que el curso pide en el capítulo de issues pero que conviene incluir siempre: el entorno. transformers trae un comando que lo imprime listo para pegar:

transformers env      # en versiones anteriores: transformers-cli env

Los dos campos con <fill in> los completás vos. El resto es exactamente lo que alguien necesita para reproducir tu problema — y con frecuencia, lo que vos necesitás para darte cuenta de que el notebook donde funciona tiene una versión de transformers y el servidor donde falla tiene otra. Esa diferencia de versiones explica una fracción enorme de los "funciona acá pero no allá".

3. Debuggear un entrenamiento que no crashea

Los bugs más peligrosos no son los que tiran una excepción — son los que entrenan sin quejarse y producen un modelo inútil. Para el caso con excepción, la receta es sistemática: revisar los datos, después cómo se arman los batches (el data_collator correcto, Capítulo 3), después el forward del modelo, después el paso del optimizador, y recién ahí sospechar de la config o el hardware (incluido el clásico CUDA out of memory, que tiene su propio checklist en la sección 4).

Paso 1: mirar lo que sale del collator

El collator es el punto donde "mi dataset" se convierte en "lo que el modelo recibe", y es el lugar donde más bugs silenciosos se esconden. Antes de entrenar, armá un batch a mano e imprimí shapes y dtypes — cinco líneas que ahorran horas:

batch = data_collator([tokenized["train"][i] for i in range(4)])
print({k: (tuple(v.shape), v.dtype) for k, v in batch.items()})

Qué mirar en esa salida:

• Que estén las claves que el modelo espera. Si el collator falla con un error críptico, casi siempre es porque el dataset todavía tiene columnas de texto ("sentence", "idx") que no se pueden convertir a tensor — Trainer las saca solo con remove_unused_columns=True, pero si armás el batch a mano, sacalas vos con remove_columns en el map.
• Que labels tenga el shape de la tarea: (4,) para clasificación de secuencias, (4, 67) para clasificación de tokens o LM. Un (4, 67) donde esperabas (4,) significa que tokenizaste la columna equivocada.
• Que los dtypes sean enteros para ids y labels (int64), y flotantes solo para cosas como pesos o pixel_values. Un float32 en labels rompe la cross-entropy con un error que no menciona el dtype.

Y un assert de rangos, porque una etiqueta fuera de rango en GPU no dice "etiqueta fuera de rango" — dice CUDA error: device-side assert triggered, que no te orienta nada:

labels = batch["labels"]
validos = labels[labels != -100]
assert validos.min() >= 0 and validos.max() < model.config.num_labels, \
    f"labels en [{validos.min()}, {validos.max()}] pero num_labels={model.config.num_labels}"

Este es exactamente el bug del ejemplo del curso: un dataset con tres clases (MNLI) y un modelo cargado con el num_labels=2 por default. En CPU el error es legible (IndexError: Target 2 is out of bounds); en GPU es el assert de CUDA. Por eso vale la pena correr un forward de prueba en CPU antes de mandar todo a la GPU.

Paso 2: sobreajustar un solo batch

Para el caso silencioso — entrena, la loss baja, pero el modelo no sirve — dos técnicas de sanity check:

• Sobreajustar deliberadamente en un solo batch: si el modelo no puede llegar a accuracy ≈100% memorizando 8 ejemplos, el problema está en los datos o en cómo está planteado el modelo — no tiene sentido seguir entrenando en el dataset completo hasta arreglar esto.
• No tocar ningún hiperparámetro hasta tener un primer baseline funcionando: ajustar learning rate o arquitectura antes de confirmar que el pipeline básico aprende algo es optimizar en la dirección equivocada.

El primero, en código — el mismo batch, una y otra vez, hasta que la loss se vaya a cero:

import torch
from transformers import set_seed

set_seed(42)
device = "cuda" if torch.cuda.is_available() else "cpu"
model.to(device).train()
optimizer = torch.optim.AdamW(model.parameters(), lr=5e-5)

batch = data_collator([tokenized["train"][i] for i in range(8)])
batch = {k: v.to(device) for k, v in batch.items()}

for step in range(30):
    out = model(**batch)
    out.loss.backward()
    optimizer.step()
    optimizer.zero_grad()
    if step % 5 == 0:
        print(step, round(out.loss.item(), 4))

model.eval()
with torch.no_grad():
    preds = model(**batch).logits.argmax(-1)
print("accuracy sobre el mismo batch:", (preds == batch["labels"]).float().mean().item())

Qué observar, y qué significa cada desvío:

• La loss baja monótonamente a ≈0 y la accuracy llega a 1.0: el pipeline es capaz de aprender. Si después el entrenamiento completo no mejora, el problema es de generalización o de hiperparámetros, no de plomería.
• La loss se queda clavada (por ejemplo en ln(num_labels), que es 1.10 para 3 clases o 0.69 para 2): el modelo no recibe señal. Labels todas iguales, labels desalineadas con los inputs, learning rate cero, o los gradientes no llegan (¿congelaste todo por error? ¿hay un torch.no_grad() de más?).
• La loss baja y después sube o da nan: learning rate demasiado alto para 8 ejemplos, o un problema numérico (fp16 sin escalado de gradientes).
• La loss baja pero la accuracy no llega a 1.0: mirá si hay ejemplos idénticos con etiquetas distintas en el batch — datos contradictorios que ningún modelo puede memorizar.

El set_seed(42) no es decorativo: fija las semillas de Python, NumPy y PyTorch (CPU y CUDA) de una vez. Sin él, dos corridas del mismo snippet dan curvas distintas y no sabés si "mejoró" porque cambiaste algo o porque el azar cayó distinto.

4. CUDA out of memory: el checklist

El error de hardware más frecuente merece más que "bajá el batch size". Es un problema de presupuesto: pesos + gradientes + estados del optimizador + activaciones tienen que entrar en la VRAM, y cada uno de esos términos tiene su propia perilla. Recorrelo en este orden:

import torch
torch.cuda.memory._record_memory_history(max_entries=100000)
try:
    # loop de entrenamiento
    train_step()
except torch.cuda.OutOfMemoryError:
    torch.cuda.memory._dump_snapshot("oom_snapshot.pickle")
    # Subir oom_snapshot.pickle a https://pytorch.org/memory_viz

5. Cómo escribir un buen issue

Si el bug es de la librería y no tuyo, un buen issue en GitHub agrega tres cosas al ejemplo mínimo reproducible de la sección 2: la información de entorno (versión de la librería, de Python, de CUDA — generada automáticamente con transformers env), una descripción clara de qué esperabas que pasara versus qué pasó realmente, y etiquetar a la persona correcta sin spamear a todo el equipo.

Antes de abrir el issue, tres verificaciones que evitan la respuesta más frecuente de un mantenedor ("no puedo reproducirlo"):

• Reproducilo con la última versión (pip install -U transformers en un entorno limpio). Una fracción grande de los bugs reportados ya están arreglados en main.
• Fijá la semilla con set_seed() y confirmá que el bug aparece siempre, no una de cada tres corridas. Si es intermitente, decilo, y decí con qué frecuencia.
• Buscá el issue tracker con el mensaje de error exacto. Si ya existe uno, sumá tu caso ahí (con tu transformers env) en vez de abrir un duplicado.

6. Errores comunes

Errores sobre cómo debuggear, no sobre el código en sí — los que hacen que tardes tres días en algo de veinte minutos.

7. Resumen

1. Un traceback se lee de abajo hacia arriba — la causa real está en la última línea; el lugar donde lo provocaste es el primer archivo tuyo contando desde abajo.
2. Pedir ayuda bien es, en el fondo, reducir el problema a su ejemplo mínimo — el paso que más rápido te acerca a la solución, incluso antes de que alguien te responda — y acompañarlo del entorno (transformers env), como texto, nunca como imagen.
3. Un entrenamiento que no crashea puede seguir estando roto — imprimir shapes/dtypes del collator, un assert de rangos de labels, sobreajustar en un batch y no tunear antes de tener un baseline son los cuatro sanity checks que lo detectan temprano.
4. CUDA out of memory es un problema de presupuesto con un orden: medir, activaciones (batch + acumulación), longitud, precisión, checkpointing, y recién después pesos/optimizador. empty_cache() no cambia el presupuesto.
5. Un buen issue = ejemplo mínimo + entorno + comportamiento esperado vs. real, reproducido con seed fija y la última versión — la misma disciplina que ya aplicaste mandando fixes reales aguas arriba.

8. Ponete a prueba

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

9. Para practicar

from transformers import pipeline
from huggingface_hub import list_repo_files

nombre = "distillbert-base-uncased"     # la doble ele es a propósito
try:
    pipeline("fill-mask", model=nombre)
except Exception as e:
    print(type(e).__name__, "→", str(e).splitlines()[0])

print(list_repo_files("distilbert-base-uncased"))   # el nombre correcto

import torch
from datasets import Dataset
from transformers import AutoTokenizer, AutoModelForSequenceClassification, DataCollatorWithPadding

ckpt = "prajjwal1/bert-tiny"
tok = AutoTokenizer.from_pretrained(ckpt)
model = AutoModelForSequenceClassification.from_pretrained(ckpt, num_labels=2)

ds = Dataset.from_dict({"text": ["muy bueno", "horrible", "excelente", "malísimo"], "label": [1, 0, 1, 2]})
tokenized = ds.map(lambda ex: tok(ex["text"], truncation=True), batched=True, remove_columns=["text"])
collator = DataCollatorWithPadding(tok)

batch = collator([tokenized[i] for i in range(4)])
print({k: (tuple(v.shape), v.dtype) for k, v in batch.items()})

labels = batch["labels"]
validos = labels[labels != -100]
assert validos.max() < model.config.num_labels, f"label {validos.max().item()} pero num_labels={model.config.num_labels}"
print(model(**batch).loss)

from transformers import set_seed

def sobreajustar(seed=None):
    if seed is not None:
        set_seed(seed)
    m = AutoModelForSequenceClassification.from_pretrained(ckpt, num_labels=2)
    opt = torch.optim.AdamW(m.parameters(), lr=1e-3)
    m.train()
    for step in range(40):
        out = m(**batch); out.loss.backward(); opt.step(); opt.zero_grad()
    return round(out.loss.item(), 5)

print("sin seed:", sobreajustar(), sobreajustar())
print("con seed:", sobreajustar(0), sobreajustar(0))

10. Fuentes y para seguir

• LLM Course, Chapter 8 — What to do when you get an error — el ejemplo original del traceback del pipeline y del config.json faltante, paso a paso.
• LLM Course, Chapter 8 — Debugging the training pipeline — la receta completa datos → collator → modelo → optimizador, incluido el caso de num_labels y el sobreajuste de un batch con Trainer.
• LLM Course, Chapter 8 — How to write a good issue — la plantilla de issue y el uso del comando de entorno.
• How to create a Minimal, Reproducible Example (Stack Overflow) — la definición canónica de "ejemplo mínimo"; leela una vez y aplicala siempre.
• A Recipe for Training Neural Networks (Karpathy, 2019) — el origen de "sobreajustá un batch primero" y "no toques hiperparámetros hasta tener un baseline"; sigue siendo la mejor lista de sanity checks.
• PyTorch — Reproducibility — qué fija una seed y qué no (kernels no deterministas de CUDA), para cuando "misma seed, distinto resultado".