26  Transformers en logística: casos prácticos

deep learning
transformers
preentrenamiento
audio
logística
Autor/a

Wilder Ramírez Delgado

Fecha de publicación

8 de noviembre de 2026

26.1 Qué vas a encontrar en este capítulo

Los capítulos de esta parte explicaron la atención, el transformer, su uso con imágenes y el audio. Este capítulo los lleva a la operación de BITLogística con dos casos resueltos de principio a fin. Los casos son independientes: cada uno tiene sus datos, su código y sus conclusiones, y se pueden leer en cualquier orden.

Caso Problema de la operación Qué entra a la red Qué sale Lo nuevo
1. Direcciones Los clientes escriben la dirección como quieren; una dirección mal separada es una entrega fallida Las palabras del mensaje Un campo por palabra (vía, número, cruce, placa…) Preentrenar con 60 000 mensajes sin etiquetar
2. Bodega Hay que encender una luz cuando suena la alarma de reversa de un montacargas y avisar cuando cae una caja Las columnas del espectrograma de 1 segundo Normal, alarma o golpe Avisos en audio continuo con una política de falsas alarmas

Dos franjas horizontales, una por caso. Cada franja tiene ocho pasos en fila: operación, datos, descriptivo, preparación, línea base, red, evaluación y decisión. En el caso 1, el paso de la red está resaltado con la nota: transformer preentrenado. En el caso 2, el de evaluación, con la nota: avisos por evento en turnos continuos.

Los dos casos como zonas independientes, con el mismo recorrido: la operación, los datos, el análisis descriptivo, la preparación, la línea base, la red, la evaluación y la decisión.

Ficha del capítulo

  • Tiempo estimado: unas 2 horas de lectura; la ejecución completa toma unos 8 minutos (5 del caso 1 y 3 del caso 2) en CPU.
  • Nivel: intermedio.
  • Conocimientos previos: Atención y transformers, ViT y multimodalidad, Audio y voz y LSTM y GRU.
  • Herramientas: PyTorch para las redes; NumPy, pandas, SciPy, scikit-learn y matplotlib para preparar los datos y analizar los resultados.

26.2 Objetivos de aprendizaje

  1. Armar un codificador transformer en PyTorch y reconocer sus parámetros en el código.
  2. Etiquetar cada palabra de un texto y comparar una regla, una GRU bidireccional y un transformer con el mismo protocolo.
  3. Preentrenar un transformer con texto sin etiquetas y medir cuánto ayuda cuando hay pocas etiquetas.
  4. Convertir audio en una secuencia de columnas del espectrograma y clasificarla con el mismo tipo de red.
  5. Escoger umbrales en validación con una política de operación y medir avisos por evento en audio continuo.
  6. Traducir los resultados en revisiones, entregas fallidas, falsas alarmas y pesos.
TipLo que necesitas recordar
Concepto En una línea Dónde se explica
Tensor, lote, época, pérdida, optimizador, semilla Las piezas de cualquier entrenamiento en PyTorch Apéndice A
Softmax y entropía cruzada De puntajes a probabilidades, y cómo se castiga el error Perceptrón y MLP
Entrenamiento, validación y prueba; precisión, sensibilidad, F1, matriz de confusión Cómo se evalúa sin engañarse Evaluación de modelos
Sobreajuste, dropout, parada temprana Cómo se evita memorizar Regularización y generalización
GRU y red bidireccional Una red recurrente que lee en los dos sentidos LSTM y GRU
Atención, consulta, llave, valor, cabezas, máscara de relleno, codificación de posición, bloque transformer Cómo cada elemento mira a los demás Atención y transformers
Trozos de imagen como tokens; preentrenamiento y adaptación Cualquier secuencia de piezas sirve de entrada; un modelo se entrena primero en general y después se adapta ViT y multimodalidad
Muestra, tasa de muestreo, ventana, espectrograma Cómo se convierte el sonido en números Audio y voz

26.3 Caso práctico 1: Separar en campos las direcciones que escriben los clientes

AdvertenciaEmpresa y datos ficticios

BITLogística es una empresa ficticia. Los mensajes de este caso salen de un simulador, simulador_direcciones.py, con reglas sencillas que puedes leer al final del caso. No corresponden a BIT ni a ningún cliente real, y los costos son supuestos del ejercicio.

La red de este caso: un transformer. Un transformer es una red que lee todas las palabras de un texto a la vez y, para entender cada una, mira a las demás y decide cuáles le importan. Se usa principalmente en traducción, buscadores, asistentes que conversan y reconocimiento de voz. Se basa en la atención: cada palabra le pregunta a las otras «¿me ayudas a saber qué soy?». En este caso, el número «93» de «frente al parque de la 93» mira a «parque» y «frente» para saber que es parte de una referencia y no el número de la calle.

Hay un segundo ingrediente que explica por qué los transformers están en todas partes: el preentrenamiento. Antes de aprender la tarea con pocos ejemplos etiquetados a mano, el transformer lee muchos textos sin etiquetar y aprende cómo se escriben. Este caso lo muestra con números.

Cómo se ve en Python. El transformer no se programa desde cero: viene en PyTorch, dentro de torch.nn. Un bloque se crea con una línea y otra línea apila los bloques:

  • d_model=64: el tamaño del vector que representa cada palabra. Más grande da más capacidad, pero pide más datos y más cálculo.
  • nhead=4: cuántas cabezas de atención tiene cada bloque. Cada cabeza puede fijarse en una relación distinta (una en el número que sigue, otra en la palabra que lo anuncia). d_model debe ser divisible por nhead: aquí cada cabeza trabaja con 64 / 4 = 16 números.
  • dim_feedforward=128: el tamaño de la red densa que procesa cada palabra después de la atención.
  • dropout=0.1: apaga al azar el 10 % de los valores al entrenar, para que la red no memorice.
  • batch_first=True: los datos llegan en el orden (mensajes, palabras, números por palabra).
  • num_layers=2: cuántos bloques se apilan. Con 2, una palabra puede usar lo que otra ya averiguó de sus vecinas.

Antes del codificador, nn.Embedding convierte cada palabra en sus 64 números y otra nn.Embedding agrega la posición de la palabra. Después, nn.Linear(64, 9) convierte el vector de cada palabra en 9 puntajes, uno por etiqueta.

Arriba, cuatro cajas con flechas hacia el código: d_model, el tamaño del vector de cada palabra, resaltado; nhead, cuántas cabezas de atención; dim_feedforward, la red densa por palabra; num_layers, cuántos bloques. Abajo, las líneas capa igual a nn.TransformerEncoderLayer con d_model 64, nhead 4, dim_feedforward 128, dropout 0.1 y batch_first True; codificador igual a nn.TransformerEncoder con capa y num_layers 2; y salida igual a nn.Linear de 64 a 9. Una nota dice: busca estas líneas en la celda Aquí se arma la red del caso.

Las líneas que arman el transformer del caso y qué significa cada parámetro.

Cada caso empieza con su propia configuración: se puede ejecutar solo, sin haber ejecutado el otro.

# 1. Librerías del caso.
import copy
import math
import platform
import re
import time
from collections import Counter
from pathlib import Path

import matplotlib
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import sklearn
import torch
from sklearn.metrics import precision_recall_fscore_support
from torch import nn
from torch.nn.utils.rnn import pad_sequence, pack_padded_sequence, pad_packed_sequence

from simulador_direcciones import (BARRIOS_CONOCIDOS, BARRIOS_RESERVADOS, COMPLEMENTOS,
                                   ETIQUETAS, VIAS, generar_direcciones, sin_tildes,
                                   tokenizar)

# 2. Semilla, CPU y carpeta de artefactos.
SEMILLA = 42
torch.manual_seed(SEMILLA)
torch.set_num_threads(2)
inicio_caso1 = time.perf_counter()
artefactos = Path("artefactos_pytorch/caso1")
artefactos.mkdir(parents=True, exist_ok=True)
print(f"Python {platform.python_version()} · PyTorch {torch.__version__} · "
      f"NumPy {np.__version__} · pandas {pd.__version__} · scikit-learn {sklearn.__version__}")
Python 3.13.16 · PyTorch 2.14.1+cu130 · NumPy 2.5.4 · pandas 3.1.0 · scikit-learn 1.9.1

26.3.1 El problema en la operación

Cuando un cliente crea un envío en la web o por WhatsApp, escribe la dirección de destino como texto libre: «cra 15 #93-47 apto 302 torre b», «Calle 93 No. 15 - 47 Int 2», «hola, es en kr15 93 47 ofi 501 frente al parque de la 93». El modelo recibe ese texto, no una imagen: el caso no lee escritura a mano, separa una cadena de texto en campos.

El sistema de rutas necesita la dirección separada en campos: tipo de vía, número de la vía, número del cruce, número de la placa, complemento, número del complemento y barrio. Con los cuatro primeros se ubica el punto en el mapa (geocodificación); con los demás el conductor llega a la puerta correcta.

NotaNomenclatura de direcciones en Bogotá

Las calles corren de oriente a occidente y se numeran de sur a norte; las carreras corren de sur a norte y se numeran de oriente a occidente. «Calle 93 # 15-47» quiere decir: sobre la calle 93, cerca del cruce con la carrera 15, a unos 47 metros de la esquina. Por eso el orden de los números importa: 93 es la vía, 15 el cruce y 47 la placa.

  • Hoy lo hace una regla que escribió el equipo de sistemas: reconoce los nombres de vía y sus abreviaturas, los números que siguen, los complementos y un catálogo de barrios. Funciona con las direcciones bien escritas y falla con las desordenadas.
  • Cuando la regla falla, una persona de servicio al cliente revisa la dirección a mano o, peor, la dirección sale mal y la entrega falla.
  • Etiquetar a mano es caro. Para entrenar una red, alguien debe marcar el campo de cada palabra. BITLogística pagó el etiquetado de 3 000 direcciones. En cambio, tiene 60 000 mensajes de envíos pasados sin etiquetar.
NotaEtiquetado de secuencias

Tarea en la que la red asigna una etiqueta a cada elemento de una secuencia, no una sola etiqueta a toda la secuencia. En «cra 15 # 93 - 47», cra es VIA, 15 es NUM_VIA, 93 es NUM_CRUCE, 47 es NUM_PLACA, y # y - son OTRO. El capítulo de atención clasificó mensajes completos; aquí se etiqueta palabra por palabra.

Las cifras de negocio son supuestos del ejercicio, iguales en todo el caso:

Supuesto Valor Por qué
Envíos diarios en Bogotá 8 000 Escala de una operación urbana mediana
Costo de una revisión manual $1 500 Unos 3 minutos de una persona de servicio al cliente
Costo de una dirección mal leída que sale a ruta $14 000 Reintento, llamada al cliente y, a veces, devolución

¿Puede un transformer separar los campos mejor que la regla y que una GRU, cuando solo hay 3 000 direcciones etiquetadas, y cuánto le ahorra eso a la operación?

Cuatro cajas en fila: el cliente escribe la dirección como texto libre; el modelo etiqueta cada palabra; se verifica que estén los cuatro campos para ubicar el punto y que la confianza sea suficiente; la dirección va a rutas o a revisión manual. Debajo, una caja aparte: 60 000 mensajes sin etiquetar sirven para preentrenar el transformer.

El recorrido de una dirección: el cliente escribe, el modelo separa los campos, una regla verifica que estén completos y la dirección va a rutas o a revisión manual.

26.3.2 Los datos

El simulador produce cinco conjuntos, cada uno con su propia semilla:

  • Etiquetadas (3 000): las que se pagaron para etiquetar. Se usan para entrenar.
  • Validación (1 000): también etiquetadas; sirven para escoger la época y el umbral de revisión.
  • Prueba (2 400): mensajes como los de cualquier día. Un tercio de los barrios de este conjunto son barrios reservados: 15 barrios que no aparecen en ninguna dirección etiquetada.
  • Prueba difícil (2 400): más errores de tipeo y más bloques fuera de orden.
  • Histórico (60 000): mensajes de envíos pasados sin etiquetas. Incluye todos los barrios de la ciudad, también los reservados, porque son direcciones de clientes; lo que falta es que alguien haya marcado sus campos.
# 1. Los cinco conjuntos del caso, cada uno con su semilla.
conjuntos = {"etiquetadas": 3000, "validacion": 1000, "prueba": 2400, "dificil": 2400}
datos = {}
for i, (nombre, cantidad) in enumerate(conjuntos.items()):
    particion = "entrenamiento" if nombre == "etiquetadas" else nombre
    datos[nombre] = generar_direcciones(cantidad, SEMILLA + i, particion)
historico = generar_direcciones(60000, SEMILLA + 10, "historico")
historico = [fila["palabras"] for fila in historico]       # del histórico solo se usan las palabras

# 2. Comprobaciones: los barrios reservados no aparecen en nada etiquetado antes de la prueba.
assert not set(BARRIOS_CONOCIDOS) & set(BARRIOS_RESERVADOS)
for nombre in ["etiquetadas", "validacion"]:
    assert not any(fila["barrio_reservado"] for fila in datos[nombre])
reservados_prueba = [fila for fila in datos["prueba"] if fila["barrio_reservado"]]
print({nombre: len(filas) for nombre, filas in datos.items()}, "· histórico:", len(historico))
print("Direcciones de prueba con barrio reservado:", len(reservados_prueba))
{'etiquetadas': 3000, 'validacion': 1000, 'prueba': 2400, 'dificil': 2400} · histórico: 60000
Direcciones de prueba con barrio reservado: 311
  • Hay 3 000 direcciones etiquetadas, 1 000 de validación y 2 400 en cada prueba, más 60 000 mensajes del histórico sin etiquetas: 20 veces más texto sin etiquetar que etiquetado, una proporción común en una empresa.
  • 311 de las 2 400 direcciones de prueba (13 %) traen un barrio reservado: ninguna dirección etiquetada lo contiene. Esas 311 miden si el método funciona con barrios que solo conoce de oídas, por el histórico.

26.3.3 Análisis descriptivo

Antes de cualquier modelo, mira cómo escriben los clientes. La primera tabla pone 8 mensajes al lado de sus campos.

# 1. Campos de una dirección: juntar las palabras de cada etiqueta.
CAMPOS = ("VIA", "NUM_VIA", "NUM_CRUCE", "NUM_PLACA", "COMPLEMENTO", "NUM_COMPLEMENTO", "BARRIO")


def campos_de(palabras, etiquetas):
    """Un diccionario campo → texto, con las palabras que tienen esa etiqueta."""
    return {campo: " ".join(p for p, e in zip(palabras, etiquetas) if e == campo)
            for campo in CAMPOS}


# 2. Ocho mensajes de las etiquetadas con sus campos de referencia.
ejemplos = pd.DataFrame([{"mensaje": f["texto"], **campos_de(f["palabras"], f["etiquetas"])}
                         for f in datos["etiquetadas"][:8]])
pd.set_option("display.max_colwidth", 70)
ejemplos
mensaje VIA NUM_VIA NUM_CRUCE NUM_PLACA COMPLEMENTO NUM_COMPLEMENTO BARRIO
0 buen día , es EN, kr172B# 18 - 70 kr 172B 18 70
1 cl137 no128C 14 of512, La Felicidad cl 137 128C 14 of 512 La Felicidad
2 la dirección es cl100#90 - 17, int330 local446, OLAYA cl 100 90 17 int local 330 446 OLAYA
3 kra134 # 135 12 SANTA Cecilia kra 134 135 12 SANTA Cecilia
4 por favor, cl167#179- 16 int 875 a media cuadra de la 3 cl 167 179 16 int 875
5 la dirección es cl119 72 -15 barrio Villa Alsacia, al lado de la p... cl 119 72 15 Villa Alsacia
6 cll20B 125-72 LOCAL897 diagonal al colegio, TEL3556111505 cll 20B 125 72 LOCAL 897
7 ENVÍO para, carrera94 87 30 carrera 94 87 30

Los 8 mensajes muestran por qué una regla se queda corta:

  • Abreviaturas distintas para lo mismo: kr, kra, cl, cll y carrera aparecen en solo 8 mensajes.
  • Números pegados y separadores que cambian: «cl137 no128C 14», «cl119 72 -15», «kra134 # 135 12». En el segundo no hay separador entre el número de la vía y el cruce.
  • Dos complementos seguidos («int330 local446»): el campo COMPLEMENTO queda «int local» y su número «330 446».
  • Barrios en mayúsculas o mezcladas («OLAYA», «SANTA Cecilia») y sin la palabra «barrio» delante.
  • Ruido que no es dirección: saludos («buen día, es EN»), un teléfono pegado («TEL3556111505») y una referencia («al lado de la panadería»).
# 1. Largo de los mensajes y frecuencia de cada etiqueta en las etiquetadas.
etiquetadas = datos["etiquetadas"]
largos = pd.Series([len(f["palabras"]) for f in etiquetadas])
print("Palabras por mensaje:", largos.describe()[["mean", "50%", "min", "max"]].round(1).to_dict())
conteo_etiquetas = Counter(e for f in etiquetadas for e in f["etiquetas"])
print(pd.Series(conteo_etiquetas).sort_values(ascending=False).to_string())

# 2. Cuántas formas distintas usan los clientes para escribir «carrera» y el separador.
formas_carrera = Counter(sin_tildes(f["forma_via"].lower()) for f in etiquetadas
                         if f["forma_via"].lower() in ("carrera", *VIAS["carrera"]))
separadores = Counter(f["separador"] or "(ninguno)" for f in etiquetadas)
print("Formas de «carrera»:", dict(formas_carrera))
print("Separadores:", dict(separadores))
Palabras por mensaje: {'mean': 11.7, '50%': 11.0, 'min': 4.0, 'max': 27.0}
OTRO               11464
REFERENCIA          4413
VIA                 3382
NUM_VIA             3338
NUM_CRUCE           3000
NUM_PLACA           3000
COMPLEMENTO         2366
NUM_COMPLEMENTO     2366
BARRIO              1646
Formas de «carrera»: {'kr': 210, 'kra': 216, 'carrera': 342, 'cra': 171, 'cr': 215}
Separadores: {'#': 1179, 'no': 484, '(ninguno)': 596, 'N°': 308, 'No.': 433}
  • Los mensajes tienen 11.7 palabras en promedio, entre 4 y 27. El largo cambia mucho porque los bloques opcionales (complementos, barrio, referencia, saludo, teléfono) aparecen o no.
  • OTRO es la etiqueta más común (11 464 palabras) y BARRIO la menos común (1 646): hay pocos ejemplos de barrios, y por eso es el campo más difícil.
  • «Carrera» aparece de 5 formas: carrera (342), kra (216), cr (215), kr (210) y cra (171). Ninguna domina.
  • El separador también varía: # en 1 179 mensajes, ninguno en 596, «no» en 484, «No.» en 433 y «N°» en 308. Una regla tiene que anticipar cada forma; una red las aprende de los ejemplos.

26.3.4 Preparación de los datos

Una red no lee texto: lee números. La preparación tiene 3 pasos.

  1. Normalizar: minúsculas y sin tildes, porque «Chicó», «CHICO» y «chico» son la misma palabra. Los errores de tipeo no se corrigen: son justamente lo que el modelo debe tolerar.
  2. Representar los números por su forma. Los números no caben en un vocabulario (hay miles de placas distintas), y lo que importa para el campo no es el valor sino la forma y el lugar: 93 se convierte en <NUM2> (dos dígitos), 93A en <NUM2L> (dos dígitos y una letra) y un celular de 10 dígitos en <NUM4> (cuatro o más dígitos). Es una de las decisiones que más ayuda al modelo, y se justifica porque una placa 47 y una placa 52 cumplen el mismo papel.
  3. Vocabulario: la lista de palabras conocidas, cada una con su número. Se construye con el histórico, que no tiene etiquetas y por eso no revela nada de la prueba. Se guardan las palabras que aparecen al menos 3 veces; las demás se convierten en <DESCONOCIDA>. Hay además <RELLENO> para completar los lotes y <MASCARA> para el preentrenamiento.

