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

apps/docs/pt-BR/tools/pdf/ocr-pdf.md

@@ -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.