IDP — Load Document

IDP — Load Document

Tipo: idp-load-document  ·  Paquete: IDP Activities v1.20.4  ·  Salida: object

Carga un documento y devuelve su texto y cada palabra con su posición en la página. Si el PDF tiene capa de texto la lee directamente; si no la tiene, lo escanea con Azure Document Intelligence. Las dos rutas devuelven la misma estructura. En el Designer en español aparece como IDP — Cargar documento.

Es la entrada del pipeline documental: lo que sale de aquí alimenta a AI — Extract o a IDP — Ground. IDP — Classify e IDP — Extract la usan por dentro.

Cómo funciona

En modo auto (el de por defecto):

• Es una imagen (.jpg, .jpeg, .png, .bmp, .tif, .tiff, .heif) → va directo al escaneo.
• Es un PDF con texto (media de caracteres por página ≥ minCharsPerPage) → lo lee con la capa de texto. Es exacto, no sale de la máquina y no cuesta nada.
• Es un PDF sin texto → lo manda a Azure Document Intelligence (modelo prebuilt-layout).

La decisión queda en el log, con la media de caracteres por página que midió y el umbral, para que puedas ver por qué eligió lo que eligió. Al terminar, el log dice cuántas páginas y palabras leyó y de qué fuente; si no reconoció ninguna palabra, deja una advertencia.

