Runbook de Respuesta a Incidentes de LLM

Resumen

Este runbook cubre los cinco incidentes de LLM en producción que más a menudo despiertan a los equipos de guardia: caídas de la API del modelo, eventos de alucinación, picos de costo, fallos de seguridad y degradación de calidad. Cada sección te da síntomas para confirmar, pasos de diagnóstico que ejecutar y acciones de recuperación en orden de prioridad.

A diferencia de un runbook clásico de infraestructura, los incidentes de LLM rara vez significan “el servidor está caído”. Los modos de fallo son más difusos: el modelo responde pero miente, la factura se triplica de la noche a la mañana, una inyección de prompt se cuela por tus guardarraíles. Por eso cada tipo de incidente combina diagnósticos técnicos con decisiones de producto, como desactivar una funcionalidad o revertir una versión de prompt.

Cópialo, reemplaza los marcadores con tus propios contactos y umbrales, y guárdalo donde tu rotación de guardia pueda encontrarlo de verdad a las 3 de la mañana.

Cómo adoptar este runbook

Antes de que este runbook pueda hacer su trabajo durante un incidente, adáptalo a tu configuración:

• Completa la tabla de contactos: reemplaza los emails y canales de ejemplo con tu rotación de guardia real, y verifica que cada uno llega efectivamente a una persona.
• Ajusta los umbrales de severidad: los valores por defecto (aumento del 20% en tasa de errores, multiplicadores de costo 3x/10x, escalado a los 15 minutos) asumen un producto de tráfico medio. Un proyecto personal puede relajarlos; una API de pago debería endurecerlos.
• Lista tus funcionalidades de IA por criticidad: los pasos de recuperación asumen que sabes qué funcionalidades puedes desactivar sin problema. Escribe esa lista ahora, no durante la caída.
• Elige tu modelo de respaldo: la sección 3 asume que existe un segundo proveedor. Si solo usas uno, decide si las respuestas cacheadas o estáticas son tu modo degradado.
• Conecta los diagnósticos a dashboards reales: cada paso de “revisa el monitoreo” debería enlazar a una URL concreta de dashboard en tu copia.

El modelo de severidad toma prestado de la gestión de incidentes clásica: consulta el capítulo sobre gestión de incidentes del libro SRE de Google y la guía pública de respuesta a incidentes de PagerDuty para ver el marco que aquí se adapta a los fallos específicos de LLM.

Archivos complementarios: el repo companion de ai-llm-incident-response-runbook tiene este runbook como archivo independiente más un script check-llm-status.sh que consulta las páginas de estado de los proveedores y prueba la conectividad de las APIs.

---

1. Niveles de severidad

La severidad decide cuánto tienes que correr y a quién se despierta. Clasifica por radio de impacto, no por lo alarmante que parece el síntoma: una alucinación en una herramienta interna es SEV-3; la misma alucinación en consejo médico es SEV-1.

SEV-1 (Crítica):
  - Servicio LLM completamente caído
  - Fallo de seguridad que causa daño a usuarios
  - Pico de costo > 10x el gasto diario normal
  - Fuga de datos por inyección de prompt
  Respuesta: Inmediata, todo el equipo, despertar guardia + dirección

SEV-2 (Alta):
  - Degradación significativa de calidad (> 20% de aumento en tasa de errores)
  - Latencia del modelo > 5x lo normal
  - Una funcionalidad rota (p. ej., RAG no devuelve resultados)
  - Pico de costo > 3x el gasto diario normal
  - Respuesta: Despertar a la guardia en 15 minutos

SEV-3 (Media):
  - Degradación menor de calidad (< 20% de aumento en tasa de errores)
  - Errores intermitentes (< 5% de las peticiones)
  - Funcionalidad no crítica degradada
  Respuesta: Notificar a la guardia en horario laboral

SEV-4 (Baja):
  - Problemas cosméticos en el formato de salida
  - Alucinación ocasional en casos límite
  - Alerta de monitoreo sin impacto en usuarios
  Respuesta: Crear ticket, abordar en el próximo sprint

Dos umbrales merecen una segunda mirada al adoptar esto: los multiplicadores de costo dependen de tu margen de presupuesto, y la línea del “20% de tasa de errores” debería fijarse contra tu propia variación de referencia, no copiarse a ciegas.

---

2. Ruta de escalado

