Cómo crear un pipeline confiable de recepción documental y OCR

Empieza con un contrato de recepción

Un pipeline de documentos se complica cuando el primer paso acepta cualquier cosa y el último da por sentado que todo se entendió. Define el contrato de recepción antes de elegir los Robots: qué fuentes se permiten, qué considera la aplicación un documento, qué metadatos se requieren, cuál es el tamaño máximo de una subida y qué resultados esperan los sistemas posteriores. Aplica un límite de páginas en la aplicación antes de crear la Assembly; el ejemplo siguiente no limita las páginas. Los PDF grandes o con muchas páginas pueden superar la ventana fija de sondeo del Robot mientras esperan una tarea asíncrona de un proveedor, aunque esa tarea finalice más tarde. Reintentar con la misma entrada no amplía esta ventana; trata los tiempos de espera agotados repetidamente como un fallo y reduce o divide la entrada antes de volver a intentarlo.

Conserva el original subido como referencia inmutable. Un PDF normalizado, un archivo de texto OCR y un registro de búsqueda son derivados con diferentes ciclos de vida y modos de fallo. Asígnales una identidad compartida en la aplicación para que un revisor pueda pasar de un resultado de búsqueda a los bytes de origen que lo generaron. La navegación por páginas específicas requiere una correspondencia de páginas independiente.

Dirige cada entrada al Robot adecuado

La extensión de un nombre de archivo no indica si un PDF contiene texto seleccionable o solo píxeles escaneados. Usa el valor de ${file.mime} determinado por Transloadit y la política de la aplicación para dirigir las entradas. La determinación del tipo MIME combina metadatos integrados, información basada en la extensión y detección por contenido; la extensión puede prevalecer cuando no hay metadatos integrados disponibles. Este filtro no demuestra cuál es el contenido del archivo. Si tu contrato de recepción exige una validación estricta del contenido, valida los bytes almacenados en tu aplicación. /file/filter puede dirigir archivos mediante condiciones accepts o declines sobre ${file.mime}; usa error_on_decline cuando una entrada no admitida deba provocar el fallo de la Assembly.

Los PDF pueden pasar directamente a /document/ocr. Usa /image/ocr para textos breves en fotografías y capturas de pantalla; su documentación advierte que la exactitud puede ser menor en imágenes de documentos con mucho texto. Para entradas de documentos de oficina como DOCX, usa /document/convert para convertirlas a PDF, tras comprobar primero los formatos de entrada documentados. Este flujo de trabajo utiliza la salida en PDF de ese Robot; hay otros formatos de salida disponibles, pero el Robot no admite PDF como entrada. Un Robot puede omitir entradas que no acepta sin que falle la Assembly, así que añade un control explícito de MIME y verifica las salidas requeridas.

Conserva la procedencia en los resultados derivados

Es difícil confiar en un texto sin información de procedencia. Almacena el ID del documento de origen, la versión del resultado y la marca de tiempo de extracción junto con el texto extraído. El ejemplo de AWS que aparece a continuación devuelve JSON a nivel de documento sin indicar a qué página corresponde cada contenido. Para obtener resultados de búsqueda de páginas específicas, la aplicación debe dividir los PDF antes de la subida y registrar los números de página originales; esta preparación queda fuera del alcance de la guía. El ejemplo permite solo una entrada por Assembly y usa nombres de objeto fijos. Un pipeline por páginas necesita una Assembly por página con claves de objeto que identifiquen la página y una correspondencia con el documento principal. Reutilizar los mismos valores de document_id y output_version para varias páginas sobrescribiría sus objetos. Nunca deduzcas la correspondencia a partir del orden del array de OCR. Si se reemplaza el original, crea una nueva versión y deja que el indexador retire el registro anterior solo después de verificar el nuevo resultado.

Mantén el texto OCR separado del documento normalizado. Un revisor puede necesitar ver juntos el documento escaneado original, el PDF convertido y el texto extraído. Esa relación también resulta útil cuando otro proveedor de OCR produce un mejor resultado.

Haz explícitas la revisión y la indexación

El valor ok de Assembly Status ASSEMBLY_COMPLETED, observado mediante sondeo o notificaciones, significa que ningún error que no se hubiera ignorado detuvo la Assembly y que sus tareas declaradas, incluidas las de almacenamiento, finalizaron. Un Step puede omitir una entrada, y ignore_errors puede suprimir un fallo de un Step, por lo que la finalización por sí sola no demuestra que existan los artefactos requeridos. Tampoco significa que el índice de búsqueda de tu aplicación haya aceptado el texto ni que una persona haya aprobado un registro sensible. Publica un evento para los sistemas posteriores solo después de que los resultados que necesitas existan y hayan superado sus verificaciones.

/document/ocr no expone puntuaciones de confianza, por lo que este Template no puede enrutar según un umbral de confianza del proveedor. Usa comprobaciones automatizadas en la aplicación para activar la revisión humana: archivos de salida ausentes, texto extraído vacío, una cantidad de texto inverosímilmente pequeña para el número de páginas informado, frases esperadas ausentes o una clase de documento que implique consecuencias importantes. Para documentos comunes, una ruta automatizada aún puede registrar las comprobaciones y conservar una forma de volver a procesar el original.

Versiona las correcciones sin perder evidencia

Las correcciones del OCR y los reemplazos del original deberían crear una nueva versión derivada. Conserva el original anterior, la salida y la decisión de revisión durante el tiempo que exija tu política de retención, para poder explicar un resultado del índice después de una corrección.

