fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable * fix: harden OCR installation portability * fix: pin OCR partials across downloads * fix: make OCR execution reliably asynchronous * fix: harden OCR portability and docs routes * fix: preserve decoder and docs safeguards
2026-08-03 07:46:42 +02:00 · 2026-07-15 03:34:24 +08:00
parent 58121f205f
commit 991c981529
409 changed files with 67151 additions and 8076 deletions
@@ -1,31 +1,39 @@
 ---
-description: "Extraia texto de imagens usando reconhecimento óptico de caracteres com IA."
-i18n_source_hash: 3d85d423b82c
+description: "Extraia texto de imagens localmente com Tesseract integrado ou o tempo de execução opcional de alta precisão RapidOCR."
+i18n_output_hash: 89cc41919a60
+i18n_source_hash: 0d453b49db02
 i18n_provenance: human
-i18n_output_hash: 6c013ab29044
 ---

 # OCR / Extração de Texto {#ocr-text-extraction}

-Extraia texto de imagens usando reconhecimento óptico de caracteres com IA. Suporta vários idiomas e níveis de qualidade.
+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.

+
+<!-- korean-ocr-contract:start -->
+::: 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`.
+:::
+<!-- korean-ocr-contract:end -->
 ## Endpoint da API {#api-endpoint}

 `POST /api/v1/tools/image/ocr`

-**Processamento:** Resposta JSON síncrona. Se `clientJobId` for fornecido, o progresso também é reportado via SSE.
+**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 de modelo:** `ocr` (5-6 GB)
+**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 {#parameters}

 | Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
 |-----------|------|----------|---------|-------------|
-| file | file | Sim | - | Arquivo de imagem (multipart) |
-| quality | string | Não | `"balanced"` | Nível de qualidade: `fast` (Tesseract), `balanced` (PaddleOCR v5), `best` (PaddleOCR VL) |
+| 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 | `true` | Pré-processar a imagem para melhor precisão do OCR |
-| engine | string | Não | - | Obsoleto. Use `quality` em vez disso. Mapeia `tesseract` para `fast`, `paddleocr` para `balanced` |
+| 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 {#example-request}

@@ -35,31 +43,55 @@ curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
  -F 'settings={"quality":"best","language":"en","enhance":true}'
 ```

-## Resposta (200 OK) {#response-200-ok}
+## Resposta aceita (202) {#accepted-response-202}

 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "filename": "document.png",
-  "text": "Extracted text content from the image...",
-  "engine": "paddleocr-vl"
+  "async": true
 }
 ```

-### Progresso (SSE, opcional) {#progress-sse-optional}
+### Progresso e resultado (SSE) {#progress-sse-optional}

-Se um campo de formulário `clientJobId` for fornecido, os eventos de progresso são transmitidos:
+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`:

+```json
+{
+  "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"
+  }
+}
 ```
-event: progress
-data: {"phase":"processing","stage":"Recognizing text...","percent":50}
-```
+
+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 {#notes}

- Requer que o pacote de modelo `ocr` esteja instalado (5-6 GB).
- O OCR retorna o texto extraído diretamente, em vez de uma URL de download da imagem.
- Usa uma cadeia de fallback: se um nível de qualidade superior falhar (por exemplo, um segfault do PaddleOCR), ele tenta automaticamente o próximo nível inferior.
- Se um nível retornar texto vazio sem falhar, ele também recorre ao próximo nível.
- Os níveis de qualidade mapeiam para os engines: `fast` = Tesseract, `balanced` = PaddleOCR v5, `best` = PaddleOCR VL.
+- `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.
@@ -1,14 +1,20 @@
 ---
-description: "Extraia texto de documentos PDF usando OCR com tecnologia de IA."
-i18n_source_hash: 1431fcba180b
+description: "Extraia texto de PDFs digitalizados localmente com Tesseract integrado ou o tempo de execução opcional de alta precisão RapidOCR."
+i18n_output_hash: fb4274f84c52
+i18n_source_hash: a19ba25a1ca8
 i18n_provenance: human
-i18n_output_hash: 42ac624970b5
 ---

 # PDF OCR {#pdf-ocr}

