Tutorial: crear y ejecutar un proyecto de extracción

Esta guía te lleva de la mano, de principio a fin, para sacar datos estructurados de documentos con Zoan Automation: crear el proyecto de extracción en el portal, extraer con un playbook, revisar lo que sacó una persona, y entregar los datos al siguiente paso. No hace falta experiencia previa.

Usaremos un ejemplo concreto: la hoja de vida de un equipo biomédico (serial, fabricante, fechas, historial de mantenimiento). Cambia los campos y ya tienes cualquier otro documento.

El mapa: qué vamos a construir

   Documento (PDF)
        │
        ▼
   idp-extract ──── lee, extrae y localiza cada valor ──── el PROYECTO gobierna todo
        │
        ▼
   Zoan Cloud (store) ── guarda el documento + la extracción, rinde las páginas
        │
        ├── ¿campos por debajo del umbral? → Estación de validación (una persona corrige)
        │
        ▼
   Cola de salida ── el bot de tu negocio recoge los datos ya validados

La idea central: el proyecto de extracción lleva toda la configuración (qué campos, qué modelo, credenciales, retención). El playbook solo dice qué proyecto y de dónde sale el documento. Quien sabe qué campos importan trabaja en el portal, sin tocar el playbook.

Los componentes

Pieza	Qué es	Dónde vive
Proyecto de extracción	El contrato del documento: esquema canónico + perfiles de formato + config.	Portal (Zoan Cloud)
Actividad IDP Extract	Extrae los campos del proyecto de un documento.	Playbook (Designer)
Store de documentos	Guarda el documento, la extracción y las páginas rendidas.	Zoan Cloud
Estación de validación	Donde una persona revisa los campos que no llegaron al umbral.	Portal
Cola de salida	El hand-off al bot que procesa los datos aguas abajo.	Zoan Cloud
Estación de clasificación	Para archivos con varios documentos: confirmar el troceo antes de extraer.	Portal

Antes de empezar

Necesitas:

Un entorno creado en Zoan Cloud (p.ej. producción o pruebas).
Un agente instalado y conectado a ese entorno (donde correrá el playbook). Ver Instalación del agente.
Una credencial del modelo: la API key de Anthropic guardada como credencial de Zoan Cloud (lo hacemos en el paso 2).

Paso 1 — Crear el proyecto de extracción

En el portal, entra al menú Proyectos de extracción y pulsa Nuevo proyecto. El proyecto se crea solo con su identidad y el resto se configura después, en pestañas.

1.1 Identidad

Campo	Ejemplo	Qué es
Nombre	`hoja-de-vida`	El nombre por el que lo llama el playbook. Sin espacios.
Tipo de documento	`hoja de vida`	Descriptivo, para las bandejas.
Descripción	`Hoja de vida de equipos biomédicos`	Ayuda al modelo a saber qué documento es.
Ámbito	`Global` o `De este entorno`	Global = compartido por todos los entornos; de entorno = solo ese (tiene prioridad).

1.2 El esquema canónico

Es el contrato de salida: los campos que el proyecto entrega, siempre con el mismo nombre, aunque el layout del documento cambie. En la pestaña Esquema canónico, añade un campo por fila:

Nombre	Tipo	Umbral	Descripción (la lee el modelo)
`serial`	string	0.85	El número de serie del equipo.
`fabricante`	string	0.80	El fabricante del equipo.
`fecha_instalacion`	date	0.90	La fecha de instalación.
`mantenimientos`	table	0.80	El historial de mantenimiento (columnas: fecha, acción, técnico).

Dos ideas clave:

La descripción es lo que el modelo usa para saber qué dato va en cada campo. Escríbela como se lo dirías a una persona.
El umbral (0 a 1) es por campo: un valor con confianza por debajo de su umbral va a revisión humana. Lo pone el negocio: un serial importa más que una nota.

La confianza no se la preguntamos al modelo. Se mide localizando el valor en el documento (grounding). Eso es lo que hace fiable el umbral.

1.3 Perfiles de formato (opcional)

Si el mismo tipo de documento viene en varios layouts (distintos fabricantes, distintas plantillas), creas un perfil por formato en la pestaña Formatos. Cada perfil:

