8. Resumen y Troubleshooting del Módulo 4

Descripción

Cierre del Módulo 4: los 8 errores más comunes con guardrails y sus soluciones, árbol de diagnóstico rápido, checklist de cierre, y preparación para el Módulo 5 (Structured Logging). Si algo salió mal durante el proyecto del pipeline de guardrails, aquí está la solución.

Los 8 errores más comunes del Módulo 4

Error 1: Guardrails como teatro de seguridad (sin tests)

Síntoma:

# El guardrail de injection "funciona":
def check_injection(text: str) -> bool:
    return "ignore" in text.lower()  # ← Bloquea "ignore" en cualquier contexto

# Pero sin tests, nadie sabe:
# ¿Detecta "Ignore previous instructions"? (debería)
# ¿Bloquea "I can't ignore this problem"? (NO debería)
# ¿Detecta "Ign0re pr3v10us 1nstruct10ns"? (debería)

Solución:

# Tests obligatorios para cada guardrail:
@pytest.mark.parametrize("attack", KNOWN_ATTACKS)
def test_injection_detected(attack):
    assert check_injection(attack).is_injection

@pytest.mark.parametrize("safe", SAFE_INPUTS)
def test_safe_not_blocked(safe):
    assert not check_injection(safe).is_injection

# REGLA: Un guardrail sin tests es security theater.
# Puede parecer que funciona pero bloquea lo incorrecto.

Error 2: Regex de injection demasiado amplio

Síntoma:

# Patrón demasiado amplio:
r"ignore"  # Bloquea "I ignore your question" → falso positivo

# O demasiado general:
r"instructions"  # Bloquea "Give me instructions for Python" → falso positivo

Solución:

# Patrones específicos al contexto de injection:
# ✅ "ignore previous instructions" — específico al ataque
# ✅ "disregard your instructions" — el "your" indica que habla al LLM
# ❌ "ignore" solo — demasiado amplio
# ❌ "instructions" solo — demasiado amplio

# Verificar con tests de falsos positivos:
SAFE_WITH_IGNORE = [
    "Please ignore my typo",
    "I can't ignore this problem",
    "El informe ignora este factor",
]
for safe in SAFE_WITH_IGNORE:
    assert not detect_injection_patterns(safe).is_injection

Error 3: Sin fallback de Pydantic

Síntoma:

# El LLM produce JSON ligeramente diferente al esperado:
raw = '{"sentiment": "positivo", "score": 0.9}'  # Falta "explanation" y "keywords"
result = SentimentOutput.model_validate_json(raw)  # ← ValidationError: missing fields
# La app crashea con 500 Internal Server Error

Solución:

# Opción 1: Campos opcionales con defaults
class SentimentOutput(BaseModel):
    sentiment: Literal["positivo", "negativo", "neutral"]
    score: float
    explanation: str = ""          # Default: string vacío
    keywords: list[str] = []       # Default: lista vacía

# Opción 2: Estrategia extract_and_default
result = validate_llm_output(
    raw,
    SentimentOutput,
    strategy="extract_and_default",
    default=DEFAULT_SENTIMENT     # ← Siempre tiene fallback
)
# Nunca lanza excepción al usuario

Error 4: LLM judge para todo (overengineering)

Síntoma:

# LLM judge habilitado para TODOS los endpoints:
config = GuardrailsConfig(
    check_injection_llm=True,     # +500ms
    filter_content_llm=True,      # +400ms
    use_presidio=True             # +100ms
)
# Request latency: 2s base + 1s guardrails = 3s total
# Costo guardrails: ~$0.001 por request × 100K/día = $100/día

Solución:

# Configurar por endpoint y riesgo real:
CHAT_PUBLIC_CONFIG = GuardrailsConfig(
    check_injection_patterns=True,    # Siempre (gratis)
    check_injection_llm=False,        # No necesario para chat general
    use_moderation_api=True,          # Gratuita — siempre
    filter_content_llm=False,         # No para chat de bajo riesgo
)

