theus-cli-linux-x64 1.2.2 → 1.3.0

package/vendor/theus-arsenal/skills/patrones-pytorch/SKILL.md

@@ -1,400 +0,0 @@
----
-name: patrones-pytorch
-description: Patrones y buenas prácticas de deep learning con PyTorch para construir pipelines de entrenamiento, arquitecturas de modelos y carga de datos robustos, eficientes y reproducibles.
----
-
-# Patrones de desarrollo con PyTorch
-
-Patrones idiomáticos de PyTorch y buenas prácticas para construir aplicaciones de deep learning robustas, eficientes y reproducibles.
-
-## Cuándo usarla
-
-- Al escribir nuevos modelos o scripts de entrenamiento en PyTorch
-- Al revisar código de deep learning
-- Al depurar bucles de entrenamiento o pipelines de datos
-- Al optimizar el uso de memoria de GPU o la velocidad de entrenamiento
-- Al montar experimentos reproducibles
-
-## Principios fundamentales
-
-### 1. Código agnóstico del dispositivo
-
-Escribe siempre código que funcione tanto en CPU como en GPU sin fijar el dispositivo a mano.
-
-```python
-# Bien: agnóstico del dispositivo
-device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-model = MyModel().to(device)
-data = data.to(device)
-
-# Mal: dispositivo fijado
-model = MyModel().cuda()  # Falla si no hay GPU
-data = data.cuda()
-```
-
-### 2. Reproducibilidad primero
-
-Fija todas las semillas aleatorias para obtener resultados reproducibles.
-
-```python
-# Bien: configuración completa de reproducibilidad
-def set_seed(seed: int = 42) -> None:
-    torch.manual_seed(seed)
-    torch.cuda.manual_seed_all(seed)
-    np.random.seed(seed)
-    random.seed(seed)
-    torch.backends.cudnn.deterministic = True
-    torch.backends.cudnn.benchmark = False
-
-# Mal: sin control de semillas
-model = MyModel()  # Pesos distintos en cada ejecución
-```
-
-### 3. Gestión explícita de shapes
-
-Documenta y verifica siempre las formas de los tensores.
-
-```python
-# Bien: forward anotado con shapes
-def forward(self, x: torch.Tensor) -> torch.Tensor:
-    # x: (batch_size, channels, height, width)
-    x = self.conv1(x)    # -> (batch_size, 32, H, W)
-    x = self.pool(x)     # -> (batch_size, 32, H//2, W//2)
-    x = x.view(x.size(0), -1)  # -> (batch_size, 32*H//2*W//2)
-    return self.fc(x)    # -> (batch_size, num_classes)
-
-# Mal: sin seguimiento de shapes
-def forward(self, x):
-    x = self.conv1(x)
-    x = self.pool(x)
-    x = x.view(x.size(0), -1)  # ¿De qué tamaño es esto?
-    return self.fc(x)           # ¿Siquiera va a funcionar?
-```
-
-## Patrones de arquitectura de modelos
-
-### Estructura limpia de nn.Module
-
-```python
-# Bien: módulo bien organizado
-class ImageClassifier(nn.Module):
-    def __init__(self, num_classes: int, dropout: float = 0.5) -> None:
-        super().__init__()
-        self.features = nn.Sequential(
-            nn.Conv2d(3, 64, kernel_size=3, padding=1),
-            nn.BatchNorm2d(64),
-            nn.ReLU(inplace=True),
-            nn.MaxPool2d(2),
-        )
-        self.classifier = nn.Sequential(
-            nn.Dropout(dropout),
-            nn.Linear(64 * 16 * 16, num_classes),
-        )
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.features(x)
-        x = x.view(x.size(0), -1)
-        return self.classifier(x)
-
-# Mal: todo en forward
-class ImageClassifier(nn.Module):
-    def __init__(self):
-        super().__init__()
-
-    def forward(self, x):
-        x = F.conv2d(x, weight=self.make_weight())  # ¡Crea los pesos en cada llamada!
-        return x
-```
-
-### Inicialización correcta de pesos
-
-```python
-# Bien: inicialización explícita
-def _init_weights(self, module: nn.Module) -> None:
-    if isinstance(module, nn.Linear):
-        nn.init.kaiming_normal_(module.weight, mode="fan_out", nonlinearity="relu")
-        if module.bias is not None:
-            nn.init.zeros_(module.bias)
-    elif isinstance(module, nn.Conv2d):
-        nn.init.kaiming_normal_(module.weight, mode="fan_out", nonlinearity="relu")
-    elif isinstance(module, nn.BatchNorm2d):
-        nn.init.ones_(module.weight)
-        nn.init.zeros_(module.bias)
-
-model = MyModel()
-model.apply(model._init_weights)
-```
-
-## Patrones de bucle de entrenamiento
-
-### Bucle de entrenamiento estándar
-
-```python
-# Bien: bucle de entrenamiento completo con buenas prácticas
-def train_one_epoch(
-    model: nn.Module,
-    dataloader: DataLoader,
-    optimizer: torch.optim.Optimizer,
-    criterion: nn.Module,
-    device: torch.device,
-    scaler: torch.amp.GradScaler | None = None,
-) -> float:
-    model.train()  # Establece siempre el modo de entrenamiento
-    total_loss = 0.0
-
-    for batch_idx, (data, target) in enumerate(dataloader):
-        data, target = data.to(device), target.to(device)
-
-        optimizer.zero_grad(set_to_none=True)  # Más eficiente que zero_grad()
-
-        # Entrenamiento con precisión mixta
-        with torch.amp.autocast("cuda", enabled=scaler is not None):
-            output = model(data)
-            loss = criterion(output, target)
-
-        if scaler is not None:
-            scaler.scale(loss).backward()
-            scaler.unscale_(optimizer)
-            torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
-            scaler.step(optimizer)
-            scaler.update()
-        else:
-            loss.backward()
-            torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
-            optimizer.step()
-
-        total_loss += loss.item()
-
-    return total_loss / len(dataloader)
-```
-
-### Bucle de validación
-
-```python
-# Bien: evaluación correcta
-@torch.no_grad()  # Más eficiente que envolverlo en un bloque torch.no_grad()
-def evaluate(
-    model: nn.Module,
-    dataloader: DataLoader,
-    criterion: nn.Module,
-    device: torch.device,
-) -> tuple[float, float]:
-    model.eval()  # Modo eval siempre — desactiva dropout y usa estadísticas acumuladas de BN
-    total_loss = 0.0
-    correct = 0
-    total = 0
-
-    for data, target in dataloader:
-        data, target = data.to(device), target.to(device)
-        output = model(data)
-        total_loss += criterion(output, target).item()
-        correct += (output.argmax(1) == target).sum().item()
-        total += target.size(0)
-
-    return total_loss / len(dataloader), correct / total
-```
-
-## Patrones de pipeline de datos
-
-### Dataset personalizado
-
-```python
-# Bien: Dataset limpio con anotaciones de tipos
-class ImageDataset(Dataset):
-    def __init__(
-        self,
-        image_dir: str,
-        labels: dict[str, int],
-        transform: transforms.Compose | None = None,
-    ) -> None:
-        self.image_paths = list(Path(image_dir).glob("*.jpg"))
-        self.labels = labels
-        self.transform = transform
-
-    def __len__(self) -> int:
-        return len(self.image_paths)
-
-    def __getitem__(self, idx: int) -> tuple[torch.Tensor, int]:
-        img = Image.open(self.image_paths[idx]).convert("RGB")
-        label = self.labels[self.image_paths[idx].stem]
-
-        if self.transform:
-            img = self.transform(img)
-
-        return img, label
-```
-
-### Configuración eficiente del DataLoader
-
-```python
-# Bien: DataLoader optimizado
-dataloader = DataLoader(
-    dataset,
-    batch_size=32,
-    shuffle=True,            # Barajar para entrenamiento
-    num_workers=4,           # Carga de datos en paralelo
-    pin_memory=True,         # Transferencia CPU->GPU más rápida
-    persistent_workers=True, # Mantiene los workers vivos entre épocas
-    drop_last=True,          # Batches de tamaño constante para BatchNorm
-)
-
-# Mal: valores por defecto lentos
-dataloader = DataLoader(dataset, batch_size=32)  # num_workers=0, sin pin_memory
-```
-
-### Collate personalizado para datos de longitud variable
-
-```python
-# Bien: rellenar secuencias en collate_fn
-def collate_fn(batch: list[tuple[torch.Tensor, int]]) -> tuple[torch.Tensor, torch.Tensor]:
-    sequences, labels = zip(*batch)
-    # Rellena hasta la longitud máxima del batch
-    padded = nn.utils.rnn.pad_sequence(sequences, batch_first=True, padding_value=0)
-    return padded, torch.tensor(labels)
-
-dataloader = DataLoader(dataset, batch_size=32, collate_fn=collate_fn)
-```
-
-## Patrones de checkpointing
-
-### Guardar y cargar checkpoints
-
-```python
-# Bien: checkpoint completo con todo el estado de entrenamiento
-def save_checkpoint(
-    model: nn.Module,
-    optimizer: torch.optim.Optimizer,
-    epoch: int,
-    loss: float,
-    path: str,
-) -> None:
-    torch.save({
-        "epoch": epoch,
-        "model_state_dict": model.state_dict(),
-        "optimizer_state_dict": optimizer.state_dict(),
-        "loss": loss,
-    }, path)
-
-def load_checkpoint(
-    path: str,
-    model: nn.Module,
-    optimizer: torch.optim.Optimizer | None = None,
-) -> dict:
-    checkpoint = torch.load(path, map_location="cpu", weights_only=True)
-    model.load_state_dict(checkpoint["model_state_dict"])
-    if optimizer:
-        optimizer.load_state_dict(checkpoint["optimizer_state_dict"])
-    return checkpoint
-
-# Mal: guardar solo los pesos (no se puede reanudar el entrenamiento)
-torch.save(model.state_dict(), "model.pt")
-```
-
-## Optimización de rendimiento
-
-### Entrenamiento con precisión mixta
-
-```python
-# Bien: AMP con GradScaler
-scaler = torch.amp.GradScaler("cuda")
-for data, target in dataloader:
-    with torch.amp.autocast("cuda"):
-        output = model(data)
-        loss = criterion(output, target)
-    scaler.scale(loss).backward()
-    scaler.step(optimizer)
-    scaler.update()
-    optimizer.zero_grad(set_to_none=True)
-```
-
-### Gradient checkpointing para modelos grandes
-
-```python
-# Bien: intercambiar cómputo por memoria
-from torch.utils.checkpoint import checkpoint
-
-class LargeModel(nn.Module):
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        # Recalcula las activaciones durante el backward para ahorrar memoria
-        x = checkpoint(self.block1, x, use_reentrant=False)
-        x = checkpoint(self.block2, x, use_reentrant=False)
-        return self.head(x)
-```
-
-### torch.compile para velocidad
-
-```python
-# Bien: compila el modelo para ejecución más rápida (PyTorch 2.0+)
-model = MyModel().to(device)
-model = torch.compile(model, mode="reduce-overhead")
-
-# Modos: "default" (seguro), "reduce-overhead" (más rápido), "max-autotune" (el más rápido)
-```
-
-## Referencia rápida: modismos de PyTorch
-
-| Modismo | Descripción |
-|---------|-------------|
-| `model.train()` / `model.eval()` | Establece siempre el modo antes de entrenar/evaluar |
-| `torch.no_grad()` | Desactiva gradientes para inferencia |
-| `optimizer.zero_grad(set_to_none=True)` | Limpieza de gradientes más eficiente |
-| `.to(device)` | Colocación de tensores/modelos agnóstica del dispositivo |
-| `torch.amp.autocast` | Precisión mixta para 2x de velocidad |
-| `pin_memory=True` | Transferencia de datos CPU→GPU más rápida |
-| `torch.compile` | Compilación JIT para velocidad (2.0+) |
-| `weights_only=True` | Carga segura de modelos |
-| `torch.manual_seed` | Experimentos reproducibles |
-| `gradient_checkpointing` | Intercambia cómputo por memoria |
-
-## Antipatrones a evitar
-
-```python
-# Mal: olvidar model.eval() durante la validación
-model.train()
-with torch.no_grad():
-    output = model(val_data)  # ¡Dropout sigue activo! ¡BatchNorm usa estadísticas del batch!
-
-# Bien: modo eval siempre
-model.eval()
-with torch.no_grad():
-    output = model(val_data)
-
-# Mal: operaciones in-place que rompen autograd
-x = F.relu(x, inplace=True)  # Puede romper el cálculo de gradientes
-x += residual                  # La suma in-place rompe el grafo de autograd
-
-# Bien: operaciones out-of-place
-x = F.relu(x)
-x = x + residual
-
-# Mal: mover datos a la GPU repetidamente dentro del bucle de entrenamiento
-for data, target in dataloader:
-    model = model.cuda()  # ¡Mueve el modelo en CADA iteración!
-
-# Bien: mover el modelo una sola vez antes del bucle
-model = model.to(device)
-for data, target in dataloader:
-    data, target = data.to(device), target.to(device)
-
-# Mal: usar .item() antes del backward
-loss = criterion(output, target).item()  # ¡Desconecta del grafo!
-loss.backward()  # Error: no se puede retropropagar a través de .item()
-
-# Bien: llamar .item() solo para registrar métricas
-loss = criterion(output, target)
-loss.backward()
-print(f"Pérdida: {loss.item():.4f}")  # .item() después del backward está bien
-
-# Mal: no usar torch.save correctamente
-torch.save(model, "model.pt")  # Guarda el modelo entero (frágil, no portable)
-
-# Bien: guardar el state_dict
-torch.save(model.state_dict(), "model.pt")
-```
-
-__Recuerda__: el código PyTorch debe ser agnóstico del dispositivo, reproducible y consciente de la memoria. Ante la duda, perfila con `torch.profiler` y revisa la memoria de GPU con `torch.cuda.memory_summary()`.
-
-## Componentes relacionados
-
-- Agente `resolutor-builds-pytorch` — para resolver errores de build/entorno de PyTorch
-- Agente `revisor-ml` — para revisiones de código de machine learning