OCR com modelo de visão do lado do servidor para documentos escaneados

Por que os documentos escaneados quebram a extração de texto

Peça a um extrator de texto para ler um PDF escaneado e você obterá quase nada. Um PDF produzido por um processador de texto carrega uma camada de texto - os caracteres são armazenados como texto, e a extração é trivial. Um PDF produzido por um scanner é, em vez disso, um envelope de imagens de página: não há camada de texto, apenas pixels. O parser do collector só consegue extrair o que realmente existe, então as páginas de apenas imagem voltam vazias ou quase, e um documento que num visualizador parece perfeitamente legível não contribui em nada para a base de conhecimento.

O Simmetric Chat trata isso do lado do servidor, antes que um documento alcance a fase de chunking e embedding. Quando a ingestão detecta um PDF pobre em texto, a plataforma o encaminha para um pipeline de OCR dedicado cujo motor não é uma biblioteca de OCR clássica de reconhecimento de padrões, mas um modelo de linguagem com capacidades de visão servido localmente via Ollama. O resultado é Markdown extraído que preserva títulos, listas e estrutura de tabelas muito melhor que um OCR em nível de caractere - e tudo roda inteiramente na sua infraestrutura. Nenhum documento jamais deixa a rede para ser lido.

Este artigo descreve como o pipeline funciona, quais controles ele expõe e a etapa de aprovação humana que impede um modelo que lê mal de poluir silenciosamente uma base de conhecimento.

Dos pixels ao Markdown: o pipeline

O OCR no Simmetric Chat é um pipeline do lado do servidor baseado em jobs. Um upload cujo texto extraído não passa do precheck - por padrão, menos de cerca de 200 caracteres extraíveis marcam um documento como escaneado - vira um job de OCR, e um agendador de polling retoma os jobs a cada 10 segundos com um limite de concorrência global, para que um lote de uploads não possa saturar a máquina. Um único documento atravessa então cinco fases:

1. Carregamento. pdfjs-dist abre o PDF do lado do servidor e enumera as páginas, com um teto de 50 páginas por job como limite de segurança contra processamentos fora de controle.
2. Renderização. Cada página é renderizada numa imagem PNG em escala ampliada - 2x por padrão - para que até a letra miúda de um escaneamento com qualidade de fax chegue ao modelo com resolução legível.
3. Reconhecimento. Cada imagem de página é enviada ao modelo de visão do Ollama configurado como imagem base64, e o modelo transcreve a página como texto Markdown.
4. Proteção. A transcrição bruta atravessa uma guarda anti-alucinação e uma etapa de limpeza de grounding. Modelos de visão às vezes anotam a saída com marcadores de grounding, ou inventam conteúdo plausível quando uma página é realmente ilegível - ambos os casos são interceptados aqui em vez de salvos.
5. Pontuação e montagem. Cada página recebe uma pontuação de qualidade, as páginas são concatenadas num único documento, e o job se conclui com um resumo honesto: as páginas falhas são contadas e reportadas como páginas falhas, nunca absorvidas em silêncio num resultado "concluído" limpo.

Cada passo desta lista acontece no servidor. O navegador nunca executa o OCR, e nenhuma API de OCR de terceiros é chamada - o único salto de rede vai do seu servidor à sua instância do Ollama.

Escolha do modelo

O modelo de visão é configurável, e o pipeline inclui um pequeno registry de modelos que sabe dialogar com cada família suportada:

• glm-ocr - o padrão (OCR_MODEL=glm-ocr:latest), um modelo de visão especializado em OCR. O registry o encaminha pelo endpoint chat do Ollama, que para essa família de modelos detecta o fim da transcrição de forma mais confiável.
• deepseek-ocr - uma segunda família otimizada para OCR que usa tokens de grounding; o registry envia a ela imagens de página única e remove os marcadores de grounding durante a limpeza.
• Qualquer modelo de visão genérico - os modelos que o registry não reconhece recuam para um prompt genérico pelo endpoint generate do Ollama, então até um modelo multimodal que você já executa localmente funciona.

Os parâmetros ligados ao modelo são variáveis de ambiente, documentadas junto com o resto da superfície de configuração:

