Motor de Evaluación Normativa

Quickstart

Levanta el motor completo desde cero en cuatro pasos.

Requisitos previos

• Docker + Docker Compose
• Python 3.12 (para indexador y parser)
• API key del proveedor de embeddings (configurable)
• API key del proveedor LLM elegido
• Tesseract + poppler (solo si hay que reprocesar PDFs)

1 — Arranque del motor RAG

cd IA-data-x
cp .env.example .env        # rellenar DATABASE_URL y las API keys del proveedor elegido
bash start.sh               # levanta postgres + ia-service con healthchecks
curl http://localhost:8001/health    # o el HOST:PORT configurado

Respuesta esperada:

{
  "status": "ok",
  "db": "connected",
  "chunks_indexados": 0,
  "models": { "embed": "<id>", "llm": "<id>" },
  "version": "0.3.0"
}

2 — Indexar normativas

cd IA-data-x
python3 indexar_criterios.py        # interactivo: confirma y empieza
# o sin confirmación:
python3 indexar_criterios.py --yes

Lee normativas-parser/output/eval_criteria.json y publica chunks vía POST /indexar.

3 — (Opcional) Reprocesar normativas desde PDFs

Solo si cambia el corpus normativo. Pipeline completo en normativas-parser/:

cd normativas-parser
bash setup.sh                              # venv + dependencias
python3 1.extract_pdfs.py
python3 2.clean_extracted.py
python3 3.pdf_parser.py
python3 4.llm_cleaner.py --model  --vision-model 
python3 5.generate_eval_json.py --model 
cd ../IA-data-x && python3 indexar_criterios.py --yes

4 — Primera evaluación

curl -N -X POST $BASE_URL/validar-archivo \
  -F "file=@mi_politica.pdf" \
  -F "embed_api_key=$EMBED_API_KEY" \
  -F "llm_api_key=$LLM_API_KEY" \
  -F "proveedor="

Visión general

Dos módulos autocontenidos que cooperan vía API HTTP.

Cadena de valor

Casos de uso

• Auditor sube un SLA — informe evaluado contra UNE-0087 y DGA, cláusulas citadas textualmente, gaps tipificados y acciones correctivas.
• Responsable de gobierno del dato sube su Política de Datos — evaluación contra UNE-0077 y UNE-0085, score por dimensión, dictamen global.
• Equipo legal sube un contrato de tratamiento — detección automática de tipo (encargado RGPD), criterios filtrados al rol del firmante, recomendaciones priorizadas.
• Consultor sube diagnóstico de madurez — evaluación arquetipo "evidencia", verificación de que cada hallazgo es concreto, referenciado y verificable.
• Integración programática — POST /validar-archivo con fichero → stream SSE + informe JSON consumible desde cualquier plataforma.

Módulo normativas-parser

Pipeline determinístico que convierte PDFs de normas UNE en el catálogo de criterios RAG.

Corpus de PDFs (ejemplo)

El parser acepta cualquier normativa en PDF con estructura de secciones. El siguiente corpus es un ejemplo de uso con normas UNE; cualquier otro conjunto de PDFs sigue el mismo pipeline.

Pipeline de 5 etapas

Cada etapa es reentrante: si se interrumpe, reanuda donde quedó detectando qué documentos ya tienen salida válida.

Modelos IA

El motor es agnóstico al proveedor: acepta cualquier modelo con interfaz Chat Completions. El modelo se pasa por parámetro en cada llamada — no hay proveedor fijo.

Criterios de selección

Recetas rápidas

# Pasar el modelo deseado como argumento
python3 4.llm_cleaner.py --model  --vision-model 
python3 5.generate_eval_json.py --model 

Formato eval_criteria.json

