Procesamiento de documentos (IDP)

El IDP (procesamiento inteligente de documentos) extrae datos estructurados de documentos cuyo formato no controlas: hojas de vida de equipos, facturas de proveedores distintos, oficios, certificados. No es OCR. El OCR te dice qué letras hay; el IDP te dice cuál de esos textos es el número de serie.

La diferencia está en de dónde sale el dato:

Una plantilla encuentra el dato por su posición — “el número de serie está en la casilla de arriba a la derecha”. Funciona hasta que llega el formato del hospital siguiente.
El IDP lo encuentra por lo que significa — “esto es un número de serie”. El formato puede cambiar y sigue funcionando.

Por eso el IDP compensa cuando el formato varía y no lo controlas. Si todos tus documentos salen del mismo sistema y siempre tienen la misma pinta, una plantilla es más barata y más rápida: no uses el IDP.

Cuándo compensa

Compensa cuando se cumplen las dos:

El formato varía entre proveedores, hospitales, clientes o años, y no puedes obligarles a usar el tuyo.
El volumen justifica automatizar. Diez documentos se teclean; dos mil, no.

No compensa si el documento es siempre igual (usa una plantilla), si el dato ya existe en una API o base de datos (pídelo ahí), o si el error es intolerable y nadie va a revisar. El IDP no elimina la revisión humana: la reduce y la dirige.

Las piezas

Cada una hace una cosa y las tres son necesarias:

Pieza	Qué hace	Por qué
Lectura	Saca el texto del documento, con la posición de cada palabra	El PDF digital se lee en la máquina, sin llamar a ningún servicio. El escaneado pasa por Azure Document Intelligence, que es lo único que lee manuscrito
Extracción	Un modelo lee ese texto y devuelve los campos de tu proyecto	Es lo que entiende el significado y aguanta el cambio de formato
Grounding	Busca cada valor extraído entre las palabras del documento	De aquí sale la confianza medida y la caja de cada campo

Las dos garantías, que no son la misma

Esto es lo que más se confunde, y confundirlo sale caro:

Clasificar responde “¿este documento es del tipo que creo?”
Groundear responde “¿este valor está escrito en el documento?”

Ninguna cubre a la otra. Si le pasas una factura a un extractor de hojas de vida, va a encontrar un número que parece un número de serie, lo va a localizar en el documento, y va a salir con confianza alta. El grounding no falla: el valor está ahí. Lo que falla es que el documento no era ése.

Por eso se clasifica antes de extraer, y se descarta lo que no toca.

El proyecto de extracción

El proyecto de extracción es el recurso de Zoan Cloud por tipo de documento. Es lo único que configuras para soportar un tipo nuevo —ni código, ni entrenar, ni etiquetar ejemplos— y lleva dentro todo lo que el pipeline necesita:

El esquema canónico — la lista de campos que entregas, el contrato que no cambia para el tipo.
N perfiles de formato — uno por layout en que llega el tipo, cada uno sobrescribiendo el canónico campo a campo.
Un router — a qué perfil va un documento dado, por su código de formato impreso.
La config — el modelo, el modo de lectura, el endpoint y las credenciales de OCR, el almacenamiento y la retención, los umbrales de revisión.

Se edita en el portal, en Proyectos de extracción, y el playbook lo referencia por su nombre:

IDP Extract   project = "hoja-de-vida"   → res

Ese es el motivo de fondo de que no sea un fichero del proyecto: quien sabe qué campos importan en un documento es el área que lo usa (cuentas por pagar con las facturas, por ejemplo), no quien escribe playbooks. Con el esquema dentro del playbook desplegado, esa persona no puede tocar un umbral sin abrir el Designer y redesplegar. Aquí cambia un campo y ya.

El esquema canónico

El esquema canónico es la lista de lo que quieres sacar, y es lo que consume el resto del tenant — los mismos nombres de campo llegue el documento en el formato que llegue:

El tipo de documento y una descripción — de ahí sale el clasificador, sin escribirlo aparte.
Cada campo: nombre, tipo (string, number, integer, boolean, date), descripción y su umbral de confianza.
Las tablas: un campo de tipo table con sus columnas.

La descripción de cada campo es lo que hace el trabajo. No es documentación: es lo que el modelo lee para decidir qué dato es cuál. “Número de serie” funciona peor que “número de serie del fabricante, impreso en la placa del equipo; no confundir con el código de inventario del hospital”.

El umbral por campo es una decisión de negocio, no técnica. El número de serie de un equipo médico mal leído es un problema serio: umbral alto. El nombre del fabricante, menos: umbral más bajo. Un campo por debajo de su umbral no falla — va a revisión.

