IDP Activities

Versión: 1.18.0  ·  ID: zoan-packages-idp  ·  Autor: Zoan Software

El paquete IDP (Intelligent Document Processing) lee documentos cuyo formato cambia de un emisor a otro: hojas de vida de equipos, facturas, actas. La idea es describir qué significa cada dato en vez de dónde está, para que la misma configuración sirva para todos los formatos de un mismo tipo de documento.

Cómo funciona este paquete

• Sin sesión: cada actividad recibe la ruta del documento y trabaja sobre él.
• La ruta se decide sola: IDP Load Document mira si el PDF tiene capa de texto. Si la tiene, la lee (gratis y exacta); si no, lo escanea con Azure Document Intelligence. Las dos rutas devuelven la misma estructura, así que lo que va detrás no cambia.
• Las coordenadas están unificadas: todas las palabras salen en píxeles al dpi que pidas, con origen arriba-izquierda, venga de donde venga el documento.

Por qué importan las coordenadas

Cada palabra viene con su caja (x, y, width, height). Eso es lo que permite volver al documento desde un dato extraído: resaltar de dónde salió un número de serie, mostrárselo a una persona para que lo valide, o auditar una extracción meses después.

Si usas el mismo dpi en PDF To Images, las cajas caen exactamente encima de la página renderizada, sin conversión ninguna. Es la base sobre la que se dibuja cualquier revisión visual.

Actividades

Las dos primeras son el camino normal. Las de abajo siguen ahí para quien necesite meterse entre medias.

Actividad	Tipo	Salida	Qué hace
IDP Classify	idp-classify	object	Lee un documento y dice de qué tipo es. Devuelve el documento ya leído
IDP Extract	idp-extract	object	Extrae los campos de un proyecto de extracción, enruta al perfil del formato y localiza cada valor en la página
IDP Load Document	idp-load-document	object	Carga un documento y devuelve su texto y sus palabras con posición
IDP Build Classifier	idp-build-classifier	object	Construye el esquema que identifica de qué tipo es el documento
IDP Build Schema	idp-build-schema	list	Trocea una taxonomía en los esquemas que caben en una llamada
IDP Ground	idp-ground	object	Localiza cada valor extraído y marca lo que necesita revisión

El pipeline

Dos nodos:

IDP Classify  →  ¿es del tipo que toca?  →  IDP Extract

IDP Classify devuelve el documento ya leído junto al veredicto, e IDP Extract lo reusa: el fichero se lee una sola vez. Con un escaneo eso no es una optimización menor — releer es pagar Azure dos veces.

Van separadas a propósito. Qué hacer con un documento que no toca es una decisión tuya, no de una actividad: una que decide sola no hacer su trabajo esconde el control de flujo, y además impide lo único que de verdad hace falta cuando la cola trae de todo — clasificar una vez y enrutar al proyecto que corresponda.

Una sola llamada, no un pipeline

IDP Extract extrae todos los campos en una sola llamada al modelo (sin gramática estricta), groundea y persiste el resultado — todo por dentro, sin que tu playbook se entere. Antes troceaba el esquema en lotes; ya no. Las actividades granulares (IDP Build Schema, IDP Build Classifier) siguen registradas para quien quiera montar el pipeline a mano.

Las dos garantías, que no son la misma

Conviene tenerlas separadas en la cabeza porque protegen de cosas distintas:

• Clasificar responde “¿es este documento del tipo que creo?”. Sin ese paso, una factura procesada como hoja de vida puede colar un dato incorrecto con confianza alta.
• Groundear responde “¿está este valor escrito en el documento?”. Detecta que el modelo se lo inventó, no que el documento sea el equivocado.

Ninguna cubre a la otra. Ver IDP Build Classifier para el caso concreto que se escapa.

Documentos escaneados

La ruta de escaneo usa Azure Document Intelligence (modelo prebuilt-layout), que lee manuscrito — importante porque en muchos documentos la parte que nadie ha digitalizado nunca (un historial de mantenimientos, una firma, una anotación al margen) está escrita a mano. No necesita entrenamiento ni etiquetado: funciona con cualquier documento desde el primer día.

¿No puedes usar el cloud?

Si el cliente rechaza que sus documentos salgan de su red, compón la ruta on-prem en el playbook: PDF To Images para rasterizar y el paquete OCR (Tesseract) para leer. Asume que Tesseract no leerá el manuscrito.

El playbook completo

Encolar (una vez por lote):