tiene un router key (el código impreso que identifica ese formato), y
puede sobrescribir campos del canónico (una descripción distinta, otro umbral) sin cambiar el contrato.

Si solo hay un layout, no necesitas perfiles.

1.4 Lectura y modelo

En la pestaña Lectura y modelo:

Campo	Valor típico	Qué es
Modelo	`claude-haiku-4-5`	El LLM que extrae.
Modo de lectura	`auto`	`auto` usa la capa de texto del PDF y solo escanea si no la hay; `text` nunca escanea; `azure-di` siempre escanea (para PDFs que son foto).
Credencial del modelo	`anthropic-key`	La credencial de Zoan Cloud con la API key (paso 2).
Endpoint / credencial de OCR	(vacío)	Solo para escaneos: el recurso de Azure Document Intelligence.

1.5 Gobernanza y retención

En la pestaña Gobernanza y retención:

Campo	Qué es
Retención (días)	Cuántos días se guardan los documentos subidos. Es responsabilidad legal: guarda lo justo.
Muestreo QA	Fracción de auto-aceptados que igual se revisa, para vigilar la calidad.
Auto-aceptar	Aprobar sin revisión los documentos sin campos bajo umbral. Actívalo solo tras calibrar.
Cola de salida	El nombre de la cola a la que van los documentos extraídos como trabajo para el bot downstream. Vacío = sin cola (los datos quedan en el store).

1.6 Publicar

Cuando el proyecto está listo, pulsa Publicar. Esto congela la versión que usa el runtime: a partir de ahí, editar el esquema o los perfiles no rompe las extracciones en vuelo — el borrador se edita aparte y solo aplica cuando vuelves a publicar. El estado se ve en el editor: Publicado / Cambios sin publicar / Sin publicar.

Paso 2 — La credencial del modelo

En Credenciales del entorno, crea una credencial:

Campo	Valor
Nombre	`anthropic-key`
Valor	(tu API key de Anthropic)

El playbook nunca ve la key: la nombra por su nombre y Zoan Cloud la resuelve. Ver Gestión de credenciales.

Paso 3 — El playbook de extracción

En el Designer, crea un playbook. El caso normal es de dos nodos: listar los ficheros y extraer cada uno.

List Files    path      = "D:\hojas-de-vida\entrada"
              pattern   = "*.pdf"
              recursive = true
              → output: archivos

For Each      items        = = archivos
              itemVariable = archivo
              │
              └── IDP Extract   path    = = archivo
                                project = "hoja-de-vida"

Eso es todo lo que necesitas para extraer. IDP Extract hace por dentro todo lo caro: lee el documento, enruta al perfil, extrae en una sola llamada al modelo, localiza cada valor (grounding), y persiste el documento + la extracción en el store. Zoan Cloud rinde las páginas para la revisión, y si el proyecto tiene cola de salida, encola los documentos limpios.

No hay pdf-to-images ni documents-upload: eso lo hace la plataforma.

Parámetros de IDP Extract

Parámetro	Qué es
`project`	El nombre del proyecto de extracción. De ahí sale todo: esquema, modelo, credenciales, modo de lectura.
`path`	La ruta del documento.
`reference`	Clave estable (idempotencia): si ese documento ya se extrajo, reusa lo guardado y no vuelve a pagar Azure/LLM. Por defecto, el nombre del fichero.
`pages`	Qué páginas leer (`"1-3"`). Vacío = todas.
`document`	Un documento que ya leyó IDP Classify — para no releerlo (útil en bundles).

credential, azureCredential, dpi, mode y el endpoint no los pones aquí: los gobierna el proyecto. Solo aparecen como override avanzado.

Paso 4 — Ejecutar

Pulsa Run en el Designer. En los logs verás algo así:

list-files: ... → 3 entries
idp-extract: routed to format 'nuevo-formato'.
idp-extract: 1 call(s), 5023 input + 410 output tokens.
idp-ground: 42 of 45 field(s) accepted; 3 need review.
idp-extract: persisted extraction as document 07d0fca7-... (reference 'hoja-de-vida-2506193.pdf').
enqueued document 07d0fca7-... → queue 'hojas-de-vida-carga' (new item ...)