Generar el borrador desde un ejemplo

Escribir el esquema a mano es tedioso, así que el editor puede proponerlo: en la pestaña Esquema canónico, sube un documento de ejemplo (PDF; un Excel entra vía excel-to-pdf) y di qué quieres extraer. El modelo propone los campos —nombre, tipo, descripción-como-instrucción, umbral— y cada propuesta se verifica contra el documento: el valor de ejemplo se localiza entre las palabras y verás su caja sobre la página (un escaneo pasa por Azure DI con la config del proyecto). Lo que no se encuentra queda marcado no verificado y desmarcado por defecto — el borrador nunca aparenta más confianza de la que tiene.

El texto que ve el modelo va con cada línea numerada, y se le pide que cite la línea de la que sacó cada valor. La caja se dibuja sobre esa línea, no sobre la primera aparición del literal en el documento: sin esto, un valor que se repite —una fecha de fabricación que reaparece como fecha de revisión— señalaría siempre la primera y engañaría. Y cuando dos valores idénticos comparten la misma fila (dos fechas iguales, una bajo “Fecha inicio” y otra bajo “Fecha fin”), se desambiguan por la etiqueta impresa que precede a cada uno: cada campo lleva su rótulo justo antes, y eso decide cuál caja es de cuál. Cuando el valor no se pudo confirmar así y además se repite en el documento, la caja se pinta en ámbar punteado: es honesto avisar “esto aparece varias veces y no pude asegurar cuál” en vez de marcar una al azar. Si el literal es único, la caja es correcta pase lo que pase y sale en verde.

Marcas lo que quieres y lo llevas a la rejilla de dos formas: Reemplazar esquema —lo que esperas al generar: define el esquema con lo marcado (si ya había campos a mano, te pide confirmación antes de pisarlos)— o Fusionar, que actualiza los campos del mismo nombre y añade los nuevos sin tocar el resto. Ninguna de las dos acumula duplicados al regenerar. Luego lo corriges (los matices —umbrales por criticidad, desambiguaciones— siguen siendo tuyos) y guardas. Nada se publica solo.

Lo mismo existe para los perfiles: en la pestaña Formatos, sube un documento del formato nuevo y el generador extrae con el canónico tal cual, verifica campo a campo, y propone overrides solo para lo que falló — más el código impreso del formato detectado para el router. Un chequeo dice cuántos campos ya cubría el canónico; si los cubre todos, quizá no necesites perfil.

Las llamadas de estos generadores son consumo de diseño: se contabilizan en el consumo del proyecto (y en el costo del operador) igual que las de extracción — un costo invisible es un costo subestimado.

Los perfiles de formato y el router

El mismo tipo llega en varios formatos —otro hospital, otro año, otra plantilla— y cada uno pinta los campos en otro sitio. En vez de una taxonomía por formato (que se desincroniza, porque entonces el contrato entregado es distinto por formato), un proyecto tiene un esquema canónico y N perfiles. Un perfil sobrescribe el canónico campo a campo: una descripción más ajustada para ese layout, otro umbral, columnas de tabla extra, o marcar un campo como no aplica aquí. Como los perfiles usan los nombres canónicos, la salida sale siempre canónica — el mapeo es identidad.

El router elige el perfil. Cada perfil declara un routerKey — el código de formato impreso de ese layout (F-GOP-007, FOR-GBM-001), literal o una regex, con una prioridad cuando varios podrían casar. IDP Extract lee el código del documento y enruta, sin consultar al modelo. Si ningún código casa, usa el perfil sin routerKey (el perfil por defecto), si lo hay; si no, extrae con el esquema general del proyecto y marca el documento a revisión (needsReview = true, formatMatched = false), aunque los campos hayan salido limpios. Un formato desconocido nunca se acepta solo ni se fuerza a un perfil equivocado.

El gold y la medición

Un proyecto puede tener un gold: un puñado de documentos etiquetados a mano con sus valores verdaderos. No es para entrenar el modelo — es para medirlo.

Etiquetar el gold se hace en la pestaña Medición (gold) del proyecto. Anotas los valores correctos campo a campo: los escalares en un formulario, y las tablas en un editor por-celda —una rejilla con las columnas reales del esquema, donde añades una fila por cada fila que tenga la tabla en el documento y escribes el valor de cada celda—. Con 10–20 documentos por formato suele bastar para una señal fiable.