El escalado existe para que un respondedor atascado nunca se queme solo durante todo el incidente. Cada peldaño tiene un límite de tiempo: si no has avanzado, escalas, aunque estés “a punto de resolverlo”.

Ingeniero de guardia
  ↓ (no lo resuelve en 15 min para SEV-1/2)
Líder del equipo de IA
  ↓ (no lo resuelve en 30 min)
Gerente de ingeniería
  ↓ (solo SEV-1)
CTO / VP de Ingeniería
  ↓ (si hay daño a usuarios o fuga de datos)
Equipo legal / PR / Seguridad

Contactos

Rol                 | Principal            | Secundario
────────────────────┼──────────────────────┼──────────────────
Ingeniero de guardia| #ai-on-call          | PagerDuty: ai-team
Líder equipo de IA  | [email-del-lider]    | [backup-del-lider]
Gerente de ing.     | [email-del-gerente]  | #engineering
Equipo de seguridad | [email-de-seguridad] | #security-urgent

---

3. Incidente: caída de la API del modelo

El proveedor está caído o inalcanzable. Este es el único incidente de LLM donde la solución es mayormente esperar: tu trabajo es mantener vivo el producto mientras ellos se recuperan.

Síntomas

• Todas las llamadas a la API del LLM devuelven errores 5xx
• Errores de timeout en cada petición
• La página de estado del proveedor muestra una caída

Pasos de diagnóstico

# 1. Revisa el estado del proveedor
curl -s https://status.openai.com/api/v2/status.json | jq

# 2. Prueba la conectividad de la API
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | jq '.data[0].id'

# 3. Revisa la tasa de errores en el monitoreo
# Mira el dashboard de tasa de errores de los últimos 30 minutos

# 4. Prueba el modelo de respaldo
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-haiku","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

Acciones de recuperación

1. Activa el modelo de respaldo:
   - Activa el feature flag: FALLBACK_MODEL=claude-3-5-sonnet
   - Enruta todo el tráfico al proveedor de respaldo
   - Avisa a los usuarios de posibles diferencias de calidad

2. Si el respaldo también está caído:
   - Activa el modo de respuestas cacheadas (devuelve la última
     respuesta válida conocida)
   - Cambia a respuestas estáticas de respaldo en las rutas críticas
   - Desactiva las funcionalidades de IA no críticas

3. Monitorea el estado del proveedor:
   - Revisa la página de estado cada 5 minutos
   - Suscríbete a las actualizaciones de estado del proveedor

4. Cuando el proveedor se recupere:
   - Devuelve el tráfico gradualmente (10% → 50% → 100%)
   - Monitorea tasas de error y latencia
   - Desactiva el respaldo tras 30 minutos de operación estable

Los porcentajes de cambio de tráfico del paso 4 importan más de lo que parece: volver de golpe al 100% en cuanto la página de estado se pone verde es la forma de pillar la recuperación tambaleante del proveedor y rebotar el incidente dos veces.

---

4. Incidente: evento de alucinación

Los usuarios reciben respuestas seguras pero incorrectas. A diferencia de una caída, esto falla en silencio: normalmente te enterarás por tickets de soporte o redes sociales antes de que se encienda cualquier dashboard.

Síntomas

• Los usuarios reportan información incorrecta en las respuestas
• El monitoreo muestra una caída en la puntuación de fidelidad
• Las redes sociales o los tickets de soporte señalan respuestas erróneas

Pasos de diagnóstico

# 1. Identifica las consultas afectadas
import json

def find_hallucinations(logs: list, threshold: float = 0.7):
    suspicious = []
    for log in logs:
        if log.get("faithfulness_score", 1.0) < threshold:
            suspicious.append({
                "query": log["query"],
                "answer": log["answer"],
                "score": log["faithfulness_score"],
                "timestamp": log["timestamp"],
            })
    return suspicious

# 2. Comprueba si la recuperación devuelve contexto erróneo
def check_retrieval(query: str, expected_source: str):
    results = vector_store.search(query, top_k=5)
    for r in results:
        if expected_source in r["metadata"]["source"]:
            return True
    return False

# 3. Comprueba si el prompt cambió recientemente
# Revisa el historial de versiones del prompt en metadata.yaml

Acciones de recuperación

1. Inmediatas:
   - Revierte a la versión anterior del prompt:
     cp versions/3.1.0.md prompt.md
   - Si el problema es de RAG: comprueba si el corpus se actualizó
     recientemente con datos incorrectos
   - Desactiva la funcionalidad afectada si las alucinaciones
     son graves

