IDP — Extract

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

Desde: v1.6.0

Extrae todo lo que pide un proyecto de extracción de un documento, enruta al perfil del formato que tenga delante y busca cada valor en la página, así que sabes de dónde salió cada dato y cuánta confianza merece. En el Designer en español aparece como IDP — Extraer.

Es el camino normal del IDP: una actividad. Por dentro carga el documento si hace falta, enruta al perfil, extrae todos los campos en una sola llamada al modelo, groundea y guarda el resultado en Zoan Cloud — pero eso es asunto suyo, no tuyo.

Idempotente: no paga dos veces

IDP — Extract guarda su resultado por reference (por defecto, el nombre del archivo). Si ese documento ya se extrajo, reusa lo guardado y no vuelve a llamar a Azure ni al modelo — un reintento tras un fallo aguas abajo no cuesta nada. También guarda el documento y la extracción, así que no necesitas Documents — Upload después.

IDP — Extract   document = doc
                project  = "factura-proveedor"
                → output: res

El proyecto trae la configuración, no el playbook

La actividad pide un proyecto de extracción y de ahí sale todo lo demás. El proyecto —que se edita en el portal, en Procesamiento de documentos— lleva:

• el esquema canónico (los campos que entregas, el contrato),
• N perfiles de formato, uno por layout, cada uno con sus ajustes sobre el canónico,
• un router que elige el perfil por el código impreso del formato,
• la config: modelo, modelo de escalada, modo de lectura, endpoint y credenciales de OCR y del modelo.

Así, quien sabe qué campos importan lo configura en el portal y no toca el playbook. El playbook solo dice qué proyecto y de dónde sale el documento.

Cómo funciona

1. Resuelve el project en Zoan Cloud (o parsea el JSON en línea, para CI).
2. Si hay reference y el documento ya se extrajo, devuelve lo guardado (con reused = true) sin llamar a nada más.
3. Usa el document que le pases o lee path con IDP — Load Document y la config del proyecto. Si pasas document y un rango pages como "4-7", recorta esa lectura al rango en vez de releer.
4. Enruta al perfil del formato y extrae todos los campos en una llamada al modelo. Si maskPii está activo, el texto del documento sale con los datos personales enmascarados y los valores reales vuelven en el resultado. Si la respuesta no es un JSON válido, pide una reparación barata; si tampoco sirve, falla.
5. Localiza cada valor con IDP — Ground, aplica la escalada de modelo si toca y marca a revisión las tablas con filas idénticas consecutivas.
6. Si hay path, reference y Zoan Cloud, guarda el archivo y la extracción y devuelve su documentId.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
project	string	—	El nombre de un proyecto de extracción del ambiente. Trae el canónico, los perfiles, el modelo, el modo de lectura y el endpoint de OCR. Para CI también acepta un JSON de resolución en línea.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
path	string	—	Ruta del documento (PDF, PNG, JPEG o TIFF), si no pasas document. Hace falta path o document.
document	Dictionary	—	Un documento que ya leyó IDP — Classify o IDP — Load Document. Si lo pasas, no se vuelve a leer el archivo — con un escaneo, releerlo es pagar Azure dos veces.
reference	string	nombre del archivo de path	Clave estable del documento (idempotencia): si ya se extrajo, se reusa el resultado sin llamar a Azure ni al modelo. Pasa una por segmento cuando partes un bundle. Vuelve en la salida como reference. Desde la versión 1.14.0.
sourceGroupId	string	—	Solo al partir un bundle: el id (por ejemplo, la reference del archivo original) que agrupa los documentos que salieron del mismo archivo. Junto con pages, marca este documento como segmento: Zoan Cloud guarda su rango de páginas y muestra solo esas páginas. Desde la versión 1.15.0.
dpi	int	200	El dpi en el que vuelven las cajas. Rango: 36 a 1200. Usa el mismo que le des a PDF To Images si vas a mostrar el documento, o las cajas caen en el sitio equivocado. Se ignora si pasas document.
pages	string	— (todas)	Qué páginas leer, como "1-3". Con document, un rango "A-B" recorta la lectura dada; con sourceGroupId, un rango "A-B" queda guardado como el rango del segmento.
maxRetries	int	5	Reintentos ante un fallo pasajero del proveedor (0 a 10). Un procesamiento masivo son miles de llamadas: el 429 o 5xx suelto es una certeza, no un riesgo.
maskPii	bool	true	Reemplaza los datos personales del texto del documento por marcadores antes de enviarlo al modelo y restaura los valores reales en el resultado. Desde la versión 1.19.0.

