Tensores y datos: el vocabulario que ya usás sin pensarlo

1. El tensor: un ndarray que sabe usar GPU y derivarse

La documentación oficial es directa: un tensor es "una estructura de datos especializada, muy similar a arrays y matrices" — básicamente un ndarray de NumPy con dos poderes extra: puede vivir en GPU (o cualquier accelerator: CUDA, MPS, XPU) y está optimizado para diferenciación automática. Se puede crear de varias formas equivalentes:

x_data = torch.tensor([[1, 2],[3, 4]])       # directo desde datos
x_np = torch.from_numpy(np_array)              # desde un array de NumPy
x_ones = torch.ones_like(x_data)               # conserva shape/dtype de otro tensor
rand_tensor = torch.rand((2,3))              # shape explícito

Tres atributos definen a cualquier tensor: .shape, .dtype y .device (dónde vive físicamente — CPU por defecto). Mover un tensor a GPU es explícito y nunca automático:

if torch.accelerator.is_available():
    tensor = tensor.to(torch.accelerator.current_accelerator())

.to() es la forma general: acepta un device ("cuda", "cuda:1", "mps", "cpu"), un dtype, o los dos a la vez, y devuelve un tensor nuevo — el original no cambia, así que x.to("cuda") sin asignar no hace nada útil. .cuda() es un atajo histórico equivalente a .to("cuda"); funciona, pero ata el código a NVIDIA y no permite combinar dtype y device en una sola copia:

x = x.to("cuda")                                  # cambia device
x = x.to(torch.bfloat16)                          # cambia dtype (copia)
x = x.to("cuda", torch.bfloat16, non_blocking=True)  # las dos cosas en una copia
x = x.cuda()                                      # == x.to("cuda"); solo NVIDIA

La API cubre más de 1200 operaciones — indexado estilo NumPy, torch.cat para concatenar, @/matmul para producto matricial, */mul para producto elemento a elemento. Vale la pena memorizar un solo hecho: tensores en CPU y arrays de NumPy pueden compartir la misma memoria subyacente — t.numpy() y torch.from_numpy(n) no copian datos, así que modificar uno modifica el otro. Es la razón por la que convertir entre ambos formatos es prácticamente gratis, y también una fuente clásica de bugs sutiles cuando no se espera ese acoplamiento.

n = np.ones(3)
t = torch.from_numpy(n)
t.add_(1)              # modifica el tensor... y el array
print(n)

Dos límites de ese puente que conviene saber de memoria: .numpy() solo funciona sobre tensores en CPU (en GPU: .cpu().numpy()) y que no requieran gradiente (con requires_grad=True: .detach().numpy()); y NumPy no tiene bfloat16, así que un tensor bf16 hay que pasarlo a .float() antes de convertirlo. Si querés una copia independiente en vez de memoria compartida, t.clone() o np.array(t).

2. Los dtypes que importan hoy

El tutorial oficial pasa por dtype en una línea. En 2026 es la decisión que más condiciona cuánto modelo entra en tu GPU y a qué velocidad corre — el bytes-por-parámetro es el número que multiplicás por el tamaño del modelo para saber si entra. Estos son los que te vas a cruzar:

La regla práctica: entrenar en bf16 con master weights en fp32 (eso hace torch.autocast, lo ves en la página 3), inferir en el dtype más chico que no rompa la calidad — bf16 si tenés memoria, int8 o fp8 si querés throughput, fp4 si el hardware lo tiene. La pérdida de precisión no es gratis: cada paso hacia abajo hay que medirlo con un eval, no asumirlo.

Cambiar de dtype es una copia, no un cast gratis, y las operaciones exigen que sus operandos coincidan: multiplicar una matriz fp32 por un vector fp16 da RuntimeError: expected scalar type Float but found Half. La excepción son los escalares de Python y las promociones "seguras" (int con float, por ejemplo), que PyTorch resuelve con sus reglas de type promotion.

w = torch.randn(4, 4)                   # float32 por default
x = torch.randn(4, dtype=torch.float16)
w @ x                                    # RuntimeError: expected scalar type Float but found Half
w @ x.to(w.dtype)                        # ok
x.element_size() * x.numel()             # bytes que ocupa: 2 * 4 = 8

3. Shapes: broadcasting, view/reshape, cat/stack

Casi todos los bugs de un forward pass son de shapes. Tres mecanismos explican el 90 % de lo que ves en código ajeno.

Broadcasting en tres reglas

1. Se alinean los shapes desde la derecha (la última dimensión con la última).
2. Dos dimensiones son compatibles si son iguales, o si una de las dos es 1, o si a uno de los tensores le falta esa dimensión (se trata como 1).
3. El resultado toma, en cada posición, el máximo de las dos — y el tensor con 1 se "estira" virtualmente, sin copiar memoria.

