IDP Load Document

IDP Load Document

Tipo: idp-load-document  ·  Paquete: IDP Activities v1.18.0  ·  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.

Es la entrada del pipeline documental: lo que sale de aquí alimenta a AI Extract.

Cómo funciona

En modo auto (el de por defecto) mide la capa de texto del PDF:

• Tiene texto → lo lee con la capa de texto. Es exacto y no cuesta nada.
• No tiene texto (o es una imagen) → lo manda a Azure Document Intelligence.

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ó.

Parámetros requeridos

Parámetro	Editor	Descripción
path	expresión	Ruta del documento: un PDF o una imagen (.jpg, .png, .tif, .bmp).

Parámetros opcionales

Parámetro	Editor	Descripción
mode	enum	auto (por defecto), text (solo capa de texto, nunca llama al cloud) o azure-di (siempre escanea).
pages	expresión	Páginas a leer: "all" (por defecto) o un rango como "1-3,5,7-9".
endpoint	expresión	URL del recurso de Azure Document Intelligence. Requerido salvo en modo text.
credential	credencial	Credencial de Zoan Cloud con la API key de Azure. Requerida salvo en modo text.
dpi	expresión	Resolución en la que se expresan las coordenadas. Por defecto 200.
minCharsPerPage	expresión	Umbral de la autodetección. Por defecto 16.

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. Por si lo quieres sin los números de línea.
pages	List	Una entrada por página: page, width, height, text.
words	List	Una entrada por palabra: text, page, x, y, width, height, confidence.

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 instalació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 calibración?”— 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 hoja de vida y extraer sus campos:

IDP Load Document   path       = = rutaDoc
                    mode       = auto
                    endpoint   = = "https://mi-recurso.cognitiveservices.azure.com"
                    credential = = credential("azure-di-key")
                    dpi        = 200
                    → output: doc
Log                 message = = "leido por " + doc["source"]
AI Extract          credential = = credential("anthropic-key")
                    prompt     = = doc["text"]
                    schema     = {…}
                    → output: equipo

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 al cloud 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	Qué pasó
'endpoint' is required to scan a document	El documento se detectó como escaneado pero no hay recurso de Azure configurado. Configúralo, o usa mode = text si el documento sí tiene capa de texto.
The credential does not contain an Azure Document Intelligence API key	La credencial existe pero está vacía o guarda otra cosa.
the text layer is empty (aviso)	Pediste mode = text sobre un escaneo. Usa auto o azure-di.

Actividades relacionadas

• AI Extract — extraer campos del documento cargado.
• PDF To Images — renderizar las páginas para dibujar las cajas encima.
• OCR — ruta on-prem para clientes sin cloud.