AI — Extract

AI — Extract

Tipo: ai-extract  ·  Paquete: AI Activities v1.4.1  ·  Salida: object

Extrae campos concretos de un documento usando un modelo de lenguaje. Tú describes qué campos quieres con un JSON Schema y el modelo está obligado a responder con esa forma exacta, así que el resultado se usa directamente como objeto. En el Designer en español aparece como IA — Extraer.

Es la actividad para leer documentos cuyo formato cambia: la misma configuración lee la factura de un proveedor y la de otro, porque describes qué significa cada campo en vez de dónde está.

Cómo funciona

1. Comprueba que el proveedor pueda garantizar una respuesta con forma de esquema (Anthropic sí) y valida schema: debe ser un objeto JSON Schema cuya raíz sea "type": "object".
2. Si maskPii está activo (por defecto), reemplaza los datos personales del prompt por marcadores (ver Datos personales).
3. Envía al modelo el prompt (el texto del documento), las images si las hay, y el schema. Con tu credential va directo al proveedor; sin ella, por la IA incluida en tu plan a través de Zoan Cloud.
4. Si la respuesta se cortó por maxTokens, falla con un mensaje claro.
5. Restaura los valores reales en la respuesta y la devuelve como objeto con sus campos, listo para leer con resultado["campo"].