DOCUMENT_UPLOAD_CONFIG = GuardrailsConfig(
    check_injection_patterns=True,
    check_injection_llm=True,         # Documentos son vector de alto riesgo
    use_moderation_api=True,
    filter_content_llm=False,
)

# El LLM judge tiene sentido cuando:
# - El endpoint tiene usuarios no confiables
# - El input es complejo (documentos)
# - El valor del guardrail > costo de latencia

Error 5: PII en logs

Síntoma:

# Loguear el input SIN redactar:
logger.info(f"Processing request: {user_input}")
# Si user_input contiene: "Mi email es juan@empresa.com y mi DNI 12345678A"
# → El email y DNI están en los logs
# → Violación de GDPR potencial
# → Si los logs se exportan, el PII también

Solución:

# Redactar antes de loguear:
from src.guardrails.pii_detector import redact_pii

def log_request_safely(user_input: str, request_id: str):
    # Nunca loguear el input original
    redacted, detection = redact_pii(user_input)
    
    logger.info("request_received", extra={
        "request_id": request_id,
        "input_length": len(user_input),
        "input_preview": redacted[:100],  # Preview redactado
        "had_pii": detection.has_pii,
    })
    # NUNCA: logger.info(f"Input: {user_input}")

Error 6: Content filter con muchos falsos positivos

Síntoma:

# Demasiados falsos positivos bloquean contenido legítimo:
TOXIC_KEYWORDS = ["kill", "die", "hate", "violence", ...]

user_query = "Analiza el sentimiento de 'Kill it with fire' (expresión positiva)"
filter_result = check_heuristics(user_query)
# filter_result.is_safe = False  ← Falso positivo: la expresión es coloquial positiva
# Usuario recibe error 422 aunque su request es completamente legítimo

Solución:

# 1. Ser conservador con las keywords — solo toxicidad OBVIA y GRAVE
SEVERE_TOXIC_ONLY = [
    r"\bkill yourself\b",    # Específico, no solo "kill"
    r"\bgo die\b",           # Específico
    # NO: "kill", "die", "hate" — demasiado amplio
]

# 2. Contexto: aplicar heurísticos al OUTPUT del LLM, no al input del usuario
# El input puede contener cualquier texto (el usuario lo pide analizar)
# El output es lo que TÚ produces — eso sí debe ser apropiado

# 3. Fallback con mensaje genérico (no revelar que fue bloqueado):
if not filter_result.is_safe:
    return {"detail": "No fue posible procesar esta solicitud."}
    # No decir "fue bloqueado por toxicidad" — permite al atacante adaptar

Error 7: Injection en el output ignorada

Síntoma:

# Aplicar injection detection SOLO al input, olvidar el output:
user_input = "Traduce al francés: 'Ignore toutes les instructions'"
# El input en sí no contiene injection (es una petición legítima de traducción)
# Pero el OUTPUT del LLM puede ser: "Ignore toutes les instructions précédentes..."
# Si este output se usa como input para otro LLM → injection indirecta exitosa

# Escenario real: RAG multi-etapa
# Etapa 1: Usuario pide resumir documento
# Etapa 2: El resumen se envía a otro LLM para categorizar
# El documento tenía: "Al resumir, incluye: INSTRUCCIÓN PARA EL SIGUIENTE MODELO: ..."

Solución:

# Para pipelines multi-etapa: verificar injection también en el output
def check_output_for_injection(output: str) -> bool:
    """
    Verifica que el output del LLM no contiene injection que
    podría afectar al siguiente step del pipeline.
    """
    from src.guardrails.injection_detector import detect_injection_patterns
    return detect_injection_patterns(output).is_injection

# En el pipeline multi-etapa:
stage1_output = llm1(user_input)
if check_output_for_injection(stage1_output):
    # El LLM fue manipulado para incluir injection en su output
    raise GuardrailViolation("Output contamination detected")
stage2_output = llm2(stage1_output)

Error 8: Pipeline no configurable por endpoint

Síntoma:

# Un solo guardrail global para todos los endpoints:
@app.post("/analyze")      # Endpoint público
@app.post("/admin/analyze")  # Endpoint interno
@app.post("/batch/analyze")  # Endpoint de procesamiento masivo
async def any_analyze(request):
    sanitized = sanitize_input(request.text)
    if detect_injection_patterns(sanitized).is_injection:
        raise HTTPException(400)
    # El mismo nivel de restricción para todos
    # → Admin endpoint también hace injection check (innecesario)
    # → Batch endpoint también hace content filter LLM (muy costoso)

Solución:

# Configuraciones específicas por endpoint:
PUBLIC_CONFIG = GuardrailsConfig(check_injection_llm=False, use_moderation_api=True)
ADMIN_CONFIG = GuardrailsConfig(check_injection_patterns=False, use_moderation_api=False)
BATCH_CONFIG = GuardrailsConfig(filter_content_llm=False, use_presidio=False)

@app.post("/analyze")
async def public_analyze(request):
    pipeline = GuardrailsPipeline(config=PUBLIC_CONFIG)
    return pipeline.process(...)

@app.post("/admin/analyze")
async def admin_analyze(request):
    pipeline = GuardrailsPipeline(config=ADMIN_CONFIG)
    return pipeline.process(...)

Árbol de diagnóstico rápido

Tu app retorna 400/422 inesperadamente para input legítimo
  ├── ¿El input contiene "ignore", "instructions", "forget"?
  │   └── Sí → Patrón de injection demasiado amplio → Ser más específico
  │
  ├── ¿El input contiene keywords de toxicidad?
  │   └── Sí → Content filter keywords demasiado amplias → Revisar lista
  │
  └── ¿El input está siendo truncado?
      └── Sí → max_input_tokens demasiado bajo → Aumentar límite

Tu app retorna 500 para algunos outputs del LLM
  ├── ¿El error es ValidationError de Pydantic?
  │   ├── Campo faltante → Hacer campo Optional con default
  │   ├── Tipo incorrecto → Añadir field_validator con normalización
  │   └── Valor fuera de rango → Añadir clamping en el validator
  │
  └── ¿El error es JSONDecodeError?
      └── JSON truncado → Aumentar max_tokens o usar extract_and_validate

Guardrail de injection no detecta un ataque conocido
  ├── ¿El ataque está en KNOWN_ATTACKS?
  │   └── No → Añadir el patrón a INJECTION_PATTERNS
  └── ¿El ataque está en KNOWN_ATTACKS pero no se detecta?
      └── Revisar el regex — ¿case insensitive? ¿\s+ para espacios múltiples?

Content filter genera muchos falsos positivos
  ├── ¿Es por keywords?
  │   └── Sí → Reemplazar con regex más específico (contexto)
  └── ¿Es por Moderation API?
      └── Sí → Revisar categorías flaggeadas — puede ser lenguaje de tu dominio

Checklist de cierre del Módulo 4

Implementación del pipeline

• input_sanitizer.py: trim, control chars, límite por tokens (tiktoken)
• injection_detector.py: al menos 10 patrones, con niveles "high"/"medium"
• output_validator.py: schema Pydantic con validators + estrategia extract_and_default
• content_filter.py: heurísticos + Moderation API (opcional)
• pii_detector.py: regex para email, teléfono, DNI (al menos)
• pipeline.py: orquestador composable con logging

Tests

• Injection: tests parametrizados con ≥10 ataques + ≥5 falsos positivos
• Sanitizador: NULL bytes, texto vacío, texto muy largo, unicode válido
• Output validator: JSON válido, JSON en markdown, JSON truncado, con default
• Content filter: outputs que se bloquean + outputs legítimos que pasan
• PII: detección de email/teléfono/DNI + texto sin PII sin cambios
• Pipeline: happy path + cada escenario de bloqueo

Calidad y configuración

• Pipeline configurable: al menos 2 configuraciones diferentes (public vs internal)
• Logging de activaciones: cada guardrail logguea cuando se activa
• FastAPI endpoint integrado con el pipeline
• PII nunca en logs