{
  "version": "2.0",
  "total_criterios": 42,
  "criterios": [
    {
      "id":                    "77.1",
      "une_fuente":            "une-0077-2023-gobierno-del-dato",
      "dimension_codigo":      "5.1",
      "dimension_nombre":      "Política de gobierno del dato",
      "criterio":              "Aprobar y publicar una política formal de gobierno del dato",
      "tipo_documento_afectado": "Política de Gobierno del Dato",
      "descripcion":           "La norma establece que la organización debe disponer…",
      "evidencias_requeridas": "Política aprobada, acta de aprobación por dirección",
      "resultado_esperado":    "Documento de política publicado y accesible",
      "posible_evidencia":     "Política firmada, publicación en intranet, acta del comité",
      "medidas_correctivas":   "Redactar y aprobar la política con patrocinio directivo",
      "origen":                "LENGUAJE_NORMATIVO",
      "referencias_normativas": [...],
      "referencias": [...]
    }
  ]
}

Puente parser → RAG: indexar_criterios.py

Único vínculo entre la fase offline y la online. Produce chunks RAG y los envía a POST /indexar.

Por cada criterio se construyen tres tipos de chunks:

El script aplica un rate limit de 1.1 s entre peticiones y reintentos con backoff exponencial (MAX_REINTENTOS=3, BACKOFF_BASE=5.0). Tras el primer pase, hace una pasada de recuperación para chunks fallidos.

Módulo IA-data-x

Stack y arquitectura

El servicio escucha en el puerto 8001. La base de datos en el puerto 5432 del contenedor (mapeado a 5434 en algunos entornos host).

Modelo de datos

Base de datos: ia_normativas.

Tabla normativas — criterios indexados:

Tabla validaciones — log de auditoría:

Mapa de módulos core/

Variables de configuración clave

Sistema de arquetipos

El motor clasifica cada documento en un arquetipo. El arquetipo determina la regla fundamental que el LLM aplica para dictaminar cumplimiento — no es lo mismo evaluar un contrato que una política o una evidencia técnica.

Flujo completo de una evaluación

Lo que ocurre cuando un usuario sube un fichero a POST /validar-archivo.

5.1 — Carga y normalización del documento

Petición entrante: multipart/form-data.

Pasos de preparación en main.py: validar_archivo:

1. Control de tamaño → HTTP 413 si > 50 MB
2. Extracción de texto (PDF: pypdf; DOCX: python-docx; TXT: UTF-8 con fallback latin-1)
3. Deduplicación de párrafos (_deduplicar_parrafos)
4. Detección de subdocumentos con inyección de marcadores ═══ SUBDOCUMENTO ═══
5. Concatenación del contexto del analista
6. Truncación inteligente si > 200 000 chars: 50% inicio + 30% centro + 20% final
7. Validación mínima: si len < 50 → HTTP 422
8. Logging completo del texto que entrará al pipeline

5.2 — Embedding y detección de norma

Se computa el embedding del documento con caché LRU (2048 entradas, clave MD5). Con ese vector se ejecuta la detección de norma aplicable si el usuario no especificó fuente_norma:

ORDER BY
  0.7 * (1 - (embedding <=> $1::vector)) +
  0.3 * ts_rank(tsv, plainto_tsquery('spanish', $2))
DESC LIMIT 40

Los scores se agregan por fuente y se normalizan a porcentaje de relevancia, devolviendo las N normativas más relevantes.

5.3 — Clasificación documental jerárquica

Tres niveles en cascada:

5.4 — Selección de criterios

Filtros en cascada, todos con fallback automático al conjunto previo si el resultado queda vacío:

1. _filtrar_criterios_por_norma — pre-filtra por prefijo de fuente UNE según tipo
2. _filtrar_criterios_por_tipo — filtra por tipo_documento_afectado
3. _filtrar_dimensiones_por_arquetipo — elimina criterios en excluir_dims
4. _filtrar_dimensiones_por_modalidad — filtrado fino adicional

5.5 — RAG bidireccional