Se configuran en el proyecto de extracción

Las credenciales no aparecen en el panel de la actividad: se configuran en la pestaña Lectura y modelo del proyecto de extracción en Zoan Cloud, junto con el modelo, el modelo de escalada, el modo de lectura y el endpoint de Azure DI.

Campo del proyecto	Parámetro	Qué controla
Credencial del modelo	credential	Tu propia clave del proveedor del modelo. Vacía, la IA incluida en tu plan.
Credencial Azure DI	azureCredential	Solo para escaneos: la clave de tu recurso de Azure Document Intelligence. Vacíos el endpoint y la credencial, la lectura incluida en tu plan.

Pásale el documento, no la ruta

Si vienes de IDP — Classify, usa document = doc. El archivo se lee una sola vez. Ten en cuenta que, sin path, la actividad no guarda el documento en Zoan Cloud: pásale también path y reference si quieres que quede guardado e idempotente.

Enruta al perfil del formato

Un mismo tipo de documento llega en varios formatos, y cada formato pinta los campos en otro sitio. El proyecto tiene un perfil por formato; IDP — Extract lee el código impreso del documento (por ejemplo F-COM-007), elige el perfil que le corresponde y funde sus ajustes sobre el canónico. La salida sale siempre con nombres canónicos — el mapeo es identidad.

Un formato que no casa con ningún perfil va a revisión

Si el proyecto tiene perfiles y el documento no coincide con ninguno, se extrae con el esquema general del proyecto, el log lo advierte y el resultado sale con needsReview = true y formatMatched = false, aunque los campos hayan salido limpios: un formato desconocido nunca se acepta solo. Un proyecto sin perfiles extrae siempre con su esquema general, sin marcar nada.

La escalada de modelo

Si el proyecto configura un modelo de escalada, cuando más del 10 % de los campos quedan bajo umbral la actividad reintenta una vez con ese modelo y se queda con el resultado que deja menos campos a revisar. Una llamada extra de céntimos que evita minutos de revisor. El consumo de ambas llamadas se suma en usage.

No clasifica

Extrae lo que se le pide, siempre. Comprobar que el documento es el que toca es una decisión tuya, y se hace antes con IDP — Classify.

No es un capricho: una actividad que decide sola no hacer su trabajo esconde el control de flujo, y además impide enrutar entre varios proyectos — que es justo lo que hace falta cuando la cola trae documentos mezclados.

Sin credenciales: la IA y la lectura incluidas en tu plan

Las credenciales son opcionales. Si ni la actividad ni el proyecto las tienen y tu plan de Zoan Cloud incluye IA e IDP, el modelo y la lectura de escaneos van por las cuentas de Zoan a través de Zoan Cloud: el robot funciona sin crear claves, y el consumo (tokens y páginas) aparece en Consumo de IA y cuenta en lo incluido en tu plan. Con tus propias credenciales, las llamadas van directo a tus proveedores y Zoan Cloud registra solo el consumo.

Con la lectura incluida, un documento que no cabe en el cupo de páginas 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).

Salida

Campo	Tipo	Qué es
values	Dictionary	Los datos, limpios: { numero: "FV-1234", items: [...] }. Es lo que consume el resto del playbook.
fields	List	Un campo por dato, con su caja, su confianza y por qué necesita revisión (la forma está en IDP — Ground). Es lo que pinta la estación de validación.
needsReview	bool	Si algún campo quedó por debajo de su umbral, una tabla repite filas, o el formato no casó con ningún perfil.
reviewFields	List	Nombres de los campos a revisar.
documentType	string	El tipo que declara el proyecto.
format	string	El perfil al que se enrutó (p. ej. F-COM-007). Sirve para trazar y mostrar qué formato se usó.
formatMatched	bool	Solo aparece, con false, cuando el proyecto tiene perfiles y ninguno casó.
source	string	text o azure-di.
dpi	int	El dpi de las cajas.
pageCount	int	Páginas leídas.
pages	List	Dimensiones de cada página (page, width, height, text), en píxeles al dpi de las cajas.
reference	string	La clave con la que se guardó (idempotencia). null si pasaste document sin path ni reference.
documentId	string	El id del documento guardado en Zoan Cloud. Solo cuando se guardó (hay path, reference y Zoan Cloud) o se reusó.
reused	bool	Solo aparece, con true, cuando el resultado se reusó de una extracción anterior.
usage	Dictionary	El consumo del documento: { model, inputTokens, outputTokens, calls }.