Como los mensajes tienen largos distintos, cada lote se rellena hasta el mensaje más largo. La máscara de relleno le dice a la atención que no mire esas posiciones, y en la pérdida se marcan con -100, el valor que nn.CrossEntropyLoss ignora con ignore_index.

# 1. De palabra a «token»: minúsculas, sin tildes y números por su forma.
def normalizar(palabra):
    return sin_tildes(palabra.lower())


def representar(palabra):
    palabra = normalizar(palabra)
    numero = re.fullmatch(r"(\d+)([a-z]?)", palabra)
    if numero:
        digitos, letra = numero.groups()
        return f"<NUM{min(len(digitos), 4)}{'L' if letra else ''}>"   # 93A → <NUM2L>
    return palabra


# 2. Vocabulario con el histórico (sin etiquetas): palabras que aparecen 3 veces o más.
conteo = Counter(representar(p) for palabras in historico for p in palabras)
vocabulario = {"<RELLENO>": 0, "<DESCONOCIDA>": 1, "<MASCARA>": 2}
for token, veces in sorted(conteo.items()):
    if veces >= 3:
        vocabulario[token] = len(vocabulario)
RELLENO, DESCONOCIDA, MASCARA = 0, 1, 2
id_etiqueta = {etiqueta: i for i, etiqueta in enumerate(ETIQUETAS)}


# 3. Un lote: identificadores de palabras y de etiquetas, rellenados al mismo largo.
def a_ids(palabras):
    return torch.tensor([vocabulario.get(representar(p), DESCONOCIDA) for p in palabras])


def preparar(filas):
    x = pad_sequence([a_ids(f["palabras"]) for f in filas], batch_first=True,
                     padding_value=RELLENO)
    y = pad_sequence([torch.tensor([id_etiqueta[e] for e in f["etiquetas"]]) for f in filas],
                     batch_first=True, padding_value=-100)        # -100: la pérdida lo ignora
    return x, y


def lotes(filas, tamano, mezclar=False, rng=None):
    """Recorre las filas en lotes; al entrenar, en un orden al azar distinto cada época."""
    orden = rng.permutation(len(filas)) if mezclar else np.arange(len(filas))
    for i in range(0, len(filas), tamano):
        yield [filas[j] for j in orden[i:i + tamano]]


# 4. Cifras de la preparación.
desconocidas = np.mean([vocabulario.get(representar(p), 1) == 1
                        for f in datos["prueba"] for p in f["palabras"]])
x, y = preparar(etiquetadas[:4])
print("Tamaño del vocabulario:", len(vocabulario))
print(f"Palabras de prueba fuera del vocabulario: {100 * desconocidas:.2f} %")
print("«cra15#93A-47» →", [representar(p) for p in ["cra", "15", "#", "93A", "-", "47"]])
print("Formas de un lote de 4 mensajes:", tuple(x.shape), tuple(y.shape))
Tamaño del vocabulario: 854
Palabras de prueba fuera del vocabulario: 0.24 %
«cra15#93A-47» → ['cra', '<NUM2>', '#', '<NUM2L>', '-', '<NUM2>']
Formas de un lote de 4 mensajes: (4, 16) (4, 16)
  • El vocabulario tiene 854 entradas: las 3 especiales y 851 palabras que aparecen al menos 3 veces en el histórico.
  • Solo el 0.24 % de las palabras de prueba queda fuera del vocabulario, casi todas con errores de tipeo raros. Los barrios reservados sí están en el vocabulario, porque el histórico los trae. Lo que no existe es un ejemplo etiquetado que diga que son barrios.
  • «cra15#93A-47» se convierte en cra, <NUM2>, #, <NUM2L>, -, <NUM2>: el tokenizador separa lo que el cliente pegó y los números quedan por su forma.
  • Un lote de 4 mensajes tiene forma (4, 16) en la entrada y en las etiquetas: 16 es el largo del mensaje más largo del lote; los demás se rellenan.

26.3.5 Una línea base sin red neuronal

La regla es la que usaría un ingeniero que conoce la nomenclatura: no está hecha para perder. Recorre el mensaje en 5 pasos:

  1. marca como referencia lo que empieza con palabras de inicio como «frente», «cerca», «lado», «portería» o «edificio», hasta la siguiente coma o el siguiente bloque que reconozca;
  2. marca como OTRO los teléfonos («cel», «tel», «llamar al» y el número que sigue);
  3. busca un nombre de vía (o una abreviatura) seguido de un número, y toma ese número como NUM_VIA, el siguiente como NUM_CRUCE y el que sigue como NUM_PLACA, saltando separadores como #, No. o -;
  4. reconoce los complementos (apto, torre, int…) seguidos de un número;
  5. busca los barrios de su catálogo: los 45 barrios que conoce, es decir, los que aparecen en las direcciones etiquetadas.
# 1. Lo que conoce la regla: alias de vías y complementos, palabras de referencia y barrios.
alias_via = sorted({tuple(normalizar(p) for p in nombre.split())
                    for via, alias in VIAS.items() for nombre in (via, *alias)},
                   key=len, reverse=True)                     # primero los de dos palabras
alias_complemento = {normalizar(a) for nombre, alias in COMPLEMENTOS.items()
                     for a in (nombre, *alias)}
inicio_referencia = {"frente", "cerca", "lado", "porteria", "edificio", "entregar", "media"}
catalogo_barrios = sorted([tuple(normalizar(p) for p in b.split()) for b in BARRIOS_CONOCIDOS],
                          key=len, reverse=True)
es_numero = re.compile(r"\d+[a-z]?").fullmatch
SEPARADORES = {"#", "no", "n", "°", ".", "-"}


def regla(palabras):
    p = [normalizar(x) for x in palabras]
    etiquetas = ["OTRO"] * len(p)
    libre = [True] * len(p)                                   # posiciones aún sin campo

    # 2. Referencias: desde la palabra de inicio hasta una coma.
    i = 0
    while i < len(p):
        if p[i] in inicio_referencia:
            while i < len(p) and p[i] != ",":
                etiquetas[i], libre[i] = "REFERENCIA", False
                i += 1
        i += 1
    # 3. Teléfonos: la palabra que lo anuncia y el número que sigue quedan como OTRO.
    for i in range(len(p) - 1):
        if p[i] in ("cel", "tel", "al") and es_numero(p[i + 1]) and len(p[i + 1]) >= 7:
            libre[i] = libre[i + 1] = False
    # 4. Vía: alias seguido de número; después cruce y placa, saltando separadores.
    for i in range(len(p)):
        via = next((a for a in alias_via if tuple(p[i:i + len(a)]) == a
                    and all(libre[i:i + len(a)])), None)
        fin = i + len(via) if via else i
        if not via or fin >= len(p) or not es_numero(p[fin]):
            continue
        etiquetas[i:fin] = ["VIA"] * len(via)
        etiquetas[fin] = "NUM_VIA"
        j = fin + 1
        if j < len(p) and p[j] in ("bis", "sur", "este"):
            etiquetas[j] = "NUM_VIA"
            j += 1
        for campo in ("NUM_CRUCE", "NUM_PLACA"):
            while j < len(p) and p[j] in SEPARADORES:
                j += 1
            if j < len(p) and es_numero(p[j]) and libre[j]:
                etiquetas[j] = campo
                j += 1
        for k in range(i, j):
            libre[k] = False
        break                                                 # solo una dirección por mensaje
    # 5. Complementos: alias seguido de número.
    for i in range(len(p) - 1):
        if p[i] in alias_complemento and libre[i] and es_numero(p[i + 1]) and libre[i + 1]:
            etiquetas[i], etiquetas[i + 1] = "COMPLEMENTO", "NUM_COMPLEMENTO"
            libre[i] = libre[i + 1] = False
    # 6. Barrios del catálogo, con o sin la palabra «barrio» antes.
    for i in range(len(p)):
        for barrio in catalogo_barrios:
            fin = i + len(barrio)
            if tuple(p[i:fin]) == barrio and all(libre[i:fin]):
                etiquetas[i:fin] = ["BARRIO"] * len(barrio)
                break
    return etiquetas


ejemplo = "hola, kr15 #93-47 apto 302 frente al parque de la 93"
print(list(zip(tokenizar(ejemplo), regla(tokenizar(ejemplo)))))
[('hola', 'OTRO'), (',', 'OTRO'), ('kr', 'VIA'), ('15', 'NUM_VIA'), ('#', 'OTRO'), ('93', 'NUM_CRUCE'), ('-', 'OTRO'), ('47', 'NUM_PLACA'), ('apto', 'COMPLEMENTO'), ('302', 'NUM_COMPLEMENTO'), ('frente', 'REFERENCIA'), ('al', 'REFERENCIA'), ('parque', 'REFERENCIA'), ('de', 'REFERENCIA'), ('la', 'REFERENCIA'), ('93', 'REFERENCIA')]

En el mensaje de ejemplo la regla acierta todo: kr es la vía, 15 el número, 93 el cruce, 47 la placa, «apto 302» el complemento, y reconoce que el último 93 es parte de la referencia «frente al parque de la 93». Es una regla seria: lo que falle después no será por descuido.

26.3.6 Diseño de la red

Se comparan tres redes con el mismo tamaño de vector (64) y el mismo protocolo de entrenamiento:

  • GRU bidireccional (del capítulo 20): lee el mensaje de izquierda a derecha y de derecha a izquierda, y junta las dos lecturas en cada palabra. Responde la pregunta obvia: ¿para qué un transformer si ya sé usar una GRU?
  • Transformer desde cero: el codificador de dos bloques, entrenado solo con las 3 000 direcciones etiquetadas.
  • Transformer preentrenado: la misma red, pero antes lee las 60 000 direcciones del histórico con la tarea de adivinar palabras ocultas, y después se ajusta con las 3 000 etiquetadas.

De izquierda a derecha: un mensaje de 12 palabras entra como 12 números; nn.Embedding y la posición lo convierten en 12 vectores de 64; dos bloques transformer los mantienen en 12 por 64; nn.Linear da 12 por 9 puntajes, una etiqueta por palabra. Debajo, la cabeza de preentrenamiento: nn.Linear de 64 al tamaño del vocabulario, que solo se usa para adivinar palabras ocultas.

El recorrido de un mensaje dentro del transformer: palabras, vector de 64 números con su posición, dos bloques de atención y 9 puntajes por palabra.
ImportanteAquí se arma la red del caso

La clase TransformerDirecciones tiene las líneas de la figura «Cómo se ve en Python»: nn.TransformerEncoderLayer(d_model=64, nhead=4, dim_feedforward=128, dropout=0.1, batch_first=True), nn.TransformerEncoder(capa, num_layers=2) y nn.Linear(64, len(ETIQUETAS)). La cabeza adivinar_palabra solo se usa en el preentrenamiento.

# 1. El transformer: palabra + posición → 2 bloques → 9 puntajes por palabra.
class TransformerDirecciones(nn.Module):
    def __init__(self):
        super().__init__()
        self.palabra = nn.Embedding(len(vocabulario), 64, padding_idx=RELLENO)
        self.posicion = nn.Embedding(64, 64)                   # hasta 64 palabras por mensaje
        capa = nn.TransformerEncoderLayer(d_model=64, nhead=4, dim_feedforward=128,
                                          dropout=0.1, batch_first=True)
        self.codificador = nn.TransformerEncoder(capa, num_layers=2,
                                                 enable_nested_tensor=False)
        self.salida = nn.Linear(64, len(ETIQUETAS))           # 64 → 9 etiquetas
        self.adivinar_palabra = nn.Linear(64, len(vocabulario))   # solo para preentrenar

    def codificar(self, x):
        posiciones = torch.arange(x.shape[1])
        z = self.palabra(x) + self.posicion(posiciones)       # (lote, palabras, 64)
        return self.codificador(z, src_key_padding_mask=x.eq(RELLENO))   # no mira el relleno

    def forward(self, x):
        return self.salida(self.codificar(x))                 # (lote, palabras, 9)


# 2. La GRU bidireccional: misma entrada de 64; 64 por dirección → 128 → 9.
class GRUDirecciones(nn.Module):
    def __init__(self):
        super().__init__()
        self.palabra = nn.Embedding(len(vocabulario), 64, padding_idx=RELLENO)
        self.gru = nn.GRU(input_size=64, hidden_size=64, bidirectional=True, batch_first=True)
        self.salida = nn.Linear(128, len(ETIQUETAS))

    def forward(self, x):
        largos = x.ne(RELLENO).sum(1)                         # la GRU salta el relleno
        z = pack_padded_sequence(self.palabra(x), largos, batch_first=True,
                                 enforce_sorted=False)
        z, _ = self.gru(z)
        z, _ = pad_packed_sequence(z, batch_first=True, total_length=x.shape[1])
        return self.salida(z)


# 3. Parámetros de cada red (sin la cabeza de preentrenamiento, que no se usa al etiquetar).
def parametros(red):
    return sum(p.numel() for n, p in red.named_parameters() if not n.startswith("adivinar"))


print("GRU bidireccional:", parametros(GRUDirecciones()))
print("Transformer:", parametros(TransformerDirecciones()))
print("Cabeza de preentrenamiento:", sum(p.numel() for p in
                                         TransformerDirecciones().adivinar_palabra.parameters()))
GRU bidireccional: 105737
Transformer: 126281
Cabeza de preentrenamiento: 55510
  • La GRU tiene 105 737 parámetros y el transformer 126 281, un 19 % más. Las dos comparten la tabla de palabras: 854 × 64 = 54 656 parámetros.
  • El transformer suma la tabla de posiciones: 64 posiciones × 64 = 4 096 parámetros.
  • La cabeza de preentrenamiento tiene 55 510 parámetros (64 × 854 + 854): un puntaje por palabra del vocabulario. Se descarta al etiquetar.

26.3.7 Preentrenamiento: aprender a leer direcciones sin etiquetas

NotaPreentrenamiento con palabras ocultas

Se toma un texto, se ocultan al azar algunas palabras (aquí el 15 %) y la red debe adivinarlas mirando las demás. No hace falta que nadie etiquete nada: la respuesta es la palabra que estaba ahí. Para adivinar bien «cra 15 # - 47», la red tiene que aprender que después de # viene un número. Así aprende cómo se escribe una dirección. Es la idea con la que se entrenan los modelos de lenguaje modernos (BERT la popularizó en 2019), y la que el capítulo de visión llamó preentrenamiento y adaptación.

El preentrenamiento usa la cabeza adivinar_palabra: un puntaje por cada palabra del vocabulario en cada posición oculta. Recorre las 60 000 direcciones del histórico 8 veces (unos 3 minutos en CPU).

# 1. Preentrenar: ocultar el 15 % de las palabras y adivinarlas.
def preentrenar(red, epocas=8, proporcion=0.15):
    torch.manual_seed(SEMILLA)
    rng = np.random.default_rng(SEMILLA)
    optimizador = torch.optim.AdamW(red.parameters(), lr=1e-3, weight_decay=0.01)
    historial = []
    for epoca in range(1, epocas + 1):
        red.train()
        suma, n = 0.0, 0
        for lote in lotes(historico, 128, mezclar=True, rng=rng):
            x = pad_sequence([a_ids(p) for p in lote], batch_first=True, padding_value=RELLENO)
            ocultas = (torch.rand(x.shape) < proporcion) & x.ne(RELLENO)   # qué se oculta
            respuesta = x.masked_fill(~ocultas, -100)          # solo se puntúan las ocultas
            entrada = x.masked_fill(ocultas, MASCARA)          # la red ve <MASCARA>
            optimizador.zero_grad()
            puntajes = red.adivinar_palabra(red.codificar(entrada))
            perdida = nn.functional.cross_entropy(puntajes.transpose(1, 2), respuesta,
                                                  ignore_index=-100)
            perdida.backward()
            optimizador.step()
            suma += perdida.item()
            n += 1
        historial.append(suma / n)
        print(f"época {epoca}: pérdida media {suma / n:.3f}")
    return historial


t0 = time.perf_counter()
preentrenado = TransformerDirecciones()
historial_preentrenamiento = preentrenar(preentrenado)
print(f"Tiempo de preentrenamiento: {time.perf_counter() - t0:.0f} s")
época 1: pérdida media 3.010
época 2: pérdida media 1.717
época 3: pérdida media 1.387
época 4: pérdida media 1.270
época 5: pérdida media 1.212
época 6: pérdida media 1.176
época 7: pérdida media 1.138
época 8: pérdida media 1.119
Tiempo de preentrenamiento: 172 s
  • La pérdida baja de 3.010 a 1.119 en las 8 épocas. Como referencia, adivinar al azar entre 854 palabras daría una pérdida de ln(854) = 6.75.
  • En la última época todavía baja (de 1.138 a 1.119), pero cada vez menos. Más épocas ayudarían poco y alargarían la ejecución.
  • Los 60 000 mensajes se leyeron 8 veces en 177 segundos, sin una sola etiqueta.

Para ver qué aprendió, se oculta 1 palabra en 3 mensajes nuevos y se miran las 3 palabras que la red propone para cada hueco.

# 1. Ocultar una palabra y ver las 3 palabras más probables según la red preentrenada.
def adivinar(palabras, posicion):
    x = a_ids(palabras).unsqueeze(0)
    x[0, posicion] = MASCARA
    preentrenado.eval()
    with torch.no_grad():
        probabilidades = preentrenado.adivinar_palabra(preentrenado.codificar(x))[0, posicion]
        probabilidades = probabilidades.softmax(-1)
    mejores = probabilidades.topk(3)
    palabras_vocabulario = list(vocabulario)
    return [(palabras_vocabulario[i], round(float(p), 3))
            for p, i in zip(mejores.values, mejores.indices)]


for mensaje, posicion in [("cra 15 # 93 - 47 apto 302", 0),
                          ("calle 80 # 20 - 15 barrio la cabrera", 8),
                          ("kr 7 # 45 - 10 frente al parque de la 93", 8)]:
    palabras = tokenizar(mensaje)
    print(f"{mensaje!r}: se oculta «{palabras[posicion]}» →", adivinar(palabras, posicion))
'cra 15 # 93 - 47 apto 302': se oculta «cra» → [('cll', 0.156), ('cl', 0.149), ('calle', 0.133)]
'calle 80 # 20 - 15 barrio la cabrera': se oculta «cabrera» → [('soledad', 0.253), ('uribe', 0.194), ('felicidad', 0.192)]
'kr 7 # 45 - 10 frente al parque de la 93': se oculta «parque» → [('parque', 0.994), ('lado', 0.003), ('colegio', 0.0)]
  • Si se oculta «cra», la red propone cll (0.156), cl (0.149) y calle (0.133). No puede saber si era calle o carrera, porque las dos son válidas ahí, pero sí sabe que ahí va un tipo de vía.
  • Si se oculta «cabrera» en «barrio la cabrera», propone soledad, uribe y felicidad: barrios que empiezan con «La» (La Soledad, La Uribe, La Felicidad). Nadie le enseñó qué es un barrio; lo dedujo del histórico.
  • Si se oculta «parque» en «frente al parque de la 93», acierta con 0.994 de probabilidad: conoce las referencias típicas.

Esto es lo que la red trae aprendido antes de ver la primera de las 3 000 direcciones etiquetadas.

26.3.8 Entrenamiento