Usa el ID del documento y la versión de salida como clave de indexación. Reutiliza una versión solo al reintentar el mismo intento de procesamiento; asigna una nueva versión para correcciones, cambios de proveedor o reprocesamientos deliberados. Serializa las escrituras de una versión para que los reintentos concurrentes no puedan sobrescribir un resultado aceptado más reciente.

Empieza con un Template acotado para PDF

El ejemplo siguiente implementa únicamente la rama de PDF: permite como máximo una subida, rechaza los tipos MIME que no sean PDF, solicita JSON de OCR de AWS y exporta el original y el JSON a claves fijas independientes bajo una sola versión del documento controlada por la aplicación. Guarda este JSON como contenido de un Template almacenado, no como parámetros completos de una solicitud de Assembly. Tu servidor proporciona la Auth Key y la firma al crear la Assembly. Prueba PDF representativos para evaluar la estructura de los resultados, la utilidad del texto y el comportamiento ante fallos antes de ampliar la configuración de ejemplo. auth.max_size limita el total de bytes de subida previstos, incluida la sobrecarga de las solicitudes: 104857600 bytes equivalen a 100 MiB, no a una asignación por archivo. No garantiza el rechazo antes de que una subida reanudable transfiera bytes ni que el OCR finalice.

Crea una cuenta de Transloadit y guarda las Assembly Instructions como un Template. Crea una credencial de Template para S3 llamada document-output con estos campos: key, secret, bucket y bucket_region; consulta credenciales de Template para configurarla. Para esta configuración de ejemplo, el servidor debe construir y enviar la solicitud completa de la Assembly, incluida la subida, en lugar de entregar los params firmados a un navegador. Debe proporcionar y validar valores de document_id y output_version no vacíos, autorizados y seguros para su uso en rutas en los campos de la solicitud. Estos se convierten en las variables ${fields.document_id} y ${fields.output_version} de las rutas de almacenamiento. Los campos multipart también aportan campos a la Assembly y no están cubiertos por la firma de params, por lo que la firma por sí sola no autoriza un prefijo de almacenamiento. No reenvíes campos proporcionados por el cliente. Verifica que las claves de almacenamiento devueltas coincidan con el prefijo esperado por el servidor antes de indexar. Guarda allow_steps_override: false en el Template almacenado para impedir que se sobrescriban los Steps en tiempo de ejecución al usar template_id. Mantén el bucket privado con Block Public Access habilitado y comprueba la autorización de quien accede a su contenido; acl: bucket-default omite la ACL del objeto y depende de la política de acceso del bucket.

Este ejemplo fija provider: aws para que la elección del proveedor sea explícita, sin garantizar respuestas idénticas. El valor predeterminado es auto. Usa los límites actuales de AWS Textract⁠ como referencia autorizada para los idiomas que admite AWS. Comprueba lo que admite cada proveedor antes de elegir AWS o GCP; sus estructuras JSON difieren. Prueba los idiomas y las disposiciones de tus documentos con el proveedor elegido y ten en cuenta que las respuestas pueden cambiar a medida que evolucionan los modelos del proveedor.

El ejemplo usa format: "json" con granularity: "list" para exportar un array de cadenas de líneas reconocidas destinado a la indexación y a las comprobaciones del volumen de texto. Esto evita la mezcla de entradas de página, línea y palabra del archivo resultante predeterminado con granularidad full, que puede repetir texto. En cambio, format: "text" exporta texto sin formato y fuerza la granularidad list. Ninguna de las dos salidas incluye la atribución de página ni puntuaciones de confianza. Si eliges la granularidad full, sus puntos de polígono opcionales usan un valor de ancho y uno de alto tomados de los metadatos del PDF y se convierten en ceros cuando faltan esas dimensiones. Valídalos antes de usarlos en superposiciones y nunca deduzcas la identidad de una página a partir de los polígonos ni del orden del array.

Una tarea de OCR completada con éxito aún puede omitir texto o reconocerlo incorrectamente. Comprueba ambos objetos exportados y contrasta el volumen de texto extraído con el número de páginas informado; envía los resultados sospechosos a revisión humana. Esas comprobaciones automatizadas señalan problemas, pero no demuestran que el reconocimiento sea completo o exacto; compara los resultados con texto conocido de documentos originales representativos antes de publicarlos.

Las claves de objeto fijas source.pdf y ocr.json hacen que los reintentos apunten a las mismas ubicaciones de almacenamiento para una versión del documento. No eliminan Assemblies duplicadas ni hacen que el OCR sea determinista; la aplicación debe serializar los reintentos y conservar la asignación correspondiente al resultado aceptado. Compara los cargos de los proveedores mediante los precios de Transloadit, incluyendo el volumen de páginas y otros procesos del flujo de trabajo. El cargo por página del OCR, específico de cada proveedor, se calcula a partir del valor page_count informado para la entrada; compara los cargos actuales antes de estimar el costo del flujo de trabajo completo.

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 1,
    "max_size": 104857600
  },
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "pdf_only": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "==", "application/pdf"]],
      "error_on_decline": true,
      "error_msg": "Upload a PDF document"
    },
    "extracted_text": {
      "use": "pdf_only",
      "robot": "/document/ocr",
      "provider": "aws",
      "format": "json",
      "granularity": "list",
      "result": true
    },
    "stored_source": {
      "use": "pdf_only",
      "robot": "/s3/store",
      "credentials": "document-output",
      "path": "documents/${fields.document_id}/${fields.output_version}/source.pdf",
      "acl": "bucket-default",
      "result": true
    },
    "stored_text": {
      "use": "extracted_text",
      "robot": "/s3/store",
      "credentials": "document-output",
      "path": "documents/${fields.document_id}/${fields.output_version}/ocr.json",
      "acl": "bucket-default",
      "result": true
    }
  }
}