Correr la medición es un botón en esa misma pestaña. Zoan Cloud compara el gold contra la extracción ya persistida de esos documentos (la que dejó IDP Extract), campo a campo —exacto / normalizado / crítico, y celda a celda en las tablas—, y guarda un reporte: acierto por campo, por perfil, por modelo. Es server-side: no re-extrae ni vuelve a pagar Azure/LLM, y mide contra el esquema publicado (lo mismo que usa el runtime), no contra el borrador que estés editando. Por eso, para medir un cambio en el esquema, publícalo antes.

El requisito es que cada gold esté enlazado a su documento (por document_id) y que ese documento ya se haya extraído; si no, el reporte te lo dice con un error claro.

Es lo que te deja responder “¿un modelo pequeño acierta bastante en mis documentos?” o “¿ayudó este cambio en una descripción?” con un número en vez de una corazonada — la forma honesta de elegir umbrales y modelos antes de correr dos mil documentos.

Dos bucles cierran el ciclo de mejora:

Publicar mide solo. Al publicar una versión del proyecto, la medición gold corre automáticamente (si hay gold extraído) y el dashboard muestra el delta frente a la medición anterior — nadie publica un esquema que empeora sin verlo.
Los campos más corregidos. Cada corrección que hace un revisor al validar queda registrada, y el dashboard los agrega: el campo que se corrige una y otra vez señala la descripción del esquema que hay que reescribir. Reescribe, publica, mide.

Alcance: del ambiente o global

Igual que las credenciales:

Global — vale para todo el tenant.
Del ambiente — solo ahí, y gana sobre la global con el mismo nombre.

Eso es lo que permite probar un cambio donde no duele antes de soltarlo en el resto.

El escape: JSON de resolución en línea

project también acepta el proyecto resuelto en línea como JSON —esquema canónico, perfiles y router en un objeto— en vez de un nombre. Es para CI y para el CLI, que no tienen sesión de Zoan Cloud y no pueden resolver un nombre. En una corrida real desde Zoan Cloud siempre pasas el nombre.

Publicar y versionar

El runtime extrae contra la versión publicada del proyecto, no contra lo que estás editando. Cuando pulsas Publicar, se congela una versión; a partir de ahí, editar el esquema o los perfiles es un borrador que no afecta a las extracciones en vuelo hasta que vuelves a publicar. El editor muestra el estado: Publicado, Cambios sin publicar o Sin publicar. Así puedes iterar el esquema con tranquilidad sin romper lo que está corriendo.

Cola de salida: el hand-off al bot downstream

En la gobernanza del proyecto puedes nombrar una cola de salida. Si la pones, los documentos extraídos entran a esa cola como trabajo para el bot que los procesa aguas abajo —los que se aceptan solos, al extraerse; los que pasan por revisión, al validarse—, siempre con sus valores ya finales. Vacío = sin cola: los datos quedan en el store y los consulta quien sea. La cola es una decisión de negocio, no una imposición del IDP.

Auto-aceptación y muestreo QA

La gobernanza del proyecto decide qué necesita ojos humanos:

Un documento con campos bajo umbral va SIEMPRE a revisión, mande lo que mande la política.
Con auto-aceptar apagado (el valor por defecto), también los documentos limpios pasan por una persona antes de fluir — es el modo prudente hasta calibrar con el gold.
Con auto-aceptar encendido, los limpios se auto-validan y fluyen solos; el muestreo QA (una fracción configurable) manda igualmente algunos limpios a la bandeja, etiquetados como QA, para vigilar la calidad. Un documento muestreado espera esa revisión antes de entrar a la cola de salida: así el proceso siguiente nunca recibe un valor que después se corrige.

En la bandeja, cada documento dice por qué está ahí: campos bajo umbral, política del proyecto, o muestreo QA.

La escalada de modelo

Si configuras un modelo de escalada, cuando la extracción deja más del 10% de los campos bajo umbral se reintenta una vez con ese modelo (más capaz) y gana el resultado con menos campos a revisar. El minuto del revisor es el costo dominante del IDP: una segunda llamada de céntimos que evita una revisión es buen negocio. El consumo de ambas llamadas se registra.

La caché de OCR en los bundles

Cuando un bundle incierto pasa por la estación de clasificación, el playbook puede subirlo con su lectura ya hecha (el parámetro document de Documents — Send Bundle to Classification). Al extraer los segmentos confirmados después, Take Confirmed Bundles devuelve esa lectura y IDP Extract la recorta por segmento — el mismo papel no se paga dos veces a Azure.

Paquetes: un fichero, varios documentos