2. Investigación:
   - Analiza entre 20 y 50 consultas afectadas
   - Determina la causa raíz: cambio de prompt, cambio de corpus,
     actualización del modelo o caso límite
   - Documenta los hallazgos en el informe del incidente

3. Prevención:
   - Añade las consultas afectadas al conjunto de pruebas
   - Refuerza las instrucciones de anclaje del system prompt
   - Añade una comprobación de fidelidad al pipeline de CI/CD
   - Configura monitoreo de alucinaciones en tiempo real

La causa raíz suele ser una de cuatro cosas: una edición del prompt, una actualización del corpus, un cambio silencioso del modelo por parte del proveedor, o una nueva clase de consultas de usuarios. Revísalas en ese orden: los cambios de prompt y corpus son tuyos y los puedes ver; los cambios de modelo requieren comparar salidas contra tu conjunto de referencia.

---

5. Incidente: pico de costo

La factura saltó. Los picos de costo son traicioneros porque nada está “roto”: el sistema funciona exactamente como se diseñó, solo que a 10 veces el precio.

Síntomas

• Costo diario del LLM > 3x lo normal (SEV-2) o > 10x lo normal (SEV-1)
• Alerta de monitoreo de costos disparada
• Notificación de umbral de presupuesto

Pasos de diagnóstico

# 1. Identifica el origen del costo
def analyze_cost_spike(daily_logs: list):
    by_feature = defaultdict(float)
    by_user = defaultdict(float)
    by_model = defaultdict(float)
    
    for log in daily_logs:
        by_feature[log["feature"]] += log["cost"]
        by_user[log["user_id"]] += log["cost"]
        by_model[log["model"]] += log["cost"]
    
    return {
        "by_feature": sorted(by_feature.items(), key=lambda x: -x[1]),
        "by_user": sorted(by_user.items(), key=lambda x: -x[1]),
        "by_model": sorted(by_model.items(), key=lambda x: -x[1]),
    }

# 2. Busca anomalías
# - ¿Un solo usuario enviando prompts anormalmente largos?
# - ¿Un bug provocando reintentos repetidos?
# - ¿El modelo cambió sin actualizar el cálculo de costos?
# - ¿RAG recuperando demasiados chunks?

Acciones de recuperación

1. Inmediatas (SEV-1):
   - Activa el límite de costo: fija daily_budget en normal * 1.5
   - Desactiva funcionalidades no críticas (descripción de imágenes,
     análisis de sentimiento)
   - Aplica rate limit a los usuarios que más gastan

2. Inmediatas (SEV-2):
   - Identifica el motor del costo (funcionalidad, usuario o modelo)
   - Si es un solo usuario: aplica rate limit
   - Si es un bug: despliega el arreglo o desactiva la funcionalidad
   - Si es un cambio de modelo: vuelve al modelo más barato

3. Investigación:
   - Revisa los logs de costo de las últimas 24 horas
   - Busca nuevas fuentes de tráfico (bot, integración, evento viral)
   - Verifica que los cálculos de precio coincidan con los del proveedor
   - Revisa los conteos de tokens de los prompts por aumentos inesperados

Los sospechosos habituales, en orden de frecuencia como culpables: un bucle de reintentos desbocado, un usuario o integración martilleando un endpoint, una funcionalidad que salió con prompts mucho más largos de lo presupuestado, y — el caro — un proveedor que cambia el precio del modelo o enruta silenciosamente a un nivel superior.

---

6. Incidente: fallo de seguridad

Un guardarraíl falló: se ejecutó una acción restringida, salida dañina, bypass por inyección o PII en una respuesta. Trata cada fallo de seguridad como SEV-1 hasta demostrar lo contrario: el coste de reaccionar de menos es mucho peor que el de desactivar una funcionalidad durante una hora.

Síntomas

• El agente ejecuta una acción restringida
• La salida contiene contenido dañino, sesgado o inapropiado
• Una inyección de prompt salta los guardarraíles
• PII filtrada en las respuestas

Pasos de diagnóstico

1. Captura el log completo de la conversación
2. Identifica la entrada que disparó el fallo
3. Comprueba si los guardarraíles de seguridad estaban activos
4. Comprueba si la entrada saltó la validación de entrada
5. Determina si es un ataque nuevo o un patrón conocido
6. Comprueba si un cambio reciente de prompt o modelo
   debilitó los guardarraíles

