Let's Build: pipeline de inteligencia documental con Transloadit
Convierte un documento PDF o DOCX en un archivo JSON local con su título, resumen e información clave opcional. Este ejemplo combina la conversión de documentos con la extracción mediante IA guiada por un esquema; revisa el resultado guardado comparándolo con el original antes de usarlo en otro lugar.
La aplicación TypeScript descargable se ejecuta fuera de este repositorio. Acepta un documento local, lo envía a Transloadit y a un proveedor de IA, y guarda la respuesta en un archivo de salida nuevo. Para la primera ejecución, usa un documento sintético o sin información sensible que tengas permiso para subir. El procesamiento se factura, incluso cuando seleccionas explícitamente las credenciales de prueba de IA proporcionadas por Transloadit.
Qué significa realmente la inteligencia documental
Un flujo de trabajo documental puede analizar texto, separar páginas y extraer campos estructurados. Son operaciones distintas: esta aplicación envía los PDF directamente a /ai/chat y convierte primero los archivos DOCX a PDF. No realiza OCR ni divide los documentos en fragmentos.
El resultado es un punto de partida para la revisión o la indexación, no una prueba de que todos los datos se hayan extraído correctamente. Su esquema describe información clave del documento, no totales de facturas, partidas ni puntuaciones de confianza.
Configura tu proyecto TypeScript
Sigue las instrucciones de instalación y acceso de la aplicación desde un directorio vacío e independiente, fuera de un proyecto Node.js o un espacio de trabajo Yarn existente. No necesitas una copia de trabajo privada ni descargar archivos de prueba; aportas tu propio PDF o DOCX. Los ejemplos de shell usan Bash.
La combinación probada es Node.js 26.12.1, Yarn
4.12.0 mediante Corepack, @transloadit/node 4.14.0, zod 3.25.76 y zod-to-json-schema 3.25.2.
Estas versiones se fijan para reproducir el ejemplo, sin afirmar que sean las más recientes.
Node 26 es una línea de versiones con mantenimiento; ten en cuenta
las actualizaciones de seguridad al adaptar el ejemplo. Corepack es un requisito independiente
en Node 26: sigue sus instrucciones de instalación si
corepack no está disponible. También necesitas cURL para las descargas.
El README instala los paquetes con las versiones fijadas y descarga tanto document-intelligence-pipeline/run.ts
como shared/runtime.ts. Mantén juntos esos directorios hermanos, porque el programa importa
../shared/runtime.ts. Su comando final --help debería funcionar antes de que
proporciones credenciales. Si la configuración falla, inspecciona el directorio parcial antes de
reintentarlo: la creación inicial de package.json no permite sobrescribir un archivo.
No la repitas sobre una aplicación existente.
Configura TRANSLOADIT_AUTH_KEY y TRANSLOADIT_AUTH_SECRET en el shell que ejecuta la aplicación,
como indica el README. Estas variables autentican tu Workspace de Transloadit. Mantenlas fuera
del control de versiones y del código del navegador. El programa lee las variables de entorno
del proceso y no carga un archivo de entorno.
El acceso a la IA se elige por separado. Asigna a TRANSLOADIT_AI_CREDENTIALS el nombre de una
credencial de IA existente que contenga una clave de Anthropic, o pasa explícitamente
--test-credentials para usar claves de prueba proporcionadas por Transloadit cuyo uso se
factura. Selecciona un modo. El programa no crea ni modifica credenciales; consulta la
documentación de /ai/chat para obtener información sobre el acceso
a proveedores y la facturación.
Paso 1: Análisis de documentos con OCR (opcional)
El Robot
/document/ocr resulta útil cuando tu flujo de trabajo independiente
necesita texto reconocido o información de diseño de un PDF. Esta aplicación utiliza en cambio
la compatibilidad con entradas PDF de anthropic/claude-sonnet-4-6, seleccionada explícitamente en
su Step de extracción.
Para las entradas DOCX, el Robot /document/convert produce el PDF que se envía al modelo. La conversión y el OCR tienen finalidades distintas; añadir un Step de OCR requeriría decidir cómo incorporar su salida a tu propio flujo de trabajo de extracción.
Paso 2: División de documentos
El Robot /document/split puede seleccionar páginas para otro flujo de trabajo. El ejemplo siguiente procesa un archivo completo. Dividir un contrato en solicitudes independientes puede hacer que se pierdan definiciones o condiciones de otras páginas, así que no supongas que combinar las respuestas por página reproduce el significado del documento completo.
Paso 3: Extracción de datos con IA guiada por un esquema
La aplicación exporta example y documentInsightsSchema. Reutilízalos al
inspeccionarla o adaptarla, en lugar de mantener una segunda copia de su configuración o de su
esquema. El Step de extracción usa format: 'json', un esquema JSON serializado y
result: true para exponer el archivo de respuesta.
title y summary son cadenas obligatorias. Los campos opcionales
son author, publication_date, document_type,
key_topics y key_points. El tipo de documento, si está presente, es uno de
whitepaper, report, contract,
invoice, receipt, statement o manual.
Un campo opcional puede omitirse; una cadena obligatoria puede estar vacía o contener datos
incorrectos. La validación del esquema comprueba la estructura, no la veracidad.
Crear un pipeline completo
Coloca un documento en document.pdf dentro del directorio de tu proyecto local,
o cambia --input por su ruta real. Elige una ruta de salida que permita escritura
y que no exista. Con la autenticación del Workspace ya configurada y TRANSLOADIT_AI_CREDENTIALS
sin definir, este comando autoriza el procesamiento facturado con claves de prueba:
node document-intelligence-pipeline/run.ts --input ./document.pdf --output ./result.json --test-credentials
Para usar una credencial de IA de Anthropic existente, configura TRANSLOADIT_AI_CREDENTIALS como se
explicó antes y omite --test-credentials. El ejecutor acepta una entrada no vacía de hasta
20 MiB y descarga como máximo 20 MiB de salida. Estos son límites del tutorial. Permite cinco
minutos para la Assembly y un plazo independiente de 30 segundos para descargar el resultado;
los límites del proveedor aún pueden hacer que se rechace un archivo que esté dentro del límite
de tamaño local.
Si la ejecución tiene éxito, la terminal imprime Saved
seguido de la ruta de salida. La entrada no se modifica y result.json es un archivo
local, no una URL temporal del resultado. Si la salida ya existe, el ejecutor la rechaza antes
de enviar una Assembly. Para repetir las ejecuciones de forma secuencial, usa otro destino;
no elimines tu resultado anterior solo para repetir un comando.
Guarda este script de inspección como inspect.ts junto a package.json.
Lee la salida guardada con el mismo esquema exportado, rechaza el texto obligatorio que esté en
blanco e imprime los dos campos que debes revisar:
import { readFile } from 'node:fs/promises'
import { documentInsightsSchema } from './document-intelligence-pipeline/run.ts'
const saved = JSON.parse(await readFile('./result.json', 'utf8'))
const insights = documentInsightsSchema.parse(saved)
if (!insights.title.trim() || !insights.summary.trim()) {
throw new Error('The title or summary is blank. Review the source and Assembly before retrying.')
}
console.log(insights.title)
console.log(insights.summary)
node inspect.ts
Comprueba los nombres, las fechas, las cantidades y las afirmaciones principales del resumen comparándolos con tu fuente. Un informe sobre la reparación de 12 bicicletas con 240 $ en repuestos no debe convertirse en un resumen sobre la venta de bicicletas o un gasto de 24 $. El script de inspección no puede determinar por ti si esos datos son correctos. Revisa también los campos opcionales del JSON y mantén privados los resultados sensibles.
Si una ejecución falla después de imprimir un ID de la Assembly, inspecciona esa Assembly en la Console antes de reintentar. Un tiempo de espera agotado o una interrupción no demuestra que el procesamiento remoto se haya detenido, y una ejecución fallida puede facturarse. El ejecutor desactiva los reintentos del SDK y elimina su salida local incompleta tras un fallo capturado; no puede garantizar la limpieza después de una terminación forzada. Inspecciona cualquier archivo restante antes de elegir un destino nuevo.
Procesar varios tipos de documentos
El ejecutor acepta nombres de archivo .pdf y .docx, incluidas
las extensiones en mayúsculas. El Robot
/file/filter dirige los archivos con tipo MIME PDF directamente a la
extracción; la otra rama los convierte primero a PDF. Esto no hace que esta CLI acepte como entrada
todos los formatos distintos de PDF. Cambiar el nombre de un archivo dañado no repara su contenido,
y una conversión exitosa no demuestra que el resumen sea preciso.
Decide qué añadir más allá del ejemplo local
Procesa los documentos secuencialmente con nombres de salida distintos mientras evalúas los resultados y los costos. Esta CLI no tiene un programador de procesamiento por lotes, una cola de revisión ni exportación a almacenamiento en la nube. Antes de procesar una colección, revisa los precios actuales y la documentación de los Robots.
Los Templates pueden hacer reutilizable un conjunto adaptado de Assembly Instructions. No son necesarios para esta ejecución local. Guardar la configuración en un Template o añadir almacenamiento no proporciona por sí solo revisión humana, controles de acceso para tu aplicación ni una política de extracción fiable.
Cuándo usar este enfoque
Este enfoque resulta útil si quieres controlar los Steps de conversión y extracción de un flujo de trabajo de archivos y puedes aportar la aplicación que los integre. Si necesitas una solución integrada de revisión o una calidad de extracción medida, compara un producto de IA especializado en documentos usando tus propios documentos. Este pequeño ejemplo no demuestra equivalencia funcional ni que esté listo para producción.
¿Todo listo para crear?
Empieza con el README de la aplicación y un documento sin información sensible cuyo contenido conozcas. Conserva juntos el JSON guardado y tu fuente para revisarlos; después, usa la documentación de los Robots de IA para planificar cualquier cambio en el flujo de trabajo de extracción.