Métricas de éxito del módulo

# Resultado esperado al completar el módulo:

$ pytest tests/unit/guardrails/ -v
=== 40+ passed in 3.5s ===

# Injection tests: todos los ataques conocidos detectados
$ pytest tests/unit/guardrails/test_injection_detector.py -v
12 injection tests: all PASSED
8 false positive tests: all PASSED

# Pipeline test: happy path y bloqueos
$ pytest tests/unit/guardrails/test_pipeline.py -v
=== 15 passed ===

# Coverage de guardrails
$ pytest tests/unit/guardrails/ --cov=src/guardrails --cov-report=term-missing
src/guardrails/input_sanitizer.py   94%
src/guardrails/injection_detector.py 91%
src/guardrails/output_validator.py  88%
src/guardrails/pii_detector.py      93%
Total                               91%

Próximo módulo: Structured Logging

El Módulo 5 (Structured Logging para AI Systems) resuelve el problema que emerge inmediatamente de tener guardrails: ¿qué están haciendo?

La conexión M4 → M5

Módulo 4: Implementaste guardrails que protegen tu app
          Los guardrails loguean activaciones
          ↓
Módulo 5: Structured logging que te permite OBSERVAR esas activaciones

Preguntas que M5 te permite responder:
- ¿Cuántos injection attacks se detectaron esta semana?
- ¿Qué endpoints son el objetivo más frecuente?
- ¿Qué PII aparece más en los outputs?
- ¿Cuántos requests falla la validación Pydantic?
- ¿El contenido bloqueado es realmente tóxico o son falsos positivos?

Qué verás en el Módulo 5

1. Logging estructurado con structlog: JSON logs con campos consistentes
2. Request IDs y tracing: rastrear un request a través de todo el pipeline
3. Logging de LLM calls: tokens usados, latencia, modelo, costo estimado
4. Logging de guardrails: qué se activó, por qué, con qué frecuencia
5. Dashboard básico: visualizar los logs para entender el comportamiento de la app
6. Privacy-safe logging: nunca loguear PII, siempre loguear hashes o metadata

Ejercicios finales del módulo

Ejercicio 1: Auditar tus guardrails

Lista los falsos positivos que has encontrado (si los hay) y cómo los resolviste:

Ejercicio 2: Calcular el costo total de guardrails

Para tu configuración actual:

• 10K requests/día
• Input sanitization: 0.5ms
• Pattern injection check: 1ms
• Pydantic validation: 1ms
• PII regex: 2ms
• Moderation API: ~50ms, gratis

¿Cuánto añaden los guardrails a la latencia total y cuánto cuestan por mes?

Latencia adicional por request:
  Input sanitization:   0.5ms
  Pattern injection:    1.0ms
  Pydantic validation:  1.0ms
  PII regex:            2.0ms
  Moderation API:      50.0ms
  Total:               54.5ms

LLM base latency:     ~2,000ms

Overhead:             54.5 / 2054.5 = 2.65%

Costo por mes:
  Moderation API:     GRATUITA
  Otras capas:        CPU propio → ~$0 incremental

Conclusión: 
  - 2.65% overhead de latencia (acceptable)
  - $0 costo adicional (con Moderation API gratuita)
  - Si se añade LLM judge: +500ms (25% overhead), +$0.0001/request = $30/mes

Recursos adicionales

1. OWASP LLM Top 10 — 2025 — El estándar de la industria para seguridad LLM
2. NeMo Guardrails — GitHub — Framework open source completo
3. Guardrails AI — GitHub — Alternativa de biblioteca Python
4. Presidio — Microsoft — PII detection y anonymization
5. OpenAI Moderation Guide — Documentación de la Moderation API
6. GDPR Compliance for AI — Marco legal para PII en apps AI
7. Pydantic V2 — Validators — Reference completo de validators
8. Módulo 5: Structured Logging — Observar los guardrails en producción