Acciones de recuperación

1. Inmediatas:
   - Desactiva el agente/funcionalidad afectada
   - Bloquea al usuario si hay intención maliciosa
   - Notifica al equipo de seguridad y a dirección
   - Conserva todos los logs para la investigación

2. Si hay fuga de PII:
   - Identifica qué PII se expuso y a quién
   - Notifica a los usuarios afectados (obligatorio por ley
     en muchas jurisdicciones)
   - Notifica al equipo legal y al DPO

3. Si hay salida dañina:
   - Añade el patrón de entrada a la lista de bloqueo
   - Refuerza las instrucciones de seguridad del system prompt
   - Añade una capa adicional de validación de salida
   - Reprueba con entradas adversarias

4. Post-incidente:
   - Realiza una revisión de seguridad completa
   - Actualiza los guardarraíles y la suite de pruebas
   - Documenta en el registro de incidentes de seguridad
   - Revisa con el equipo legal/de cumplimiento

El “conserva todos los logs” del paso 1 es fácil de saltarse bajo presión y doloroso de saltarse legalmente: si una fuga de PII se convierte en obligación de divulgación, esos logs son tu evidencia del alcance.

---

7. Incidente: degradación de calidad

Nada está caído, nada es caro, nada es inseguro: las respuestas simplemente son peores. La deriva de calidad es el incidente más difícil de detectar y el más fácil de ignorar hasta que aparece el churn.

Síntomas

• Las puntuaciones de satisfacción de usuarios bajan
• La tasa de errores aumenta
• Tickets de soporte sobre respuestas erróneas o poco útiles
• El monitoreo muestra una caída de precisión

Pasos de diagnóstico

1. Busca cambios recientes:
   - Cambios de versión del prompt (revisa metadata.yaml)
   - Actualizaciones de versión del modelo (el proveedor puede
     haber actualizado el modelo)
   - Cambios en el corpus (documentos nuevos, contenido actualizado)
   - Cambios de configuración (temperature, max_tokens, top_k)

2. Ejecuta el conjunto de pruebas de referencia:
   python scripts/eval_prompt.py --prompt current --test-set golden.jsonl
   Compara los resultados con la línea base

3. Muestrea 50 respuestas recientes:
   - Puntúa cada una en precisión, relevancia y fidelidad
   - Identifica patrones en las respuestas con puntuación baja

Acciones de recuperación

1. Si la degradación la causó un cambio de prompt:
   - Revierte a la versión anterior del prompt
   - Vuelve a ejecutar la evaluación para confirmar la recuperación

2. Si la causó una actualización del modelo:
   - Cambia al modelo de respaldo
   - Reporta el problema al proveedor del modelo
   - Ajusta el prompt al comportamiento del nuevo modelo

3. Si la causó un cambio del corpus:
   - Identifica qué documentos se añadieron/modificaron
   - Comprueba si los nuevos documentos contienen información
     incorrecta o conflictiva
   - Elimina o corrige los documentos problemáticos
   - Reconstruye el índice vectorial

4. Si no hay cambios recientes:
   - Busca un cambio de distribución en las consultas de usuarios
   - Monitorea entradas adversarias
   - Considera cambios estacionales o por eventos en los
     patrones de consulta

Si tu conjunto de pruebas de referencia no detecta la degradación que los usuarios reportan, lo que hay que arreglar es el conjunto de pruebas: ya no representa lo que los usuarios preguntan de verdad. Es un hallazgo que merece su propia acción.

---

8. Checklist post-incidente

[ ] Incidente documentado en el tracker de incidentes
[ ] Cronología de eventos registrada
[ ] Causa raíz identificada
[ ] Arreglo desplegado y verificado
[ ] Conjunto de pruebas actualizado con casos de regresión
[ ] Umbrales de monitoreo ajustados si hace falta
[ ] Postmortem programado en 48 horas
[ ] Acciones asignadas con fechas límite
[ ] Stakeholders notificados de la resolución
[ ] Runbook actualizado con los aprendizajes

El último ítem es el que hace que este documento mejore con el tiempo: cada incidente que no está en este runbook es un hueco que acabas de descubrir gratis.

Ver también

• Guía completa de LLM Prompt Engineering
• Guía completa de LangChain en Producción
• Guía completa de Arquitectura de Aplicaciones LLM
• Guía completa de Optimización de Costos LLM
• Guía completa de Evaluación de LLM