IDP — Classify

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

Desde: v1.7.0

Lee un documento y dice de cuál de los tipos que le listas es. Devuelve el documento ya leído junto al veredicto, para que IDP — Extract no tenga que releerlo. Y si el archivo trae varios documentos pegados, los parte en segmentos para extraer cada uno por separado. En el Designer en español aparece como IDP — Clasificar.

IDP — Classify   path     = contenido["path"]
                 projects = ["factura-proveedor", "orden-de-compra"]
                 → output: doc

If   condition = doc["recognized"] == false
  Log   message = "No es ninguno de los tipos que conozco: " + doc["documentType"]

Los tipos son proyectos de extracción

El parámetro projects recibe los nombres de proyectos de extracción del ambiente. Cada proyecto declara su tipo de documento y una descripción; eso es lo que el clasificador lee para distinguirlos. Así el mismo sitio donde configuras qué extraer define también qué tipos hay que distinguir — no se mantienen dos listas.

El primer proyecto de la lista gobierna cómo se lee el documento (modo de lectura, endpoint y credencial de OCR) y qué credencial del modelo se usa.

Cómo funciona

1. Resuelve cada nombre de projects en Zoan Cloud (o parsea el JSON en línea, para CI).
2. Lee el documento con IDP — Load Document, con la configuración de lectura del primer proyecto.
3. Clasifica cada página en una sola llamada al modelo (con AI — Extract por dentro): su tipo y si inicia un documento nuevo. Si maskPii está activo, el texto de las páginas sale con los datos personales enmascarados.
4. Agrupa las páginas en segments contiguos y calcula si el troceo es de fiar (splitNeedsReview).
5. Devuelve el documento leído más el veredicto. El log dice cuántos documentos encontró en cuántas páginas y, si la confianza es baja, que conviene enviarlo a la estación de clasificación.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
path	string	—	Ruta del documento: PDF, PNG, JPEG o TIFF.
projects	string | List	—	Los tipos a distinguir: nombres de proyectos de extracción del ambiente. Uno solo es un caso legítimo. Para CI también acepta un JSON de resolución de proyecto en línea.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
model	string	"claude-opus-4-8"	Modelo del clasificador. Vacío usa el predeterminado del proveedor. Clasificar es fácil comparado con extraer: un modelo pequeño (por ejemplo claude-haiku-4-5) suele bastar y cuesta menos.
dpi	int	200	El dpi en el que vendrán las cajas. Rango: 36 a 1200. Viaja con el documento hasta IDP — Extract, así que se dice una vez.
pages	string	— (todas)	Qué páginas leer, como "1-3" o "1-3,5". Vacío = todas.
maskPii	bool	true	Reemplaza los datos personales del texto del documento por marcadores antes de enviarlo al modelo. Desde la versión 1.19.0.

Se configuran en el proyecto de extracción

Estos ajustes 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, y la actividad toma los del primer proyecto de projects.

Campo del proyecto	Parámetro	Qué controla
Credencial del modelo	credential	Tu propia clave del modelo. Vacía, la IA incluida en tu plan.
Modo de lectura	mode	auto, text o azure-di.
Endpoint Azure DI	endpoint	URL de tu recurso de Azure Document Intelligence.
Credencial Azure DI	azureCredential	Clave de tu recurso de Azure Document Intelligence. Vacíos el endpoint y la credencial, la lectura incluida en tu plan.

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

Es el documento entero —el mismo que devuelve IDP — Load Document: path, source, dpi, pageCount, text, markdown, lines, pages, words— más el veredicto y los segmentos:

Campo	Tipo	Qué es
documentType	string	El tipo del primer segmento, o unknown.
recognized	bool	true si al menos un segmento tiene un tipo reconocido. La señal para tu If: si es false, no extraigas — a cuarentena/revisión.
segments	List	Los documentos lógicos que trae el archivo, cada uno { pageStart, pageEnd, type, recognized }. Cada segmento lleva su tipo real. Un archivo de un solo documento sale como un único segmento.
splitNeedsReview	bool	true cuando el troceo es de baja confianza (hay páginas sin reconocer, o se partió en varios sin ninguna marca impresa). Es la señal para mandar el bundle a la estación de clasificación.

Pásaselo tal cual a IDP — Extract en su parámetro document y el archivo no se vuelve a leer.

Ramifica por recognized, no por la cadena

If condition = doc["recognized"] es más robusto que comparar doc["documentType"] == "unknown" a mano: un typo en la cadena y un documento equivocado pasaría como bueno. Un unknown nunca debe descartarse en silencio — va a revisión.

Parte los archivos que traen varios documentos

Un proveedor entrega un solo PDF con la factura, la orden de compra, la remisión y anexos, todo pegado. IDP — Classify clasifica cada página: su tipo y si inicia un documento nuevo. Una frontera se abre cuando cambia el tipo, cuando el modelo detecta un inicio (membrete, encabezado nuevo, un campo que solo sale en la página 1) o cuando aparece la marca impresa «página 1 de N». Con eso agrupa las páginas en segments contiguos, cada uno con su tipo real.