Un cliente rara vez te entrega un documento por fichero. Un solo PDF llega con la hoja de vida, sus reportes de mantenimiento, calibraciones y anexos pegados. IDP Classify se encarga de eso: clasifica cada página —su tipo y si inicia un documento nuevo— y parte el fichero en segmentos contiguos, cada uno con su tipo real. Las fronteras salen del cambio de tipo, del inicio que detecta el modelo (membrete, encabezado nuevo, un campo de página 1) o de la marca impresa “página 1 de N”.

El playbook itera los segmentos y extrae cada uno contra su propio proyecto, por su rango de páginas. Un fichero de un solo documento sale como un único segmento, así que el caso normal no cambia.

Cuando el troceo no está claro: la estación de clasificación

Partir varios documentos del mismo tipo pegados sin marca es ambiguo. IDP Classify señala esos casos con splitNeedsReview. En vez de extraer a ciegas, el bundle va a la estación de clasificación: una persona ve las páginas, ajusta las fronteras y los tipos, y confirma; recién entonces se extrae cada segmento. Es el gate condicional que hace que, llegue como llegue el documento, el troceo quede bien. Ver el tutorial.

Configuración

Sin credenciales: incluido en tu plan

Si tu plan de Zoan Cloud incluye IA e IDP, puedes dejar vacías la credencial del modelo y las de Azure (en el proyecto, en Lectura y modelo, y en las actividades). Los robots, las pruebas del Designer y los borradores del esquema usan entonces las cuentas de Zoan a través de Zoan Cloud: empiezas a extraer sin contratar proveedores ni guardar claves, y todo el consumo —tokens y páginas— queda en Consumo de IA, contado en lo incluido en tu plan.

Con credenciales propias, las llamadas van directo a tus proveedores con tus condiciones, y Zoan Cloud registra solo el consumo para que lo veas en el mismo panel. Puedes combinar: tu propio modelo y la lectura incluida, o al revés.

Un documento que no cabe en el cupo de páginas que queda se rechaza antes de leerlo, con las cifras, y nunca se entrega una lectura a medias como si fuera completa: tampoco un borrador del esquema hecho con medio documento.

La credencial del modelo

Créala en el ambiente con una sola propiedad, llamada exactamente value, con la API key dentro.

Campo	Valor
Nombre	`anthropic-key`
Propiedad → clave	`value`
Propiedad → valor	la API key
Sensible	marcado

El nombre de la propiedad importa: con una sola propiedad llamada value, Zoan Cloud devuelve la clave suelta. Con cualquier otro nombre —o con varias propiedades— devuelve un objeto, y entonces hay que indexarla en el playbook: credential("mi-credencial")["api-key"].

Si te equivocas no falla en silencio: la actividad avisa de que la credencial no contiene la API key.

Azure Document Intelligence (solo para escaneos)

Hace falta únicamente si vas a procesar documentos escaneados o con manuscrito. Un PDF con capa de texto se lee sin salir de la máquina y sin coste.

Con la lectura incluida en tu plan no configuras nada. Con tu propio recurso, configura su endpoint y una credencial con su clave. Con mode = auto, la actividad decide sola: si el documento tiene texto lo lee directo; si no, lo manda a Azure. Las dos rutas devuelven lo mismo, así que nada de lo que viene detrás cambia.

El dpi, en los dos sitios

Si vas a subir el documento para revisarlo, las páginas se renderizan con PDF To Images. El dpi tiene que ser el mismo que le diste a IDP Load Document: las cajas de los campos vienen en píxeles a ese dpi y se dibujan sobre esas imágenes sin conversión.

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

La revisión

Un documento procesado acaba en uno de estos estados:

Sin extraer — se subió pero no se extrajo. Es un estado real: subir y extraer son dos pasos distintos.
Por revisar — extraído y sin firmar por nadie.
Validado — una persona lo dio por bueno.

Pendiente no significa “el IDP dudó”. Significa que nadie lo ha mirado todavía. Un documento con los 44 campos limpios sigue necesitando que alguien lo firme; el contador de campos marcados solo te dice cuánto trabajo tiene dentro.

En la estación de validación se ve el documento a la izquierda con la caja de cada campo encima, y el panel de trabajo a la derecha. La revisión es un flujo guiado, no una lista que escanear:

La estación te lleva de un pendiente al siguiente: Enter acepta el valor y avanza, Shift+Enter retrocede, y cada campo tiene su botón ✓ de “está bien”. Una barra de progreso dice cuánto queda.
La sincronía es en ambos sentidos: pinchar un campo salta a su página, centra su caja y atenúa las demás; pinchar una caja sobre el documento lleva a su campo y lo enfoca.
Los campos ya verificados se colapsan a una línea — con 45 campos y 3 por revisar, ves 3.
Las tablas se editan a lo ancho de la página (una tabla es ancha por naturaleza), con cabecera fija y las celdas por revisar destacadas; en el panel queda un chip por tabla con sus celdas pendientes.
La imagen tiene zoom (+/−/ajustar) y las miniaturas de página marcan cuántos pendientes tiene cada una.