Con la lectura incluida en tu plan, cada intento espera hasta 10 minutos y los fallos pasajeros se reintentan hasta 3 veces.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
path	string	—	Ruta del documento: un PDF o una imagen (.jpg, .jpeg, .png, .bmp, .tif, .tiff, .heif). Las imágenes siempre pasan por el escaneo.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
mode	string	"auto"	Cómo leerlo: auto (capa de texto, y escaneo solo si no la hay), text (solo capa de texto, nunca llama a la nube) o azure-di (siempre escanea).
pages	string	"all"	Páginas a leer: "all" o un rango como "1-3,5,7-9".
endpoint	string	—	URL de tu propio recurso de Azure Document Intelligence (https://<nombre>.cognitiveservices.azure.com). Vacío, junto con credential, usa la lectura incluida en tu plan.
credential	credential	—	Clave de tu recurso de Azure (va con endpoint). Vacíos los dos, la lectura incluida en tu plan de Zoan Cloud.
dpi	int	200	Resolución en la que se expresan las coordenadas. Rango: 36 a 1200. Usa el mismo en PDF To Images para que las cajas caigan encima de las páginas.
minCharsPerPage	int	16	En modo auto, un PDF con menos caracteres por página de media se trata como escaneado. No puede ser negativo.

Sin endpoint ni credencial: la lectura incluida en tu plan

endpoint y credential son opcionales (desde la versión 1.20.0):

• Vacíos: si tu plan de Zoan Cloud incluye IDP, los escaneos se leen con el Azure Document Intelligence de Zoan a través de Zoan Cloud. No creas un recurso de Azure ni guardas claves; las páginas aparecen en Consumo de IA y cuentan en el cupo de páginas de tu plan.
• Con tu recurso de Azure: el documento va directo del robot a tu recurso. Zoan Cloud registra solo cuántas páginas se leyeron, y no descuentan del cupo del plan.
• Solo uno de los dos: la actividad falla con un mensaje claro, para no cobrar del plan algo que querías pagar aparte.

Un PDF con capa de texto se sigue leyendo en la máquina, sin salir de ella y sin consumir nada.

Límites de la lectura incluida

Límite	Valor
Tamaño del archivo	Hasta 50 MB
Páginas por lectura	Hasta 2000; un documento más largo se lee por partes con pages
Páginas al mes	El cupo de páginas de tu plan

Documentos cerca del tope de páginas

Antes de leer con la lectura incluida, Zoan Cloud cuenta las páginas del documento (o las del rango de pages). Si no caben en lo que queda del cupo del mes —o en lo que alcanza el consumo de IA que te queda—, la actividad falla al instante con las cifras y no se lee nada: no pagas por una lectura que no te sirve.

• Sin pages, el mensaje habla del documento: «El documento tiene 12 páginas y quedan 5 en el cupo de tu plan este mes».
• Con pages, habla del rango pedido: «La lectura pide 8 páginas y quedan 5 en el cupo de tu plan este mes».

Nunca recibes una lectura a medias como si fuera completa. Si el número de páginas no se puede saber antes y la lectura llena lo que quedaba del cupo (o llega al máximo de 2000 páginas), el resultado no se entrega y la actividad falla con un error claro (las páginas leídas sí cuentan en el consumo). Para leer un documento largo con poco cupo, divídelo con pages o usa tu propio recurso de Azure.

Salida

Devuelve un object con esta forma:

Campo	Tipo	Qué es
path	string	La ruta que se cargó.
source	string	Por qué ruta entró: text o azure-di.
dpi	int	El dpi en el que están las coordenadas.
pageCount	int	Número de páginas leídas.
text	string	Todo el texto del documento, con cada línea numerada ([12] ...). Es lo que se le pasa al modelo, y lo que le permite citar de qué línea sacó cada valor.
lines	List	Una entrada por línea: index, page, x, y, width, height, text. Es lo que usa IDP — Ground para leer la caja de la línea que el modelo citó.
markdown	string	El texto original sin numerar — el markdown del servicio en la ruta de escaneo, o el texto reconstruido en la de capa de texto.
pages	List	Una entrada por página: page, width, height, text.
words	List	Una entrada por palabra: text, page, x, y, width, height, confidence.

Un documento sin texto reconocible devuelve la misma estructura con words y lines vacías (y una advertencia en el log); no falla.

source no está para que el playbook se ramifique, sino para poder explicar un resultado malo: la confianza de la capa de texto y la del OCR no significan lo mismo.

Por qué el texto va numerado

Cada línea empieza por su número ([12] Fecha de emisión: | 15/01/2024). No es decoración: el modelo devuelve, por cada campo, la línea de la que sacó el valor, y IDP — Ground lee la caja directa de esa línea. Es lo que resuelve que un valor repetido —tres fechas idénticas— caiga cada uno en su sitio. El markdown de las tablas de la ruta de escaneo sigue disponible en markdown.

Casillas: solo por la ruta de escaneo

Una casilla (☑/☐) es una marca gráfica, no texto: la ruta de capa de texto no la ve. La ruta azure-di sí detecta las marcas de selección con su estado y su confianza, y se inyectan en el texto como ☑ (marcada) o ☐ (vacía), en su posición y como un token localizable. Así un campo de tipo boolean —“¿Requiere envío urgente?”— se extrae del estado real de la casilla, no adivinando del texto de alrededor.

Por eso, para un documento con casillas hay que leerlo con mode = azure-di (o auto si es un escaneo). Un PDF digital con casillas necesita forzar azure-di: por la capa de texto las casillas se pierden.

La confianza de la ruta de texto siempre es 1

En un PDF digital el carácter es el que el generador del PDF escribió: no hay reconocimiento y no hay incertidumbre. Solo la ruta azure-di devuelve confianzas reales por palabra.

Las coordenadas

Todas las palabras salen en píxeles al dpi que pidas, con origen arriba-izquierda, venga el documento de donde venga. Si renderizas la misma página con PDF To Images al mismo dpi, las cajas caen exactamente encima:

IDP — Load Document   path = rutaDoc   dpi = 200   → output: doc
PDF To Images         path = rutaDoc   dpi = 200   outputDir = carpeta   → output: imagenes

Ejemplo

Cargar una factura con la lectura incluida en el plan y extraer sus campos:

IDP — Load Document   path = rutaFactura
                      dpi  = 200
                      → output: doc
Log                   message = "Leído por " + doc["source"] + ": " + doc["pageCount"] + " páginas"
AI — Extract          prompt = doc["text"]
                      schema = {…}
                      → output: factura

Leer solo las tres primeras páginas de un escaneo largo con tu propio recurso de Azure:

IDP — Load Document   path       = rutaEscaneo
                      mode       = azure-di
                      pages      = "1-3"
                      endpoint   = "https://mi-recurso.cognitiveservices.azure.com"
                      credential = credential("azure-di-key")
                      → output: doc

Recorrer las palabras (para resaltar, medir o localizar un valor):

Foreach   items = doc["words"]   itemVariable = palabra
  Log   message = palabra["text"] + " en x=" + toString(palabra["x"])

Encadenar índices no funciona

doc["words"][0]["text"] falla: el motor no encadena indexadores sobre un valor sin tipo. Recorre la lista con Foreach, que sí tipa el elemento.

El umbral de autodetección

Por defecto es 16 caracteres por página, y significa “la capa de texto está prácticamente vacía” — porque la señal de un escaneo es que no tiene texto, no que tenga poco. El margen que queda cubre los escáneres que estampan una marca de agua o un pie de página como texto real.

Un umbral generoso (100 o más) manda a la nube cualquier documento digital corto —una portada, un acta de una línea, un certificado— que se leería gratis y perfecto por la capa de texto.

Súbelo solo si tus escaneos llegan con una capa de texto propia en la que no confías (por ejemplo, un OCR previo de mala calidad).

Errores comunes

Mensaje	Causa y solución
No se encontró el archivo.	La ruta de path no existe en la máquina del robot.
'mode' debe ser uno de: auto, text, azure-di. Se recibió: …	Valor de mode no válido.
'dpi' debe estar entre 36 y 1200. Se recibió: … / 'minCharsPerPage' no puede ser negativo. Se recibió: …	Parámetro fuera de rango (o no entero).
Rango de páginas no válido '…'. Usa "all", un número de página o un rango como "1-3,5,7-9". / Rango de páginas no válido '…': la página inicial es mayor que la final.	pages mal escrito.
Página(s) fuera de rango: …. El documento tiene N páginas.	En la ruta de capa de texto, pages pide páginas que el PDF no tiene.
Para escanear un documento, indica el endpoint y la credencial de tu recurso de Azure Document Intelligence, o ejecuta con Zoan Cloud para usar la lectura de documentos incluida en tu plan (en el Designer, inicia sesión en Zoan Cloud).	El documento es un escaneo, no hay recurso de Azure y la ejecución no tiene Zoan Cloud (p. ej. una prueba sin sesión). Abre tu sesión, configura tu recurso, o usa mode = text si el documento tiene capa de texto.
'endpoint' es obligatorio para escanear con tu propio recurso de Azure Document Intelligence. … / 'credential' es obligatoria para escanear con tu propio recurso de Azure Document Intelligence. …	Pusiste solo uno de los dos: completa el otro, o deja ambos vacíos para usar la lectura incluida.
'endpoint' debe ser la URL completa del recurso de Azure Document Intelligence, como https://<name>.cognitiveservices.azure.com. Se recibió: …	El endpoint no es una URL absoluta.
La credencial no contiene una API key de Azure Document Intelligence. Guarda la clave como valor de la credencial en Zoan Cloud.	La credencial existe pero está vacía o guarda otra cosa.
Tu plan de Zoan Cloud no incluye la lectura de documentos. …	Sin recurso propio y tu plan no incluye IDP. Configura tu recurso de Azure o activa la lectura incluida.
El documento tiene N páginas y quedan M en el cupo de tu plan este mes. No se leyó nada, así que no recibes un resultado incompleto. Lee menos páginas ('pages'), usa tu propio recurso de Azure Document Intelligence o amplía el plan.	El documento no cabe en el cupo de páginas que queda este mes.
La lectura pide N páginas y quedan M en el cupo de tu plan este mes. No se leyó nada, …	El rango de pages no cabe en el cupo que queda. Pide menos páginas.
El documento tiene N páginas y el consumo de IA que queda en tu plan este mes alcanza para M. No se leyó nada, … / La lectura pide N páginas y el consumo de IA que queda en tu plan este mes alcanza para M. No se leyó nada, …	Lo que queda del consumo de IA incluido no alcanza para leer todas esas páginas.
La lectura llegó a N páginas, las que quedaban en el cupo de tu plan este mes, y el documento puede tener más. El resultado estaría incompleto, así que no se entregó. … / La lectura llegó a N páginas, lo que alcanzaba el consumo de IA que quedaba en tu plan este mes, y el documento puede tener más. …	No se pudo saber antes cuántas páginas tenía y la lectura llenó el cupo o el consumo restante: el resultado no se entrega porque estaría incompleto.
El documento tiene N páginas y una lectura admite hasta 2000. Léelo por partes con 'pages'. / La lectura pide N páginas y una lectura admite hasta 2000. Léelo por partes con 'pages'. / La lectura llegó a N páginas, el máximo de una lectura, y el documento puede tener más. … / El documento es demasiado largo para una lectura (hasta 2000 páginas). Léelo por partes con 'pages'.	Más de 2000 páginas en una lectura. Léelo por tramos con pages (por ejemplo, en un bucle de "1-2000", "2001-4000"…).
Se alcanzaron las páginas de documentos incluidas en tu plan este mes. Usa tu propio recurso de Azure Document Intelligence o amplía el plan.	Se usó todo el cupo de páginas del mes. Con tu recurso de Azure el robot sigue sin pausa.
La solicitud es demasiado grande para la IA incluida en tu plan (… 50 MB por documento). …	El archivo pasa de 50 MB. Divídelo o usa tu recurso de Azure.
El proveedor de IA no respondió a tiempo a través de Zoan Cloud. … / No se pudo contactar a Zoan Cloud: …	Fallo pasajero tras 3 reintentos. Envuelve la actividad en un Retry.
La capa de texto está vacía. Si el documento es un escaneo, usa el modo 'auto' o 'azure-di'. (advertencia)	Pediste mode = text sobre un escaneo. No falla, pero no hay palabras.

Actividades relacionadas

• AI — Extract — extraer campos del documento cargado.
• IDP — Extract — carga, extrae, ubica y guarda en una sola actividad.
• PDF To Images — renderizar las páginas para dibujar las cajas encima.
• OCR — ruta local, sin nube.