Activo si el documento supera DOC_RAG_THRESHOLD (15 000 chars). La clave: el score no es solo query→corpus, sino criterio↔chunks del documento:

1. Chunking del documento: 1 500 chars, overlap 200, corte en saltos de línea
2. Embeddings en batch (caché LRU compartida)
3. Ajuste dinámico de top-K: >40 criterios → K=1; >20 → K=2
4. BM25-lite en memoria (k1=1.5, b=0.75) con keywords del criterio
5. Score híbrido: coseno ponderado + BM25-lite
6. Top-K pasajes por criterio, recortados a 1 200 chars
7. Fallback robusto: si fallan embeddings → primeros 15 chunks

5.6 — Evaluación LLM por batches

Batches de EVAL_BATCH_SIZE = 25 criterios por llamada LLM. Por cada batch:

1. Construcción del prompt con regla del arquetipo + contexto de modalidad + criterios + pasajes RAG
2. Llamada al LLM: max_tokens 32 K, timeout 180 s, temperatura 0.1–0.6 según modelo
3. Reparación del JSON: extrae bloques markdown, corrige comas finales, cierra strings truncados, recupera objeto a objeto como último recurso
4. Normalización de resultado a valores canónicos: Cumple / Parcial / No cumple / Ausencia
5. Segunda pasada de completion si quedan criterios sin respuesta válida
6. Deduplicación por criterio_codigo

Esquema JSON de respuesta por criterio:

{
  "criterio_codigo": "77.1",
  "criterio_nombre": "...",
  "dimension": "...",
  "fuente": "UNE-0077:2023",
  "resultado": "Cumple" | "Parcial" | "No cumple" | "Ausencia",
  "justificacion": "...",
  "razonamiento": "...",
  "evidencias": [{ "cita": "...", "ubicacion": "...", "comentario": "..." }],
  "gap_type": "PARTIAL_COVERAGE" | "MISSING" | "MISALIGNED" | null,
  "gap_detectado": "...",
  "accion_requerida": "...",
  "confianza": "alta" | "media" | "baja",
  "lecturas_alternativas_descartadas": [...]
}

5.7 — Cálculo determinístico de campos derivados

Sin LLM. Pura aritmética sobre los resultados agregados:

Score ponderado = (suma de scores / nº criterios) × 100. Dictamen global:

5.8 — Persistencia, trazabilidad y SSE

Eventos SSE durante una evaluación típica:

event: paso         data: {"paso":"embed","msg":"Generando embedding..."}
event: norma_inicio data: {"fuente":"UNE-0085-2024","idx":1,"total":1}
event: paso         data: {"paso":"clasificar","msg":"Clasificando documento..."}
event: paso         data: {"paso":"filtrar","msg":"Filtrando criterios..."}
event: paso         data: {"paso":"rag","msg":"Recuperando pasajes RAG..."}
event: paso         data: {"paso":"llm","msg":"Evaluando criterios 1–25 de 87..."}
event: paso         data: {"paso":"llm","msg":"Evaluando criterios 26–50 de 87..."}
...
event: resultado    data: { ...informe JSON completo... }
event: todo_fin     data: {"total":1}

Trazabilidad en tres niveles:

1. BD (validaciones.chunks_recuperados): IDs y scores de chunks RAG usados
2. Log de servicio (ia-service.log): líneas [TEXTOCLIENTE], [EMBED], [SEARCH], [PROMPT], [LLM-RESPONSE]
3. Log por evaluación (/app/logs/ia/evaluations/<user_id>/): JSON íntegro del informe

API Reference

Todos los endpoints del servicio. El host y puerto dependen de tu configuración de despliegue (por defecto localhost:8001 en desarrollo local).

Ejemplos de uso (curl)

En los ejemplos siguientes, sustituye $BASE_URL por la dirección de tu instancia.

Health check

curl -s $BASE_URL/health | jq

Listar normativas indexadas

curl -s $BASE_URL/normas | jq

