IDP Activities

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

El paquete IDP (Intelligent Document Processing) lee documentos cuyo formato cambia de un emisor a otro: facturas, órdenes de compra, actas, formularios. 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. En el Designer en español aparece como Procesamiento de documentos (IDP).

Cómo funciona este paquete

• Sin sesión: cada actividad recibe la ruta del documento (o el documento ya leído) 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.
• IA y lectura incluidas en tu plan (desde la versión 1.20.0): sin credenciales en la actividad ni en el proyecto, el modelo y la lectura de escaneos van por Zoan Cloud, sin claves que configurar; el consumo (tokens y páginas) aparece en Consumo de IA. Con tus propias credenciales, las llamadas van directo a tus proveedores.
• Los datos personales se ocultan antes de salir: IDP — Classify e IDP — Extract enmascaran cédulas, NIT, correos, teléfonos, cuentas, direcciones y nombres del texto antes de enviarlo al modelo (maskPii, activo por defecto) y restauran los valores reales en el resultado.

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 factura, 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, dice de qué tipo es y lo parte en segmentos. 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, localiza cada valor y guarda el resultado
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<object>	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 archivo 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 guarda el resultado — todo por dentro, sin que tu playbook se entere. Las actividades granulares (IDP — Build Schema, IDP — Build Classifier, IDP — Ground) 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 orden de compra procesada como factura 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 (una firma, una anotación al margen, un formulario llenado a mano) está escrita a mano. No necesita entrenamiento ni etiquetado: funciona con cualquier documento desde el primer día.

Con la lectura incluida en tu plan, cada lectura admite hasta 50 MB y 2000 páginas, y cuenta en el cupo mensual de páginas. Un documento que no cabe en lo que queda se rechaza antes de leerlo, con las cifras, y nunca recibes una lectura a medias como si fuera completa (ver IDP — Load Document).

¿No puedes usar la nube?

Si los documentos no pueden salir de tu red, compón la ruta local 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("FACTURAS_DIR")   pattern = "*.pdf"   recursive   → ficheros
Foreach   items = ficheros   itemVariable = ruta
    Queue Add Item   queueName = "facturas"   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 = "facturas"   itemVariable = item   onError = continue

  Set Variable   name = contenido   value = item.SpecificContent

  IDP — Classify   path     = contenido["path"]
                   projects = ["factura-proveedor"]
                   dpi      = 200
                   → doc

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

  IDP — Extract   document  = doc                    ← ya leído: no se relee
                  path      = contenido["path"]
                  reference = item.Reference
                  project   = "factura-proveedor"
                  → res

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

IDP — Extract guarda el documento y su extracción en Zoan Cloud, donde Zoan Cloud muestra las páginas en la estación de validación; no hace falta subirlo aparte con Documents — Upload.

El proyecto va por su nombre, y lleva todo dentro

project = "factura-proveedor" es el nombre de un proyecto de extracción del ambiente, 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 (alguien del área, no quien escribe playbooks) los cambia sin abrir el Designer ni redesplegar, y el playbook se queda sin model/mode/endpoint.

Para CI, que no tiene 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 todos los sitios

Si renderizas tú las páginas con PDF To Images, hazlo al mismo dpi que le diste a IDP — Classify. Es lo que hace que las cajas caigan justo encima de la imagen, sin conversión.

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

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 — Classify — saber de qué tipo es antes de extraer.
• IDP — Extract — extraer, ubicar y guardar en una actividad.
• IDP — Load Document — cargar el documento y sus límites de lectura.
• Procesamiento de documentos (IDP) — proyectos de extracción y estaciones de revisión.
• OCR — ruta local, sin nube.