Las tres redes se entrenan con el mismo protocolo, con las 3 000 direcciones etiquetadas:

  • AdamW, una variante de Adam que además encoge un poco los pesos en cada paso (weight_decay=0.01), una regularización suave.
  • Calentamiento de la tasa de aprendizaje: la tasa sube en línea recta de casi 0 a su valor durante los primeros 100 pasos (un poco más de una época) y después se queda fija. Los transformers son sensibles a pasos grandes al comienzo, cuando la atención todavía es aleatoria; el calentamiento lo evita. Para que la comparación sea justa, la GRU usa lo mismo.
  • Tasa de 0.001 para la GRU y el transformer desde cero, y 0.0005 para el preentrenado: la mitad, para ajustar sin borrar lo que aprendió leyendo el histórico.
  • Lotes de 32, hasta 40 épocas, el mejor estado según la pérdida de validación y parada temprana con paciencia de 6 épocas.
# 1. Entrenar una red para etiquetar, con el mismo protocolo para las tres.
def entrenar(red, tasa, epocas=40, paciencia=6, calentamiento=100):
    torch.manual_seed(SEMILLA)
    rng = np.random.default_rng(SEMILLA)
    pesos = [p for n, p in red.named_parameters() if not n.startswith("adivinar")]
    optimizador = torch.optim.AdamW(pesos, lr=tasa, weight_decay=0.01)
    # 2. Calentamiento: la tasa sube en línea recta durante los primeros pasos y se queda fija.
    calendario = torch.optim.lr_scheduler.LambdaLR(
        optimizador, lambda paso: min(1.0, (paso + 1) / calentamiento))
    perdida = nn.CrossEntropyLoss(ignore_index=-100)
    historial = []
    mejor = {"perdida": float("inf"), "epoca": 0, "estado": None}
    for epoca in range(1, epocas + 1):
        # 3. Una pasada por las 3 000 etiquetadas.
        red.train()
        for lote in lotes(etiquetadas, 32, mezclar=True, rng=rng):
            x, y = preparar(lote)
            optimizador.zero_grad()
            error = perdida(red(x).transpose(1, 2), y)        # (lote, 9, palabras) contra (lote, palabras)
            error.backward()
            nn.utils.clip_grad_norm_(pesos, 1.0)              # evita pasos desmedidos
            optimizador.step()
            calendario.step()
        # 4. Pérdida por palabra en entrenamiento y validación.
        red.eval()
        with torch.no_grad():
            valores = []
            for filas in (etiquetadas, datos["validacion"]):
                x, y = preparar(filas)
                valores.append(perdida(red(x).transpose(1, 2), y).item())
        historial.append((epoca, *valores))
        # 5. Mejor estado y parada temprana.
        if valores[1] < mejor["perdida"]:
            mejor = {"perdida": valores[1], "epoca": epoca,
                     "estado": copy.deepcopy(red.state_dict())}
        elif epoca - mejor["epoca"] >= paciencia:
            break
    red.load_state_dict(mejor["estado"])
    return pd.DataFrame(historial, columns=["época", "entrenamiento", "validación"]), mejor["epoca"]


# 6. Las tres redes.
redes, historiales, resumen = {}, {}, []
for nombre, red, tasa in [("GRU", GRUDirecciones(), 1e-3),
                          ("Transformer desde cero", TransformerDirecciones(), 1e-3),
                          ("Transformer preentrenado", preentrenado, 5e-4)]:
    t0 = time.perf_counter()
    historiales[nombre], epoca = entrenar(red, tasa)
    redes[nombre] = red
    resumen.append({"red": nombre, "épocas ejecutadas": len(historiales[nombre]),
                    "mejor época": epoca,
                    "pérdida de validación": round(historiales[nombre].loc[epoca - 1, "validación"], 4),
                    "segundos": round(time.perf_counter() - t0)})
resumen = pd.DataFrame(resumen)
assert (resumen["mejor época"] < 40).all(), "alguna red quedó en el límite de épocas"
resumen
red épocas ejecutadas mejor época pérdida de validación segundos
0 GRU 34 28 0.0027 39
1 Transformer desde cero 19 13 0.0261 25
2 Transformer preentrenado 29 23 0.0055 38
  • Ninguna red llegó al límite de 40 épocas: la GRU paró en la 34 con su mejor época en la 28, el transformer desde cero en la 19 (mejor, la 13) y el preentrenado en la 29 (mejor, la 23).
  • La pérdida de validación del transformer desde cero (0.0261) es casi 10 veces la de la GRU (0.0027) y casi 5 veces la del preentrenado (0.0055). Con solo 3 000 ejemplos, el transformer sin preentrenar aprende peor.
  • Cada entrenamiento tomó entre 26 y 41 segundos: el costo grande fue el preentrenamiento.
fig, ejes = plt.subplots(1, 3, figsize=(12, 3.4), sharey=True)
for eje, (nombre, h) in zip(ejes, historiales.items()):
    eje.plot(h["época"], h["entrenamiento"], "-", color="#1786B3", label="entrenamiento")
    eje.plot(h["época"], h["validación"], "--", color="#EE5400", label="validación")
    eje.set(title=nombre, xlabel="época", yscale="log")
ejes[0].set_ylabel("pérdida por palabra")
ejes[0].legend()
plt.tight_layout()
plt.show()
Tres paneles, uno por red. En cada uno, la pérdida de entrenamiento en línea continua y la de validación en línea discontinua, en escala logarítmica, contra la época. El transformer desde cero queda más arriba que los otros dos en validación.
Figura 26.1: Pérdida por palabra en entrenamiento y validación de las tres redes
  • En el transformer desde cero la brecha es la más grande: la pérdida de entrenamiento sigue bajando hasta la última época, mientras la de validación se estanca cerca de 0.026 desde la época 8. Está memorizando las 3 000 direcciones en lugar de aprender a leerlas.
  • La GRU y el preentrenado bajan mucho más en validación. El preentrenado llega a la zona baja en pocas épocas, porque empieza sabiendo cómo se escribe una dirección.
  • Los saltos del preentrenado al final (épocas 26 a 29) son pasos grandes del optimizador. La parada temprana conservó la época 23, antes de ellos.

26.3.9 Evaluación

La prueba se usa una sola vez, ahora. Se miden 2 cosas por dirección, por separado:

  • Campos para geocodificar correctos: VIA, NUM_VIA, NUM_CRUCE y NUM_PLACA coinciden con los valores de referencia. El caso mide la extracción de campos, no la ubicación: saber si el punto en el mapa es correcto exigiría pasar la dirección por un geocodificador y comparar coordenadas, y eso queda fuera del caso.
  • Todos los campos correctos: además el complemento, su número y el barrio. Un error en el apartamento o la torre puede hacer fallar la entrega aunque el punto en el mapa sea el correcto: el conductor llega al edificio, pero no a la puerta.

Se reportan cuatro grupos: la prueba normal, la difícil, las direcciones de prueba con barrio reservado y las que traen una referencia con número («frente al parque de la 93»).

# 1. Predecir: etiqueta y confianza (probabilidad de la etiqueta escogida) de cada palabra.
def predecir(metodo, filas):
    if metodo == "Regla":
        return [(regla(f["palabras"]), [1.0] * len(f["palabras"])) for f in filas]
    red = redes[metodo]
    red.eval()
    salida = []
    with torch.no_grad():
        for lote in lotes(filas, 256):
            x, _ = preparar(lote)
            confianza, ids = red(x).softmax(-1).max(-1)
            for fila, i_fila, c_fila in zip(lote, ids, confianza):
                n = len(fila["palabras"])
                salida.append(([ETIQUETAS[i] for i in i_fila[:n].tolist()], c_fila[:n].tolist()))
    return salida


# 2. ¿Coinciden los campos? Primero los 4 para geocodificar, después los 7.
GEOCODIFICAR = CAMPOS[:4]


def aciertos(fila, etiquetas):
    real = campos_de(fila["palabras"], fila["etiquetas"])
    estimado = campos_de(fila["palabras"], etiquetas)
    geo = all(normalizar(real[c]) == normalizar(estimado[c]) for c in GEOCODIFICAR)
    todos = all(normalizar(real[c]) == normalizar(estimado[c]) for c in CAMPOS)
    return geo, todos


# 3. Los cuatro grupos de evaluación.
grupos = {"prueba normal": datos["prueba"], "prueba difícil": datos["dificil"],
          "barrios reservados": reservados_prueba,
          "referencia con número": [f for f in datos["prueba"] if f["referencia_con_numero"]]}
METODOS = ["Regla", "GRU", "Transformer desde cero", "Transformer preentrenado"]
predicciones = {m: {g: predecir(m, filas) for g, filas in grupos.items()} for m in METODOS}

filas_tabla = []
for metodo in METODOS:
    for grupo, filas in grupos.items():
        resultado = np.array([aciertos(f, e) for f, (e, _) in zip(filas, predicciones[metodo][grupo])])
        filas_tabla.append({"método": metodo, "grupo": f"{grupo} ({len(filas)})",
                            "geocodificar (%)": 100 * resultado[:, 0].mean(),
                            "todos los campos (%)": 100 * resultado[:, 1].mean()})
tabla_direcciones = pd.DataFrame(filas_tabla)
tabla_direcciones.to_csv(artefactos / "direcciones.csv", index=False)
tabla_direcciones.pivot(index="grupo", columns="método", values="todos los campos (%)")[METODOS].round(1)
método Regla GRU Transformer desde cero Transformer preentrenado
grupo
barrios reservados (311) 0.0 70.1 55.0 92.9
prueba difícil (2400) 64.5 91.6 80.7 93.9
prueba normal (2400) 79.6 94.8 89.7 98.0
referencia con número (337) 78.6 97.0 84.0 98.5

La tabla muestra el porcentaje de direcciones con todos los campos correctos. La comparación tiene 4 lecturas:

  • El transformer preentrenado gana en los cuatro grupos: 98.0 % en la prueba normal, frente a 94.8 % de la GRU, 89.7 % del transformer desde cero y 79.6 % de la regla.
  • La mayor diferencia está en los barrios reservados: 92.9 % frente a 70.1 % de la GRU. La GRU nunca vio esos barrios etiquetados y los confunde. El preentrenado los conoce del histórico.
  • Sin preentrenar, el transformer pierde contra la GRU en todo (89.7 % frente a 94.8 % en la normal; 55.0 % frente a 70.1 % en barrios reservados). Con pocas etiquetas, la atención por sí sola no basta.
  • La regla obtiene 0 % en barrios reservados: no están en su catálogo, así que nunca recupera el campo barrio. En la prueba difícil cae a 64.5 %.
# 1. La otra métrica: los 4 campos para geocodificar.
tabla_direcciones.pivot(index="grupo", columns="método", values="geocodificar (%)")[METODOS].round(1)
método Regla GRU Transformer desde cero Transformer preentrenado
grupo
barrios reservados (311) 97.4 99.4 96.8 99.7
prueba difícil (2400) 83.8 98.7 92.5 97.7
prueba normal (2400) 95.6 99.7 98.0 99.6
referencia con número (337) 94.1 100.0 97.3 100.0

Con los 4 campos para geocodificar, la historia cambia:

  • La GRU y el preentrenado empatan en la prueba normal (99.7 % y 99.6 %), y en la difícil la GRU queda un poco arriba (98.7 % frente a 97.7 %).
  • La ventaja del preentrenado está en el barrio y el complemento, no en el núcleo de la dirección. Para ubicar el punto en el mapa, la GRU basta. Para que el conductor llegue a la puerta correcta, conviene el preentrenado.
  • La regla ubica bien el 95.6 % en la normal, pero solo el 83.8 % en la difícil: los errores de tipeo en «carrera» o «calle» le hacen perder la vía.

¿En qué etiquetas está la diferencia? La F1 por etiqueta en la prueba normal lo muestra.

# 1. F1 por etiqueta en la prueba normal, para los cuatro métodos.
real = [e for f in datos["prueba"] for e in f["etiquetas"]]
f1 = {}
for metodo in METODOS:
    estimado = [e for etiquetas, _ in predicciones[metodo]["prueba normal"] for e in etiquetas]
    _, _, valores, _ = precision_recall_fscore_support(real, estimado, labels=list(ETIQUETAS),
                                                      zero_division=0)
    f1[metodo] = valores
pd.DataFrame(f1, index=ETIQUETAS).round(3)
Regla GRU Transformer desde cero Transformer preentrenado
VIA 0.979 0.999 0.994 0.999
NUM_VIA 0.979 1.000 0.999 1.000
NUM_CRUCE 0.979 1.000 0.997 1.000
NUM_PLACA 0.979 1.000 0.998 0.999
COMPLEMENTO 0.978 0.998 0.986 0.999
NUM_COMPLEMENTO 0.978 0.999 0.999 0.999
BARRIO 0.754 0.958 0.924 0.985
REFERENCIA 0.805 0.994 0.980 0.998
OTRO 0.899 0.995 0.993 0.998
  • En los campos del núcleo (VIA, NUM_VIA, NUM_CRUCE, NUM_PLACA) las tres redes superan 0.99 de F1. La regla queda en 0.979.
  • La diferencia está en BARRIO: 0.985 del preentrenado, 0.958 de la GRU, 0.924 del transformer desde cero y 0.754 de la regla.
  • En REFERENCIA la regla tiene 0.805: sus palabras de inicio no cubren todos los casos («al lado del…» empieza con «al») y a veces la referencia se come el bloque siguiente cuando no hay coma.

26.3.9.1 Qué mira la atención

La figura muestra los pesos de atención de una cabeza del último bloque del transformer preentrenado, en un mensaje con una referencia que trae un número. Cada fila es una palabra que «pregunta» y cada columna una palabra que «responde»; el punto naranja marca a quién le presta más atención cada palabra.

# 1. Los pesos de atención del último bloque para un mensaje.
def pesos_atencion(red, palabras, cabeza):
    x = a_ids(palabras).unsqueeze(0)
    red.eval()
    with torch.no_grad():
        z = red.palabra(x) + red.posicion(torch.arange(x.shape[1]))
        for bloque in red.codificador.layers[:-1]:
            z = bloque(z)
        ultimo = red.codificador.layers[-1]
        _, pesos = ultimo.self_attn(z, z, z, need_weights=True, average_attn_weights=False)
    return pesos[0, cabeza].numpy()


# 2. Un mensaje con referencia con número, bien etiquetado por el preentrenado.
red_final = redes["Transformer preentrenado"]
mensaje = next(f for f, (e, _) in zip(grupos["referencia con número"],
                                      predicciones["Transformer preentrenado"]["referencia con número"])
               if aciertos(f, e)[1] and len(f["palabras"]) <= 16)
palabras = mensaje["palabras"]
pesos = pesos_atencion(red_final, palabras, cabeza=0)

fig, eje = plt.subplots(figsize=(7, 6))
imagen = eje.imshow(pesos, cmap="Blues", vmin=0)
eje.set_xticks(range(len(palabras)), palabras, rotation=60, ha="right")
eje.set_yticks(range(len(palabras)), palabras)
for fila, columna in enumerate(pesos.argmax(1)):
    eje.plot(columna, fila, "o", color="#EE5400", markersize=5)
eje.set(xlabel="palabra que responde", ylabel="palabra que pregunta")
fig.colorbar(imagen, ax=eje, label="peso de atención")
plt.tight_layout()
plt.show()
print("Etiquetas de referencia:", mensaje["etiquetas"])
Una matriz de palabras contra palabras para un mensaje con una referencia que trae un número. Cada celda es el peso de atención, más oscuro cuanto más alto, y un punto naranja marca el mayor peso de cada fila.
Figura 26.2: Pesos de atención de una cabeza del último bloque del transformer preentrenado
Etiquetas de referencia: ['VIA', 'NUM_VIA', 'OTRO', 'NUM_CRUCE', 'NUM_PLACA', 'REFERENCIA', 'REFERENCIA', 'REFERENCIA', 'REFERENCIA', 'REFERENCIA', 'REFERENCIA']

El mensaje es «cra 22 # 48 78 frente AL parque de la 63», y el 63 es parte de la referencia:

  • La mayoría de las palabras atienden sobre todo a la siguiente: «cra» a «22», «frente» a «AL», «de» a «la». Esta cabeza aprendió a mirar a la derecha.
  • «63» reparte su atención entre «la» y «AL», dos palabras de la referencia. Las dos están lejos de los números de la dirección.
  • «22» y «#» miran a «48»: el número de la vía y el separador se relacionan con el cruce que viene.
AdvertenciaLa atención no es una explicación

Que una palabra atienda mucho a otra no prueba que esa otra haya causado la decisión: la red tiene varias cabezas, dos bloques y una red densa después de la atención. Para saber si una palabra importa hay que intervenir: cambiar el mensaje y ver si cambia la etiqueta. Es la misma advertencia del capítulo de visión.

La intervención: en el mismo mensaje se borran las palabras de la referencia que van antes del número, de modo que el número queda solo, y se mira qué etiqueta recibe.

# 1. Borrar el contexto de la referencia y volver a etiquetar.
def etiquetar(palabras):
    falsa = {"palabras": palabras, "etiquetas": ["OTRO"] * len(palabras)}
    return predecir("Transformer preentrenado", [falsa])[0][0]


posiciones = [i for i, e in enumerate(mensaje["etiquetas"]) if e == "REFERENCIA"]
numero = next(i for i in posiciones if palabras[i].isdigit())
sin_contexto = [p for i, p in enumerate(palabras) if not (i in posiciones and i < numero)]
antes = etiquetar(palabras)
despues = etiquetar(sin_contexto)
print("Con la referencia completa:", list(zip(palabras, antes))[numero - 2:numero + 1])
print("Sin las palabras de la referencia:", [(p, e) for p, e in zip(sin_contexto, despues)
                                            if p == palabras[numero]])
Con la referencia completa: [('de', 'REFERENCIA'), ('la', 'REFERENCIA'), ('63', 'REFERENCIA')]
Sin las palabras de la referencia: [('63', 'NUM_PLACA')]
  • Con la referencia completa, el 63 recibe la etiqueta REFERENCIA.
  • Sin las palabras «frente al parque de la», el mismo 63 pasa a NUM_PLACA. La red ve un número suelto después de «48 78» y lo toma como otra placa. El contexto de la referencia era lo que decidía la etiqueta: ahora sí hay evidencia de que esas palabras importan.

Por último, 8 mensajes de la prueba difícil que el transformer preentrenado etiquetó con algún campo mal.

# 1. Ocho mensajes de la prueba difícil con algún campo mal, y el primer campo que falló.
errores = []
for fila, (etiquetas, _) in zip(grupos["prueba difícil"],
                                predicciones["Transformer preentrenado"]["prueba difícil"]):
    real = campos_de(fila["palabras"], fila["etiquetas"])
    estimado = campos_de(fila["palabras"], etiquetas)
    campo = next((c for c in CAMPOS if normalizar(real[c]) != normalizar(estimado[c])), None)
    if campo:
        errores.append({"mensaje": fila["texto"], "campo": campo,
                        "referencia": real[campo], "red": estimado[campo]})
    if len(errores) == 8:
        break
pd.DataFrame(errores)
mensaje campo referencia red
0 buen dia , es en, carrera55B SXR8 80 toxre581, LOCAL1 NUM_VIA 55B SXR 55B
1 avda kr 154 sux 65 84 NUM_VIA 154 sux 154
2 buen día , ES en, cll180 # 167- 50 int760, barrio Lucero Bajo entr... BARRIO Lucero Bajo Lucero Bajo entregar
3 Clarett calle84 N ° 192 42 apto842 VIA calle Clarett calle
4 xnt 781 carrerx6 No . 11 -43 Quiroga, A media cuadra DE la84 VIA carrerx xnt carrerx
5 BUENAS tardes cr189B 2 42 ofi377 barrioo Multicentro BARRIO Multicentro
6 Toberín kr102 # 19C 43, LOCAL126 tel3769779020 VIA kr Toberín kr
7 avda CALLE 118 este 162C-21 Castxlla llamar antes BARRIO Castxlla