Buscar criterios por keyword

curl -s -X POST "$BASE_URL/buscar?query=catalogación+activos&top_k=5" | jq

Detectar norma aplicable

curl -s "$BASE_URL/detectar-norma?texto=la%20organización%20designará%20un%20Data%20Owner" | jq

Validación síncrona (texto plano)

curl -X POST $BASE_URL/validar \
  -H 'Content-Type: application/json' \
  -d '{
    "texto": "La organización designa…",
    "fuente_norma": "nombre-de-la-norma",
    "proveedor": "tu-modelo",
    "embed_api_key": "sk-…",
    "llm_api_key": "sk-…"
  }' | jq

Validación de fichero con streaming SSE

curl -N -X POST $BASE_URL/validar-archivo \
  -F "file=@politica_datos.pdf" \
  -F 'fuentes_norma=["norma-1","norma-2"]' \
  -F "proveedor=tu-modelo" \
  -F "top_k=10" \
  -F "contexto=Empresa del sector financiero, 2000 empleados" \
  -F "embed_api_key=$EMBED_API_KEY" \
  -F "llm_api_key=$LLM_API_KEY" \
  -F "user_id=auditor-42"

Generar recomendaciones

curl -X POST $BASE_URL/recomendar \
  -H 'Content-Type: application/json' \
  -d '{
    "eval_name": "Evaluación Q1",
    "criterios": [
      {"codigo":"Gob.1","descripcion":"OGD no constituida","dimension":"Gobernanza"}
    ],
    "top_k": 5
  }' | jq

Códigos de error HTTP

Glosario

Rendimiento y costes

Latencias típicas

Caché

LRU de embeddings en proceso (max=2048). Hit-ratio típico tras precalentar: 60–80 % en cargas similares. cache_stats() expuesta en /health.

Costes orientativos

• Embedding de 1 documento de 50K chars → ~40K tokens (despreciable)
• Evaluación completa con LLM medio → ~120K–200K tokens input + ~30K output (varía con el número de criterios)
• Indexar el corpus completo de normativas → ~600K tokens (parser etapa 5, una sola vez)

Tuning

Seguridad y privacidad

Limitaciones conocidas

• Tamaño máximo de fichero: 50 MB (HTTP 413)
• Texto procesado por evaluación: 200 000 chars (configurable). Por encima → truncación inteligente 50/30/20 %
• Ventana de contexto LLM: depende del modelo elegido. El motor parte criterios en batches de 25 pero el documento + prompt deben caber
• Idioma: optimizado para español (tsvector('spanish'), prompts en castellano). Documentos en otros idiomas funcionan pero la calidad de BM25 baja
• PDFs escaneados: /validar-archivo usa pypdf que requiere texto extraíble. Un PDF escaneado producirá texto vacío y HTTP 422 (el OCR solo está en el pipeline parser)
• Dependencia de APIs externas: requiere conectividad al servicio de embeddings y al LLM. Sin red → sin evaluaciones
• Determinismo: la evaluación no es 100% reproducible entre ejecuciones (LLM con temperature > 0). Para auditoría → guardar chunks_recuperados + documento_hash
• Evaluación incremental: cada /validar-archivo es independiente. Se puede simular pasando ambos ficheros concatenados o usando contexto para anexos cortos

Troubleshooting

Diagnóstico rápido

# Health completo  (reemplaza HOST:PORT por tu endpoint)
curl -s http://HOST:PORT/health | python3 -m json.tool

# Logs en tiempo real
docker logs -f ia-service

# Chunks por fuente
curl -s http://HOST:PORT/normas | python3 -c "
import json,sys; d=json.load(sys.stdin)
[print(f'{x[\"fuente\"]}: {x[\"total_criterios\"]} criterios') for x in d]
"

# Re-indexar desde cero
cd IA-data-x && ./start-all.sh --reset && python3 indexar_criterios.py --yes

FAQ