schema es un literal: no se evalúa campo por campo, así que sus textos ("type": "object", las descripciones) no se interpretan como expresiones. Si escribes una cadena que no empieza por {, se evalúa como expresión (por ejemplo, una variable que contiene el esquema).

Los reintentos, esperas y el registro ai-governance funcionan igual que en AI — Complete.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
prompt	string	—	El texto del documento del que extraer, y cualquier indicación sobre él. No puede quedar vacío. Es el texto que se enmascara con maskPii.
schema	Dictionary | string	—	JSON Schema del objeto a extraer (el objeto del editor, o el JSON como texto). La raíz debe ser "type": "object". Las descripciones de cada campo son parte del prompt.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
credential	credential	—	Tu propia clave del proveedor. Vacía usa la IA incluida en tu plan de Zoan Cloud: nada que configurar, y el consumo aparece en Consumo de IA. Opcional desde la versión 1.4.0.
provider	string	"anthropic"	Proveedor de IA. Valores válidos: anthropic (Anthropic, Claude).
model	string	"claude-opus-4-8"	Id del modelo. Vacío usa el modelo por defecto del proveedor. Con la IA incluida, debe estar en el catálogo de Zoan Cloud.
system	string	—	Instrucciones de sistema: qué tipo de documento es y cómo leerlo. El esquema ya describe los campos, así que úsalo para contexto, no para el formato. No se enmascara.
images	string | List	—	Ruta o lista de rutas de imágenes de las que extraer: .jpg, .jpeg, .png, .gif, .webp. Se envían sin enmascarar.
effort	string	—	Cuánto trabajo pone el modelo: low, medium, high, xhigh, max. Vacío usa el ajuste del proveedor.
thinking	bool	false	Deja que el modelo razone antes de responder. Ayuda con documentos densos o inconsistentes.
maxTokens	int	16000	Tamaño máximo del objeto extraído, en tokens. Rango: 1 a 64000.
timeout	int	600	Segundos de espera por intento. Rango: 1 a 3600. Con la IA incluida, cada intento espera como máximo 600 s.
maxRetries	int	5	Reintentos ante un fallo pasajero. Rango: 0 a 10; 0 los desactiva. Desde la versión 1.1.0.
usageVariable	string	—	Nombre de una variable (declárala como objeto) donde se escribe el consumo: { model, inputTokens, outputTokens }. Un documento extraído por tandas cuesta una llamada por tanda: súmalas. Desde la versión 1.1.0.
maskPii	bool	true	Reemplaza los datos personales del prompt por marcadores antes de enviarlo y restaura los valores reales en el objeto extraído. Desde la versión 1.2.0.
piiKinds	List	— (todos)	Qué tipos ocultar con maskPii: cedula, nit, email, telefono, cuenta, direccion, persona. Vacío = todos. Desde la versión 1.2.0.

Sin credencial: la IA incluida en tu plan

credential es opcional desde la versión 1.4.0:

• Vacía: si tu plan de Zoan Cloud incluye IA, la actividad usa la cuenta de Zoan a través de Zoan Cloud. No creas claves ni contratas un proveedor: el robot trabaja desde la primera ejecución, y lo que consume aparece en Consumo de IA y cuenta en el consumo incluido en tu plan. Funciona en las ejecuciones de Zoan Cloud y en las pruebas del Designer con tu sesión abierta.
• Con tu credencial: la llamada va directo del robot a tu proveedor, con tu clave y tus condiciones. Zoan Cloud registra solo el consumo (modelo y tokens) para que lo veas en el mismo panel; el contenido nunca pasa por Zoan Cloud y ese uso no descuenta del consumo incluido.

Con la IA incluida puedes usar los modelos de Anthropic (Claude) del catálogo de Zoan Cloud. El texto y las imágenes viajan por Zoan Cloud hasta el proveedor sin guardarse —solo se registra el consumo— y el enmascarado de datos personales se aplica en el robot, antes de enviarlos. Cada llamada admite hasta 20 MB y 20 imágenes.

Datos personales: maskPii y piiKinds

Igual que en AI — Complete: con maskPii = true, cada dato personal del prompt (cédulas, NIT, correos, teléfonos, cuentas, direcciones, nombres en contexto) se reemplaza por un marcador como <CEDULA_1> antes de enviarlo, y el robot restituye los valores reales dentro del JSON de la respuesta antes de convertirlo en objeto. Los campos extraídos llegan con los datos reales; el proveedor solo vio marcadores.

Solo se enmascara el prompt: las images y el system se envían tal cual. Si la política de datos personales de tu organización lo exige, el enmascarado se aplica aunque pongas maskPii = false.

Salida

Devuelve un object (un diccionario) con la forma que definiste en schema. Los campos se leen con resultado["nombre"]:

• Los objetos del esquema llegan como diccionarios, los arreglos como listas.
• Los números enteros llegan como enteros (long) y los decimales como double; true/false como booleanos; null como null.
• Un campo que no está en required y el modelo no encontró puede faltar del objeto: márcalos como required si vas a leerlos siempre.

Si indicas usageVariable, esa variable recibe { model, inputTokens, outputTokens }.

El esquema es parte del prompt

El modelo lee las descripciones de cada campo para decidir qué poner en él, así que escríbelas como se las explicarías a una persona que ve el documento por primera vez:

{
  "type": "object",
  "properties": {
    "numero":   { "type": "string", "description": "Número de la factura tal y como aparece impreso" },
    "fecha":    { "type": "string", "description": "Fecha de emisión en formato AAAA-MM-DD" },
    "total":    { "type": "number", "description": "Importe total con impuestos incluidos" },
    "proveedor":{ "type": "string", "description": "Razón social de quien emite la factura" }
  },
  "required": ["numero", "fecha", "total", "proveedor"],
  "additionalProperties": false
}

Pide el valor literal cuando importe la trazabilidad

Si necesitas saber de dónde salió un dato (para revisarlo, resaltarlo o auditarlo), añade un campo con el texto tal cual aparece en el documento — descrito como “el texto literal del que sale este valor”. Un valor que puedes volver a encontrar en el documento es un valor que puedes verificar.

Ejemplo

Leer una factura en PDF y usar sus campos, con la IA incluida en el plan:

PDF Get Text   path = rutaFactura   → output: texto
AI — Extract   prompt = texto
               schema = {…}
               → output: factura
Log            message = "Factura " + factura["numero"] + ": " + factura["total"]

Extraer de un documento escaneado, pasando por OCR primero:

PDF To Images   path = rutaEscaneo   dpi = 200   → output: paginas
OCR Get Lines   path = paginas[0]                → output: lineas
AI — Extract    credential = credential("anthropic-key")
                prompt     = join(map(lineas, "l => l[\"text\"]"), "\n")
                schema     = {…}
                → output: pedido

Errores comunes

Mensaje	Causa y solución
'schema' debe ser un JSON Schema cuya raíz sea "type": "object", para que el resultado extraído corresponda a campos con nombre.	El esquema pide una lista o un valor suelto. Envuélvelo en un objeto con un campo que sea esa lista.
'schema' es obligatorio. / 'schema' no es JSON válido: … / 'schema' debe ser un objeto JSON Schema, pero es …	Falta el esquema o el texto no es un JSON de objeto. Revisa la sintaxis.
'prompt' es obligatorio.	El texto del documento quedó vacío (por ejemplo, un PDF escaneado leído con PDF Get Text). Valídalo antes.
El modelo llegó al límite de 'maxTokens' antes de terminar su respuesta. Sube 'maxTokens' o pide una salida más corta.	El objeto extraído no cabe. Sube maxTokens o pide menos campos por llamada.
Anthropic (Claude) devolvió una respuesta que no es JSON válido pese al esquema: …	No debería ocurrir con un esquema estricto; si ocurre, reintenta.
'maxTokens' debe estar entre 1 y 64000. Recibido: … / 'timeout' debe estar entre 1 y 3600 segundos. Recibido: … / 'maxRetries' debe estar entre 0 y 10. Recibido: … / 'effort' debe ser uno de: …	Un parámetro fuera de rango. Corrígelo.
'piiKinds' contiene un tipo desconocido '…'. Válidos: cedula, nit, email, telefono, cuenta, direccion, persona.	Un tipo mal escrito en piiKinds.
No se encontró la imagen. / Formato de imagen no admitido '…'. …	Una ruta de images no existe o no es una imagen admitida.
La credencial no contiene una API key de Anthropic. Guarda la clave como valor de la credencial en Zoan Cloud.	La credencial existe pero está vacía o guarda otra cosa.
Claude rechazó esta solicitud por motivos de seguridad: …	El modelo rechazó el contenido. Es una respuesta del modelo, no un fallo de configuración.
Elige una credencial o activa la IA incluida en tu plan. La IA incluida va a través de Zoan Cloud: …	Sin credencial y sin Zoan Cloud en la ejecución. Abre tu sesión o usa una credencial propia.
Elige una credencial o activa la IA incluida en tu plan.	Sin credencial y tu plan no incluye IA.
Se alcanzó el consumo de IA incluido en tu plan este mes. Usa una credencial propia o amplía el plan.	Se usó todo el consumo de IA incluido este mes. Con una credencial propia el robot sigue sin pausa.
El modelo «…» no está disponible en la IA incluida en tu plan. Elige otro modelo o usa una credencial propia.	Elige un modelo del catálogo de Zoan Cloud, o usa tu credencial.
La solicitud es demasiado grande para la IA incluida en tu plan (hasta 20 MB y 20 imágenes por llamada, …).	Divide el documento o envía menos imágenes.
Zoan Cloud está atendiendo muchas solicitudes de IA a la vez. … / El proveedor de IA no respondió a tiempo a través de Zoan Cloud. …	Fallo pasajero tras agotar los reintentos. Sube maxRetries o usa un Retry.

Actividades relacionadas

• AI — Complete — cuando quieres texto en vez de campos.
• PDF Get Text — obtener el texto antes de extraer.
• OCR — leer documentos escaneados.
• IDP — Extract — extracción con proyecto, ubicación de cada valor y revisión.
• Queue Process — extraer un lote grande de documentos con reintentos.