-Extraia texto de documentos PDF usando reconhecimento óptico de caracteres com tecnologia de IA. Oferece suporte a vários níveis de qualidade e idiomas. Requer que o pacote de recurso OCR esteja instalado.
+Extraia texto de documentos PDF digitalizados página por página sem enviar o PDF 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.

+
+<!-- korean-ocr-contract:start -->
+::: 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`.
+:::
+<!-- korean-ocr-contract:end -->
 ## API Endpoint {#api-endpoint}

 `POST /api/v1/tools/pdf/ocr-pdf`
@@ -19,9 +25,14 @@ Aceita dados de formulário multipart com um arquivo PDF e um campo JSON `settin

 | Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
 |-----------|------|----------|---------|-------------|
-| quality | string | Não | `"balanced"` | Nível de qualidade do OCR: `fast`, `balanced`, `best` |
+| file | file | Sim | - | Arquivo PDF (multipart), codificado até 512 MiB; um limite inferior de upload do operador ainda se aplica |
+| quality | string | Não | Dinâmico | Nível de qualidade OCR: `fast`, `balanced` ou `best` |
 | language | string | Não | `"auto"` | Idioma do documento: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | pages | string | Não | `"all"` | Seleção de páginas, por exemplo `"all"`, `"1-3"`, `"1,3,5"` |
+| 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.

 ## Example Request {#example-request}

@@ -29,7 +40,7 @@ Aceita dados de formulário multipart com um arquivo PDF e um campo JSON `settin
 curl -X POST http://localhost:1349/api/v1/tools/pdf/ocr-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@scanned.pdf" \
-  -F 'settings={"quality": "best", "language": "en", "pages": "1-5"}'
+  -F 'settings={"quality": "best", "language": "en", "pages": "1-5", "enhance": true}'
 ```

 ## Example Response {#example-response}
@@ -46,8 +57,11 @@ Retorna `202 Accepted`. Acompanhe o progresso via SSE em `/api/v1/jobs/{jobId}/p
 ## Notes {#notes}

 - Formato de entrada aceito: `.pdf`.
- Esta é uma ferramenta de IA que requer que o **pacote de recurso OCR** esteja instalado. Se o pacote não estiver instalado, a API retorna `501 Not Implemented`.
- O nível de qualidade `fast` usa um modelo mais leve para processamento mais rápido; `best` usa um modelo mais preciso ao custo de velocidade.
- A configuração de idioma `auto` tenta detectar o idioma do documento automaticamente.
+- `fast` está integrado e adiciona cerca de 25 MiB à imagem oficial. `balanced` e `best` requerem o pacote OCR preciso opcional (cerca de 208-234 MiB para download e 409-488 MiB instalados, dependendo do destino).
+- O pacote preciso suporta Linux amd64 e arm64 e usa ONNX Runtime em CPU, inclusive em hosts NVIDIA.
+- Um nível solicitado explicitamente nunca sofre downgrade silenciosamente. Se `balanced` ou `best` não estiver disponível, API retornará `501` com `FEATURE_NOT_INSTALLED` ou `FEATURE_INCOMPATIBLE`.
+- As páginas PDF são rasterizadas em alta resolução antes de OCR. `best` executa os modelos PP-OCRv6 médios de maior precisão e pontua variantes de orientação e aprimoramento, melhorando o reconhecimento ao custo da velocidade.
+- A configuração de idioma `auto` permite o reconhecimento em todo o conjunto de scripts suportados; uma dica explícita pode melhorar os resultados para um idioma de documento conhecido.
 - Você pode direcionar páginas específicas usando intervalos (`"1-3"`), listas separadas por vírgula (`"1,3,5"`) ou `"all"` para todas as páginas.
+- Uma solicitação pode processar no máximo 50 páginas. Os dados rasterizados rasterizados são limitados a 512 MiB e a resposta agregada UTF-8 OCR é limitada a 1.000.000 bytes; trabalhos acima do limite falham em vez de retornar texto parcial.
 - Para PDFs que já contêm texto selecionável, considere usar a ferramenta [PDF to Text](./pdf-to-text), que é mais rápida.