a = torch.arange(3).reshape(3, 1)     # shape (3, 1)
b = torch.arange(4).reshape(1, 4)     # shape (1, 4)
(a + b).shape                            # (3, 4): tabla de sumas

x = torch.randn(8, 128)                 # batch de 8 vectores
mu = x.mean(dim=1, keepdim=True)         # (8, 1) — keepdim conserva la dim para broadcastear
(x - mu).shape                           # (8, 128): resta la media de cada fila

torch.randn(8, 128) + torch.randn(8)     # RuntimeError: (8,128) vs (8) → alinea 128 con 8

El último caso es el error típico: querías restar un valor por fila y PyTorch alineó desde la derecha. La solución es darle la forma (8, 1) con keepdim=True, .unsqueeze(1) o [:, None]. Cuando una máscara de atención, un bias o un factor de escala "no entra", el diagnóstico empieza por escribir los dos shapes alineados a la derecha.

view vs reshape vs contiguous()

Un tensor es un puntero a memoria más strides (cuántos elementos saltar por cada dimensión). t.T, permute, transpose y el slicing con paso no mueven datos: solo cambian los strides, y el tensor deja de ser contiguo. view exige contigüidad porque se limita a reinterpretar la misma memoria sin copiar; reshape devuelve una view si puede y una copia si no; contiguous() hace la copia explícitamente.

x = torch.randn(4, 6)
x.view(24)                     # ok: comparte memoria
y = x.t()                      # (6, 4), no contiguo
y.is_contiguous()              # False
y.view(24)                     # RuntimeError: view size is not compatible with input tensor's size and stride...
y.reshape(24)                  # ok: copia por detrás
y.contiguous().view(24)        # ok: la misma copia, explícita

Por eso en el código de atención vas a ver siempre .transpose(1, 2).contiguous().view(B, T, C) al volver de "cabezas separadas" a "embedding plano": el transpose rompió la contigüidad y view no perdona. Usar reshape ahí es correcto y más corto — la única razón para preferir view es que falla ruidosamente cuando esperabas no copiar.

torch.cat vs torch.stack

cat concatena a lo largo de una dimensión que ya existe; stack apila tensores del mismo shape creando una dimensión nueva.

a, b = torch.zeros(2, 3), torch.ones(2, 3)
torch.cat([a, b], dim=0).shape     # (4, 3): más filas
torch.cat([a, b], dim=1).shape     # (2, 6): más columnas
torch.stack([a, b], dim=0).shape   # (2, 2, 3): dimensión nueva adelante
torch.stack([a, b], dim=0).equal(torch.cat([a[None], b[None]]))  # True: stack == unsqueeze + cat

Regla mnemotécnica: el collate por defecto de DataLoader hace stack (N ítems de shape S → batch de shape (N, S)); la KV cache de un LLM hace cat (los K y V del token nuevo se pegan a los anteriores en la dimensión de secuencia).

4. Operaciones in-place: el detalle que rompe autograd

Las operaciones que terminan en guion bajo (x.add_(5), x.copy_(y), x.t_()) modifican el tensor en el lugar en vez de crear uno nuevo — ahorran memoria, pero la documentación oficial es explícita: su uso está desaconsejado, porque pueden causar una pérdida inmediata del historial necesario para calcular derivadas. Si un tensor participa en el grafo de autograd y se sobreescribe in-place, PyTorch puede no tener forma de reconstruir el valor que necesitaba para el backward pass — el error clásico es RuntimeError: a leaf Variable that requires grad is being used in an in-place operation, o peor, un gradiente silenciosamente incorrecto.

w = torch.randn(3, requires_grad=True)
w.mul_(0.5)                    # RuntimeError: a leaf Variable that requires grad is being used in an in-place operation.

with torch.no_grad():          # así lo hacen los optimizadores: fuera del grafo
    w.mul_(0.5)

y = w * 2
y.sigmoid_()                   # permitido (y no es hoja)... pero
y.sum().backward()             # RuntimeError: one of the variables needed for gradient computation has been modified by an inplace operation

El segundo error es el sutil: sigmoid necesita su propia salida para calcular la derivada, y la sobreescribiste. PyTorch lo detecta con un contador de versión por tensor y corta la ejecución en vez de devolver un gradiente incorrecto. Dónde sí se usan in-place sin culpa: en el step() de los optimizadores (bajo no_grad), en zero_grad(), en máscaras (masked_fill_) sobre tensores que no requieren gradiente, y en buffers de inferencia como una KV cache preasignada.

