Como criar um pipeline confiável de recebimento de documentos e OCR

Comece com um contrato de entrada

Um pipeline de documentos se torna difícil quando a primeira etapa aceita qualquer coisa e a última presume que tudo foi compreendido. Defina o contrato de entrada antes de escolher os Robots: quais origens são permitidas, o que a aplicação considera um documento, quais metadados são obrigatórios, qual o tamanho máximo de um upload e quais saídas os sistemas seguintes esperam. Aplique um limite de número de páginas na aplicação antes de criar a Assembly; o exemplo abaixo não limita o número de páginas. PDFs grandes ou com muitas páginas podem exceder a janela fixa de consultas periódicas do Robot enquanto ele aguarda uma tarefa assíncrona do provedor, mesmo que essa tarefa seja concluída depois. Tentar novamente com a entrada inalterada não amplia essa janela; trate tempos limite repetidos como uma falha e reduza ou divida a entrada antes de outra tentativa.

Mantenha o original enviado por upload como referência imutável. Um PDF normalizado, um arquivo de texto de OCR e um registro de pesquisa são derivados com ciclos de vida e modos de falha diferentes. Atribua a eles uma identidade compartilhada na aplicação para que um revisor possa partir de um resultado de pesquisa e chegar aos bytes de origem que o produziram. A navegação por páginas específicas exige um mapeamento de páginas separado.

Encaminhe cada entrada para o Robot adequado

A extensão do nome de arquivo não informa se um PDF contém texto selecionável ou apenas pixels digitalizados. Use o valor de ${file.mime} determinado pela Transloadit e a política da aplicação para encaminhar as entradas. A determinação do tipo MIME combina metadados incorporados, informações baseadas na extensão e inspeção do conteúdo; a extensão pode prevalecer quando os metadados incorporados não estão disponíveis. Essa barreira de validação não comprova o conteúdo do arquivo. Se o contrato de entrada exigir validação rigorosa do conteúdo, valide os bytes armazenados na sua aplicação. /file/filter pode encaminhar arquivos com condições accepts ou declines aplicadas a ${file.mime}; use error_on_decline quando uma entrada não compatível deva causar a falha da Assembly.

Os PDFs podem ir diretamente para /document/ocr. Use /image/ocr para textos curtos em fotografias e capturas de tela; sua documentação alerta que a precisão pode ser menor em imagens de documentos com conteúdo denso. Para entradas de formatos de escritório, como DOCX, use /document/convert para converter para PDF, verificando primeiro os formatos de entrada documentados. Este fluxo de trabalho usa a saída PDF desse Robot; outros formatos de saída estão disponíveis, mas PDF não é aceito como entrada. Um Robot pode ignorar entradas que não aceita sem causar a falha da Assembly, então adicione uma barreira explícita de validação de MIME e verifique as saídas obrigatórias.

Preserve a proveniência nas saídas derivadas

É difícil confiar em texto sem proveniência. Armazene o ID do documento de origem, a versão da saída e a data e hora da extração junto com o texto extraído. O exemplo com AWS abaixo retorna JSON em nível de documento, sem atribuição de página. Para resultados de busca específicos por página, a aplicação deve dividir os PDFs antes do upload e registrar os números das páginas originais; essa preparação está fora do escopo do guia. O exemplo permite uma entrada por Assembly e usa nomes fixos de objetos. Um pipeline por página precisa de uma Assembly por página, com chaves de objeto que identifiquem a página e um mapeamento para o documento pai. Reutilizar os mesmos document_id e output_version para várias páginas sobrescreveria os objetos dessas páginas. Nunca deduza o mapeamento pela ordem do array de OCR. Se o documento de origem for substituído, crie uma nova versão e deixe que o indexador retire o registro antigo somente após a verificação da nova saída.

Mantenha o texto de OCR separado do documento normalizado. Um revisor pode precisar da digitalização original, do PDF convertido e do texto extraído lado a lado. Essa relação também é útil quando outro provedor de OCR produz um resultado melhor.

Torne a revisão e a indexação explícitas

O valor ok ASSEMBLY_COMPLETED do Assembly Status, observado por consultas periódicas ou notificações, significa que nenhum erro não ignorado interrompeu a Assembly e que os Jobs declarados nela, incluindo os Jobs de armazenamento, foram concluídos. Um Step pode pular uma entrada, e ignore_errors pode suprimir uma falha de um Step, então a conclusão por si só não comprova que os artefatos necessários existem. Isso também não significa que o índice de busca da sua aplicação tenha aceitado o texto ou que uma pessoa tenha aprovado um registro sensível. Publique um evento para as etapas posteriores do fluxo somente depois que as saídas necessárias existirem e tiverem passado pelas verificações.

/document/ocr não expõe pontuações de confiança, então este Template não pode direcionar o fluxo com base em um limiar de confiança do provedor. Use verificações automatizadas na aplicação, como arquivos de saída ausentes, texto extraído vazio, quantidade de texto implausivelmente pequena para o número de páginas informado, frases esperadas ausentes ou uma classe de documento de alto impacto, para acionar a avaliação humana. Para documentos comuns, um fluxo automatizado ainda pode registrar as verificações e manter uma forma de reprocessar o documento de origem.

