SnapOtter/apps/docs/pt-BR/tools/image/ocr.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
Extraia texto de imagens localmente com Tesseract integrado ou o tempo de execução opcional de alta precisão RapidOCR.	89cc41919a60	0d453b49db02	human

OCR / Extração de Texto

Extraia texto de imagens sem enviar a imagem para um serviço externo. A camada fast integrada usa Tesseract. As camadas opcionais balanced e best usam RapidOCR com modelos PP-OCR ONNX fixados.

::: info Compatibilidade do OCR em coreano O OCR rápido oferece suporte a auto, en, de, es, fr, zh e ja, mas não a coreano (ko). Coreano exige o pacote de OCR preciso e balanced ou best. O pacote funciona nos contêineres oficiais Linux amd64 e arm64, inclusive em hosts NVIDIA, onde o OCR continua na CPU. Sistemas não compatíveis recebem um erro explícito e nunca retornam silenciosamente para fast. Coreano com fast ou com o alias legado tesseract é rejeitado antes da fila com FEATURE_INCOMPATIBLE e fast-korean-unsupported. :::

Endpoint da API

POST /api/v1/tools/image/ocr

Processamento: O OCR é sempre assíncrono. Após a validação e o enfileiramento, o endpoint retorna imediatamente 202 Accepted com um jobId. Acompanhe o fluxo de progresso SSE da tarefa até o evento terminal complete ou failed; o result de um evento bem-sucedido contém os campos de OCR.

Pacote OCR preciso: Tempo de execução ocr opcional (cerca de 208-234 MiB para download e 409-488 MiB instalados, dependendo do destino). fast não requer este pacote; o instalador verifica os tamanhos exatos vinculados ao índice assinado.

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
file	file	Sim	-	Arquivo de imagem (multipart), até 512 MiB codificados e 40 megapixels decodificados; um limite inferior de upload do operador ainda se aplica
quality	string	Não	Dinâmico	Nível de qualidade: fast (Tesseract), balanced (RapidOCR com os modelos PP-OCRv6 pequenos) ou best (os modelos PP-OCRv6 médios de maior precisão com pontuação de variante calibrada)
language	string	Não	"auto"	Sugestão de idioma: auto, en, de, fr, es, zh, ja, ko
enhance	boolean	Não	Dependente do nível	Melhore o contraste local antes do reconhecimento. Fast aplica-o diretamente; Balanceado e Melhor retêm a variante somente quando a pontuação calibrada melhora o resultado. O padrão é true para best e false para fast/balanced
engine	string	Não	-	Alias ​​de compatibilidade obsoleta. Use quality. tesseract mapeia para fast; o valor legado paddleocr é mapeado para balanced, mas não carrega PaddlePaddle

Quando quality e engine são omitidos, o SnapOtter escolhe o melhor nível disponível nesta ordem: best, balanced, fast. Para coreano, fast nunca é escolhido; usa-se best, depois balanced, ou é retornado o erro de instalação ou compatibilidade do runtime preciso.

Exemplo de Requisição

curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
  -F "file=@document.png" \
  -F 'settings={"quality":"best","language":"en","enhance":true}'

Resposta aceita (202)

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

Progresso e resultado (SSE)

Conecte-se a GET /api/v1/jobs/{jobId}/progress com o jobId retornado pela resposta 202 (ou o clientJobId fornecido). Mantenha o fluxo aberto até o evento terminal complete ou failed. Um frame terminal bem-sucedido contém a saída do OCR em result:

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "single",
  "phase": "complete",
  "stage": "complete",
  "percent": 100,
  "result": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/document_ocr.txt",
    "originalSize": 12345,
    "processedSize": 47,
    "text": "Extracted text content from the image...",
    "engine": "rapidocr-onnx",
    "requestedQuality": "best",
    "actualQuality": "best",
    "device": "cpu",
    "provider": "CPUExecutionProvider",
    "degraded": false,
    "warnings": [],
    "runtimeVersion": "2.1.0",
    "modelVersion": "PP-OCRv6-best-v1-medium"
  }
}

As falhas de processamento chegam no campo error do evento terminal failed; elas não são retornadas como HTTP 422 após o enfileiramento.

Notas

• fast está sempre disponível em imagens SnapOtter suportadas. balanced e best requerem o pacote OCR preciso opcional.
• Tesseract integrado adiciona cerca de 25 MiB à imagem oficial. O pacote exato é armazenado em /data/ai, e não incorporado à imagem.
• O pacote exato é publicado para os contêineres oficiais Linux amd64 e arm64. Ele usa deliberadamente o provedor CPU de ONNX Runtime, inclusive em hosts NVIDIA, portanto, não depende de bibliotecas CUDA ou de compatibilidade com GPU. As instalações originais e pré-construídas do bare-metal usam o Fast OCR, a menos que forneçam seu próprio tempo de execução compatível.
• O result terminal bem-sucedido inclui o texto extraído em text e um artefato .txt para download em downloadUrl.
• SnapOtter respeita um nível solicitado explicitamente. Se balanced ou best não estiver disponível, API retornará 501 com FEATURE_NOT_INSTALLED ou FEATURE_INCOMPATIBLE; ele nunca faz downgrade silenciosamente da solicitação para outro nível.
• Um resultado vazio bem-sucedido permanece um resultado vazio. As falhas de tempo de execução retornam um erro em vez de tentar novamente com um mecanismo de qualidade inferior.
• O result terminal bem-sucedido relata requestedQuality e actualQuality, além do mecanismo, dispositivo, provedor, tempo de execução e versões do modelo, e quaisquer avisos.
• Suporta os formatos de entrada HEIC/HEIF, RAW, TGA, PSD, EXR e HDR via decodificação automática.
• Entradas codificadas superdimensionadas retornam 413. Imagens com mais de 40 megapixels e respostas OCR acima de seus limites de saída limitados são rejeitadas em vez de serem parcialmente processadas.