5. Dataset: tres métodos, cualquier fuente de datos

torch.utils.data.Dataset es deliberadamente minimalista: cualquier clase que implemente __init__, __len__ y __getitem__ ya es un Dataset válido, sin heredar nada más complejo.

class CustomImageDataset(Dataset):
    def __init__(self, annotations_file, img_dir, transform=None):
        self.img_labels = pd.read_csv(annotations_file)
        self.img_dir = img_dir
        self.transform = transform

    def __len__(self): return len(self.img_labels)

    def __getitem__(self, idx):
        img_path = os.path.join(self.img_dir, self.img_labels.iloc[idx, 0])
        image = decode_image(img_path)
        label = self.img_labels.iloc[idx, 1]
        if self.transform: image = self.transform(image)
        return image, label

El diseño es intencional: desacoplar el código de datos del código de entrenamiento. Un Dataset no sabe nada de batches, GPUs, ni epochs — solo sabe cuántos ítems tiene y cómo devolver el ítem i. Esta simplicidad es la razón por la que casi cualquier fuente de datos (un CSV, una carpeta de imágenes, un dataset del Hub de HF, un stream remoto) puede envolverse en la misma interfaz de tres métodos.

Dos consecuencias prácticas de esa interfaz. Primera: __getitem__ corre una vez por ítem, en cada epoch, así que lo caro (tokenizar, decodificar JPEG, abrir archivos) conviene hacerlo ahí — en paralelo, con los workers del DataLoader — y no en __init__, salvo que el dataset entero entre en RAM. Segunda: como cada ítem se pide por índice, la interfaz asume acceso aleatorio; para streams sin largo conocido (un archivo de 200 GB de texto, una cola de Kafka) existe IterableDataset, que solo implementa __iter__ y renuncia al shuffle automático. Los datasets de HF ofrecen las dos variantes (streaming=True da la iterable).

class TokenizedText(Dataset):
    def __init__(self, texts, labels, tokenizer, max_len=256):
        self.texts, self.labels, self.tok, self.max_len = texts, labels, tokenizer, max_len
    def __len__(self): return len(self.texts)
    def __getitem__(self, i):
        ids = self.tok(self.texts[i], truncation=True, max_length=self.max_len)["input_ids"]
        return torch.tensor(ids), torch.tensor(self.labels[i])   # largo variable por ítem

6. DataLoader: batching, shuffling y paralelismo gratis

DataLoader envuelve un Dataset y resuelve todo lo que un training loop necesita y un Dataset deliberadamente no sabe hacer: agrupar en mini-batches, barajar en cada epoch, y usar multiprocessing para que la carga de datos no bloquee la GPU esperando el próximo batch.

train_dataloader = DataLoader(training_data, batch_size=64, shuffle=True)

train_features, train_labels = next(iter(train_dataloader))
# train_features.shape → [64, 1, 28, 28] — el batch ya armado

Iterar el DataLoader da tuplas (features, labels) ya agrupadas en el tamaño de batch pedido — el mismo patrón exacto que ya usaste, sin necesariamente haberlo escrito a mano, en Trainer de HF y en el Learner de fastai/miniai: ambos son, por dentro, un DataLoader de PyTorch con una capa de conveniencia encima.

Los argumentos que cambian la velocidad

collate_fn: padding de secuencias de largo variable

Con el TokenizedText de la sección anterior, el collate por defecto explota: RuntimeError: stack expects each tensor to be equal size. La solución es darle al DataLoader una función que rellene cada batch hasta el largo del ítem más largo de ese batch — no del dataset entero — y devuelva la máscara que indica qué posiciones son reales:

from torch.nn.utils.rnn import pad_sequence

def collate_pad(batch, pad_id=0):
    ids, labels = zip(*batch)                                    # lista de tensores 1D, lista de escalares
    input_ids = pad_sequence(ids, batch_first=True, padding_value=pad_id)   # (B, L_max del batch)
    attention_mask = (input_ids != pad_id).long()
    return {"input_ids": input_ids,
            "attention_mask": attention_mask,
            "labels": torch.stack(labels)}

loader = DataLoader(ds, batch_size=16, shuffle=True, collate_fn=collate_pad,
                    num_workers=4, pin_memory=True, persistent_workers=True)
batch = next(iter(loader))
batch["input_ids"].shape, batch["attention_mask"].sum(1)   # (16, L_max), largos reales