List Files   path = = env("HOSPITAL_DOCS_DIR")   pattern = "*.pdf"   recursive   → ficheros
Foreach   items = = ficheros   itemVariable = ruta
    Queue Add Item   queueName = "hojas-de-vida"   reference = = ruta
                     specificContent = { "path": = ruta }

reference = la ruta. Es la clave de idempotencia de la cola y la que llevará el documento en Zoan Cloud, así que relanzarlo no duplica nada y desde el item se llega al documento.

Procesar:

Queue Process   queueName = "hojas-de-vida"   itemVariable = item   onError = continue

  Set Variable   name = contenido   value = = item.SpecificContent

  IDP Classify   path = = contenido["path"]
                 projects = ["hoja-de-vida"]
                 credential = = credential("anthropic-key")
                 dpi = 200
                 azureCredential = = credential("azure-di-key")
                 → doc

  If   condition = = doc["recognized"] == false
    Queue Set Transaction Status   item = = item   status = "successful"
                                   output = { "descartado": true, "reason": = doc["reason"] }
    Continue

  IDP Extract   document = = doc                    ← ya leído: no se relee
                project = "hoja-de-vida"
                credential = = credential("anthropic-key")
                azureCredential = = credential("azure-di-key")
                → res

  PDF To Images     path = = contenido["path"]   dpi = 200   outputDir = = tmpFolder   → paginas
  Documents Upload  path = = contenido["path"]   reference = = item.Reference
                    pages = = paginas   dpi = 200   extraction = = res
                    documentType = = res["documentType"]   → subido

  Queue Set Transaction Status   item = = item   status = "successful"
                                 output = { "documentId": = subido["id"],
                                            "needsReview": = res["needsReview"],
                                            "values": = res["values"] }

El proyecto va por su nombre, y lleva todo dentro

project = "hoja-de-vida" es el nombre de un proyecto de extracción del entorno, que se edita en el portal. Lleva el esquema canónico, los perfiles de formato, el modelo, el modo de lectura y el endpoint de OCR — así quien sabe qué campos importan (un ingeniero biomédico, no quien escribe playbooks) los cambia sin abrir el Designer ni redesplegar, y el playbook se queda sin model/mode/endpoint.

Para CI y el CLI, que no tienen sesión de Zoan Cloud, project también acepta un JSON de resolución en línea.

El dpi tiene que ser el mismo en los dos sitios

PDF To Images renderiza al mismo dpi que le diste a IDP Classify. Es lo que hace que las cajas caigan justo encima de la imagen en la estación de validación, sin conversión.

Con dpi distintos no falla nada: las cajas caen en el sitio equivocado, y nadie te avisa.

Subir es una decisión del playbook, no del IDP

El IDP no sube nada — sabe leer documentos, no hablar con Zoan Cloud. Subir es un nodo aparte que eliges llamar.

Eso es lo que mantiene viva la ruta on-prem: un cliente que no quiera que sus documentos salgan de su red no instala el paquete Documents, y el resto funciona igual.

Telemetría: cierra el item tú

Queue Process cierra cada item solo —successful si el cuerpo termina, failed si lanza— pero lo cierra con output vacío: tira el resultado. Con el auto-cierre, tu telemetría es “procesé 400, fallaron 12” y nada más.

Por eso el ejemplo llama a Queue Set Transaction Status a mano: si el cuerpo ya fijó el estado, el auto-cierre se aparta. Así cada documento deja su rastro consultable — qué se extrajo, con qué confianza, por qué fue a revisión, y por qué se descartó si se descartó.

Con eso tienes:

Dónde	Qué te da
GET /queues/:id/metrics	Total, cuentas por estado, tasa de éxito, throughput por hora, tiempos medio y p95.
GET /queues/:id/items	Cada documento con su reference, estado y el output que le pusiste.
Cola validacion-*	Cuántos y cuáles necesitan una persona.

El estado review de Zoan Cloud no es la validación del IDP

Es una compuerta de entrada: con accept_automatically = false los items nacen en review y aprobarlos los suelta al bot. Responde “¿debe procesarse esto?”, no “¿están bien estos campos?”. La validación del IDP es la segunda cola.

Siguientes pasos

• IDP Load Document — cargar el documento.
• IDP Build Classifier — saber de qué tipo es antes de extraer.
• IDP Build Schema — describir qué extraer, con una taxonomía por tipo de documento.
• IDP Ground — localizar lo extraído y decidir qué va a revisión.
• OCR — ruta on-prem para clientes sin cloud.