Pipeline IA: Manejo de Errores y Handoff

Parte 3 de 3. Parte 1 | Parte 2

Manejo de Errores

Ningún pipeline es inmune a fallos. Las APIs de LLM tienen rate limits, downtime y errores transitorios. Uso tres capas de manejo de errores para cada pipeline, más dos capas de monitoreo:

Dead Letter Queues (DLQ): Almacena eventos que fallan todos los reintentos. Máximo 10k eventos, alerto cuando supera 1k.
Backoff Exponencial: Reintenta con delays crecientes (1s, 2s, 4s, 8s) hasta 5 intentos. Jitter de ±30% para evitar thundering herd.
Circuit Breakers: Detiene llamadas a LLM si devuelven errores 429 repetidos. Se abre tras 5 errores consecutivos, se cierra tras 60 segundos.
Alertas: Alerta sobre tamaño de DLQ, altas tasas de error y latencia de API.
Logging: Registra todos los errores, reintentos y eventos de DLQ en Elasticsearch.

Configuración de DLQ y reintentos con Redis Streams:

apiVersion: v1
kind: ConfigMap
metadata:
  name: redis-dlq-config
  namespace: ai-pipelines
data:
  dlq-max-len: "10000"
  retry-max-attempts: "5"
  retry-backoff-base: "1000"
  retry-backoff-jitter: "0.3"
  circuit-breaker-threshold: "5"
  circuit-breaker-timeout: "60000"
---
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: ai-pipeline-alerts
  namespace: ai-pipelines
spec:
  groups:
  - name: dlq
    rules:
    - alert: DLQSizeHigh
      expr: redis_stream_length{stream="dlq"} > 1000
      for: 5m
      labels:
        severity: critical
      annotations:
        summary: "DLQ size exceeds 1000 events"

Patrón de Handoff n8n → Temporal

El handoff entre n8n y Temporal es donde la mayoría de los pipelines se rompen. n8n es excelente para ingerir webhooks, pero no está diseñado para orquestación de workflows largos, reintentos complejos o gestión de estado. Temporal maneja eso. El handoff usa el nodo HTTP Request de n8n para llamar a la API gRPC de Temporal.

Tres salvaguardas:

Reintento: n8n reintenta 3 veces si Temporal no está disponible.
Cola de Fallback: Si Temporal está caído por más de 5 minutos, envía eventos a una cola Redis.
Autenticación: mTLS entre n8n y Temporal en producción.

Configuración del nodo HTTP Request de n8n:

{
  "method": "POST",
  "url": "https://temporal-api.ai-pipelines.svc.cluster.local:7233/api/v1/namespaces/default/workflows",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{$env.TEMPORAL_API_KEY}}"
  },
  "body": {
    "workflowType": "processLLMWorkflow",
    "taskQueue": "ai-pipelines",
    "input": "{{$json.event}}",
    "workflowId": "llm-{{$json.dedupKey}}",
    "retryPolicy": {
      "maximumAttempts": 5,
      "initialInterval": "1s",
      "backoffCoefficient": 2
    }
  },
  "timeout": 10000,
  "retryOnFail": true,
  "maxRetries": 3,
  "fallback": {
    "action": "sendToQueue",
    "queue": "fallback-queue"
  }
}

FAQ

¿Cuál es la diferencia entre al-menos-una-vez y a-lo-más-una-vez?

Al-menos-una-vez garantiza que un evento se procese una o más veces (posibles duplicados). A-lo-más-una-vez garantiza 0 o 1 veces (eventos pueden perderse). Para pipelines de IA, al-menos-una-vez con idempotencia es la opción segura. Perder eventos críticos como tickets de soporte o pagos es peor que procesarlos dos veces.

¿Por qué usar Redis Streams en lugar de una lista simple?

Redis Streams tiene grupos de consumidores que permiten a varios workers compartir la carga y recuperarse de caídas. Las listas simples pierden mensajes si un worker muere a mitad del procesamiento. Lo aprendí por las malas en producción.

¿Cómo manejo los rate limits de la API de LLM?

Implementa backoff exponencial con jitter en Temporal y un circuit breaker para 429s repetidos. Uso el plugin temporal-circuit-breaker. El circuit breaker se abre tras 5 errores 429 consecutivos y se cierra tras 60 segundos.

¿Qué es una dead letter queue y cuándo usarla?

Es una cola para eventos que fallaron tras agotar todos los reintentos. Revisa los eventos de DLQ a diario. Alerta cuando la longitud exceda 1k eventos. Si la DLQ crece más rápido de lo que la procesas, tienes un problema sistémico.

¿Puedo usar solo n8n sin Temporal?

Para menos de 100 eventos/día, sí. Para producción, n8n no tiene soporte nativo para workflows largos, reintentos complejos u orquestación stateful. Lo intenté con un cliente de 50k eventos/día. En una semana teníamos pérdida de eventos, timeouts y sin forma de recuperar estados a medio procesar.

¿Cómo monitoreo el backpressure?

Mide longitud de cola, lag de consumidores (XINFO GROUPS) y tasa de error de LLM. Uso Prometheus y Grafana en cada cluster. Cuando el lag supera 10k eventos, es hora de escalar workers.

¿Cómo escalo esta arquitectura?

Agrega más shards de Redis Streams, más workers de Temporal (autoscaling horizontal funciona bien) y balancea el ingress de n8n. He llegado a 1.2M eventos/día con 5 workers de Temporal y 3 shards de Redis.

Próximos Pasos

Una vez construido el pipeline, ejecuta esta checklist:

Validación de webhooks con HMAC + lista de IPs
Redis Streams desplegado con persistencia y monitoreo
Claves de idempotencia implementadas
DLQ configurada con alertas
Workflows de Temporal probados con reintentos
Pruebas de carga a 2x del pico esperado

He usado esta arquitectura para 6 despliegues en producción. Nunca me ha fallado.

Partes in this series: ← Parte 2