Los 8 errores caen en 3 grupos:

  • Errores de tipeo que crean palabras nuevas: «xnt» (por «int») queda pegado a la vía, «SXR» (por «sur») no se reconoce como parte del número de la vía y «sux» tampoco.
  • Barrios con errores o en un lugar raro: «Castxlla», «barrioo Multicentro» y «Clarett» (Claret con una t de más, al comienzo del mensaje) se pierden o contagian a la vía.
  • Fronteras de bloque sin coma: en «Lucero Bajo entregar…», la red alarga el barrio con la palabra siguiente.

Son errores que también cometería una persona apurada. La regla de revisión debe atraparlos antes de que salgan a ruta.

26.3.10 De la predicción a la decisión de operación

Un diagrama de decisión. Primera pregunta: ¿están los cuatro campos para geocodificar, una sola vez cada uno? Si no, revisión manual. Si sí, segunda pregunta: ¿la palabra menos segura de esos campos supera el umbral? Si no, revisión manual; si sí, va a rutas. Las direcciones que van a rutas con algún campo mal se convierten en entregas fallidas.

De los campos a la decisión: si falta un campo indispensable o la confianza es baja, la dirección va a revisión; si no, va directo a rutas.

La regla de operación tiene dos condiciones, y basta una para mandar la dirección a revisión manual:

  1. Falta un campo indispensable: el modelo no asignó ninguna palabra a VIA o a NUM_VIA, o no asignó exactamente un número a NUM_CRUCE y uno a NUM_PLACA. Esto va a revisión siempre, aunque las demás etiquetas tengan confianza alta. Se aplica igual a la regla y a las redes, para que la comparación sea justa.
  2. Confianza baja: la palabra menos segura del mensaje tiene una probabilidad menor que un umbral. Se mira todo el mensaje, y no solo los cuatro campos para geocodificar, porque un barrio o un apartamento mal etiquetados también hacen fallar la entrega. Solo aplica a las redes; la regla no da probabilidades.

Si no se cumple ninguna, la dirección va directo a rutas. Si sale a rutas con cualquier campo mal, incluido el complemento, se cuenta como entrega fallida: es el error que el conductor sufre en la puerta. El umbral de cada red se escoge en validación, el que da el menor costo total.

# 1. ¿Va a revisión? Condición 1 (falta un campo) y confianza mínima de los campos indispensables.
def revisar(palabras, etiquetas, confianza):
    falta = any(sum(1 for e in etiquetas if e == campo) != 1 for campo in ("NUM_CRUCE", "NUM_PLACA"))
    falta |= not any(e == "VIA" for e in etiquetas)
    falta |= not any(e == "NUM_VIA" and p[0].isdigit() for p, e in zip(palabras, etiquetas))
    minima = min(confianza)                                   # la palabra menos segura del mensaje
    return falta, minima


def evaluar_politica(filas, prediccion, umbral):
    """Cuenta revisiones (por campo faltante y por confianza) y entregas fallidas."""
    por_campo = por_confianza = fallidas = 0
    for fila, (etiquetas, confianza) in zip(filas, prediccion):
        falta, minima = revisar(fila["palabras"], etiquetas, confianza)
        if falta:
            por_campo += 1
        elif minima < umbral:
            por_confianza += 1
        elif not aciertos(fila, etiquetas)[1]:
            fallidas += 1                                     # salió a rutas con un campo mal
    costo = 1500 * (por_campo + por_confianza) + 14000 * fallidas
    return {"revisión por campo": por_campo, "revisión por confianza": por_confianza,
            "fallidas": fallidas, "costo": costo}


# 2. Umbral de cada red escogido en validación: el de menor costo.
UMBRALES = np.round(np.arange(0, 1.0, 0.05), 2)
umbral, curvas = {"Regla": 0.0}, {}
for metodo in METODOS[1:]:
    prediccion_val = predecir(metodo, datos["validacion"])
    costos = [evaluar_politica(datos["validacion"], prediccion_val, u)["costo"] for u in UMBRALES]
    curvas[metodo] = costos
    umbral[metodo] = float(UMBRALES[int(np.argmin(costos))])
print("Umbral elegido en validación:", umbral)

# 3. Robustez: cuántas direcciones de validación cambian de decisión con el umbral vecino.
for metodo in METODOS[1:]:
    prediccion_val = predecir(metodo, datos["validacion"])
    minimas = np.array([revisar(f["palabras"], e, c)[1]
                        for f, (e, c) in zip(datos["validacion"], prediccion_val)])
    i = int(np.flatnonzero(UMBRALES == umbral[metodo])[0])
    cambios = [int(((minimas < umbral[metodo]) != (minimas < UMBRALES[k])).sum())
               for k in (i - 1, i + 1) if 0 <= k < len(UMBRALES)]
    print(f"{metodo}: decisiones que cambian con los umbrales vecinos: {cambios}")
Umbral elegido en validación: {'Regla': 0.0, 'GRU': 0.95, 'Transformer desde cero': 0.95, 'Transformer preentrenado': 0.8}
GRU: decisiones que cambian con los umbrales vecinos: [9]
Transformer desde cero: decisiones que cambian con los umbrales vecinos: [29]
Transformer preentrenado: decisiones que cambian con los umbrales vecinos: [3, 4]
  • La GRU y el transformer desde cero escogen 0.95, el umbral más alto probado: les conviene mandar mucho a revisión porque se equivocan seguido. Puede que prefirieran uno aún más alto, que la grilla no incluye.
  • El preentrenado escoge 0.80.
  • El umbral del preentrenado es estable: con los vecinos (0.75 y 0.85) cambian solo 3 y 4 de las 1 000 decisiones de validación. Con la GRU, bajar a 0.90 cambia 9, y con el transformer desde cero, 29.
fig, eje = plt.subplots(figsize=(7.5, 3.5))
for (metodo, costos), estilo in zip(curvas.items(), ["-o", "--s", "-^"]):
    eje.plot(UMBRALES, np.array(costos) / 1000, estilo, markersize=4, label=metodo)
eje.set(xlabel="umbral de confianza", ylabel="costo en validación (miles de $)")
eje.legend()
plt.tight_layout()
plt.show()
Tres curvas de costo contra el umbral, una por red, con estilos de línea distintos. Las curvas son planas para umbrales bajos y suben cuando el umbral se acerca a 1, porque casi todo va a revisión.
Figura 26.3: Costo de revisiones y entregas fallidas en validación según el umbral de confianza
  • El transformer desde cero cuesta más de $500 000 en validación con umbrales bajos y baja hasta unos $250 000 con 0.95: depende de la revisión para no fallar.
  • La GRU y el preentrenado están mucho más abajo (entre unos $60 000 y $120 000), y sus curvas se cruzan varias veces: en validación, con 1 000 direcciones, la diferencia entre los dos es pequeña. La prueba, con 2 400 direcciones, lo aclara.

Ahora sí, la política se aplica en la prueba normal y se lleva a los 8 000 envíos de un día.

# 1. Costo diario de cada método en la prueba normal, llevado a 8 000 envíos.
factor = 8000 / len(datos["prueba"])
filas_costo = []
for metodo in METODOS:
    r = evaluar_politica(datos["prueba"], predicciones[metodo]["prueba normal"], umbral[metodo])
    filas_costo.append({"método": metodo, "umbral": umbral[metodo],
                        "revisiones por día": round(factor * (r["revisión por campo"]
                                                              + r["revisión por confianza"])),
                        "  por campo faltante": round(factor * r["revisión por campo"]),
                        "  por confianza": round(factor * r["revisión por confianza"]),
                        "entregas fallidas por día": round(factor * r["fallidas"]),
                        "costo diario ($)": round(factor * r["costo"])})
tabla_costos = pd.DataFrame(filas_costo).set_index("método")
tabla_costos.to_csv(artefactos / "costos.csv")
tabla_costos
umbral revisiones por día por campo faltante por confianza entregas fallidas por día costo diario ($)
método
Regla 0.00 337 337 0 1293 18611667
GRU 0.95 917 10 907 103 2821667
Transformer desde cero 0.95 1137 93 1043 313 6091667
Transformer preentrenado 0.80 120 13 107 107 1673333

En pesos por día, para 8 000 envíos:

  • La regla cuesta $18.6 millones al día: manda 337 direcciones a revisión y deja salir 1 293 con algún campo mal.
  • La GRU cuesta $2.8 millones: para fallar poco (103 entregas fallidas), revisa 917 direcciones al día, casi todas por confianza baja.
  • El transformer preentrenado cuesta $1.7 millones: falla en un número parecido (107), pero revisa solo 120. Ahorra $1.1 millones al día frente a la GRU y $16.9 millones frente a la regla.
  • El transformer desde cero ($6.1 millones) queda en medio: revisa 1 137 al día y aun así falla en 313.

La lección de negocio: con pocas etiquetas, preentrenar con el texto que la empresa ya tiene es lo que convierte al transformer en la mejor opción.

Antes de cerrar, se guarda el modelo con todo lo que hace falta para usarlo (vocabulario, etiquetas, umbral) y se comprueba que al cargarlo da lo mismo.

# 1. Guardar el transformer preentrenado y ajustado, con sus metadatos.
ruta = artefactos / "transformer_direcciones.pt"
torch.save({"pesos": red_final.state_dict(), "vocabulario": vocabulario,
            "etiquetas": ETIQUETAS, "umbral": umbral["Transformer preentrenado"],
            "semilla": SEMILLA}, ruta)

# 2. Cargarlo en una red nueva y comparar las predicciones en 50 mensajes de validación.
paquete = torch.load(ruta, weights_only=True)
copia = TransformerDirecciones()
copia.load_state_dict(paquete["pesos"])
copia.eval()
x, _ = preparar(datos["validacion"][:50])
with torch.no_grad():
    assert torch.equal(copia(x).argmax(-1), red_final(x).argmax(-1))
print(f"Modelo guardado ({ruta.stat().st_size / 1024:.0f} KB) y recargado sin cambios.")
print(f"Tiempo total del caso: {time.perf_counter() - inicio_caso1:.0f} s")
Modelo guardado (737 KB) y recargado sin cambios.
Tiempo total del caso: 287 s

26.3.11 Errores frecuentes en este caso

Dos errores fáciles de cometer, medidos sobre el mismo modelo ya entrenado, en las 1 000 direcciones de validación:

  1. Preparar distinto al usar el modelo. Al poner el modelo en producción, alguien olvida la función representar y pasa los números tal cual: 93 en lugar de <NUM2>.
  2. Olvidar la posición. Se calcula la entrada sin sumar posicion. La atención no sabe de orden: sin la posición, «cra 15 93 47» y «cra 47 93 15» se ven iguales.
# 1. Error 1: los números entran sin representar (como palabras desconocidas).
def con_numeros_crudos(palabras):
    return torch.tensor([vocabulario.get(normalizar(p), DESCONOCIDA) for p in palabras])


# 2. Error 2: la entrada sin la posición.
def sin_posicion(red, x):
    return red.salida(red.codificador(red.palabra(x), src_key_padding_mask=x.eq(RELLENO)))


def porcentaje_completo(entradas, calcular):
    red_final.eval()
    bien = 0
    with torch.no_grad():
        for fila, x in zip(datos["validacion"], entradas):
            etiquetas = [ETIQUETAS[i] for i in calcular(x.unsqueeze(0))[0].argmax(-1).tolist()]
            bien += aciertos(fila, etiquetas)[1]
    return 100 * bien / len(datos["validacion"])


normales = [a_ids(f["palabras"]) for f in datos["validacion"]]
crudas = [con_numeros_crudos(f["palabras"]) for f in datos["validacion"]]
pd.DataFrame({"condición": ["preparación correcta", "números sin representar", "sin posición"],
              "todos los campos (%)": [porcentaje_completo(normales, red_final),
                                       porcentaje_completo(crudas, red_final),
                                       porcentaje_completo(normales,
                                                           lambda x: sin_posicion(red_final, x))]}
             ).round(1)
condición todos los campos (%)
0 preparación correcta 99.0
1 números sin representar 50.5
2 sin posición 0.0
  • Sin representar los números, el porcentaje de direcciones completas cae de 99.0 % a 50.5 %. Cada número llega como <DESCONOCIDA> y la red solo puede adivinar por la posición.
  • Sin la posición cae a 0.0 %. Sin orden, la red no puede distinguir el número de la vía del cruce ni de la placa: el mensaje queda como una bolsa de palabras.
Lo que ves Qué pasó Cómo se arregla
El modelo funcionaba en el notebook y en producción falla con casi todas las direcciones La preparación de producción no es la misma del entrenamiento (los números entran crudos) Guardar la preparación junto al modelo y usar la misma función en los dos lugares
La red confunde cruce, placa y número de vía Falta la posición: para la atención, el mensaje es una bolsa de palabras Sumar la codificación de posición antes del codificador
El transformer desde cero rinde menos que la GRU Pocos datos etiquetados para una red que no trae ninguna idea previa del orden Preentrenar con texto sin etiquetas o, si no lo hay, usar la GRU
El umbral escogido cambia mucho al volver a entrenar Se escogió con pocas direcciones de validación o mirando la prueba Escogerlo solo en validación y reportar cuántas decisiones cambian con umbrales vecinos

26.3.12 Conclusiones del caso

  • Con solo 3 000 direcciones etiquetadas, el transformer preentrenado recupera todos los campos en el 98.0 % de la prueba normal y en el 92.9 % de los barrios que nunca vio etiquetados. La GRU, en el 94.8 % y el 70.1 %.
  • Sin preentrenar, el transformer pierde contra la GRU. La ventaja viene de los 60 000 mensajes sin etiquetar, no de la arquitectura sola.
  • Para ubicar el punto en el mapa, la GRU basta (99.7 % frente a 99.6 %). El preentrenado gana en lo que hace llegar al conductor a la puerta: barrio y complemento.
  • En la operación, el preentrenado cuesta $1.7 millones al día frente a $2.8 de la GRU y $18.6 de la regla, con un umbral de revisión estable (3 y 4 decisiones cambian con los vecinos).

¿Qué se lleva el lector de este caso? Que, con 3 000 etiquetas, la ventaja práctica del transformer no está solo en la atención, sino en que se puede preentrenar con texto sin etiquetas, que casi toda empresa tiene en abundancia. Con pocas etiquetas, un transformer sin preentrenar no le gana a una GRU; preentrenado, sí, y sobre todo en lo que nunca vio etiquetado. Y que una red es solo una parte del sistema: la regla de revisión y su umbral, escogidos en validación, deciden cuánto cuesta cada error.

Límites del caso. Los mensajes son simulados con un número limitado de formatos; los clientes reales escriben de formas más variadas. El costo supone que toda dirección con un campo mal termina en entrega fallida, lo que exagera un poco: a veces el conductor resuelve por teléfono. La GRU también se podría preentrenar, aunque en la práctica casi todos los modelos preentrenados disponibles son transformers.

26.3.13 Ejercicios del caso

  1. Sube las etiquetadas de 3 000 a 12 000 (cambia conjuntos) y vuelve a comparar la GRU y los dos transformers. ¿Se cierra la brecha del transformer desde cero?
  2. Preentrena solo 2 épocas en lugar de 8. ¿Cuánto cae el resultado en los barrios reservados?
  3. Cambia el costo de una entrega fallida a $30 000 y vuelve a escoger los umbrales en validación. ¿Qué pasa con las revisiones por día?
  4. Agrega a la regla los 15 barrios reservados en su catálogo. ¿Cuánto mejora? ¿Es una comparación justa?
  5. Entrena el transformer con nhead=1. ¿Cambia el resultado en las referencias con número?
  1. Con más etiquetas, el transformer desde cero suele acercarse a la GRU, pero el preentrenado conserva la ventaja en barrios reservados, porque esos barrios siguen sin aparecer etiquetados. Compara siempre en validación antes de mirar la prueba.
  2. La pérdida de preentrenamiento todavía baja en la época 8; con 2 épocas la red sabe menos del histórico y la ventaja en barrios reservados se reduce.
  3. Un costo de falla más alto mueve el umbral hacia arriba: se revisa más para fallar menos.
  4. Mejora mucho en barrios reservados, pero ya no es una prueba de generalización: la regla «conoce» la respuesta. En la operación, el catálogo siempre llega tarde a los barrios nuevos.
  5. Con una cabeza, la red sigue aprendiendo, pero pierde la posibilidad de mirar varias relaciones a la vez; mide la diferencia en el grupo de referencias con número.

26.3.14 El simulador del caso

Estas son las reglas con que se generan los mensajes. El código completo está en el desplegable.

Simulador de direcciones que los clientes de BITLogística escriben como texto libre.