For Each   items = doc["segments"]   itemVariable = segmento
  IDP — Extract   document = doc
                  project  = segmento["type"]
                  pages    = segmento["pageStart"] + "-" + segmento["pageEnd"]

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

Partir varios documentos del mismo tipo pegados sin marca es ambiguo. Cuando la confianza es baja, IDP — Classify lo señala con splitNeedsReview = true. En ese caso, en vez de extraer a ciegas, envías el bundle a la estación de clasificación con Documents — Send Bundle to Classification, una persona confirma las fronteras y los tipos, y Documents — Take Confirmed Bundles los devuelve para extraerlos.

If   condition = doc["splitNeedsReview"] == true
     then:
       Documents — Send Bundle to Classification   path = archivo, reference = archivo,
                                                    segments = doc["segments"], document = doc,
                                                    pages = doc["pages"], dpi = 200
       Continue

La marca impresa refuerza, no es la única vía

La marca «página 1 de N» sigue siendo una señal fuerte (y determinista), pero el troceo no depende solo de ella: la clasificación por página también reconoce el tipo y el inicio de documento. Lo que no queda claro, lo confirma una persona.

Siempre puede decir unknown

El enum del clasificador incluye siempre ese valor, y no es un detalle.

Sin una salida honesta, el modelo elige el tipo menos malo de la lista — porque el esquema le obliga a elegir uno. Y un documento equivocado clasificado como bueno es el fallo caro: el grounding no lo detecta, porque verifica que el texto esté en el documento, no que el documento sea el que crees. Una orden de compra tiene números que parecen números de factura, y saldrían localizados y con confianza alta.

Azure llegó a lo mismo

Su categoría other es obligatoria desde que el servicio es GA, con esta razón escrita en su documentación: «si no se incluye, todos los ficheros se clasifican en una de tus categorías».

Un solo proyecto es un caso normal

«¿Esto es una factura, sí o no?» es la pregunta más común en una cola de un solo tipo. Con un proyecto, el enum es ["factura-proveedor", "unknown"] — y esa segunda opción es la que hace que la pregunta tenga sentido.

Por qué va aparte de la extracción

Porque qué hacer con un documento que no toca es una decisión del playbook. Una actividad que decide sola no hacer su trabajo esconde el control de flujo, y además impide clasificar una vez y enrutar al proyecto que corresponda — que es el caso real de una cola con documentos mezclados.

Lo que ahorra

Clasificar cuesta una llamada corta: entran las páginas, salen el veredicto y los segmentos. Extraer cuesta una llamada por documento con todos los campos, y una respuesta mucho más larga.

En una medición de referencia sobre un documento de 3 páginas, clasificar costó unos $0,003 y extraer unos $0,041. Descartar antes de extraer ahorra el 95 % del coste de un documento equivocado — y evita meter datos plausibles y falsos en tu sistema.

Ejemplo

Clasificar lo que llega a una cola de facturas y extraer solo lo reconocido:

IDP — Classify   path     = contenido["path"]
                 projects = ["factura-proveedor"]
                 model    = "claude-haiku-4-5"
                 → output: 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
                 project  = "factura-proveedor"
                 → output: res
Log              message = "Campos a revisar: " + toString(res["reviewFields"])

type es el tipo de documento del proyecto

documentType y el type de cada segmento son el tipo de documento que declara cada proyecto. Si en tus proyectos coincide con el nombre (lo más práctico), puedes pasarlo tal cual como project a IDP — Extract, como en el bucle de segmentos de arriba; si no, tradúcelo con un diccionario tipo → proyecto.

Errores comunes

Mensaje	Causa y solución
'projects' es obligatorio. / 'projects' está vacío; no hay nada que distinguir.	No se indicó ningún proyecto.
El proyecto de extracción '…' no existe en este ambiente. Créalo en el portal.	Un nombre de projects no coincide con ningún proyecto del ambiente. Revisa el nombre en Procesamiento de documentos.
'…' es el nombre de un proyecto, pero no hay un entorno de Zoan Automation para resolverlo. Ejecuta el playbook desde Zoan Automation o pasa un JSON de proyecto en línea para CI.	La ejecución no tiene Zoan Cloud (por ejemplo, desde la línea de comandos). Ejecútalo desde Zoan Cloud o el Designer con sesión.
Zoan Cloud no pudo resolver el proyecto de extracción '…' (…): …	Zoan Cloud respondió con error al buscar el proyecto. Reintenta.
No se encontró el archivo. / Rango de páginas no válido '…'. … / 'dpi' debe estar entre 36 y 1200. Se recibió: …	Errores de la lectura: ver IDP — Load Document.
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 de pages) no cabe en el cupo de páginas. Mensajes completos 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 clasificador no devolvió una respuesta.	El modelo no devolvió una clasificación. Reintenta.

Actividades relacionadas

• IDP — Extract — extraer, una vez sabes que es el que toca
• Documents — Send Bundle to Classification — cuando el troceo no está claro
• IDP — Build Classifier — el esquema suelto, si montas el pipeline a mano