Como o OCR lê um PDF digitalizado, e por que esta ferramenta devolve Markdown

Um PDF digitalizado guarda as páginas como imagens raster: fotografias de texto, não caracteres selecionáveis. O OCR (reconhecimento óptico de caracteres) examina esses pixels, estima quais formas são caracteres e emite texto de verdade. No PDF123 isso roda como ferramenta gratuita no navegador e como POST /api/v1/misc/ocr-pdf; a resposta é Markdown, não um PDF reescrito.

A digitalização continua sendo uma imagem

O OCR não limpa, não deixa mais nítido nem substitui o bitmap. Uma digitalização nítida que o OCR lê errado continua parecendo nítida. O gargalo nunca foi a imagem, foi o reconhecimento. Trocar o motor de reconhecimento no mesmo lote de digitalizações pode mudar bastante a precisão, mesmo com os pixels em si intocados.

O OCR clássico em PDF grava uma segunda camada de texto, invisível, alinhada sob a imagem, para que selecionar e buscar cheguem às palavras certas. É o que o diagrama mostra, e é assim que muitas ferramentas de desktop ainda funcionam.

O que este endpoint devolve de verdade

A rota OCR chama /api/v1/misc/ocr-pdf, que roda sobre um crate Rust independente, o pdf-inspector (compilado com o recurso ocr). Ele não entrega o PDF inteiro para um modelo de reconhecimento. O pdf-inspector primeiro classifica cada página como já tendo texto nativo extraível ou sendo só imagem. Páginas com texto nativo mantêm esse texto como está e nunca chegam a tocar o modelo de reconhecimento; páginas só de imagem passam pelo pipeline de reconhecimento: o PDFium (o mesmo renderizador de código aberto que o Chrome usa internamente) rasteriza a página, e o ONNX Runtime executa o modelo PP-OCRv6 Small para lê-la. Os dois tipos de página são então costurados em ordem num único documento Markdown, por isso a resposta é text/markdown e o download termina em .md.

Esse contrato é novo nesta reescrita. O backend em Java/Spring Boot que este projeto usava antes chamava o OCRmyPDF, a abordagem clássica de "imagem mais camada de texto oculta", e devolvia um PDF. A reescrita em Rust substituiu esse caminho por completo pelo OCR seletivo do pdf-inspector, e a saída passou de PDF para Markdown junto com essa mudança. O antigo backend em Java já foi removido do repositório; não é uma opção que se possa reativar.

Se você precisa de um PDF pesquisável (imagem mais camada de texto), esta não é a saída certa. Se você precisa de texto que um agente ou um pipeline consiga ler, o Markdown é justamente o ponto.

Auto e Force OCR

O formulário tem um campo ocrType:

• Normal (qualquer valor diferente de force-ocr) corresponde ao modo Auto: reaproveita o texto onde o arquivo já tem e roda OCR nas páginas que são só imagem. Num PDF nativo digital limpo, o Auto não chega a carregar o runtime de OCR.
• Force OCR (ocrType=force-ocr) refaz o reconhecimento em todas as páginas, inclusive nas que já têm camada de texto. Em páginas genuinamente só de imagem, você paga tempo sem ganhar precisão; em troca, recebe uma leitura que ignora uma camada existente quebrada ou incompleta.

O padrão do portal é Force OCR. Não existe controle de idioma: códigos tessdata que sobraram do antigo caminho em Java são ignorados.

A divisão entre Auto e Force acontece dentro da própria requisição, e nem o portal nem a sonda de capacidades da API verificam isso de antemão. GET /api/v1/settings/get-endpoints-status sempre reporta ocr-pdf como habilitado, sem checar de fato se o PDFium, o ONNX Runtime ou o modelo PP-OCRv6 estão instalados. A checagem real só acontece no momento em que uma requisição dispara o reconhecimento: se algum deles estiver faltando, o endpoint devolve 503, em vez de um Markdown degradado que caia silenciosamente para apenas o texto nativo. O modelo PP-OCRv6 Small tem cerca de 31 MB; a menos que tenha sido pré-carregado no cache local no momento do deploy, ele é baixado pela rede na primeira vez que uma página realmente precisa de reconhecimento. Uma máquina offline sem o modelo pré-carregado provavelmente vai falhar bem ali, na primeira requisição Force, em vez de simplesmente rodar mais devagar.

O reconhecimento é probabilístico

Os motores comparam padrões de pixel com modelos de letras e palavras. Vão bem em impressão limpa, de alto contraste e fonte padrão, e vão pior em:

• Digitalizações de baixa resolução ou baixo contraste (qualidade de fax contra um original a 300 DPI)
• Manuscrito, fontes decorativas e diagramações incomuns (tabelas de várias colunas, texto girado, formulários densos)
• Páginas tortas, que deformam os glifos o suficiente para confundir a comparação

Um fax borrado não sai do OCR como uma digitalização limpa, use Auto ou Force. Isso é uma limitação do próprio modelo, não algo que um parâmetro consiga corrigir.

O que o OCR não faz

O OCR entrega texto. Ele não remonta parágrafos, títulos, tabelas nem um documento Word refluível. Layout editável é um problema de conversão que se soma ao erro de reconhecimento, e não o mesmo trabalho de ler uma digitalização.

Fazer OCR de um PDF roda no servidor, sem conta. O download é Markdown. Se uma camada de texto existente parecer errada, use Force OCR para que o modo Auto não confie nela; para checar se uma determinada máquina realmente tem o PDFium e o modelo instalados, rodar uma requisição de verdade é mais confiável do que confiar no status da sonda de capacidades, já que ela só confirma que o endpoint existe, não que o runtime dele está pronto. Para chaves de automação e OpenAPI, veja Desenvolvedores.