Let's Build: pipeline de inteligência documental com Transloadit
Transforme um documento PDF ou DOCX em um arquivo JSON local com título, resumo e informações extraídas opcionais. Este exemplo combina conversão de documentos com extração por IA orientada por esquema; você confere o resultado salvo com o original antes de usá-lo em outro lugar.
A aplicação TypeScript para download é executada fora deste repositório. Ela aceita um documento local, envia-o à Transloadit e a um provedor de IA e salva a resposta em um novo arquivo de saída. Na primeira execução, use um documento sintético ou sem dados sensíveis que você tenha permissão para enviar por upload. O processamento é cobrado, inclusive quando você seleciona explicitamente credenciais de teste de IA fornecidas pela Transloadit.
O que inteligência documental realmente significa
Um fluxo de trabalho com documentos pode analisar texto, separar páginas e extrair campos estruturados. Essas são operações distintas: a aplicação deste exemplo envia PDFs diretamente para /ai/chat e converte arquivos DOCX em PDF primeiro. Ela não executa OCR nem divide documentos em blocos.
O resultado é um ponto de partida para revisão ou indexação, e não uma prova de que todos os fatos foram extraídos corretamente. Seu esquema descreve informações extraídas do documento, não totais de faturas, itens discriminados ou pontuações de confiança.
Configuração do seu projeto TypeScript
Siga as instruções de instalação e acesso da aplicação em um diretório vazio e independente, fora de um projeto Node.js ou workspace Yarn existente. Não é necessário um checkout privado nem baixar arquivos de teste; você fornece seu próprio PDF ou DOCX. Os exemplos de shell usam Bash.
A combinação testada é Node.js 26.12.1, Yarn
4.12.0 via Corepack, @transloadit/node 4.14.0, zod 3.25.76 e zod-to-json-schema 3.25.2.
Essas versões são fixadas para reproduzir o exemplo, sem afirmar que sejam as mais recentes.
O Node 26 é uma linha de versões com manutenção ativa;
considere as atualizações de segurança ao adaptar o exemplo. O Corepack é um pré-requisito
separado no Node 26: siga suas instruções de instalação
se corepack não estiver disponível. Você também precisa do cURL para os downloads.
O README instala os pacotes nas versões fixadas e baixa ambos os arquivos: document-intelligence-pipeline/run.ts
e shared/runtime.ts. Mantenha esses diretórios lado a lado, pois o programa importa
../shared/runtime.ts. O comando final --help deve funcionar antes de você fornecer qualquer credencial.
Se a configuração falhar, inspecione o diretório parcial antes de tentar novamente: a criação
inicial de package.json se recusa a sobrescrever um arquivo. Não a repita sobre uma aplicação existente.
Configure TRANSLOADIT_AUTH_KEY e TRANSLOADIT_AUTH_SECRET no shell que executa a aplicação,
conforme mostrado no README. Essas variáveis autenticam seu Workspace da Transloadit. Mantenha-as
fora do controle de versão e do código do navegador. O programa lê variáveis de ambiente do
processo e não carrega um arquivo de ambiente.
O acesso à IA é uma escolha separada. Defina TRANSLOADIT_AI_CREDENTIALS com o nome de uma credencial
de IA existente que contenha uma chave da Anthropic ou passe explicitamente --test-credentials
para usar chaves de teste fornecidas pela Transloadit, com cobrança. Selecione um modo. O programa
não cria nem altera credenciais; consulte a documentação de /ai/chat
para saber mais sobre acesso ao provedor e cobrança.
Etapa 1: análise de documentos com OCR (opcional)
O Robot
/document/ocr é útil quando seu fluxo de trabalho separado
precisa de texto reconhecido ou informações de layout de um PDF. Esta aplicação usa, em vez disso,
o suporte à entrada de PDF de anthropic/claude-sonnet-4-6, selecionado explicitamente no Step de extração.
Para entradas DOCX, o Robot /document/convert produz o PDF enviado ao modelo. Conversão e OCR têm finalidades diferentes; adicionar um Step de OCR exigiria decidir como usar sua saída no seu próprio fluxo de extração.
Etapa 2: divisão de documentos
O Robot /document/split pode selecionar páginas para outro fluxo de trabalho. O exemplo abaixo processa um arquivo inteiro. Dividir um contrato em requisições independentes pode causar a perda de definições ou termos de outras páginas, então não presuma que combinar respostas por página reproduza o significado de um documento inteiro.
Etapa 3: extração de dados com IA orientada por esquema
A aplicação exporta example e documentInsightsSchema. Reutilize essas exportações ao
inspecionar ou adaptar a aplicação, em vez de manter uma segunda cópia da configuração de processamento ou do
esquema. O Step de extração usa format: 'json', um JSON Schema serializado, e
result: true para disponibilizar o arquivo de resposta.
title e summary são strings obrigatórias. Os campos opcionais são
author, publication_date, document_type, key_topics e key_points.
O tipo de documento, quando presente, é um dos seguintes: whitepaper,
report, contract, invoice, receipt, statement ou manual.
Um campo opcional pode ser omitido; uma string obrigatória ainda pode estar vazia ou conter
informações factualmente incorretas. A validação do esquema verifica a estrutura, não a veracidade.
Criação de um pipeline completo
Coloque um documento em document.pdf no diretório do seu projeto ou altere
--input para o caminho real do documento. Escolha um caminho de saída com permissão de escrita
que ainda não exista. Com a autenticação do Workspace já configurada e TRANSLOADIT_AI_CREDENTIALS não definida,
este comando autoriza o processamento cobrado com chaves de teste:
node document-intelligence-pipeline/run.ts --input ./document.pdf --output ./result.json --test-credentials
Para usar uma credencial de IA da Anthropic existente, defina TRANSLOADIT_AI_CREDENTIALS conforme descrito acima e
omita --test-credentials. O executor aceita uma entrada não vazia de no máximo 20 MiB e baixa no
máximo 20 MiB de saída. Esses são limites do tutorial. Ele permite cinco minutos para a Assembly
e um período separado de 30 segundos para baixar o resultado; os limites do provedor ainda podem
impedir o processamento de um arquivo que esteja dentro do limite de tamanho local.
Em caso de sucesso, o terminal imprime Saved seguido do caminho de saída.
A entrada permanece inalterada, e result.json é um arquivo local, não uma URL temporária de resultado.
Uma saída existente é recusada antes do envio de uma Assembly. Para reexecuções sequenciais, use
outro destino; não exclua seu resultado anterior apenas para repetir um comando.
Salve este script de inspeção como inspect.ts ao lado de package.json. Ele lê a saída salva
usando o mesmo esquema exportado, rejeita texto obrigatório em branco e imprime os dois campos
que você deve 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
Confira nomes, datas, quantidades e as principais afirmações do resumo com sua fonte. Um relatório sobre o conserto de 12 bicicletas com $240 em peças de reposição não pode virar um resumo sobre a venda de bicicletas ou um gasto de $24. O script de inspeção não pode fazer essa avaliação factual por você. Revise também os campos opcionais no JSON e mantenha os resultados sensíveis privados.
Se uma execução falhar após imprimir um Assembly ID, inspecione essa Assembly no Console antes de tentar novamente. Um tempo limite excedido ou uma interrupção não comprova que o processamento remoto parou, e uma execução com falha ainda pode ser cobrada. O executor desativa as novas tentativas do SDK e remove sua saída local incompleta após uma falha capturada; ele não pode garantir a limpeza após um encerramento forçado. Inspecione qualquer arquivo restante antes de escolher um novo destino.
Processamento de vários tipos de documento
O executor aceita nomes de arquivo .pdf e .docx, inclusive com extensões em
maiúsculas. O Robot /file/filter
encaminha arquivos com o tipo MIME de PDF diretamente para a extração; o outro ramo converte para
PDF primeiro. Isso não faz de todo formato diferente de PDF uma entrada aceita por esta CLI.
Renomear um arquivo danificado não repara seu conteúdo, e uma conversão bem-sucedida não comprova
que o resumo seja preciso.
Decida o que adicionar além do exemplo local
Execute os documentos sequencialmente com nomes de arquivo de saída distintos enquanto avalia os resultados e os custos. Esta CLI não tem agendador de lotes, fila de revisão nem exportação para armazenamento em nuvem. Antes de processar uma coleção, consulte os preços atuais e a documentação dos Robots.
Os Templates podem tornar reutilizável um conjunto adaptado de Assembly Instructions. Eles não são necessários para esta execução local. Salvar a configuração de processamento em um Template ou adicionar armazenamento não fornece, por si só, revisão humana, controles de acesso para sua aplicação ou uma política de extração confiável.
Quando usar esta abordagem
Esta abordagem é útil quando você quer controlar os Steps de conversão e extração em um fluxo de trabalho com arquivos e pode desenvolver a aplicação ao redor deles. Compare um produto de IA específico para documentos usando seus próprios documentos se precisar de uma experiência de revisão pronta para uso ou de qualidade de extração medida. Este pequeno exemplo não comprova paridade de recursos nem que a aplicação esteja pronta para produção.
Tudo pronto para criar?
Comece pelo README da aplicação e por um documento sem dados sensíveis cujo conteúdo você conheça. Mantenha o JSON salvo junto da fonte para revisão e use a documentação dos Robots de IA para planejar quaisquer alterações no fluxo de extração.