Esto es, línea por línea, lo que hace DataCollatorWithPadding de Transformers en el Capítulo 2 de HF — dynamic padding: rellenar por batch en vez de a un largo fijo global ahorra cómputo porque la mayoría de los batches no contienen la secuencia más larga del dataset. Un refinamiento habitual es ordenar los ítems por largo antes de agrupar (bucketing), para que cada batch tenga poco padding; el group_by_length=True del Trainer hace exactamente eso con un sampler.

7. Errores comunes

Casi todos los errores de esta página vienen con un mensaje bastante explícito — el trabajo es reconocerlos a primera vista.

8. Resumen

1. Un tensor es un ndarray con dos poderes extra: puede vivir en un accelerator y soporta diferenciación automática. .to() devuelve un tensor nuevo y sirve para device y dtype a la vez; .cuda() es el atajo viejo, solo NVIDIA.
2. Tensores en CPU y arrays de NumPy comparten memoria — convertir entre ambos es gratis, pero acopla los dos objetos; .detach().cpu().numpy() es la secuencia segura.
3. El dtype es la decisión de memoria: fp32 (4 bytes) para master weights, bf16 (2) para entrenar e inferir, int8/fp8 (1) y fp4 (0,5) para inferencia cuantizada — cada escalón hay que medirlo.
4. Broadcasting alinea desde la derecha; view exige contigüidad y reshape copia si hace falta; cat une en una dimensión existente y stack crea una nueva.
5. Las operaciones in-place (sufijo _) ahorran memoria pero pueden romper el historial que necesita autograd — evitarlas quirúrgicamente, no por default.
6. Dataset son solo tres métodos (__init__, __len__, __getitem__); DataLoader agrega batching, shuffle y paralelismo encima, sin que el Dataset sepa nada de eso. num_workers, pin_memory y un collate_fn con padding dinámico son las tres perillas que más importan.
7. fastai, miniai y HF Transformers construyen sus propias abstracciones de datos directamente sobre estas dos clases — no las reemplazan, las envuelven.

9. Ponete a prueba

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

10. Para practicar

import torch
x = torch.randn(1_000_000)
for dt in [torch.float32, torch.bfloat16, torch.float16, torch.int8, torch.float8_e4m3fn]:
    y = x.to(dt)
    mb = y.element_size() * y.numel() / 1e6
    err = (y.float() - x).abs().max().item() if dt.is_floating_point else float("nan")
    print(f"{str(dt):22s} {y.element_size()} B/valor  {mb:5.2f} MB  error máx {err:.4f}")

import torch
from torch.utils.data import Dataset, DataLoader
from torch.nn.utils.rnn import pad_sequence

class FakeText(Dataset):
    def __init__(self, n=512, seed=0):
        g = torch.Generator().manual_seed(seed)
        self.lens = torch.randint(8, 200, (n,), generator=g)
    def __len__(self): return len(self.lens)
    def __getitem__(self, i):
        return torch.randint(1, 1000, (int(self.lens[i]),)), torch.tensor(i % 2)

def collate_pad(batch):
    ids, labels = zip(*batch)
    x = pad_sequence(ids, batch_first=True, padding_value=0)
    return x, (x != 0), torch.stack(labels)

def padding_total(loader):
    return sum((~mask).sum().item() for _, mask, _ in loader)

ds = FakeText()
shuffled = DataLoader(ds, batch_size=32, shuffle=True, collate_fn=collate_pad)
orden = ds.lens.argsort().tolist()                      # bucketing casero: índices por largo
bucketed = DataLoader(ds, batch_size=32, sampler=orden, collate_fn=collate_pad)

x, mask, y = next(iter(shuffled))
print(x.shape, mask.sum(1)[:5])
print("padding con shuffle:", padding_total(shuffled))
print("padding con bucketing:", padding_total(bucketed))

11. Fuentes y para seguir

• Tensors — Learn the Basics — el tutorial original de esta página; leelo para ver los ejemplos de indexado y las operaciones básicas que acá se dan por sabidas.
• Datasets & DataLoaders — Learn the Basics — el ejemplo completo de FashionMNIST con CustomImageDataset, con visualización de batches.
• Broadcasting semantics — la especificación formal de las tres reglas de §3, con los casos borde de in-place y broadcasting.
• torch.Tensor — dtypes — la tabla completa de dtypes disponibles, incluidos los fp8 y los empaquetados de baja precisión; consultala cuando dudes del nombre exacto.
• torch.utils.data — la referencia de DataLoader: samplers, IterableDataset, los detalles de multiprocessing por plataforma y la nota sobre pin_memory.
• torchao — la librería oficial de cuantización y baja precisión (int8, fp8, fp4/NVFP4) sobre PyTorch; el lugar donde mirar cuando quieras pasar de la tabla de §2 a código que corre.