Qué pasó: se leyó una vez, se extrajeron los 45 campos en una llamada, se localizaron (3 quedaron bajo umbral → revisión), se guardó el documento, y como no necesitaba revisión completa se encoló para el bot downstream.

Si vuelves a correr, verás already extracted — reusing the stored result, skipping OCR+LLM: la idempotencia evita re-pagar.

Paso 5 — Revisar

Los documentos con campos bajo umbral aparecen en Documentos → Por revisar del entorno. Ábrelo: es la estación de validación.

A la izquierda, las páginas del documento (las rinde Zoan Cloud).
Sobre cada valor, una caja con su confianza. Los que necesitan revisión salen primero.
Corriges el valor si hace falta y pulsas Dar por bueno.

Al validar, el documento pasa a validado y, si el proyecto tiene cola de salida, entra a la cola con sus valores corregidos. Un botón Volver te regresa sin validar.

Paso 6 — El bot downstream (performer)

Los documentos ya listos (limpios al extraer, revisados al validar) están en la cola de salida. Un segundo playbook los procesa:

Process Queue   queueName    = "hojas-de-vida-carga"
                itemVariable = item
                │
                ├── Set Variable   name  = datos
                │                  value = = item.SpecificContent
                │
                ├── (aquí va tu carga real: item.SpecificContent["values"]
                │    tiene los campos; carga en tu sistema destino)
                │
                └── Set Transaction Status   item   = = item
                                             status = successful

El item lleva los datos (values) + un documentId para trazar. El performer los carga en tu sistema y cierra la transacción. Ningún bot queda esperando la revisión: es asíncrona.

Documentos con varios tipos en un archivo

Si un PDF trae varios documentos pegados (hoja de vida + reporte + calibración), usa IDP Classify antes de extraer. Clasifica cada página (su tipo y si inicia un documento nuevo) y devuelve segments.

IDP Classify   path     = = archivo
               projects = ["hoja-de-vida", "reporte-mantenimiento"]
               → output: doc

Si el troceo es claro, el playbook extrae cada segmento por su rango y su tipo.
Si es incierto (doc["splitNeedsReview"] es true), sube el bundle a la estación de clasificación con documents-classify-bundle y sigue. Una persona confirma las fronteras/tipos en Documentos → Clasificar, y el playbook idp-extraer-confirmados extrae los confirmados con documents-take-classified.

Así, sin importar cómo lleguen los documentos, siempre hay forma de que el troceo quede bien.

Comportamiento: lo que conviene saber

Una sola llamada al modelo. La extracción pide todos los campos de una, sin gramática estricta, y valida el resultado. El documento se lee una vez (antes eran ~10 llamadas re-enviando el documento).
Confianza medida, no declarada. El grounding localiza el literal en la página; de ahí sale la confianza y la caja. Un valor que no se localiza queda marcado.
Idempotencia. IDP Extract no re-paga OCR/LLM si el documento (por su reference) ya se extrajo.
Versionado. El runtime extrae contra la versión publicada; editar el proyecto es un borrador hasta que vuelves a publicar.
Retención. Los documentos caducan según la retención del proyecto/entorno; un barrendero los borra.
Páginas. Zoan Cloud rinde las páginas del documento bajo demanda desde el fichero — no las sube el playbook.

Referencia rápida de actividades

Actividad	Para qué	Doc
IDP Extract	Extraer los campos de un proyecto de un documento.	Ver
IDP Classify	Decir de qué tipo es cada página y trocear un bundle.	Ver
Documents Classify Bundle	Enviar un bundle incierto a la estación de clasificación.	—
Documents Take Classified	Tomar los bundles ya confirmados para extraerlos.	—
Add Queue Item / Process Queue	Encolar y procesar el trabajo downstream.	Colas

Siguientes pasos

Conceptos a fondo: Procesamiento de documentos (IDP).
Calibrar con un conjunto gold antes de activar el auto-aceptar.
Programar el performer con un trigger programado.