Lo usa solo el Caso práctico 1 del capítulo. Genera mensajes como los que llegan por el formulario web o por el chat («hola, la dirección es cra 15 #93-47 apto 302, frente al parque de la 93») y, para cada palabra, la etiqueta del campo al que pertenece.

Reglas de la simulación (todas las cifras son inventadas, con órdenes de magnitud plausibles):

  1. El núcleo de la dirección sigue la nomenclatura de Bogotá: tipo de vía, número de la vía (a veces con letra, «bis», «sur» o «este»), un separador opcional («#», «No.», «N°»), el número del cruce y el de la placa. Calle y carrera son las vías más comunes.
  2. El 70 % de los tipos de vía se abrevia (cra, kr, cl, cll, dg, tv…).
  3. Bloques opcionales: uno o dos complementos (torre 2 apto 302), el barrio (con o sin la palabra «barrio»), una referencia y frases de relleno, saludos o un teléfono.
  4. Muchas referencias traen números que NO son de la dirección: «frente al parque de la 93», «cerca a la estación de la 72». Para saber que ese 93 es parte de una referencia hay que mirar las palabras de alrededor.
  5. Los teléfonos («cel 3104567890») tampoco son parte de la dirección.
  6. El orden de los bloques puede cambiar y hay errores de tipeo, mayúsculas y tildes perdidas. El conjunto «difícil» tiene más cambios de orden y más errores.
  7. Quince barrios solo aparecen en las particiones de prueba: así se mide si el método funciona con barrios que nunca vio etiquetados.
  8. El «histórico» son mensajes de envíos pasados sin etiquetar: traen todos los barrios de la ciudad, porque son direcciones reales de clientes, pero nadie marcó sus campos.
"""Simulador de direcciones que los clientes de BITLogística escriben como texto libre.

Lo usa solo el Caso práctico 1 del capítulo. Genera mensajes como los que llegan por el
formulario web o por el chat («hola, la dirección es cra 15 #93-47 apto 302, frente al
parque de la 93») y, para cada palabra, la etiqueta del campo al que pertenece.

Reglas de la simulación (todas las cifras son inventadas, con órdenes de magnitud plausibles):

1. El núcleo de la dirección sigue la nomenclatura de Bogotá: tipo de vía, número de la vía
   (a veces con letra, «bis», «sur» o «este»), un separador opcional («#», «No.», «N°»),
   el número del cruce y el de la placa. Calle y carrera son las vías más comunes.
2. El 70 % de los tipos de vía se abrevia (cra, kr, cl, cll, dg, tv...).
3. Bloques opcionales: uno o dos complementos (torre 2 apto 302), el barrio (con o sin la
   palabra «barrio»), una referencia y frases de relleno, saludos o un teléfono.
4. Muchas referencias traen números que NO son de la dirección: «frente al parque de la 93»,
   «cerca a la estación de la 72». Para saber que ese 93 es parte de una referencia hay que
   mirar las palabras de alrededor.
5. Los teléfonos («cel 3104567890») tampoco son parte de la dirección.
6. El orden de los bloques puede cambiar y hay errores de tipeo, mayúsculas y tildes
   perdidas. El conjunto «difícil» tiene más cambios de orden y más errores.
7. Quince barrios solo aparecen en las particiones de prueba: así se mide si el método
   funciona con barrios que nunca vio etiquetados.
8. El «histórico» son mensajes de envíos pasados sin etiquetar: traen todos los barrios
   de la ciudad, porque son direcciones reales de clientes, pero nadie marcó sus campos.
"""

import re
import unicodedata

import numpy as np

BARRIOS = (
    "Chapinero", "La Soledad", "Galerías", "Palermo", "Teusaquillo",
    "Quinta Paredes", "La Esmeralda", "Ciudad Salitre", "Modelia", "Hayuelos",
    "Normandía", "La Felicidad", "Santa Cecilia", "Capellanía", "Fontibón Centro",
    "El Tintal", "Patio Bonito", "Castilla", "Marsella", "Carvajal",
    "Villa Alsacia", "Timiza", "Roma", "Boitá", "Alquería",
    "Venecia", "Muzú", "Santa Isabel", "Veraguas", "Eduardo Santos",
    "Restrepo", "Olaya", "Quiroga", "Claret", "Centenario",
    "San Carlos", "Tunal", "Meissen", "Lucero Alto", "Lucero Bajo",
    "Sierra Morena", "Arborizadora Alta", "Arborizadora Baja", "Perdomo", "Madelena",
    "El Nogal", "La Cabrera", "El Retiro", "Chicó", "El Virrey",
    "San Patricio", "Santa Bibiana", "Santa Bárbara", "Multicentro", "Cedritos",
    "Contador", "El Redil", "Verbenal", "Toberín", "La Uribe",
)
BARRIOS_CONOCIDOS = BARRIOS[:45]          # aparecen en entrenamiento, validación y prueba
BARRIOS_RESERVADOS = BARRIOS[45:]         # solo en prueba
ETIQUETAS = (
    "VIA", "NUM_VIA", "NUM_CRUCE", "NUM_PLACA", "COMPLEMENTO",
    "NUM_COMPLEMENTO", "BARRIO", "REFERENCIA", "OTRO",
)
VIAS = {                                  # nombre completo: abreviaturas usadas por los clientes
    "calle": ("cl", "cll"),
    "carrera": ("cra", "kr", "cr", "kra"),
    "avenida calle": ("av cl", "avda calle"),
    "avenida carrera": ("av cra", "avda kr"),
    "diagonal": ("dg", "diag"),
    "transversal": ("tv", "transv"),
}
COMPLEMENTOS = {
    "apartamento": ("apto", "apt", "ap"), "torre": ("torre", "t"),
    "interior": ("int",), "bloque": ("blq", "bloque"), "casa": ("casa",),
    "oficina": ("ofi", "of"), "local": ("local",),
}
# Referencias: {} se reemplaza por un número que NO es parte de la dirección.
REFERENCIAS = (
    "frente al parque", "al lado de la panadería", "portería", "entregar en recepción",
    "frente al parque de la {}", "cerca a la estación de la {}", "al lado del éxito de la {}",
    "diagonal al colegio", "edificio mirador", "a media cuadra de la {}",
)
SALUDOS = ("hola", "buenas tardes", "la dirección es", "envío para", "buen día, es en")
RELLENOS = ("por favor", "casa de", "entregar a", "llamar antes", "gracias")
PATRON = re.compile(r"[^\W\d_]+|\d+[^\W\d_]?|[#\-.,°º]", re.UNICODE)


def tokenizar(texto):
    """Separa palabras, números (con su letra pegada, como 93A) y signos."""
    return PATRON.findall(texto)


def sin_tildes(texto):
    """Quita las tildes: «Chicó» → «Chico»."""
    letras = unicodedata.normalize("NFD", texto)
    return "".join(letra for letra in letras if not unicodedata.combining(letra))


def generar_direcciones(cantidad, semilla, particion):
    """Genera ``cantidad`` mensajes. Cada uno trae texto, palabras y etiquetas."""
    if particion not in ("entrenamiento", "validacion", "prueba", "dificil", "historico"):
        raise ValueError(f"Partición desconocida: {particion}")
    rng = np.random.default_rng(semilla)
    dificil = particion == "dificil"
    prueba = particion in ("prueba", "dificil", "historico")   # pueden traer barrios reservados
    prob_orden = 0.55 if dificil else 0.20              # 6. cambiar el orden de los bloques
    prob_errata = 0.12 if dificil else 0.03             # 6. error de tipeo por palabra
    filas = []

    for _ in range(cantidad):
        # 1. Núcleo de la dirección: vía, número, separador, cruce y placa.
        via = str(rng.choice(tuple(VIAS), p=[.39, .39, .06, .06, .05, .05]))
        forma_via = str(rng.choice(VIAS[via])) if rng.random() < .70 else via   # 2.
        numero = str(rng.integers(1, 201))
        cruce = str(rng.integers(1, 201))
        placa = str(rng.integers(1, 100))
        if rng.random() < .13:
            numero += str(rng.choice(list("ABC")))     # «93A»
        if rng.random() < .12:
            cruce += str(rng.choice(list("ABC")))
        sufijo = str(rng.choice(["bis", "sur", "este"])) if rng.random() < .12 else ""
        separador = str(rng.choice(["#", "No.", "N°", "no", ""], p=[.4, .15, .1, .15, .2]))
        guion = "-" if rng.random() < .65 else ""
        nucleo = [(forma_via, "VIA"), (numero, "NUM_VIA"), (sufijo, "NUM_VIA"),
                  (separador, "OTRO"), (cruce, "NUM_CRUCE"), (guion, "OTRO"),
                  (placa, "NUM_PLACA")]

        # 2. Bloques opcionales, cada uno con sus etiquetas.
        extras = []
        barrio = None
        for _ in range(int(rng.choice([0, 1, 2], p=[.40, .42, .18]))):   # 3. complementos
            complemento = str(rng.choice(tuple(COMPLEMENTOS)))
            alias = str(rng.choice(COMPLEMENTOS[complemento]))
            valor = str(rng.integers(1, 901))
            extras.append([(alias, "COMPLEMENTO"), (valor, "NUM_COMPLEMENTO")])
        if rng.random() < .40:                                            # 3. barrio
            reservado = prueba and rng.random() < .33
            barrio = str(rng.choice(BARRIOS_RESERVADOS if reservado else BARRIOS_CONOCIDOS))
            palabra = [("barrio", "OTRO")] if rng.random() < .55 else []
            extras.append(palabra + [(barrio, "BARRIO")])
        con_numero = False
        if rng.random() < .35:                                            # 4. referencia
            referencia = str(rng.choice(REFERENCIAS))
            con_numero = "{}" in referencia
            referencia = referencia.format(int(rng.integers(1, 181)))
            extras.append([(referencia, "REFERENCIA")])
        if rng.random() < .15:                                            # 5. teléfono
            telefono = "3" + "".join(str(d) for d in rng.integers(0, 10, 9))
            extras.append([(str(rng.choice(["cel", "tel", "llamar al"])), "OTRO"),
                           (telefono, "OTRO")])
        if rng.random() < .20:                                            # 3. relleno
            extras.append([(str(rng.choice(RELLENOS)), "OTRO")])

        # 3. El orden de los bloques puede cambiar; el saludo siempre va al inicio.
        bloques = [nucleo, *extras]
        if extras and rng.random() < prob_orden:
            bloques.insert(0, bloques.pop(int(rng.integers(1, len(bloques)))))
        if rng.random() < .25:
            bloques.insert(0, [(str(rng.choice(SALUDOS)), "OTRO")])

        # 4. Escribir el texto: errores de tipeo, tildes, mayúsculas y espacios pegados.
        palabras, etiquetas, fragmentos = [], [], []
        anterior = ""
        for b, bloque in enumerate(bloques):
            for fragmento, etiqueta in bloque:
                for token in tokenizar(fragmento):
                    if token.isalpha() and len(token) >= 3 and rng.random() < prob_errata:
                        i = int(rng.integers(len(token)))
                        token = token[:i] + str(rng.choice(["", token[i] * 2, "x"])) + token[i + 1:]
                    if rng.random() < .50:
                        token = sin_tildes(token)
                    if rng.random() < .15:
                        token = token.upper()
                    # Pegar el token al anterior solo donde los clientes lo hacen (cra15#93-47).
                    pegable = token in "#-" or anterior in ("#", "-")
                    pegable |= anterior.isalpha() and token[0].isdigit()
                    espacio = "" if fragmentos and pegable and rng.random() < .58 else " "
                    fragmentos.append(espacio + token)
                    palabras.append(token)
                    etiquetas.append(etiqueta)
                    anterior = token
            if b < len(bloques) - 1 and rng.random() < .30:   # coma entre bloques
                fragmentos.append(",")
                palabras.append(",")
                etiquetas.append("OTRO")
                anterior = ","
        texto = "".join(fragmentos).strip()
        assert tokenizar(texto) == palabras            # el texto se vuelve a partir igual
        filas.append({"texto": texto, "palabras": palabras, "etiquetas": etiquetas,
                      "barrio": barrio, "barrio_reservado": barrio in BARRIOS_RESERVADOS,
                      "referencia_con_numero": con_numero,
                      "forma_via": forma_via, "separador": separador})
    return filas

26.4 Caso práctico 2: Detectar sonidos de riesgo en la bodega

AdvertenciaEmpresa y datos ficticios

BITLogística es una empresa ficticia y su bodega de Funza también. Todos los sonidos de este caso salen de un simulador, simulador_bodega.py, con fórmulas sencillas que puedes leer al final del caso. Los costos y las frecuencias de los sonidos son supuestos del ejercicio.

La red de este caso: un transformer. Es el mismo tipo de red del caso anterior, aplicado a sonido. Un transformer lee todas las partes de una secuencia a la vez y, para entender cada una, mira a las demás. Se usa principalmente en texto, pero también en reconocimiento de voz y de sonidos. Se basa en la atención. Aquí la secuencia son los pedazos de 10 milisegundos de un segundo de audio: para saber si un pedazo es parte de una alarma, la red mira si los pedazos de alrededor tienen el mismo tono sostenido o si todo pasó en un instante, como en un golpe.

Cómo se ve en Python. Es la misma capa del caso 1: nn.TransformerEncoderLayer(d_model=64, nhead=4, dim_feedforward=128, dropout=0.1, batch_first=True) apilada con nn.TransformerEncoder(capa, num_layers=2). Solo cambian la entrada y la salida:

  • Entrada: nn.Linear(64, 64) en lugar de nn.Embedding. Cada pedazo de audio ya llega como 64 números (la energía en 64 bandas de frecuencia), así que basta una capa lineal para llevarlo al tamaño d_model.
  • Salida: el caso 1 daba una etiqueta por palabra; aquí hay una sola decisión por segundo de audio. Se promedian los 97 vectores de salida y nn.Linear(64, 3) da 3 puntajes: normal, alarma o golpe.

Arriba, cuatro cajas con flechas hacia el código: nn.Linear de 64 bandas a 64, resaltada, que reemplaza a nn.Embedding; la misma capa del caso 1; el promedio de las 97 columnas; y nn.Linear de 64 a 3 clases. Abajo, las líneas entrada igual a nn.Linear de 64 a 64, capa igual a nn.TransformerEncoderLayer con d_model 64 y nhead 4, codificador con num_layers 2 y salida igual a nn.Linear de 64 a 3.

Las líneas que arman el transformer de audio: la entrada lineal, la misma capa del caso 1 y la salida de 3 clases.

Este caso tiene su propia configuración y se puede ejecutar sin el caso 1.

# 1. Librerías del caso.
import copy
import platform
import time
from collections import Counter
from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import scipy
import torch
from scipy.io import wavfile
from scipy.signal import resample
from sklearn.metrics import confusion_matrix, precision_recall_fscore_support
from torch import nn
from torch.utils.data import DataLoader, TensorDataset

from simulador_bodega import (CLASES, INOFENSIVOS, NUEVO, TASA, TONOS, fondo, mezclar,
                              simular_clips, simular_turno, sonido)

# 2. Semilla, CPU y carpetas.
SEMILLA = 42
torch.manual_seed(SEMILLA)
torch.set_num_threads(2)
inicio_caso2 = time.perf_counter()
artefactos = Path("artefactos_pytorch/caso2")
artefactos.mkdir(parents=True, exist_ok=True)
print(f"Python {platform.python_version()} · PyTorch {torch.__version__} · "
      f"SciPy {scipy.__version__} · NumPy {np.__version__}")
Python 3.13.16 · PyTorch 2.14.1+cu130 · SciPy 1.18.1 · NumPy 2.5.4

26.4.1 El problema en la operación

En los 6 pasillos del centro de distribución de BITLogística en Funza trabajan montacargas entre personas que alistan pedidos. Dos sonidos importan:

  • La alarma de reversa del montacargas. Si suena cerca de un pasillo con personas, hay riesgo de atropello: el sistema debe encender una luz de advertencia en ese pasillo.
  • El golpe de una caja que cae. Puede ser mercancía dañada que nadie reporta: el sistema debe avisarle al supervisor.

Un micrófono por pasillo escucha todo el turno. La bodega está llena de otros sonidos inofensivos: el pito de un carro afuera, el timbre de un celular, una puerta que se cierra, un carro de mano que rueda. La regla actual, basada en la energía del sonido, dispara falsas alarmas con algunos y deja pasar muchos eventos reales; los supervisores ya no le creen.

NotaFalsa alarma por cada 100 sonidos inofensivos

Un aviso que no corresponde a ningún evento real. Se cuenta por cada 100 sonidos inofensivos que ocurrieron, y no por hora, porque los turnos simulados tienen muchos más sonidos por hora que una bodega real: así la cifra se puede llevar después a la densidad real de la bodega.

Los supuestos de negocio, iguales en todo el caso:

Supuesto Valor Por qué
Pasillos con micrófono 6 Una bodega mediana
Turno 8 horas Jornada de referencia
Alarmas de reversa por pasillo y hora 20 Montacargas que entran y salen del pasillo
Golpes de caja por pasillo y hora 1 Evento poco frecuente
Sonidos inofensivos por pasillo y hora 60 Uno por minuto
Costo de una falsa alarma $5 000 Tiempo del supervisor que va a verificar
Costo de un golpe no detectado $40 000 Mercancía dañada que sale sin reportar
Política de avisos máximo 3 falsas alarmas por cada 100 sonidos inofensivos Con 60 inofensivos por hora, unas 2 por hora y pasillo: lo que un supervisor tolera

¿Puede un transformer que lee el espectrograma reconocer la alarma y los golpes con pocas falsas alarmas, qué tan rápido avisa y qué pasa cuando oye un sonido que nunca escuchó?

Cinco cajas en fila: micrófono del pasillo a 16 000 muestras por segundo; ventana de 1 segundo que avanza cada 0.25 segundos; espectrograma de 97 columnas por 64 bandas; transformer con 3 probabilidades; y la decisión: si la probabilidad de alarma supera su umbral se enciende la luz del pasillo, si la de golpe supera el suyo se avisa al supervisor.

El recorrido: el micrófono del pasillo, ventanas de 1 segundo cada 0.25 segundos, el espectrograma, el transformer, y la decisión: luz de reversa o aviso al supervisor.

26.4.2 Los datos

El simulador produce dos tipos de datos:

  • Clips de 1 segundo con su etiqueta (normal, alarma o golpe), en igual cantidad de cada clase, para entrenar y para la evaluación por clip. Entre los normales, tres de cada cuatro tienen un sonido inofensivo y el resto es solo fondo. Un sonido puede quedar cortado por el borde del clip, como pasa en la operación.
  • Turnos continuos de 3 minutos, con la lista de sonidos que ocurrieron y su instante. Son los que se usan para escoger los umbrales (validación) y para la evaluación final (prueba).

Para medir si el modelo sirve con equipos que no vio:

  • Montacargas nuevos: cada montacargas tiene su tono de alarma. Los tonos de prueba (1 090, 1 210 y 1 285 Hz) no aparecen al entrenar ni al validar, aunque están dentro del mismo rango.
  • Un sonido nuevo: la cinta de embalaje que se rasga. No aparece en ningún dato de entrenamiento ni de validación, solo en un segundo grupo de turnos de prueba, «con sonido nuevo».
NotaRelación señal-ruido (dB)

Cuánto más fuerte suena el evento que el fondo, en decibeles. A +20 dB el evento tiene 100 veces la potencia del fondo; a 0 dB, la misma; a −5 dB, apenas un tercio: el evento está casi tapado por el ruido de la bodega. Los sonidos del simulador se mezclan entre −5 y +20 dB.

Escucha cuatro sonidos, cada uno sobre el fondo de la bodega:

# 1. Cuatro audios de ejemplo de 2 s a 16 kHz, guardados como WAV de 16 bits.
rng = np.random.default_rng(SEMILLA + 90)
ejemplos = {}
for nombre, archivo in [("alarma", "alarma"), ("golpe", "golpe"),
                        ("carro de mano", "carro-de-mano"), ("cinta", "cinta-nuevo")]:
    audio = fondo(2 * TASA, rng)
    frecuencia = 1180 if nombre == "alarma" else None
    mezclar(audio, sonido(nombre, rng, frecuencia, repetir=True), int(0.3 * TASA), 12)
    wavfile.write(f"figuras/{archivo}.wav", TASA, (32767 * np.clip(audio, -1, 1)).astype(np.int16))
    ejemplos[nombre] = audio
print("Audios guardados:", list(ejemplos))
Audios guardados: ['alarma', 'golpe', 'carro de mano', 'cinta']

Alarma de reversa (dos pitidos):

Golpe de una caja:

Carro de mano, inofensivo:

Cinta de embalaje, el sonido nuevo que solo aparece en la prueba:

# 1. Clips de 1 s: 4 800 para entrenar, 600 para validar y 900 para la prueba.
cantidades = {"entrenamiento": 4800, "validacion": 600, "prueba": 900}
clips = {grupo: simular_clips(n, SEMILLA + i, grupo) for i, (grupo, n) in enumerate(cantidades.items())}

# 2. Comprobaciones: tonos de prueba nuevos y la cinta fuera de los clips.
assert not set(TONOS["prueba"]) & (set(TONOS["entrenamiento"]) | set(TONOS["validacion"]))
assert all(d["evento"] != NUEVO for grupo in clips for d in clips[grupo][2])
for grupo, (audio, etiquetas, detalles) in clips.items():
    print(f"{grupo}: {audio.shape[0]} clips de {audio.shape[1]} muestras, "
          f"por clase {np.bincount(etiquetas).tolist()}")
print(pd.Series(Counter(d["evento"] for d in clips["entrenamiento"][2])).to_string())
entrenamiento: 4800 clips de 16000 muestras, por clase [1600, 1600, 1600]
validacion: 600 clips de 16000 muestras, por clase [200, 200, 200]
prueba: 900 clips de 16000 muestras, por clase [300, 300, 300]
fondo             403
alarma           1600
golpe            1600
puerta            299
carro de mano     292
pito              299
timbre            307
  • Hay 1 600 clips por clase para entrenar, 200 para validar y 300 para la prueba. Las clases están balanceadas a propósito, para que la red no aprenda a decir siempre «normal».
  • Entre los 1 600 normales de entrenamiento, 403 son solo fondo y el resto se reparte entre timbre (307), puerta (299), pito (299) y carro de mano (292).
  • La cinta no aparece en ningún clip: se comprobó con assert.

26.4.3 Análisis descriptivo

Un espectrograma muestra el sonido en 2 ejes: el tiempo (horizontal) y la frecuencia (vertical); el color es la energía. Es la forma de ver el audio que se explicó en el capítulo de audio.

fig, ejes = plt.subplots(2, 4, figsize=(13, 5.5))
for j, (nombre, audio) in enumerate(ejemplos.items()):
    t = np.arange(len(audio)) / TASA
    ejes[0, j].plot(t, audio, lw=0.5, color="#1786B3")
    ejes[0, j].set(title=nombre, xlabel="tiempo (s)")
    ejes[1, j].specgram(audio, NFFT=400, Fs=TASA, noverlap=240, cmap="magma")
    ejes[1, j].set(ylim=(0, 4000), xlabel="tiempo (s)")
ejes[0, 0].set_ylabel("amplitud")
ejes[1, 0].set_ylabel("frecuencia (Hz)")
plt.tight_layout()
plt.show()
Ocho paneles en dos filas. Arriba, la forma de onda de alarma, golpe, carro de mano y cinta. Abajo, sus espectrogramas de 0 a 4 000 Hz: la alarma son líneas horizontales cerca de 1 180 Hz y sus armónicos, interrumpidas cada segundo; el golpe es una raya vertical corta; el carro de mano es una mancha ancha y sostenida en frecuencias bajas; la cinta son golpecitos verticales repetidos en frecuencias altas.
Figura 26.4: Forma de onda y espectrograma de los cuatro sonidos de ejemplo
  • La alarma son líneas horizontales: el tono principal cerca de 1 180 Hz y sus armónicos a 2 360 y 3 540 Hz, interrumpidos cada segundo (pitido, pausa, pitido).
  • El golpe es una raya vertical corta: mucha energía en todas las frecuencias durante unos milisegundos.
  • El carro de mano es una mancha ancha y sostenida, con un tono grave cerca de 170 Hz. Visto entero no se parece a un golpe; cortado por el borde de una ventana, su comienzo sí.
  • La cinta son rayas verticales repetidas en las frecuencias altas. Cada chasquido se parece a un golpe pequeño: por eso es una buena prueba de un sonido nuevo.
# 1. Relación señal-ruido de los clips de entrenamiento con sonido.
snr = pd.Series([d["snr"] for d in clips["entrenamiento"][2] if d["snr"] is not None])
print("Relación señal-ruido (dB):", snr.describe()[["mean", "min", "25%", "50%", "75%", "max"]].round(1).to_dict())
print(f"Clips con −5 a 0 dB (el evento casi tapado): {100 * (snr < 0).mean():.1f} %")
Relación señal-ruido (dB): {'mean': 7.3, 'min': -5.0, '25%': 0.9, '50%': 7.2, '75%': 13.7, 'max': 20.0}
Clips con −5 a 0 dB (el evento casi tapado): 21.1 %
  • La relación señal-ruido media es de 7.3 dB: un sonido típico tiene unas 5 veces la potencia del fondo.
  • El 21.1 % de los clips con sonido está por debajo de 0 dB: el evento suena más bajo que el fondo de la bodega. Es la parte difícil, para la regla y para la red.

26.4.4 Preparación de los datos

Cada clip de 1 segundo se convierte en una secuencia de columnas:

  1. Espectrograma con torch.stft: ventanas de 25 ms (400 muestras) que avanzan 10 ms (160 muestras). 25 ms es lo bastante largo para distinguir un tono de 1 100 Hz de uno de 1 200 Hz, y 10 ms lo bastante corto para ver un golpe de 30 ms. Con 16 000 muestras salen 97 columnas.
  2. 64 bandas: las primeras 256 frecuencias (de 0 a 8 000 Hz) se agrupan de a 4. Menos números por columna, la misma información útil.
  3. Escala logarítmica: el oído y la red distinguen mejor en decibeles; sin el logaritmo, un golpe fuerte aplastaría todo lo demás.
  4. Normalización por banda con la media y la desviación de entrenamiento.

Cada columna es un token, como cada palabra en el caso 1 o cada trozo de imagen en el capítulo de visión. Un segundo de audio queda como una secuencia de 97 tokens de 64 números.

La misma función calcula los dos números que usa la regla (sección siguiente), para que la regla y la red vean el mismo espectrograma.

# 1. Parámetros del espectrograma.
VENTANA, SALTO, N_FFT, BANDAS = 400, 160, 512, 64       # 25 ms, 10 ms, 512 puntos, 64 bandas
hann = torch.hann_window(VENTANA)


def espectrograma(audio):
    """Potencia de (lote, 257 frecuencias, 97 columnas)."""
    z = torch.stft(audio, n_fft=N_FFT, hop_length=SALTO, win_length=VENTANA, window=hann,
                   center=False, return_complex=True)
    return z.abs().square()


def a_tokens(potencia):
    """(lote, 97 columnas, 64 bandas) en escala logarítmica."""
    lote, _, columnas = potencia.shape
    bandas = potencia[:, :256, :].reshape(lote, BANDAS, 4, columnas).mean(2)   # de a 4 frecuencias
    return bandas.clamp_min(1e-8).log10().transpose(1, 2)


# 2. Los dos números de la regla (se explican en la línea base).
def numeros_regla(potencia):
    total = potencia.sum(1)                                   # energía de cada columna
    mediana = total.median(1).values.clamp_min(1e-8)
    banda_alarma = potencia[:, 29:45, :].sum(1)               # de 906 a 1 406 Hz
    pureza = (banda_alarma / total.clamp_min(1e-8)).max(1).values
    alarma = torch.minimum(pureza, banda_alarma.max(1).values / mediana / 10)
    agudos = potencia[:, 32:193, :].sum(1)                    # de 1 000 a 6 000 Hz
    nivel = agudos.median(1).values.clamp_min(1e-8)[:, None]
    despues = torch.cat([agudos[:, 15:], agudos[:, -1:].expand(-1, 15)], 1)   # 150 ms después
    golpe = torch.minimum(agudos / nivel, agudos / despues.clamp_min(1e-8)).max(1).values
    return torch.stack([alarma, golpe], 1)


def preparar_audio(audio):
    tokens, regla = [], []
    for lote in torch.as_tensor(audio).split(256):
        potencia = espectrograma(lote)
        tokens.append(a_tokens(potencia))
        regla.append(numeros_regla(potencia))
    return torch.cat(tokens), torch.cat(regla).numpy()


# 3. Todos los clips, y la normalización con estadísticos de entrenamiento.
preparados = {grupo: preparar_audio(clips[grupo][0]) for grupo in clips}
x_ent = preparados["entrenamiento"][0]
media = x_ent.mean((0, 1))                                    # una media por banda
desviacion = x_ent.std((0, 1)).clamp_min(1e-3)
COLUMNAS = x_ent.shape[1]
for grupo, (tokens, _) in preparados.items():
    print(f"{grupo}: {tuple(tokens.shape)}  (clips, columnas, bandas)")
entrenamiento: (4800, 97, 64)  (clips, columnas, bandas)
validacion: (600, 97, 64)  (clips, columnas, bandas)
prueba: (900, 97, 64)  (clips, columnas, bandas)
  • Cada clip queda como una secuencia de 97 columnas de 64 bandas: (4 800, 97, 64) en entrenamiento, (600, 97, 64) en validación y (900, 97, 64) en prueba.
  • 97 columnas = (16 000 − 400) / 160 + 1: cuántas ventanas de 400 muestras caben avanzando de a 160.

26.4.5 Una línea base sin red neuronal

La regla actual mira 2 números por clip, calculados del mismo espectrograma:

  • Alarma: la «pureza» de la banda de 906 a 1 406 Hz, es decir, qué fracción de la energía de una columna está en esa banda, siempre que además suene fuerte frente al fondo. Una alarma es un tono puro: casi toda su energía cae ahí.
  • Golpe: cuánto sube la energía de 1 000 a 6 000 Hz frente a su nivel normal y cuánto baja 150 ms después. Un golpe sube de repente y se apaga rápido; un ruido sostenido no.

Si el número supera su umbral, la regla avisa. Los umbrales se escogen igual que los de la red, en los turnos de validación (más adelante).

26.4.6 Diseño de la red

De izquierda a derecha: el espectrograma de 97 columnas por 64 bandas; nn.Linear y la posición lo convierten en 97 vectores de 64; dos bloques transformer los mantienen en 97 por 64; el promedio de las columnas da un vector de 64; nn.Linear da 3 puntajes: normal, alarma y golpe.

El recorrido de un segundo de audio dentro de la red: 97 columnas de 64 bandas, la entrada lineal más la posición, dos bloques transformer, el promedio y 3 puntajes.
ImportanteAquí se arma la red del caso

La clase TransformerBodega tiene las líneas de la figura «Cómo se ve en Python»: la entrada nn.Linear(BANDAS, 64), la misma nn.TransformerEncoderLayer(d_model=64, nhead=4, dim_feedforward=128, dropout=0.1, batch_first=True) del caso 1 apilada con nn.TransformerEncoder(capa, num_layers=2), el promedio z.mean(1) y la salida nn.Linear(64, 3).

# 1. El transformer de audio: columna → 64 + posición → 2 bloques → promedio → 3 clases.
class TransformerBodega(nn.Module):
    def __init__(self):
        super().__init__()
        self.entrada = nn.Linear(BANDAS, 64)                  # 64 bandas → d_model
        self.posicion = nn.Embedding(COLUMNAS, 64)            # una posición por columna
        capa = nn.TransformerEncoderLayer(d_model=64, nhead=4, dim_feedforward=128,
                                          dropout=0.1, batch_first=True)
        self.codificador = nn.TransformerEncoder(capa, num_layers=2,
                                                 enable_nested_tensor=False)
        self.salida = nn.Linear(64, len(CLASES))              # 64 → normal, alarma, golpe

    def forward(self, x):                                     # x: (lote, 97, 64)
        z = self.entrada(x) + self.posicion(torch.arange(x.shape[1]))
        z = self.codificador(z)                               # (lote, 97, 64)
        return self.salida(z.mean(1))                         # promedio de columnas → (lote, 3)


red = TransformerBodega()
print("Parámetros:", sum(p.numel() for p in red.parameters()))
print("  entrada:", sum(p.numel() for p in red.entrada.parameters()),
      "· posición:", red.posicion.weight.numel(),
      "· 2 bloques:", sum(p.numel() for p in red.codificador.parameters()),
      "· salida:", sum(p.numel() for p in red.salida.parameters()))
Parámetros: 77507
  entrada: 4160 · posición: 6208 · 2 bloques: 66944 · salida: 195
  • La red tiene 77 507 parámetros, menos que la del caso 1, porque no necesita una tabla de palabras.
  • La entrada aporta 4 160 (64 × 64 + 64), la posición 6 208 (97 × 64), los 2 bloques 66 944 y la salida 195 (64 × 3 + 3).
  • Casi todo está en los dos bloques, que son exactamente los mismos del caso 1.

26.4.7 Entrenamiento

Adam con tasa 0.001, lotes de 64, hasta 40 épocas, el mejor estado según la pérdida de validación y parada temprana con paciencia de 6 épocas.

NotaSuavizado de etiquetas

En lugar de pedirle a la red una probabilidad de 1 para la clase correcta, se le pide un poco menos (aquí, el 10 % de la probabilidad se reparte entre las tres clases). Sin suavizado, la red aprende a responder 0.9999 en casi todo y los umbrales quedan apretados contra el 1, donde un cambio mínimo los mueve mucho. En PyTorch es un argumento: nn.CrossEntropyLoss(label_smoothing=0.1).

# 1. Cargadores: tokens normalizados con los estadísticos de entrenamiento.
def cargador(grupo, mezclar_orden=False):
    x = (preparados[grupo][0] - media) / desviacion
    y = torch.from_numpy(clips[grupo][1])
    generador = torch.Generator().manual_seed(SEMILLA)
    return DataLoader(TensorDataset(x, y), batch_size=64, shuffle=mezclar_orden,
                      generator=generador)


# 2. Entrenamiento con validación, mejor estado y parada temprana.
def entrenar(red, epocas=40, paciencia=6):
    optimizador = torch.optim.Adam(red.parameters(), lr=1e-3)
    perdida = nn.CrossEntropyLoss(label_smoothing=0.1)
    historial = []
    mejor = {"perdida": float("inf"), "epoca": 0, "estado": None}
    for epoca in range(1, epocas + 1):
        red.train()
        suma = 0.0
        for x, y in cargador("entrenamiento", mezclar_orden=True):
            optimizador.zero_grad()
            error = perdida(red(x), y)
            error.backward()
            optimizador.step()
            suma += error.item() * len(y)
        red.eval()
        with torch.no_grad():
            validacion = sum(perdida(red(x), y).item() * len(y) for x, y in cargador("validacion"))
        historial.append((epoca, suma / cantidades["entrenamiento"],
                          validacion / cantidades["validacion"]))
        if historial[-1][2] < mejor["perdida"]:
            mejor = {"perdida": historial[-1][2], "epoca": epoca,
                     "estado": copy.deepcopy(red.state_dict())}
        elif epoca - mejor["epoca"] >= paciencia:
            break
    red.load_state_dict(mejor["estado"])
    return pd.DataFrame(historial, columns=["época", "entrenamiento", "validación"]), mejor["epoca"]


t0 = time.perf_counter()
historial, mejor_epoca = entrenar(red)
print(f"Épocas ejecutadas: {len(historial)} · mejor época: {mejor_epoca} · "
      f"pérdida de validación: {historial.loc[mejor_epoca - 1, 'validación']:.4f} · "
      f"{time.perf_counter() - t0:.0f} s")
assert mejor_epoca < 40, "la mejor época quedó en el límite"
Épocas ejecutadas: 16 · mejor época: 10 · pérdida de validación: 0.3103 · 120 s
  • El entrenamiento paró en la época 16 y conservó la 10, con una pérdida de validación de 0.3103. Tomó 120 segundos.
  • La pérdida no baja de 0.29 con suavizado de etiquetas. Con un 10 % repartido, la respuesta ideal ya no es 1: la pérdida mínima posible es cerca de 0.29. El 0.3103 está muy cerca de ese piso.
  • El salto de la época 5 (validación en 0.455) es un paso malo del optimizador. La red se recuperó en la siguiente época, y la parada temprana guarda el mejor estado de todos modos.
fig, eje = plt.subplots(figsize=(7, 3.2))
eje.plot(historial["época"], historial["entrenamiento"], "-", color="#1786B3", label="entrenamiento")
eje.plot(historial["época"], historial["validación"], "--", color="#EE5400", label="validación")
eje.axvline(mejor_epoca, color="#89878C", lw=1, ls=":", label=f"mejor época ({mejor_epoca})")
eje.set(xlabel="época", ylabel="pérdida")
eje.legend()
plt.tight_layout()
plt.show()
Dos líneas contra la época: entrenamiento continua y validación discontinua. Las dos bajan rápido en las primeras épocas y la de validación se aplana.
Figura 26.5: Pérdida de entrenamiento y validación por época

26.4.8 Evaluación

La evaluación tiene 2 niveles. Primero, por clip: ¿la red reconoce el sonido de un segundo aislado? Después, por evento en turnos continuos, que es como se usaría en la bodega.

# 1. Probabilidades de la red para muchos clips.
def probabilidades(tokens):
    red.eval()
    with torch.no_grad():
        return torch.cat([red(lote).softmax(-1)
                          for lote in ((tokens - media) / desviacion).split(256)]).numpy()


# 2. Por clip, en la prueba: la clase más probable.
y_prueba = clips["prueba"][1]
prediccion = probabilidades(preparados["prueba"][0]).argmax(1)
precision, sensibilidad, f1, _ = precision_recall_fscore_support(y_prueba, prediccion,
                                                                 labels=[0, 1, 2])
display(pd.DataFrame({"precisión": precision, "sensibilidad": sensibilidad, "F1": f1},
                     index=CLASES).round(3))
print("Matriz de confusión (filas: real; columnas: red):")
print(pd.DataFrame(confusion_matrix(y_prueba, prediccion), index=CLASES, columns=CLASES))
precisión sensibilidad F1
normal 0.980 0.997 0.988
alarma 1.000 0.997 0.998
golpe 0.997 0.983 0.990
Matriz de confusión (filas: real; columnas: red):
        normal  alarma  golpe
normal     299       0      1
alarma       1     299      0
golpe        5       0    295

En los 900 clips aislados de prueba, la red casi no se equivoca:

  • F1 de 0.998 en alarma, 0.990 en golpe y 0.988 en normal.
  • Los errores son 7 de 900: 5 golpes tomados como normales, 1 alarma tomada como normal y 1 normal tomado como golpe.

Pero un clip con el sonido centrado no es la operación. La prueba que importa es la del turno continuo.

26.4.8.1 Por evento, en turnos continuos

En la bodega la red no recibe clips listos: recibe el audio del pasillo sin pausa. Se toma una ventana de 1 segundo que avanza cada 0.25 segundos y en cada ventana la red da sus 3 probabilidades. Si la de alarma (o la de golpe) supera su umbral, hay aviso. El conteo sigue estas reglas, iguales para la regla y para la red:

NotaCómo se cuentan los avisos
  1. Puntaje de la ventana: el promedio de la probabilidad de esa ventana y de la anterior (para la regla, el promedio de sus dos números). Un golpe que cabe en 1 s aparece en unas cuatro ventanas seguidas; un pedazo de carro de mano cortado por el borde, en una sola. Promediar dos ventanas premia lo que se sostiene y castiga lo que aparece en una ventana aislada, a cambio de unos 0.25 s más de demora.
  2. Agrupar: las ventanas consecutivas que disparan la misma clase, separadas por 0.5 s o menos, forman un solo aviso. El instante del aviso es el final de la primera ventana del grupo: el primer momento en que el sistema tiene los datos para alertar.
  3. Emparejar por el instante del aviso: un aviso es un acierto si su instante cae entre el inicio de un evento real de su clase y 1 s después de su final. Cada evento real cuenta como máximo un acierto; si el instante cae en dos eventos de la misma clase, se asigna al primero que aún no tenga acierto. Un aviso cuyos eventos posibles ya tienen todos su acierto es un aviso repetido: no suma aciertos ni falsas alarmas.
  4. Falsa alarma: un aviso cuyo instante no cae en el intervalo de ningún evento real de su clase.
  5. Demora: instante del aviso menos inicio del evento. Nunca es negativa, y puede ser menor de 0.25 s: si el sonido empieza justo antes del final de una ventana y la red ya lo reconoce, el aviso llega casi de inmediato.

Una línea de tiempo de 11 a 13.5 segundos. Arriba, un golpe corto que empieza en 12.10 s. Debajo, ventanas de 1 segundo escalonadas cada 0.25 s; la que termina en 12.25 s es la primera que contiene el golpe y está resaltada. Una flecha marca la demora de 0.15 s entre el inicio del golpe y el final de esa ventana.

Un golpe que empieza en 12.10 s y las ventanas de 1 s que avanzan cada 0.25 s: la ventana que termina en 12.25 s ya lo contiene, así que la demora puede ser de 0.15 s.
# 1. Puntaje de cada ventana: promedio de esa ventana y la anterior.
def promedio_dos(puntajes):
    suavizado = puntajes.copy()
    suavizado[1:] = (puntajes[1:] + puntajes[:-1]) / 2
    return suavizado


# 2. Turnos de 3 minutos: ventanas de 1 s cada 0.25 s, con probabilidades y números de la regla.
def preparar_turnos(grupo, cantidad, semilla_base, con_sonido_nuevo=False):
    turnos = []
    for i in range(cantidad):
        audio, eventos = simular_turno(180, SEMILLA + semilla_base + i, grupo, con_sonido_nuevo)
        ventanas = torch.from_numpy(audio).unfold(0, TASA, TASA // 4)   # (ventanas, 16 000)
        tokens, regla = preparar_audio(ventanas)
        fin_ventana = 1.0 + 0.25 * np.arange(len(ventanas))           # instante en que termina
        turnos.append({"fin": fin_ventana, "eventos": eventos,
                       "regla": promedio_dos(regla),                  # mismo trato a los dos
                       "red": promedio_dos(probabilidades(tokens))})
    return turnos


# 3. Agrupar ventanas en avisos y emparejar avisos con eventos (reglas del recuadro).
def avisos(fin, dispara):
    lista, anterior = [], -np.inf
    for t in fin[dispara]:
        if t - anterior > 0.5:
            lista.append(float(t))                            # empieza un aviso nuevo
        anterior = t
    return lista


def medir(turnos, metodo, clase, umbral):
    j = CLASES.index(clase)                                   # 1: alarma, 2: golpe
    r = {"detectados": 0, "reales": 0, "falsas": 0, "repetidos": 0, "inofensivos": 0,
         "falsas por cinta": 0, "demoras": []}
    for turno in turnos:
        puntaje = turno["regla"][:, j - 1] if metodo == "Regla" else turno["red"][:, j]
        reales = [e for e in turno["eventos"] if e["evento"] == clase]
        r["reales"] += len(reales)
        r["inofensivos"] += sum(e["evento"] in (*INOFENSIVOS, NUEVO) for e in turno["eventos"])
        con_acierto = set()
        for instante in avisos(turno["fin"], puntaje >= umbral):
            posibles = [i for i, e in enumerate(reales) if e["inicio"] <= instante <= e["fin"] + 1]
            libres = [i for i in posibles if i not in con_acierto]
            if libres:
                con_acierto.add(libres[0])
                r["demoras"].append(instante - reales[libres[0]]["inicio"])
            elif posibles:
                r["repetidos"] += 1
            else:
                r["falsas"] += 1
                r["falsas por cinta"] += any(e["evento"] == NUEVO and
                                             e["inicio"] <= instante <= e["fin"] + 1
                                             for e in turno["eventos"])
    r["detectados"] = len(r["demoras"])
    return r


# 4. Treinta turnos de validación (90 minutos de audio).
t0 = time.perf_counter()
turnos_validacion = preparar_turnos("validacion", 30, 100)
eventos_val = Counter(e["evento"] for t in turnos_validacion for e in t["eventos"])
print(f"Turnos de validación listos en {time.perf_counter() - t0:.0f} s:", dict(eventos_val))
Turnos de validación listos en 12 s: {'pito': 109, 'golpe': 102, 'timbre': 94, 'carro de mano': 97, 'alarma': 101, 'puerta': 102}

Los 30 turnos de validación suman 90 minutos con 605 sonidos: 101 alarmas, 102 golpes y 402 inofensivos (109 pitos, 102 puertas, 97 carros de mano y 94 timbres). Prepararlos tomó 12 segundos.

Los umbrales se escogen en validación con la política: la mayor detección con máximo 3 falsas alarmas por cada 100 sonidos inofensivos. Se prueban 200 umbrales por método y clase. Entre los que cumplen la política y más detectan, se queda el de menos falsas alarmas.

# 1. Probar umbrales en validación y escoger el que cumple la política y detecta más.
LIMITE = 3.0                                                  # falsas alarmas por 100 inofensivos


def explorar(metodo, clase):
    j = CLASES.index(clase)
    valores = np.concatenate([t["regla"][:, j - 1] if metodo == "Regla" else t["red"][:, j]
                              for t in turnos_validacion])
    filas = []
    for u in np.unique(np.quantile(valores, np.linspace(0.5, 1, 200))):
        r = medir(turnos_validacion, metodo, clase, u)
        filas.append({"umbral": u, "detección (%)": 100 * r["detectados"] / r["reales"],
                      "falsas por 100": 100 * r["falsas"] / r["inofensivos"]})
    return pd.DataFrame(filas)


exploracion, umbrales = {}, {}
for metodo in ["Regla", "Transformer"]:
    for clase in ["alarma", "golpe"]:
        tabla = explorar(metodo, clase)
        exploracion[(metodo, clase)] = tabla
        cumplen = tabla[tabla["falsas por 100"] <= LIMITE]
        # Entre los que más detectan, el de menos falsas alarmas (el umbral más alto).
        mejor = cumplen.sort_values(["detección (%)", "falsas por 100", "umbral"],
                                    ascending=[False, True, False]).iloc[0]
        umbrales[(metodo, clase)] = float(mejor["umbral"])

# 2. Robustez: cuántos avisos de validación cambian con el umbral vecino de cada lado.
def robustez(metodo, clase):
    tabla = exploracion[(metodo, clase)]
    i = int(np.flatnonzero(np.isclose(tabla["umbral"], umbrales[(metodo, clase)]))[0])
    j = CLASES.index(clase)
    cambios = []
    for k in (i - 1, i + 1):
        if 0 <= k < len(tabla):
            total = 0
            for t in turnos_validacion:
                puntaje = t["regla"][:, j - 1] if metodo == "Regla" else t["red"][:, j]
                a = set(avisos(t["fin"], puntaje >= umbrales[(metodo, clase)]))
                b = set(avisos(t["fin"], puntaje >= tabla["umbral"][k]))
                total += len(a ^ b)
            cambios.append(total)
    return cambios


filas = []
for (metodo, clase), u in umbrales.items():
    r = medir(turnos_validacion, metodo, clase, u)
    filas.append({"método": metodo, "clase": clase, "umbral": round(u, 4),
                  "detectados": f"{r['detectados']} de {r['reales']}",
                  "falsas por 100": round(100 * r["falsas"] / r["inofensivos"], 2),
                  "avisos que cambian con los vecinos": robustez(metodo, clase)})
pd.DataFrame(filas)
método clase umbral detectados falsas por 100 avisos que cambian con los vecinos
0 Regla alarma 0.4727 53 de 101 0.00 [44, 58]
1 Regla golpe 130.7868 10 de 102 2.74 [29, 22]
2 Transformer alarma 0.9407 101 de 101 0.00 [27, 25]
3 Transformer golpe 0.9379 99 de 102 0.00 [38, 26]

En validación, con la política de máximo 3 falsas alarmas por cada 100 inofensivos:

  • El transformer detecta las 101 alarmas y 99 de los 102 golpes, sin ninguna falsa alarma.
  • La regla detecta 53 de 101 alarmas sin falsas alarmas, pero solo 10 de 102 golpes, con 2.74 falsas alarmas por cada 100 inofensivos. Para no pasarse del límite, el umbral de golpe tiene que ser tan alto que casi nunca avisa: la puerta y el timbre también tienen subidas bruscas en los agudos.
  • Con los umbrales vecinos cambian entre 22 y 58 avisos de validación. La cuenta incluye los avisos que solo se adelantan o se atrasan un cuarto de segundo, no solo los que aparecen o desaparecen.
fig, ejes = plt.subplots(1, 2, figsize=(11, 3.8), sharey=True)
for eje, clase in zip(ejes, ["alarma", "golpe"]):
    for metodo, marca in [("Regla", "o"), ("Transformer", "^")]:
        t = exploracion[(metodo, clase)]
        t = t[t["falsas por 100"] <= 15]
        eje.plot(t["falsas por 100"], t["detección (%)"], marca, ms=4, alpha=0.6, label=metodo)
    eje.axvline(LIMITE, color="#EE5400", ls="--", label="límite de la política")
    eje.set(title=clase, xlabel="falsas alarmas por 100 sonidos inofensivos")
ejes[0].set_ylabel("eventos detectados (%)")
ejes[0].legend()
plt.tight_layout()
plt.show()
Dos paneles, alarma y golpe. En cada uno, la regla con círculos y el transformer con triángulos: el porcentaje de eventos detectados contra las falsas alarmas por cada 100 sonidos inofensivos. Una línea vertical naranja marca el límite de 3. En alarma el transformer llega al 100 % sin falsas alarmas; en golpe la detección sube con las falsas alarmas.
Figura 26.6: Validación: detección contra falsas alarmas para cada umbral probado
  • En la alarma, el transformer llega al 100 % de detección sin falsas alarmas. La regla nunca pasa del 72 %, aunque acepte más de 14 falsas alarmas por cada 100 inofensivos.
  • En el golpe, el transformer tiene umbrales con 99 % de detección dentro del límite. La regla no pasa del 30 % ni con 14 falsas alarmas por cada 100.

Con los umbrales fijos, se abre la prueba: 30 turnos con montacargas nuevos, y otros 30 que además traen el sonido nuevo de la cinta.

# 1. Los dos grupos de turnos de prueba.
t0 = time.perf_counter()
turnos_prueba = {"prueba": preparar_turnos("prueba", 30, 300),
                 "prueba con sonido nuevo": preparar_turnos("prueba", 30, 500, con_sonido_nuevo=True)}

# 2. Resultados por evento con los umbrales de validación.
filas = []
for grupo, turnos in turnos_prueba.items():
    for (metodo, clase), u in umbrales.items():
        r = medir(turnos, metodo, clase, u)
        filas.append({"grupo": grupo, "método": metodo, "clase": clase,
                      "detectados": r["detectados"], "reales": r["reales"],
                      "detección (%)": round(100 * r["detectados"] / r["reales"], 1),
                      "falsas": r["falsas"],
                      "falsas por 100": round(100 * r["falsas"] / r["inofensivos"], 2),
                      "por la cinta": r["falsas por cinta"], "repetidos": r["repetidos"],
                      "demora mediana (s)": round(float(np.median(r["demoras"])), 2)
                      if r["demoras"] else None})
tabla_eventos = pd.DataFrame(filas)
tabla_eventos.to_csv(artefactos / "eventos.csv", index=False)
print(f"Turnos de prueba evaluados en {time.perf_counter() - t0:.0f} s")
tabla_eventos[tabla_eventos["grupo"] == "prueba"].drop(columns=["grupo", "por la cinta"])
Turnos de prueba evaluados en 25 s
método clase detectados reales detección (%) falsas falsas por 100 repetidos demora mediana (s)
0 Regla alarma 52 106 49.1 0 0.00 16 0.32
1 Regla golpe 10 101 9.9 17 4.34 0 0.36
2 Transformer alarma 106 106 100.0 0 0.00 1 0.51
3 Transformer golpe 95 101 94.1 0 0.00 0 0.42

En los 30 turnos de prueba, con montacargas que la red nunca escuchó:

  • El transformer detecta las 106 alarmas (100 %) y 95 de los 101 golpes (94.1 %), sin ninguna falsa alarma. Los tonos nuevos (1 090, 1 210 y 1 285 Hz) no le cuestan nada.
  • La regla detecta 52 alarmas (49.1 %) y solo 10 golpes (9.9 %), y además da 17 falsas alarmas de golpe: 4.34 por cada 100 inofensivos, por encima del límite que cumplía en validación.
  • La demora mediana del transformer es de 0.51 s en alarma y 0.42 s en golpe: medio segundo después de empezar el sonido, la luz ya está encendida.
  • La regla tiene 16 avisos repetidos de alarma. Avisa dos veces por la misma alarma (un aviso por pitido) cuando su puntaje baja entre los dos.
turno = turnos_prueba["prueba"][0]
fig, eje = plt.subplots(figsize=(11, 2.8))
for e in turno["eventos"]:
    if e["inicio"] > 60:
        break
    marca = {"alarma": ("^", "#1786B3"), "golpe": ("o", "#EE5400")}.get(e["evento"], ("x", "#89878C"))
    eje.plot(e["inicio"], 2, marca[0], color=marca[1], ms=8)
    eje.text(e["inicio"], 2.25, e["evento"], fontsize=8, ha="center")
for fila, metodo in [(1, "Regla"), (0, "Transformer")]:
    for clase, marca, color in [("alarma", "^", "#1786B3"), ("golpe", "o", "#EE5400")]:
        j = CLASES.index(clase)
        puntaje = turno["regla"][:, j - 1] if metodo == "Regla" else turno["red"][:, j]
        lista = [a for a in avisos(turno["fin"], puntaje >= umbrales[(metodo, clase)]) if a <= 60]
        eje.plot(lista, [fila] * len(lista), marca, color=color, ms=8)
eje.set(xlim=(0, 61), ylim=(-0.5, 2.7), xlabel="tiempo del turno (s)")
eje.set_yticks([0, 1, 2], ["transformer", "regla", "eventos reales"])
plt.tight_layout()
plt.show()
Una línea de tiempo de 0 a 60 segundos con tres filas: eventos reales, avisos de la regla y avisos del transformer. Las alarmas se marcan con triángulos azules y los golpes con círculos naranjas; los sonidos inofensivos con cruces grises en la fila de eventos.
Figura 26.7: Primer minuto de un turno de prueba: eventos reales y avisos de la regla y del transformer

En el primer minuto (60 s) del primer turno de prueba:

  • El transformer da exactamente un aviso por evento: las 3 alarmas y el golpe. No reacciona al timbre ni al carro de mano.
  • La regla avisa un golpe en el segundo 2, donde no hubo golpe, y da dos avisos por casi cada alarma: los avisos repetidos de la tabla.
  • La regla también pierde el golpe del segundo 38.

26.4.8.2 Un sonido que la red nunca oyó

La cinta de embalaje no aparece en ningún dato de entrenamiento ni de validación. Así se comportan los dos métodos en los turnos que la traen:

# 1. Resultados en los turnos con el sonido nuevo.
tabla_eventos[tabla_eventos["grupo"] == "prueba con sonido nuevo"].drop(columns=["grupo"])
método clase detectados reales detección (%) falsas falsas por 100 por la cinta repetidos demora mediana (s)
4 Regla alarma 33 71 46.5 0 0.00 0 12 0.34
5 Regla golpe 7 77 9.1 37 8.15 32 0 0.52
6 Transformer alarma 71 71 100.0 0 0.00 0 0 0.49
7 Transformer golpe 71 77 92.2 11 2.42 11 0 0.39

La cinta no estuvo en ninguno de los 4 800 clips de entrenamiento:

  • Al transformer le cuesta 11 falsas alarmas de golpe, todas por la cinta: 2.42 por cada 100 inofensivos. Sigue dentro del límite, pero pasa de 0 a 11. Los chasquidos de la cinta se parecen a golpes pequeños.
  • Las alarmas no se afectan: 71 de 71 detectadas, sin falsas alarmas. La cinta no tiene un tono sostenido.
  • A la regla le cuesta mucho más: 37 falsas alarmas de golpe (8.15 por cada 100), 32 de ellas por la cinta.
  • La lección para la operación: después de instalar el sistema hay que vigilar las falsas alarmas por tipo de sonido. Cuando aparezca uno nuevo, se graba, se agrega al entrenamiento y se vuelve a escoger el umbral.

26.4.8.3 Según la relación señal-ruido

¿Qué golpes se le escapan al transformer? En los turnos de prueba, la detección de golpes separada por la relación señal-ruido del golpe:

# 1. Para cada golpe real: ¿algún aviso cae en su intervalo? Y su relación señal-ruido.
def golpes_detectados(turnos, metodo):
    filas = []
    for t in turnos:
        puntaje = t["regla"][:, 1] if metodo == "Regla" else t["red"][:, 2]
        lista = avisos(t["fin"], puntaje >= umbrales[(metodo, "golpe")])
        for e in t["eventos"]:
            if e["evento"] == "golpe":
                filas.append({"snr": e["snr"],
                              "detectado": any(e["inicio"] <= a <= e["fin"] + 1 for a in lista)})
    return pd.DataFrame(filas)


rangos = [(-5, 2), (2, 10), (10, 20.01)]
nombres_rango = ["−5 a 2 dB", "2 a 10 dB", "10 a 20 dB"]
fig, eje = plt.subplots(figsize=(7, 3.4))
for k, (metodo, color) in enumerate([("Regla", "#89878C"), ("Transformer", "#EE5400")]):
    g = golpes_detectados(turnos_prueba["prueba"], metodo)
    tasas = [100 * g[(g.snr >= a) & (g.snr < b)]["detectado"].mean() for a, b in rangos]
    eje.bar(np.arange(3) + (k - 0.5) * 0.38, tasas, width=0.38, color=color, label=metodo)
    print(metodo, "detección por rango (%):", [round(float(x), 1) for x in tasas],
          "· golpes por rango:", [int(((g.snr >= a) & (g.snr < b)).sum()) for a, b in rangos])
eje.set_xticks(range(3), nombres_rango)
eje.set(ylabel="golpes detectados (%)", xlabel="relación señal-ruido del golpe", ylim=(0, 100))
eje.legend()
plt.tight_layout()
plt.show()
Regla detección por rango (%): [0.0, 0.0, 22.7] · golpes por rango: [25, 32, 44]
Transformer detección por rango (%): [80.0, 100.0, 97.7] · golpes por rango: [25, 32, 44]
Barras agrupadas de la regla y del transformer para tres rangos de relación señal-ruido: de −5 a 2 dB, de 2 a 10 dB y de 10 a 20 dB. El transformer detecta más golpes en todos los rangos y la diferencia crece cuando el golpe es más fuerte que el fondo.
Figura 26.8: Turnos de prueba: golpes detectados según su relación señal-ruido
  • Con −5 a 2 dB, el transformer detecta el 80.0 % de los 25 golpes; con 2 a 10 dB, los 32 (100 %); con 10 a 20 dB, el 97.7 % de 44.
  • Los golpes perdidos son sobre todo los que suenan más bajo que el fondo: tapados por el ruido de la bodega, una persona tampoco los oiría.
  • La regla solo detecta golpes fuertes: 0 % en los dos primeros rangos y 22.7 % en el más alto.

26.4.9 De la predicción a la decisión de operación

Dos ramas. Arriba, si la probabilidad de alarma supera su umbral, se enciende la luz de reversa del pasillo; una alarma perdida es un riesgo de atropello. Abajo, si la probabilidad de golpe supera su umbral, se avisa al supervisor; cada falsa alarma cuesta 5 000 pesos y cada golpe perdido 40 000.

Los avisos se convierten en acciones: la alarma enciende la luz del pasillo y el golpe le avisa al supervisor; las falsas alarmas y los golpes perdidos tienen costo.

Los turnos simulados tienen un sonido cada 6 a 12 segundos, muchos más que una bodega real. Por eso las tasas medidas en prueba (detección y falsas alarmas por cada 100 inofensivos) se llevan a la densidad de la bodega de la tabla de supuestos: 6 pasillos, 8 horas, 20 alarmas, 1 golpe y 60 sonidos inofensivos por pasillo y hora.

# 1. Llevar las tasas de la prueba a un turno real de la bodega.
pasillo_horas = 6 * 8
filas = []
for metodo in ["Regla", "Transformer"]:
    fila = {"método": metodo}
    falsas = 0.0
    for clase, por_hora in [("alarma", 20), ("golpe", 1)]:
        r = tabla_eventos[(tabla_eventos["grupo"] == "prueba") & (tabla_eventos["método"] == metodo)
                          & (tabla_eventos["clase"] == clase)].iloc[0]
        reales = por_hora * pasillo_horas
        fila[f"{clase}s reales"] = reales
        fila[f"{clase}s perdidas"] = round(reales * (1 - r["detección (%)"] / 100))
        falsas += r["falsas por 100"] / 100 * 60 * pasillo_horas
    fila["falsas alarmas"] = round(falsas)
    fila["costo del turno ($)"] = 5000 * fila["falsas alarmas"] + 40000 * fila["golpes perdidas"]
    filas.append(fila)
tabla_turno = pd.DataFrame(filas).set_index("método").rename(columns={"golpes perdidas": "golpes perdidos",
                                                                      "golpes reales": "golpes reales"})
tabla_turno.to_csv(artefactos / "turno.csv")
tabla_turno
alarmas reales alarmas perdidas golpes reales golpes perdidos falsas alarmas costo del turno ($)
método
Regla 960 489 48 43 125 2345000
Transformer 960 0 48 3 0 120000

En un turno de 8 horas, con los 6 pasillos:

  • La regla pierde 489 de las 960 alarmas de reversa: casi la mitad de las veces que un montacargas retrocede, la luz del pasillo no se enciende. Es el resultado más importante del caso, y no tiene precio en la tabla.
  • La regla pierde además 43 de los 48 golpes y da 125 falsas alarmas: $2 345 000 por turno.
  • El transformer no pierde alarmas, pierde 3 golpes y da 0 falsas alarmas: $120 000 por turno.
  • El ahorro es de $2.2 millones por turno. Además, los supervisores pueden volver a creer en los avisos: una falsa alarma cada pocos minutos es la razón por la que la regla actual se ignora.

Se guarda el modelo con todo lo que necesita para usarse en el pasillo y se comprueba la recarga.

# 1. Guardar el modelo con los parámetros de la preparación y los umbrales.
ruta = artefactos / "transformer_bodega.pt"
torch.save({"pesos": red.state_dict(), "tasa": TASA, "ventana": VENTANA, "salto": SALTO,
            "n_fft": N_FFT, "bandas": BANDAS, "clases": CLASES, "media": media,
            "desviacion": desviacion, "umbral_alarma": umbrales[("Transformer", "alarma")],
            "umbral_golpe": umbrales[("Transformer", "golpe")]}, ruta)

# 2. Recargar en una red nueva y comparar con 32 clips de validación.
paquete = torch.load(ruta, weights_only=True)
copia = TransformerBodega()
copia.load_state_dict(paquete["pesos"])
copia.eval()
x = (preparados["validacion"][0][:32] - media) / desviacion
with torch.no_grad():
    assert torch.allclose(copia(x), red(x))
print(f"Modelo guardado ({ruta.stat().st_size / 1024:.0f} KB) y recargado sin cambios.")
print(f"Tiempo total del caso: {time.perf_counter() - inicio_caso2:.0f} s")
Modelo guardado (315 KB) y recargado sin cambios.
Tiempo total del caso: 167 s

26.4.10 Errores frecuentes en este caso

Dos errores medidos sobre el mismo modelo, con los 600 clips de validación:

  1. Olvidar la normalización al usar el modelo: los tokens entran en la escala original.
  2. Cambiar la tasa de muestreo sin avisar. Se instala un micrófono que graba a 22 050 muestras por segundo y nadie remuestrea: el sistema sigue creyendo que son 16 000. Todo suena más grave: la alarma de 1 180 Hz aparece cerca de 860 Hz, fuera de lo que la red aprendió. (El capítulo de audio explica por qué la tasa importa.)
# 1. La preparación correcta.
y_val = clips["validacion"][1]
correcta = probabilidades(preparados["validacion"][0]).argmax(1)

# 2. Error 1: sin normalizar (se llama a la red con los tokens crudos).
red.eval()
with torch.no_grad():
    sin_normalizar = torch.cat([red(lote) for lote in preparados["validacion"][0].split(256)]).argmax(1).numpy()

# 3. Error 2: audio grabado a 22 050 Hz tratado como si fuera de 16 000 Hz.
audio_22k = resample(clips["validacion"][0], int(TASA * 22050 / 16000), axis=1).astype(np.float32)
tokens_mal, _ = preparar_audio(audio_22k[:, :TASA])          # se toman 16 000 muestras como 1 s
tasa_equivocada = probabilidades(tokens_mal).argmax(1)

pd.DataFrame({"condición": ["preparación correcta", "sin normalizar", "tasa de muestreo equivocada"],
              "exactitud (%)": [100 * np.mean(p == y_val)
                                for p in (correcta, sin_normalizar, tasa_equivocada)]}).round(1)
condición exactitud (%)
0 preparación correcta 99.3
1 sin normalizar 63.2
2 tasa de muestreo equivocada 33.5
  • Sin normalizar, la exactitud cae de 99.3 % a 63.2 %: los tokens llegan en otra escala y la red reconoce menos de dos de cada tres clips.
  • Con la tasa de muestreo equivocada cae a 33.5 %, lo mismo que adivinar al azar entre 3 clases. La alarma suena más grave de lo que la red aprendió, y el golpe y el fondo cambian de forma. El error no produce ningún mensaje: el sistema sigue funcionando, solo que mal.
Lo que ves Qué pasó Cómo se arregla
La red predice casi todo como una sola clase Los tokens no se normalizaron con la media y la desviación de entrenamiento Guardar media y desviacion con el modelo y aplicarlas siempre
Tras cambiar un micrófono, la red deja de reconocer las alarmas La tasa de muestreo cambió y nadie remuestreó Revisar la tasa de cada fuente y remuestrear a 16 000 Hz antes del espectrograma
Las falsas alarmas en prueba son mucho más que en validación Pocos turnos de validación: con pocas falsas alarmas, la cifra es inestable Usar más audio de validación y reportar cuántos avisos cambian con umbrales vecinos
Un sonido nuevo en la bodega dispara avisos de golpe La red solo conoce los sonidos con que se entrenó Vigilar las falsas alarmas por tipo de sonido y agregar al entrenamiento los sonidos nuevos que aparezcan

26.4.11 Conclusiones del caso

  • En turnos continuos con montacargas nuevos, el transformer detecta el 100 % de las alarmas de reversa y el 94.1 % de los golpes, sin falsas alarmas. La regla detecta el 49.1 % y el 9.9 %.
  • Avisa en medio segundo (demora mediana de 0.51 s en alarma y 0.42 s en golpe).
  • Un sonido nuevo cuesta falsas alarmas: la cinta produjo 11 en 90 minutos. Es el riesgo que hay que vigilar después de instalarlo.
  • En un turno de la bodega, pasa de 489 alarmas perdidas y $2.3 millones a 0 alarmas perdidas y $120 000.

¿Qué se lleva el lector de este caso? Que el mismo transformer del texto sirve para el sonido: solo cambian la entrada (columnas del espectrograma en lugar de palabras) y la salida. Que una red con 99 % de exactitud por clip no basta: lo que decide si se puede instalar es cómo se comporta en un turno continuo, con una política de falsas alarmas escogida en validación. Y que un modelo solo conoce lo que vio: un sonido nuevo es el primer riesgo que hay que vigilar después de instalarlo.

Límites del caso. El audio es simulado: una bodega real tiene eco, varios sonidos a la vez, micrófonos distintos y distancias variables, y exigiría grabar y etiquetar audio propio. Las frecuencias de los sonidos y los costos son supuestos. La alarma de reversa perdida no tiene precio en la tabla porque es un riesgo para las personas; se reporta como cantidad.

26.4.12 Ejercicios del caso

  1. Cambia la política a máximo 1 falsa alarma por cada 100 inofensivos y vuelve a escoger los umbrales en validación. ¿Cuántos golpes se pierden ahora?
  2. Agrega la cinta de embalaje a los sonidos inofensivos de entrenamiento (en simulador_clips) y vuelve a medir los turnos con sonido nuevo.
  3. Reduce el codificador a una capa (num_layers=1). ¿Cambia la detección de golpes?
  4. Cambia el paso entre ventanas de 0.25 s a 0.5 s. ¿Qué pasa con la demora y con los avisos repetidos?
  5. Quita el suavizado de etiquetas y mira qué umbrales se escogen en validación.
  1. Una política más estricta sube el umbral de golpe: menos falsas alarmas y más golpes perdidos. Compara los dos costos del turno.
  2. Las falsas alarmas por la cinta deberían caer casi a cero; es lo que se haría en la operación al detectar un sonido nuevo.
  3. Con una capa la red tiene menos de la mitad de parámetros del codificador; mira la detección de golpes en validación antes de abrir la prueba.
  4. La demora mínima posible crece con el paso, y los avisos repetidos bajan porque hay menos ventanas por evento.
  5. Sin suavizado, las probabilidades se pegan a 1 y los umbrales escogidos quedan muy cerca de 1; mira cuántos avisos cambian con los umbrales vecinos.

26.4.13 El simulador del caso

Simulador de los sonidos de la bodega de BITLogística en Funza (datos sintéticos).

Lo usa solo el Caso práctico 2 del capítulo. Genera audio a 16 000 muestras por segundo: clips de 1 segundo con su etiqueta (normal, alarma o golpe) y turnos continuos de varios minutos con la lista de los sonidos que ocurrieron y su instante.

Reglas de la simulación (todas las cifras son inventadas, con órdenes de magnitud plausibles):

  1. El fondo siempre suena: ruido de máquinas, zumbido eléctrico de 60 Hz (la red eléctrica de Colombia), ventilación y voces lejanas.
  2. La alarma de reversa es un pitido de 0.43 a 0.54 s con su tono principal entre 1 000 y 1 300 Hz y dos armónicos débiles, más un eco corto. Cada montacargas tiene su tono; los tonos de prueba no aparecen al entrenar ni al validar, pero están dentro del mismo rango: son montacargas nuevos del mismo tipo.
  3. El golpe de una caja es una ráfaga de ruido de 30 a 120 ms con una resonancia grave de 60 a 150 Hz que se apaga rápido.
  4. Sonidos inofensivos (la red no debe avisar): pito de un carro, timbre de celular, puerta que se cierra y carro de mano. Aparecen en todas las particiones.
  5. Sonido nuevo: la cinta de embalaje que se rasga. Solo aparece en los turnos de prueba «con sonido nuevo», para medir qué pasa cuando la red oye algo que nunca escuchó.
  6. Cada sonido se mezcla con el fondo con una relación señal-ruido al azar entre −5 y +20 dB.
  7. En los clips, un sonido puede quedar cortado por el borde: así se ve en la operación, cuando la ventana de 1 s se desliza por el turno y corta los sonidos largos.
"""Simulador de los sonidos de la bodega de BITLogística en Funza (datos sintéticos).

Lo usa solo el Caso práctico 2 del capítulo. Genera audio a 16 000 muestras por segundo:
clips de 1 segundo con su etiqueta (normal, alarma o golpe) y turnos continuos de varios
minutos con la lista de los sonidos que ocurrieron y su instante.

Reglas de la simulación (todas las cifras son inventadas, con órdenes de magnitud plausibles):

1. El fondo siempre suena: ruido de máquinas, zumbido eléctrico de 60 Hz (la red eléctrica de
   Colombia), ventilación y voces lejanas.
2. La alarma de reversa es un pitido de 0.43 a 0.54 s con su tono principal entre 1 000 y
   1 300 Hz y dos armónicos débiles, más un eco corto. Cada montacargas tiene su tono; los
   tonos de prueba no aparecen al entrenar ni al validar, pero
   están dentro del mismo rango: son montacargas nuevos del mismo tipo.
3. El golpe de una caja es una ráfaga de ruido de 30 a 120 ms con una resonancia grave de
   60 a 150 Hz que se apaga rápido.
4. Sonidos inofensivos (la red no debe avisar): pito de un carro, timbre de celular, puerta
   que se cierra y carro de mano. Aparecen en todas las particiones.
5. Sonido nuevo: la cinta de embalaje que se rasga. Solo aparece en los turnos de prueba
   «con sonido nuevo», para medir qué pasa cuando la red oye algo que nunca escuchó.
6. Cada sonido se mezcla con el fondo con una relación señal-ruido al azar entre −5 y +20 dB.
7. En los clips, un sonido puede quedar cortado por el borde: así se ve en la operación,
   cuando la ventana de 1 s se desliza por el turno y corta los sonidos largos.
"""

import numpy as np
from scipy.signal import butter, sosfilt

TASA = 16000                                   # muestras por segundo
CLASES = ("normal", "alarma", "golpe")
TONOS = {                                      # tono principal de la alarma de cada montacargas (Hz)
    "entrenamiento": (1000, 1060, 1120, 1180, 1240, 1300),
    "validacion": (1030, 1150, 1270),
    "prueba": (1090, 1210, 1285),
}
INOFENSIVOS = ("pito", "timbre", "puerta", "carro de mano")
NUEVO = "cinta"                                # solo en los turnos de prueba con sonido nuevo
FILTRO_VOCES = butter(2, [300, 3000], btype="bandpass", fs=TASA, output="sos")
FILTRO_CINTA = butter(2, [1500, 6000], btype="bandpass", fs=TASA, output="sos")


def tiempo(n):
    """Instante en segundos de cada una de las n muestras."""
    return np.arange(n, dtype=np.float32) / TASA


def tono(t, frecuencia):
    return np.sin(2 * np.pi * frecuencia * t)


def fondo(n, rng):
    """1. Fondo de la bodega: ruido, zumbido de 60 Hz, ventilación y voces lejanas."""
    t = tiempo(n)
    x = rng.normal(0, .013, n).astype(np.float32)                # máquinas
    x += .006 * tono(t, 60) + .002 * tono(t, 120)                # zumbido eléctrico
    x += .005 * tono(t, 96) * (.65 + .35 * tono(t, 1.7))         # ventilación
    voces = sosfilt(FILTRO_VOCES, rng.normal(0, .008, n)).astype(np.float32)
    x += voces * (.55 + .45 * tono(t, 4))                        # unas 4 sílabas por segundo
    return x


def sonido(nombre, rng, frecuencia=None, repetir=False):
    """Genera la onda de un sonido. Con ``repetir`` la alarma suena dos veces (pitido, pausa, pitido)."""
    if nombre == "alarma":                                       # 2.
        n = int(TASA * rng.uniform(.43, .54))
        t = tiempo(n)
        x = tono(t, frecuencia) + .22 * tono(t, 2 * frecuencia) + .08 * tono(t, 3 * frecuencia)
        borde = min(100, n // 2)                                 # bordes suaves, sin clic
        x[:borde] *= np.linspace(0, 1, borde)
        x[-borde:] *= np.linspace(1, 0, borde)
        demora = int(TASA * .018)                                # eco a 18 ms
        x[demora:] += rng.uniform(.07, .22) * x[:-demora].copy()
        if repetir:
            pausa = np.zeros(TASA - n, dtype=np.float32)
            x = np.concatenate((x, pausa, x))
    elif nombre in ("golpe", "puerta"):                          # 3. y la puerta, más suave y grave
        duracion = rng.uniform(.03, .12) if nombre == "golpe" else rng.uniform(.08, .16)
        t = tiempo(int(TASA * duracion))
        ruido = 1.0 if nombre == "golpe" else .20
        grave = rng.uniform(60, 150) if nombre == "golpe" else rng.uniform(40, 75)
        x = (ruido * rng.normal(size=len(t)) + .8 * tono(t, grave)) * np.exp(-5 * t / duracion)
    elif nombre == "pito":
        t = tiempo(int(TASA * rng.uniform(.48, .85)))
        f = rng.uniform(400, 500)
        x = tono(t, f) + .45 * tono(t, 2 * f)
    elif nombre == "timbre":
        t = tiempo(int(TASA * rng.uniform(.35, .65)))
        x = np.where((t % .20) < .10, tono(t, 880), tono(t, 1470))
    elif nombre == "carro de mano":
        t = tiempo(int(TASA * rng.uniform(.4, .85)))
        x = .30 * rng.normal(size=len(t)) + tono(t, 170) * (.6 + .4 * tono(t, 17))
    elif nombre == "cinta":                                      # 5. rasgado: chasquidos agudos rápidos
        t = tiempo(int(TASA * rng.uniform(.5, .9)))
        chasquidos = (np.sin(2 * np.pi * rng.uniform(20, 35) * t) > .6).astype(np.float32)
        x = sosfilt(FILTRO_CINTA, rng.normal(size=len(t))) * (.3 + chasquidos)
    else:
        raise ValueError(f"Sonido desconocido: {nombre}")
    return np.asarray(x, dtype=np.float32)


def mezclar(audio, senal, inicio, snr):
    """6. Suma la señal al fondo con la relación señal-ruido pedida (en dB). Devuelve el fin."""
    if inicio < 0:                                               # empieza antes del clip: se corta
        senal = senal[-inicio:]
        inicio = 0
    fin = min(inicio + len(senal), len(audio))
    senal = senal[:fin - inicio]
    tramo = audio[inicio:fin]
    energia_fondo = float(np.mean(tramo ** 2))
    activos = senal[np.abs(senal) > .01 * np.max(np.abs(senal))]     # sin contar los silencios
    energia_senal = float(np.mean(activos ** 2))
    factor = np.sqrt(energia_fondo / max(energia_senal, 1e-12) * 10 ** (snr / 10))
    tramo += factor * senal
    return fin


def simular_clips(cantidad, semilla, particion):
    """Clips de 1 s. Las clases se alternan para que haya la misma cantidad de cada una."""
    rng = np.random.default_rng(semilla)
    clips = np.empty((cantidad, TASA), dtype=np.float32)
    etiquetas, detalles = [], []
    for i in range(cantidad):
        clase = CLASES[i % len(CLASES)]
        evento = clase
        if clase == "normal":                       # 75 % con un sonido inofensivo, 25 % solo fondo
            evento = str(rng.choice(INOFENSIVOS)) if rng.random() < .75 else "fondo"
        audio = fondo(TASA, rng)
        frecuencia = int(rng.choice(TONOS[particion])) if evento == "alarma" else None
        snr = float(rng.uniform(-5, 20)) if evento != "fondo" else None
        if evento != "fondo":
            senal = sonido(evento, rng, frecuencia)
            # 7. Los sonidos inofensivos pueden quedar cortados por el borde del clip, como
            #    pasa con la ventana que se desliza por el turno. La alarma y el golpe quedan
            #    por lo menos en su mitad dentro del clip.
            mitad = len(senal) // 2
            inicio = int(rng.integers(-mitad, TASA - mitad))
            mezclar(audio, senal, inicio, snr)
        clips[i] = audio
        etiquetas.append(CLASES.index(clase))
        detalles.append({"evento": evento, "frecuencia": frecuencia, "snr": snr})
    return clips, np.asarray(etiquetas), detalles


def simular_turno(segundos, semilla, particion, con_sonido_nuevo=False):
    """Un tramo continuo de turno. Cada 6 a 12 s ocurre un sonido; se devuelve la lista."""
    rng = np.random.default_rng(semilla)
    audio = fondo(segundos * TASA, rng)
    opciones = ["alarma", "golpe", *INOFENSIVOS] + ([NUEVO, NUEVO] if con_sonido_nuevo else [])
    eventos = []
    segundo = 2.0
    while segundo < segundos - 3:
        evento = str(rng.choice(opciones))
        frecuencia = int(rng.choice(TONOS[particion])) if evento == "alarma" else None
        snr = float(rng.uniform(-5, 20))
        inicio = int(segundo * TASA)
        fin = mezclar(audio, sonido(evento, rng, frecuencia, repetir=True), inicio, snr)
        eventos.append({"evento": evento, "inicio": inicio / TASA, "fin": fin / TASA,
                        "frecuencia": frecuencia, "snr": snr})
        segundo += float(rng.uniform(6, 12))
    return audio, eventos

26.5 Referencias

  • Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., Kaiser, Ł. y Polosukhin, I. (2017). Attention is all you need. Advances in Neural Information Processing Systems 30.
  • Devlin, J., Chang, M.-W., Lee, K. y Toutanova, K. (2019). BERT: Pre-training of deep bidirectional transformers for language understanding. Proceedings of NAACL-HLT 2019, 4171–4186.
  • Gong, Y., Chung, Y.-A. y Glass, J. (2021). AST: Audio Spectrogram Transformer. Proceedings of Interspeech 2021, 571–575.
  • Szegedy, C., Vanhoucke, V., Ioffe, S., Shlens, J. y Wojna, Z. (2016). Rethinking the Inception architecture for computer vision. Proceedings of CVPR 2016 (suavizado de etiquetas).
  • Documentación de PyTorch: nn.TransformerEncoderLayer, nn.TransformerEncoder y torch.stft.