# OCR vision do lado do servidor
OCR_MODEL=glm-ocr:latest   # modelo de visão (suporta model:version)
OCR_TIMEOUT=600000         # 10 minutos - modelos de visão são lentos
OCR_NUM_PREDICT=8192       # tokens máximos de saída por página

Um endpoint de prewarm permite a um administrador carregar o modelo em memória antes do primeiro job, para que o primeiro upload escaneado do dia não pague o custo de inicialização a frio do modelo.

O humano no ciclo: aprovar ou rejeitar

A qualidade da transcrição varia com a qualidade do escaneamento, e uma base de conhecimento é o lugar errado para descobrir que um modelo leu mal uma página. Por isso o pipeline trata a saída do OCR como rascunho, não como fato. Cada job produz um artefato revisável: a prévia mantém o texto extraído vinculado à mesma porção de página do painel com a imagem, para que um revisor possa verificar qualquer página comparando-a com o escaneamento de onde veio.

No painel de configurações de OCR um administrador vê o catálogo de modelos, a lista de jobs com pontuações de qualidade e credibilidade por página, e o próprio fluxo de trabalho:

• Aprovar - as páginas extraídas são aceitas e prosseguem: um job de arquivo aprovado materializa as páginas na base de conhecimento, e a partir do resultado aprovado pode ser iniciada uma execução de síntese.
• Rejeitar - a saída é descartada e a decisão fica registrada no job.

A automação está disponível sem abrir mão do portão. Um hook de auto-aprovação guiado por eventos pode finalizar os jobs cujos sinais de qualidade estão limpos, e preserva deliberadamente o fluxo de aprovação manual em todos os lugares onde a decisão humana é o contrato - uma importação explicitamente encaminhada para uma base de conhecimento nunca é auto-aprovada em silêncio. Em qualquer caso, os resumos de jobs permanecem honestos sobre a saúde das páginas: um job concluído com três páginas falhas declara isso no seu resultado e nos logs.

O sentido do ceremonial é um único invariante: o texto entra no seu índice RAG apenas após uma passagem de qualidade limpa ou após ter sido examinado por um humano.

Para onde vai o texto extraído

A saída de OCR aprovada retorna ao fluxo normal de ingestão. Para os documentos enviados, o Markdown extraído substitui a camada de texto que faltava no escaneamento, e o documento prossegue com chunking, embedding e indexação para a busca híbrida exatamente como um PDF nativo. Para os archives, as páginas aprovadas passam a fazer parte da base de conhecimento curada do workspace, onde wikilinks, backlinks e o pipeline de síntese podem operar sobre elas como sobre qualquer outra página.

Como o pipeline é do lado do servidor, ele se compõe com as garantias do resto da plataforma: os filtros DLP continuam escaneando os conteúdos antes que saiam da rede, o RBAC continua decidindo quem pode iniciar jobs e aprovar resultados, e nenhum ponto do percurso de OCR exige uma conexão de saída para um serviço de OCR na nuvem.

Ajustes práticos

A maioria das implantações requer apenas três decisões:

• Habilitá-lo. OCR_ENABLED e OCR_PRECHECK_CHARS - o limiar de caracteres que encaminha um PDF para o pipeline - são gerenciados nas configurações de administração.
• Escolher o modelo. glm-ocr:latest é um padrão sensato; o catálogo de modelos lista o que o registry reconhece, a escolha de modelo por job está disponível no painel de configurações, e instruções personalizadas podem afinar o comportamento de transcrição para o seu domínio documental.
• Orçar o tempo. O OCR de visão troca velocidade por fidelidade. O timeout padrão de 10 minutos e o teto de 50 páginas existem para que um escaneamento patológico degrade num fracasso visível em vez de num worker travado.

Se o seu corpus é feito sobretudo de PDFs nativos, você raramente notará o pipeline: camadas de texto saudáveis ignoram completamente o OCR. No momento em que chega um documento escaneado, ele passa por renderização, modelo de visão e sua aprovação - e termina pesquisável em vez de invisível.

Leia o guia completo na documentação →