Versione as correções sem perder evidências

As correções de OCR e as substituições do documento de origem devem criar uma nova versão derivada. Mantenha o documento de origem anterior, a saída anterior e a decisão de revisão por tempo suficiente para atender à sua política de retenção, para que seja possível explicar um resultado do índice após uma correção.

Use o ID do documento e a versão da saída como chave de indexação. Reutilize uma versão somente ao repetir a mesma tentativa de processamento; atribua uma nova versão para correções, mudanças de provedor ou reprocessamentos deliberados. Serialize as gravações de uma versão para que novas tentativas simultâneas não possam sobrescrever um resultado mais recente já aceito.

Comece com um Template de PDF com limites definidos

O exemplo abaixo implementa apenas a ramificação para PDFs: permite no máximo um upload, rejeita tipos MIME que não sejam de PDF, solicita JSON de OCR da AWS e exporta o documento de origem e o JSON para chaves fixas distintas dentro de uma única versão de documento controlada pela aplicação. Salve este JSON como conteúdo de um Template armazenado, e não como os parâmetros completos de uma requisição de Assembly. Seu servidor fornece a Auth Key e a assinatura ao criar a Assembly. Teste PDFs representativos para avaliar a estrutura da saída, verificar se o texto é utilizável e observar o comportamento em caso de falha antes de ampliar a configuração de exemplo. auth.max_size limita o total de bytes de upload esperados, incluindo a sobrecarga da requisição: 104857600 bytes equivalem a 100 MiB, não a uma cota por arquivo. Esse parâmetro não garante a rejeição antes que um upload retomável transfira bytes, nem que o OCR seja concluído.

Crie uma conta na Transloadit e salve as Assembly Instructions como um Template. Crie uma credencial de Template para S3 chamada document-output com key, secret, bucket e bucket_region; consulte Credenciais de Template para configurar. Para esta configuração de exemplo, o servidor deve montar e enviar a requisição completa de Assembly, incluindo o upload, em vez de repassar params assinados a um navegador. Ele deve fornecer e validar, nos campos da requisição, valores de document_id e output_version que não estejam vazios, sejam autorizados e sejam seguros para uso em caminhos. Esses valores se tornam as variáveis ${fields.document_id} e ${fields.output_version} nos caminhos de armazenamento. Os campos multipart também são incorporados aos campos da Assembly e não são cobertos pela assinatura de params, portanto a assinatura por si só não autoriza um prefixo de armazenamento. Não encaminhe campos fornecidos pelo cliente. Antes de indexar, verifique se as chaves de armazenamento retornadas correspondem ao prefixo esperado pelo servidor. Salve allow_steps_override: false no Template armazenado para impedir sobrescritas de Steps em tempo de execução ao usar template_id. Mantenha o bucket privado com Block Public Access habilitado e verifique a autorização de quem acessa para leitura; acl: bucket-default omite uma ACL de objeto e depende da política de acesso do bucket.

Este exemplo fixa provider: aws para explicitar a escolha do provedor, sem garantir respostas idênticas. O padrão é auto. Use os limites atuais do AWS Textract⁠ como referência oficial para o suporte da AWS a idiomas. Verifique o suporte do provedor antes de escolher AWS ou GCP; suas estruturas JSON são diferentes. Teste os idiomas e layouts dos seus documentos com o provedor escolhido e espere mudanças nas respostas à medida que os modelos do provedor evoluírem.

O exemplo usa format: "json" com granularity: "list" para exportar um array de strings de linhas reconhecidas para indexação e verificações do volume de texto. Isso evita a mistura de entradas de página, linha e palavra do artefato padrão com granularidade full, que pode repetir texto. Já format: "text" exporta texto simples e força a granularidade list. Nenhuma das saídas inclui a indicação da página de origem nem pontuações de confiança. Se você escolher a granularidade full, os pontos opcionais dos polígonos usam um valor de largura e um valor de altura dos metadados do PDF, assumindo o valor zero quando essas dimensões estão ausentes. Valide esses pontos antes de criar sobreposições e nunca deduza a identidade da página pelos polígonos ou pela ordem do array.

Um Job de OCR bem-sucedido ainda pode deixar de reconhecer texto ou reconhecê-lo incorretamente. Verifique tanto os objetos exportados quanto o volume de texto extraído em relação à contagem de páginas informada e encaminhe resultados suspeitos para avaliação humana. Essas verificações automatizadas sinalizam problemas, mas não comprovam que o reconhecimento seja completo ou preciso; compare os resultados com texto conhecido em documentos de origem representativos antes de publicar.

As chaves de objeto fixas source.pdf e ocr.json fazem com que as novas tentativas usem os mesmos locais de armazenamento para uma versão do documento. Elas não deduplicam Assemblies nem tornam o OCR determinístico; a aplicação deve serializar as novas tentativas e manter o mapeamento do resultado aceito. Compare as cobranças dos provedores usando os preços da Transloadit, incluindo o volume de páginas e os demais processamentos do fluxo de trabalho. A cobrança de OCR por página, específica de cada provedor, é calculada com base no valor de page_count informado para a entrada; compare as cobranças atuais antes de estimar o fluxo de trabalho 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
    }
  }
}