AI Extract

AI Extract

Tipo: ai-extract  ·  Paquete: AI Activities v1.0.0  ·  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.

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

Envía al modelo el prompt (el texto del documento), las images si las hay, y el schema. La respuesta llega ya validada contra el esquema y se devuelve como objeto con sus campos, listo para leer con resultado["campo"].

Parámetros requeridos

Parámetro	Editor	Descripción
credential	credencial	Credencial de Zoan Cloud con la API key del proveedor.
prompt	expresión	El texto del documento del que extraer, y cualquier instrucción sobre él.
schema	JSON	JSON Schema del objeto a extraer. La raíz debe ser "type": "object".

Parámetros opcionales

Parámetro	Editor	Descripción
provider	enum	Proveedor de IA. Por defecto, Anthropic (Claude).
model	expresión	Id del modelo. Vacío usa el modelo por defecto del proveedor.
system	expresión	Instrucciones de sistema: qué tipo de documento es y cómo leerlo.
images	lista	Rutas de imágenes de las que extraer (.jpg, .png, .gif, .webp).
effort	enum	Cuánto trabajo dedica el modelo: low, medium, high, xhigh, max.
thinking	booleano	Deja que el modelo razone antes de responder.
maxTokens	expresión	Tamaño máximo del objeto extraído, en tokens. Por defecto 16000.
timeout	expresión	Segundos de espera. Por defecto 600.

Salida

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

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:

PDF Get Text   path = = rutaFactura   → output: texto
AI Extract     credential = = credential("anthropic-key")
               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: equipo

Errores comunes

Mensaje	Qué pasó
'schema' must be a JSON Schema whose root is "type": "object"	El esquema pide una lista o un valor suelto. Envuélvelo en un objeto con un campo que sea esa lista.
The model hit the 'maxTokens' limit before finishing	El objeto extraído no cabe. Sube maxTokens o pide menos campos por llamada.
The credential does not contain an Anthropic API key	La credencial existe pero está vacía o guarda otra cosa.
Claude declined this request for safety reasons	El modelo rechazó el contenido. Es una respuesta del modelo, no un fallo de configuración.

Actividades relacionadas

• AI Complete — cuando quieres texto en vez de campos.
• PDF Get Text — obtener el texto antes de extraer.
• OCR — leer documentos escaneados.
• Queue Process — extraer un lote grande de documentos con reintentos.