El consumo viene en tokens, no en dólares

La extracción pide todos los campos en una llamada, así el documento se lee una vez. usage lleva los tokens de esa llamada (y de la reparación o la escalada, si las hubo). Va en tokens y no en dólares a propósito: el precio por modelo cambia, así que el costo lo calcula quien consume con la tarifa vigente. El consumo también aparece en Consumo de IA.

La confianza no se le pregunta al modelo

Un modelo que se autoevalúa dice «95 %» con la misma seguridad cuando acierta que cuando se lo inventa. Esa confianza no está calibrada.

La de aquí sale de buscar el literal entre las palabras del documento. Si está, hay confianza y hay caja. Si no está, el valor no se puede verificar y el campo va a revisión. Es una comprobación mecánica, no una opinión.

Ejemplo

Extraer un documento de una cola y cerrar el item con los datos:

IDP — Extract   path      = contenido["path"]
                reference = item.Reference
                project   = "factura-proveedor"
                → output: res

If   condition = res["needsReview"]
  Log   message = "A revisión: " + toString(res["reviewFields"])

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

Extraer cada segmento de un bundle sin releerlo:

For Each   items = doc["segments"]   itemVariable = segmento
  IDP — Extract   document      = doc
                  path          = archivo
                  project       = segmento["type"]
                  pages         = segmento["pageStart"] + "-" + segmento["pageEnd"]
                  reference     = archivo + "#" + segmento["pageStart"]
                  sourceGroupId = archivo
                  → output: res

Errores comunes

Mensaje	Causa y solución
'project' es obligatorio.	Falta el nombre del proyecto.
Indica un 'path' para leer o un 'document' que IDP Classify ya haya leído.	No se pasó ni path ni document.
El proyecto de extracción '…' no existe en este ambiente. Créalo en el portal.	El nombre no coincide con ningún proyecto del ambiente.
'…' es el nombre de un proyecto, pero no hay un entorno de Zoan Automation para resolverlo. …	Sin Zoan Cloud en la ejecución (p. ej. desde la línea de comandos). Ejecútalo desde Zoan Cloud o el Designer, o pasa el JSON del proyecto.
Este proyecto de extracción todavía no tiene campos en su esquema. Agrégalos en Zoan Cloud antes de extraer.	El proyecto está vacío. Configura su esquema canónico y publícalo.
El modelo no devolvió un JSON válido para la extracción, ni siquiera tras un intento de reparación.	Respuesta irrecuperable del modelo. Reintenta con un Retry; si se repite, revisa las descripciones de los campos.
Zoan Cloud rechazó la búsqueda del documento (…): … / Zoan Cloud rechazó guardar el documento (…): … / Zoan Cloud rechazó guardar la extracción (…): …	Zoan Cloud no aceptó la consulta o el guardado. El detalle trae el código; reintenta.
El documento tiene N páginas y quedan M en el cupo de tu plan este mes. … / La lectura pide N páginas y quedan M en el cupo de tu plan este mes. …	El documento o el rango no cabe en el cupo de páginas. Todos los mensajes de lectura en IDP — Load Document.
Se alcanzó el consumo de IA incluido en tu plan este mes. Usa una credencial propia o amplía el plan.	Se agotó el consumo de IA incluido. Configura una credencial propia en el proyecto o amplía el plan.
Elige una credencial o activa la IA incluida en tu plan.	Ni el proyecto ni la actividad tienen credencial y tu plan no incluye IA.
El modelo llegó al límite de 'maxTokens' antes de terminar su respuesta. …	El documento tiene demasiados campos o filas para una respuesta. Divide el documento por páginas.

Actividades relacionadas

• IDP — Classify — de qué tipo es, antes de extraer
• IDP — Ground — el grounding suelto, si montas el pipeline a mano
• Documents — Upload — subir un documento a mano para revisarlo