Corriges lo que haga falta y firmas.

Un valor corregido pierde su marca de revisión —ya lo miró una persona— pero se conserva todo lo demás: cajas, confianzas y motivos. Es la trazabilidad de dónde salió cada dato, y perderla al validar dejaría el documento sin poder explicarse.

Retención

Los documentos que subes caducan. Cada ambiente tiene una retención por defecto, y cada subida puede pedir la suya.

Esto no es un detalle de infraestructura. El almacenamiento cuesta céntimos; guardar de más es responsabilidad legal. Un documento clínico o una nómina que sigue ahí tres años después de haber cumplido su función es un riesgo, no un archivo. Vale la pena decidirlo a conciencia: quizá 90 días para lo ya validado y años para lo que exija una norma, en el mismo lote.

Al vencer, el documento sale de la plataforma sin que tengas que acordarte. Por defecto se archiva: el original y su extracción van a un .zip en formato abierto, en el almacenamiento de Zoan Cloud o en tu propio contenedor, y se conservan hasta que tú los borres. Si prefieres que se borren sin archivo, elígelo en Retención de datos.

Aislamiento

Los documentos nunca se mezclan entre tenants. Cada uno vive bajo el prefijo de su tenant en el almacenamiento, y la base de datos lo fuerza a nivel de fila: aunque una consulta se dejara el filtro, no devuelve nada de otro tenant.

Ni el tenant ni el ambiente viajan en la petición de subida: los resuelve Zoan Cloud desde la ejecución autenticada. Un playbook no puede subir al tenant equivocado, ni por error ni a propósito.

Costes

Esto es lo que consume, y solo una parte es cara:

	Coste
Leer un PDF digital	Sin costo de lectura — no sale de la máquina
Leer un escaneo (Azure DI)	Por página (con la lectura incluida, cuenta en el cupo de páginas del plan)
Guardar el documento en Zoan Cloud	Cada página guardada para la revisión cuenta en el cupo de páginas del plan, sea digital o escaneada
Clasificar	Una llamada corta por documento
Extraer	Lo que pesa: entra el documento entero, sale un JSON

El cupo de páginas del plan suma las páginas que se guardan en Zoan Cloud y las que lee el Azure Document Intelligence incluido; las que lees con tu propio recurso de Azure se miden, pero no cuentan. Como IDP Extract guarda el documento al extraerlo, un PDF digital no paga lectura, pero sus páginas sí cuentan en el cupo.

Cada actividad de IA puede dejar su consumo —modelo, tokens de entrada y de salida— en una variable. Guárdalo en el resultado del item y tendrás el coste real por documento, consultable por API, sin estimar nada.

La pestaña Consumo del proyecto agrega todo esto en unidades: páginas procesadas (la unidad que aplica a la facturación del servicio), documentos, tokens por modelo y páginas de OCR. El costo de proveedor en dólares no aparece en el portal del tenant — es información del operador de la plataforma y vive en su portal (detalle del cliente → Consumo IDP), calculado con los precios de billing.provider_pricing ($/millón de tokens por modelo, $/página de Azure DI), editables sin redesplegar. Un modelo con consumo pero sin precio configurado se marca como sin tarifar — el costo mostrado es un piso, nunca un $0 engañoso.

La forma de bajarlo mucho: un modelo pequeño acierta igual en documentos estructurados. Conviene medirlo con tus documentos, con el gold, antes de pagar uno grande.

Un límite que conviene conocer

IDP Extract pide todos los campos en una sola llamada: el documento se envía una vez y el esquema no se trocea, por grande que sea. El límite está en el tamaño de la respuesta: un documento con muchísimos campos o tablas muy largas puede llegar al tope de maxTokens antes de terminar, y entonces la actividad falla con un error claro en vez de entregar datos a medias. La salida es dividir el documento por páginas (pages).

Si montas el pipeline a mano con las actividades granulares, IDP — Build Schema sí devuelve varios esquemas, porque la salida con gramática estricta rechaza los esquemas grandes: ahí el playbook recorre esa lista y el documento se envía una vez por lote.

Siguientes pasos

Actividades de IDP — qué hace cada nodo y el playbook completo
Colas de trabajo — el patrón para procesar lotes con reintentos
Gestión de credenciales — cómo se guardan y se resuelven