mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
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
This commit is contained in:
SnapOtter
+41
-17
@@ -1,18 +1,26 @@
|
||||
---
|
||||
description: "Referência do motor de IA com todas as ferramentas de ML locais. Remoção de fundo, ampliação, OCR, detecção de rostos, restauração de fotos e muito mais."
|
||||
i18n_source_hash: 14728c1dcd05
|
||||
i18n_provenance: machine
|
||||
i18n_output_hash: 9c63b9ba2ca7
|
||||
i18n_output_hash: 37b479358342
|
||||
i18n_source_hash: aa9a56cdddc7
|
||||
i18n_provenance: human
|
||||
---
|
||||
|
||||
# Referência do Motor de IA {#ai-engine-reference}
|
||||
|
||||
O pacote `@snapotter/ai` conecta o Node.js a um **sidecar Python persistente** para todas as operações de ML. O processo despachante permanece ativo entre as requisições para um desempenho rápido com início a quente. O NVIDIA CUDA é detectado automaticamente na inicialização e usado quando disponível; caso contrário, as ferramentas de IA rodam na CPU.
|
||||
O pacote `@snapotter/ai` coordena ferramentas nativas e tempos de execução Python para operações ML locais. A maioria das ferramentas ML usa um Python sidecar persistente para inicializações a quente rápidas. OCR é intencionalmente separado: `fast` invoca o binário Tesseract nativo, enquanto `balanced` e `best` usam um JSONL dispatcher persistente dedicado fixado na geração RapidOCR ativa e imutável em `/data/ai/v3`. Cada solicitação contém um generation lease. Durante uma atualização, SnapOtter executa um smoke test no candidato antes da ativação, alterna atomicamente para o novo dispatcher e, em seguida, drena a geração antiga antes de garbage collection.
|
||||
|
||||
NVIDIA CUDA é detectado automaticamente e usado por tempos de execução que o suportam. OCR usa CPU em todos os hosts, incluindo sistemas com GPUs NVIDIA, evitando CUDA e acoplamento de driver para esta ferramenta.
|
||||
|
||||
A aceleração por iGPU Intel/AMD via VA-API, Quick Sync ou OpenCL não é suportada para inferência de IA hoje. Mapear `/dev/dri` em um contêiner não acelera essas ferramentas do sidecar Python a menos que uma GPU NVIDIA compatível com CUDA esteja disponível.
|
||||
|
||||
19 ferramentas de IA no sidecar Python em quatro modalidades (imagem, áudio, vídeo, documento), mais 2 ferramentas com capacidades opcionais de IA. Todos os modelos rodam localmente - nenhuma conexão com a internet é necessária após o download inicial do modelo.
|
||||
|
||||
|
||||
<!-- 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 -->
|
||||
## Arquitetura {#architecture}
|
||||
|
||||
```
|
||||
@@ -22,15 +30,17 @@ Node.js Tool Route
|
||||
@snapotter/ai bridge.ts
|
||||
| (stdin/stdout JSON + stderr progress events)
|
||||
v
|
||||
Python dispatcher (persistent process, "ai" profile)
|
||||
+-- Native Tesseract + Ghostscript (fast image/PDF OCR)
|
||||
|
|
||||
+-- Isolated OCR runtime (persistent JSONL dispatcher)
|
||||
| `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
|
||||
|
|
||||
`-- Python dispatcher (persistent process, "ai" profile)
|
||||
|
|
||||
|-- remove_bg.py (rembg / BiRefNet)
|
||||
|-- upscale.py (RealESRGAN)
|
||||
|-- inpaint.py (LaMa ONNX)
|
||||
|-- outpaint.py (LaMa canvas expansion)
|
||||
|-- ocr.py (PaddleOCR / Tesseract)
|
||||
|-- ocr_pdf.py (page-by-page document OCR)
|
||||
|-- ocr_preprocess.py (image enhancement for OCR)
|
||||
|-- detect_faces.py (MediaPipe)
|
||||
|-- face_landmarks.py (MediaPipe landmarks)
|
||||
|-- enhance_faces.py (GFPGAN / CodeFormer)
|
||||
@@ -52,7 +62,7 @@ Os modelos de IA são empacotados por pilha de dependências compartilhada, e n
|
||||
|
||||
A imagem Docker inclui a aplicação mais o runtime comum. Arquivos grandes de modelos são baixados sob demanda para o volume persistente `/data/ai`, e depois reutilizados por todas as ferramentas que precisam deles. Se um pacote já estiver instalado porque outra ferramenta precisou dele, habilitar uma nova ferramenta dependente não baixa esse pacote novamente.
|
||||
|
||||
Cada ferramenta de IA requer um ou mais pacotes de recursos antes de poder rodar. A interface de administração instala por ferramenta através de `POST /api/v1/admin/tools/:toolId/features/install`, que resolve a lista completa de pacotes, pula os pacotes já instalados e enfileira apenas os downloads que faltam. Por exemplo, habilitar Foto para Passaporte em uma instância nova enfileira `background-removal` e `face-detection`; habilitá-la depois que a Remoção de Fundo já estiver instalada enfileira apenas `face-detection`.
|
||||
A maioria das ferramentas de IA requer um ou mais pacotes de recursos antes de serem executadas. A UI administrativa os instala por ferramenta por meio do `POST /api/v1/admin/tools/:toolId/features/install`, que resolve a lista completa de pacotes, ignora os pacotes que já estão instalados e enfileira apenas os downloads ausentes. Por exemplo, ativar a foto do passaporte em uma nova instância enfileira `background-removal` e `face-detection`; habilitá-lo após a remoção de segundo plano já estar instalada enfileira apenas `face-detection`. OCR é a exceção porque `fast` não precisa de pacote; instale seu tempo de execução preciso opcional por meio da UI ou `POST /api/v1/admin/features/ocr/install`.
|
||||
|
||||
| Pacote | Tamanho | Grupo de dependências compartilhado | Ferramentas que o usam |
|
||||
|--------|------|-------------------------|-------------------|
|
||||
@@ -61,7 +71,7 @@ Cada ferramenta de IA requer um ou mais pacotes de recursos antes de poder rodar
|
||||
| `object-eraser-colorize` | 1-2 GB | inpainting/outpainting LaMa e DDColor | erase-object, colorize, ai-canvas-expand |
|
||||
| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, remoção de ruído | upscale, enhance-faces, noise-removal |
|
||||
| `photo-restoration` | 4-5 GB | reparo de arranhões e pipeline de restauração | restore-photo |
|
||||
| `ocr` | 5-6 GB | pilha de OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
|
||||
| `ocr` | ~208-234 MiB baixado / ~409-488 MiB instalado | Modelos opcionais RapidOCR 3.9.1, ONNX Runtime 1.20.1 e PP-OCR fixado | ocr, ocr-pdf (somente `balanced` e `best`) |
|
||||
| `transcription` | ~600 MB | modelos de fala para texto faster-whisper | transcribe-audio, auto-subtitles |
|
||||
|
||||
Ferramentas com dependências entre pacotes:
|
||||
@@ -71,7 +81,17 @@ Ferramentas com dependências entre pacotes:
|
||||
| `passport-photo` | `background-removal`, `face-detection` | Remove o fundo e depois usa marcos faciais para enquadrar o recorte conforme as regras de fotos de passaporte e documentos de identidade. |
|
||||
| `enhance-faces` | `upscale-enhance`, `face-detection` | Detecta rostos antes de rodar o realce GFPGAN ou CodeFormer nas regiões de rosto selecionadas. |
|
||||
|
||||
Uma ferramenta fica disponível apenas quando todos os seus pacotes necessários estão instalados. Instalações parciais são válidas e tratadas de forma incremental: pacotes instalados são reutilizados, pacotes que faltam são mostrados como downloads e as instalações enfileiradas rodam uma de cada vez para que o ambiente Python compartilhado não seja modificado simultaneamente.
|
||||
Uma ferramenta está disponível somente quando todos os seus pacotes necessários estão instalados, exceto OCR: sua camada `fast` integrada permanece disponível sem o pacote OCR opcional. As instalações parciais são válidas e tratadas de forma incremental: os pacotes configuráveis instalados são reutilizados, os pacotes perdidos são mostrados como downloads e as instalações na fila são executadas uma de cada vez, para que o ambiente Python compartilhado não seja modificado simultaneamente.
|
||||
|
||||
### Instalação precisa do tempo de execução do OCR {#accurate-ocr-runtime-installation}
|
||||
|
||||
O pacote OCR preciso é um tempo de execução específico da plataforma para o contêiner oficial Linux amd64 ou Linux arm64. A construção amd64 usa Python 3.12; a compilação arm64 usa Python 3.11. Ambas as compilações executam RapidOCR por meio do `CPUExecutionProvider` do ONNX Runtime, portanto, o mesmo pacote funciona apenas em hosts CPU e NVIDIA Docker. O tempo de execução preciso requer pelo menos 4 GiB de memória efetiva: o limite cgroup do contêiner configurado, caso contrário, memória do host. Um sistema abaixo do mínimo de compatibilidade assinado é rejeitado antes do download. Este requisito não se aplica ao Fast OCR integrado. As compilações Bare-metal são rejeitadas porque seus libc e Python ABI não podem ser inferidos com segurança; O OCR rápido permanece disponível quando o host fornece Tesseract e Ghostscript.
|
||||
|
||||
O artefato opcional tem cerca de 208-234 MiB compactado e 409-488 MiB extraído, dependendo da arquitetura. O índice assinado vincula as contagens exatas de bytes compactados e extraídos impostas pelo instalador. Tesseract integrado adiciona cerca de 25 MiB à imagem oficial e não precisa de arquivos em `/data/ai`.
|
||||
|
||||
A instalação online busca um índice de versão assinado e o artefato exato endereçado ao conteúdo para a plataforma atual. SnapOtter verifica a assinatura do índice Ed25519, tamanho do artefato, resumo SHA-256, resumos de modelo, caminhos, modos de arquivo e smoke test preparado antes de ativar atomicamente a nova geração. Uma instalação com falha deixa a geração íntegra anterior ativa.
|
||||
|
||||
Para instalação isolada, carregue o `ocr-runtime-index.json` da versão e o arquivo de tempo de execução OCR correspondente para `POST /api/v1/admin/features/import` usando campos multipartes chamados `index` e `archive`. A importação offline aplica as mesmas verificações de assinatura, hash, extração, compatibilidade e teste de fumaça da instalação online; um arquivo sem seu índice assinado confiável é rejeitado.
|
||||
|
||||
---
|
||||
|
||||
@@ -143,16 +163,16 @@ Desfoca o fundo mantendo o sujeito nítido.
|
||||
## OCR / Extração de Texto {#ocr-text-extraction}
|
||||
|
||||
**Rota da ferramenta:** `ocr`
|
||||
**Modelos:** Tesseract (rápido), PaddleOCR PP-OCRv5 (equilibrado), PaddleOCR-VL 1.5 (melhor)
|
||||
**Modelos:** Tesseract (`fast`); RapidOCR com modelos pequenos PP-OCRv6 (`balanced`); Modelos médios PP-OCRv6 com pontuação de variante calibrada (`best`)
|
||||
|
||||
| Parâmetro | Tipo | Padrão | Descrição |
|
||||
|-----------|------|---------|-------------|
|
||||
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Nível de processamento |
|
||||
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinâmico | 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. |
|
||||
| `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
|
||||
| `enhance` | boolean | `true` | Pré-processar a imagem para melhorar a precisão do OCR |
|
||||
| `engine` | string | - | Obsoleto. Mapeia `tesseract` para `fast`, `paddleocr` para `balanced` |
|
||||
| `enhance` | booleano | Dependente do nível | Melhore o contraste local. Fast aplica-o diretamente; níveis precisos mantêm a variante somente quando a pontuação calibrada melhora OCR. O padrão é Melhor |
|
||||
| `engine` | corda | - | Alias de compatibilidade obsoleta. Mapeia `tesseract` para `fast` e o valor herdado de `paddleocr` para `balanced`; não carrega PaddlePaddle |
|
||||
|
||||
Retorna resultados estruturados com caixas delimitadoras, pontuações de confiança e blocos de texto extraídos.
|
||||
Retorna o texto extraído mais os metadados de origem: mecanismo, qualidade solicitada e real, dispositivo, provedor, estado de degradação, avisos e versões de tempo de execução/modelo precisos, quando aplicável. Solicitações de qualidade explícitas nunca voltam para outro nível. Se `balanced` ou `best` não estiver disponível, API retornará `FEATURE_NOT_INSTALLED` ou `FEATURE_INCOMPATIBLE` em vez de executar `fast` silenciosamente.
|
||||
|
||||
## OCR de PDF {#pdf-ocr}
|
||||
|
||||
@@ -163,9 +183,13 @@ Extrai texto de documentos PDF digitalizados usando OCR com IA, página por pág
|
||||
|
||||
| Parâmetro | Tipo | Padrão | Descrição |
|
||||
|-----------|------|---------|-------------|
|
||||
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Nível de processamento |
|
||||
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinâmico | 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. |
|
||||
| `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
|
||||
| `pages` | string | `"all"` | Seleção de páginas: `"all"`, `"1-3"`, `"1,3,5"` |
|
||||
| `enhance` | booleano | Dependente do nível | Melhore o contraste local. Fast aplica-o diretamente; níveis precisos mantêm a variante somente quando a pontuação calibrada melhora OCR. O padrão é Melhor |
|
||||
| `engine` | corda | - | Alias de compatibilidade obsoleta. Mapeia `tesseract` para `fast` e o valor herdado de `paddleocr` para `balanced`; não carrega PaddlePaddle |
|
||||
|
||||
A mesma regra de não downgrade se aplica a PDF OCR. As páginas PDF são rasterizadas antes do reconhecimento e uma solicitação pode selecionar no máximo 50 páginas.
|
||||
|
||||
## Desfoque de Rosto / PII {#face-pii-blur}
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
description: "Referência completa da API REST. Endpoints de ferramentas, processamento em lote, pipelines, biblioteca de arquivos, autenticação, times e operações administrativas."
|
||||
i18n_source_hash: 8646977f7cc9
|
||||
i18n_provenance: machine
|
||||
i18n_output_hash: cf7876adfe84
|
||||
i18n_source_hash: b89b5df16af5
|
||||
i18n_provenance: human
|
||||
---
|
||||
|
||||
# Referência da API REST {#rest-api-reference}
|
||||
@@ -178,7 +178,7 @@ Todas as ferramentas de IA rodam no seu hardware: CPU por padrão ou NVIDIA CUDA
|
||||
| `remove-background` | Remover Fundo | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
|
||||
| `upscale` | Ampliação de Imagem | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
|
||||
| `erase-object` | Apagador de Objetos | LaMa (ONNX) | Máscara enviada como segunda parte de arquivo (fieldname `mask`), `format`, `quality` |
|
||||
| `ocr` | OCR / Extração de Texto | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
|
||||
| `ocr` | OCR / Extração de texto | Tesseract (rápido); RapidOCR + PP-OCR ONNX (equilibrado/melhor) | `quality` (rápido/equilibrado/melhor), `language`, `enhance` |
|
||||
| `blur-faces` | Desfoque de Rosto / PII | MediaPipe | `blurRadius`, `sensitivity` |
|
||||
| `smart-crop` | Recorte Inteligente | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
|
||||
| `image-enhancement` | Aprimoramento de Imagem | Baseado em análise | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
|
||||
@@ -425,7 +425,9 @@ Algumas ferramentas expõem endpoints adicionais além da rota padrão `POST /ap
|
||||
|
||||
## Processamento em Lote {#batch-processing}
|
||||
|
||||
Aplica uma ferramenta genérica habilitada para lote a vários arquivos de uma vez. Retorna um arquivo ZIP. Rotas personalizadas de múltiplos arquivos ou de múltiplas etapas, como assinatura de PDF, OCR de PDF e as rotas de preset de PDF para imagem, usam seu próprio contrato de endpoint em vez da rota genérica `/batch`.
|
||||
Aplica uma ferramenta genérica habilitada para lote a vários arquivos de uma vez. Retorna um arquivo ZIP. Rotas personalizadas de múltiplos arquivos ou de múltiplas etapas, como assinatura de PDF e as rotas de preset de PDF para imagem, usam seu próprio contrato de endpoint em vez da rota genérica `/batch`.
|
||||
|
||||
A ferramenta `ocr-pdf` oferece suporte a esta rota genérica `/batch`.
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
|
||||
@@ -594,6 +596,8 @@ Parâmetros de consulta:
|
||||
|
||||
Gerencia os pacotes de recursos de IA (instala/desinstala pacotes de modelos de IA no ambiente Docker). Prefira o endpoint de instalação em nível de ferramenta ao habilitar uma ferramenta a partir de automação personalizada: algumas ferramentas de IA precisam de mais de um pacote compartilhado, e este endpoint pula os pacotes já instalados enquanto enfileira apenas os que faltam.
|
||||
|
||||
OCR é um aprimoramento opcional em vez de uma dependência rígida. Seu nível `fast` Tesseract funciona sem pacote; `POST /api/v1/admin/features/ocr/install` instala o pacote RapidOCR assinado para `balanced` e `best` em Linux amd64 ou arm64. O tempo de execução OCR preciso usa CPU em hosts somente CPU e NVIDIA e requer pelo menos 4 GiB de memória efetiva (o limite cgroup do contêiner configurado, caso contrário, memória do host). SnapOtter relata `requiredMemoryBytes`, `effectiveMemoryBytes` e um motivo de compatibilidade `insufficient-memory` e rejeita uma instalação incompatível antes do download. Este requisito de memória não se aplica ao `fast`. O pacote tem cerca de 208-234 MiB para download e 409-488 MiB instalados, dependendo do destino; o índice assinado vincula os tamanhos exatos aplicados durante a instalação.
|
||||
|
||||
| Método | Caminho | Acesso | Descrição |
|
||||
|--------|------|--------|-------------|
|
||||
| `GET` | `/api/v1/features` | Autenticado | Lista todos os pacotes de recursos e seu status de instalação |
|
||||
@@ -601,7 +605,18 @@ Gerencia os pacotes de recursos de IA (instala/desinstala pacotes de modelos de
|
||||
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Instala todos os pacotes que uma ferramenta requer; retorna o status enfileirado/pulado por pacote |
|
||||
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Desinstala um pacote de recursos e limpa os arquivos de modelo |
|
||||
| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Obtém o uso total de disco dos modelos de IA |
|
||||
| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Importa um arquivo de pacote de IA offline |
|
||||
| `POST` | `/api/v1/admin/features/import` | Administrador (`features:manage`) | Importe um pacote de IA legado (`file`) ou uma versão OCR off-line assinada (`index` mais `archive`) |
|
||||
|
||||
Uma importação OCR sem comunicação deve incluir o `ocr-runtime-index.json` assinado da versão e o arquivo da plataforma correspondente. SnapOtter aplica a mesma assinatura Ed25519, hash de artefato, compatibilidade, extração e verificações de teste de fumaça usadas pela instalação online:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:1349/api/v1/admin/features/import \
|
||||
-H "Authorization: Bearer <admin-token>" \
|
||||
-F "index=@ocr-runtime-index.json" \
|
||||
-F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
|
||||
```
|
||||
|
||||
Use o arquivo `linux-arm64-cpu-py311` em arm64. Um artefato assinado para outro destino é rejeitado em vez de instalado.
|
||||
|
||||
## Operações Administrativas {#admin-operations}
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
description: "Estrutura do monorepo, arquitetura de apps e pacotes, ciclo de vida das requisições e uso de recursos do SnapOtter."
|
||||
i18n_source_hash: 9e8f80499a37
|
||||
i18n_provenance: human
|
||||
i18n_output_hash: 93555b8e15c0
|
||||
i18n_source_hash: 733cb3c10884
|
||||
i18n_provenance: human
|
||||
---
|
||||
|
||||
# Arquitetura {#architecture}
|
||||
@@ -36,13 +36,13 @@ Este pacote não tem dependências de rede e roda inteiramente em processo.
|
||||
|
||||
### `@snapotter/ai` {#snapotter-ai}
|
||||
|
||||
Uma camada de ponte que chama scripts Python para operações de ML. No primeiro uso, a ponte inicia um processo de dispatcher Python persistente que pré-importa bibliotecas pesadas (PIL, NumPy, MediaPipe, rembg) para que as chamadas de IA subsequentes dispensem o custo de importação. Se o dispatcher ainda não estiver pronto, a ponte recorre a gerar um novo subprocesso Python por requisição.
|
||||
Uma camada de ponte que chama tempos de execução nativos e Python ML. A maioria das ferramentas Python usa um dispatcher persistente que pré-importa bibliotecas pesadas (PIL, NumPy, MediaPipe, rembg) para que as chamadas subsequentes ignorem a sobrecarga de importação. OCR é isolado desse ambiente compartilhado mutável: `fast` invoca Tesseract nativo, enquanto `balanced` e `best` usam um JSONL dispatcher persistente dedicado fixado na geração RapidOCR/ONNX ativa e imutável. Cada solicitação contém um generation lease. A ativação primeiro executa um smoke test em um candidato e depois alterna atomicamente para seu dispatcher. O dispatcher anterior é drenado antes que sua geração seja coletada como lixo.
|
||||
|
||||
**Os modelos não são pré-carregados.** Cada script de ferramenta carrega os pesos do seu modelo do disco no momento da requisição e os descarta quando a requisição termina. Consulte [Uso de recursos](#resource-footprint) para o perfil de memória completo.
|
||||
|
||||
Operações suportadas: remoção de fundo (rembg/BiRefNet), upscaling (RealESRGAN), desfoque de rostos (MediaPipe), aprimoramento de rostos (GFPGAN/CodeFormer), apagamento de objetos (LaMa ONNX), OCR (PaddleOCR/Tesseract), colorização (DDColor), remoção de ruído, remoção de olhos vermelhos, restauração de fotos, geração de foto de passaporte, correção de transparência (HR-matting do BiRefNet) e redimensionamento com reconhecimento de conteúdo (binário caire em Go).
|
||||
Operações suportadas: remoção de fundo (rembg/BiRefNet), upscaling (RealESRGAN), desfoque de rosto (MediaPipe), aprimoramento de rosto (GFPGAN/CodeFormer), apagamento de objeto (LaMa ONNX), OCR (Tesseract e RapidOCR com modelos PP-OCR ONNX), colorização (DDColor), remoção de ruído, remoção de olhos vermelhos, restauração de fotos, foto de passaporte geração, correção de transparência (BiRefNet HR-matting) e redimensionamento com reconhecimento de conteúdo (Go caire binário).
|
||||
|
||||
Os scripts Python ficam em `packages/ai/python/`. A imagem Docker pré-baixa todos os pesos de modelo durante o build para que o contêiner funcione totalmente offline.
|
||||
Os scripts Python residem em `packages/ai/python/`. Grandes pacotes de modelos opcionais são instalados sob demanda no volume `/data/ai` persistente. O OCR preciso usa artefatos assinados e específicos da plataforma; a camada Tesseract integrada não requer download de pacote de modelo.
|
||||
|
||||
### `@snapotter/shared` {#snapotter-shared}
|
||||
|
||||
@@ -87,7 +87,7 @@ Este site VitePress. Implantado no Cloudflare Pages automaticamente a cada push
|
||||
2. O frontend envia um POST multipart para `/api/v1/tools/:section/:toolId` com o arquivo e as configurações.
|
||||
3. A rota da API valida a entrada com o Zod e depois despacha o processamento.
|
||||
4. Para ferramentas padrão, o job é enfileirado no pool BullMQ apropriado (image, media ou docs, conforme a modalidade). O worker BullMQ em processo orienta automaticamente a imagem com base nos metadados EXIF, executa a função de processamento da ferramenta e retorna o resultado.
|
||||
5. Para ferramentas de IA, a ponte TypeScript envia uma requisição ao dispatcher Python persistente (ou gera um novo subprocesso como fallback), aguarda a conclusão e lê o arquivo de saída.
|
||||
5. Para a maioria das ferramentas de IA, a ponte TypeScript envia uma solicitação ao Python dispatcher persistente. Em vez disso, o OCR rápido invoca Tesseract, e o OCR preciso inicia o executável fixado a partir da geração OCR imutável ativa. A camada OCR solicitada é fixada na entrada e nunca é alterada silenciosamente durante a execução.
|
||||
6. O progresso do job é persistido na tabela `jobs` no PostgreSQL, de modo que o estado sobrevive a reinícios do contêiner. As atualizações em tempo real são entregues via SSE em `/api/v1/jobs/:jobId/progress`.
|
||||
7. A API retorna um `jobId` e um `downloadUrl`. O usuário baixa o arquivo processado de `/api/v1/download/:jobId/:filename`.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
description: "Implante o SnapOtter em produção com Docker. Requisitos de hardware, configuração de GPU e configs de proxy reverso para Nginx, Traefik e Cloudflare."
|
||||
i18n_source_hash: 6b6957060fa6
|
||||
i18n_provenance: machine
|
||||
i18n_output_hash: 05bdb8a0d544
|
||||
i18n_output_hash: b3176447b423
|
||||
i18n_source_hash: e0d8d5f6fc87
|
||||
i18n_provenance: human
|
||||
---
|
||||
|
||||
# Implantação {#deployment}
|
||||
@@ -11,6 +11,12 @@ O SnapOtter é implantado como uma stack Docker Compose de 3 contêineres: a ima
|
||||
|
||||
Consulte [Imagem Docker](./docker-tags) para configuração de GPU, exemplos de Docker Compose e fixação de versão.
|
||||
|
||||
|
||||
<!-- 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 -->
|
||||
## Início Rápido (CPU) {#quick-start-cpu}
|
||||
|
||||
```yaml
|
||||
@@ -113,7 +119,7 @@ O app fica então disponível em `http://localhost:1349`.
|
||||
|
||||
## Início Rápido (NVIDIA CUDA) {#quick-start-nvidia-cuda}
|
||||
|
||||
Para aceleração NVIDIA CUDA em ferramentas de IA (remoção de fundo, upscaling, aprimoramento de rosto, OCR):
|
||||
Para aceleração NVIDIA CUDA em ferramentas de IA suportadas (remoção de fundo, aumento de escala, aprimoramento de rosto):
|
||||
|
||||
```yaml
|
||||
# docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
|
||||
@@ -251,10 +257,10 @@ deploy:
|
||||
|---|---|
|
||||
| CPU | 4 núcleos |
|
||||
| RAM | 4 GB |
|
||||
| Disco | 3 GB (imagem) + 24 GB (modelos de IA) + workspace |
|
||||
| Disk | 3 GB (imagem) + cerca de 20 GB (todos os pacotes AI opcionais) + espaço de trabalho |
|
||||
| GPU | Não obrigatória (fallback para CPU) |
|
||||
|
||||
**Instalar os bundles de IA é o que empurra a RAM para 4 GB.** Sem nenhuma IA instalada, o app fica ocioso em torno de 360 MB; com todos os sete bundles instalados, ele mantém ~2,6 GB residentes, porque o sidecar de IA em Python pré-carrega seus modelos (remoção de fundo, upscaling, OCR, transcrição, detecção de rosto, restauração) na inicialização. Instalações sem IA permanecem leves; instalações de IA precisam de ≥4 GB.
|
||||
**Instalar e executar pacotes maiores de IA é o que leva a recomendação para 4 GB de RAM.** Sem pacotes opcionais instalados, o aplicativo fica ocioso em torno de 360 MB. As ferramentas Python legadas compartilham um sidecar, enquanto o OCR preciso usa um dispatcher dedicado de longa duração fixado à geração imutável ativa. Antes da ativação, o instalador executa um smoke test no candidato. Em seguida, ele muda atomicamente para o novo dispatcher e drena o dispatcher anterior antes de garbage collection. Cada artefato oficial de OCR preciso deve passar seu pior caso release suite dentro de 4 GiB cgroup, enquanto a recomendação de host de 4 GB deixa espaço para o aplicativo Node.js, Postgres, Redis, filas e trabalho simultâneo.
|
||||
|
||||
A maioria das ferramentas de IA é perfeitamente utilizável em CPU; algumas realmente precisam de uma GPU. Medido em uma CPU moderna de 4 núcleos:
|
||||
|
||||
@@ -271,7 +277,7 @@ O SnapOtter intencionalmente não incorpora esses downloads de modelos na imagem
|
||||
|
||||
Algumas ferramentas dependem de mais de um bundle compartilhado. Por exemplo, Foto de Passaporte precisa tanto de `background-removal` quanto de `face-detection`; se `background-removal` já estiver instalado, habilitar Foto de Passaporte baixa apenas o bundle `face-detection` que faltava. A mesma reutilização se aplica a todas as ferramentas de IA.
|
||||
|
||||
Tamanhos de download dos modelos de IA:
|
||||
Estimativas opcionais de armazenamento do pacote AI:
|
||||
|
||||
| Bundle | Tamanho em Disco |
|
||||
|---|---|
|
||||
@@ -279,9 +285,16 @@ Tamanhos de download dos modelos de IA:
|
||||
| Upscale + Aprimoramento de rosto + Remoção de ruído | 5-6 GB |
|
||||
| Detecção de rosto | 200-300 MB |
|
||||
| Apagador de objetos + Colorizar | 1-2 GB |
|
||||
| OCR | 5-6 GB |
|
||||
| OCR preciso (`balanced`/`best`) | ~208-234 MiB baixado / ~409-488 MiB instalado |
|
||||
| Restauração de foto | 4-5 GB |
|
||||
| **Todos os bundles** | **~24 GB** |
|
||||
| Transcrição | ~600MB |
|
||||
| **Todos os pacotes** | **~20 GB instalados** |
|
||||
|
||||
O OCR rápido é integrado à imagem por meio do Tesseract, adiciona cerca de 25 MiB e não requer o pacote OCR opcional ou seu requisito de memória de 4 GiB. O pacote exato está disponível nos contêineres oficiais Linux amd64 e arm64 e executa ONNX Runtime em CPU. Os hosts NVIDIA usam o mesmo tempo de execução CPU OCR, portanto, OCR não depende da versão CUDA ou da arquitetura GPU. O tempo de execução preciso requer pelo menos 4 GiB de memória efetiva: o limite cgroup do contêiner configurado, caso contrário, memória do host. SnapOtter rejeita sistemas abaixo do mínimo de compatibilidade assinado antes de baixar o pacote. A instalação do pacote preciso também é rejeitada em arquivos bare-metal/pré-construídos cujos libc e Python ABI não podem ser garantidos.
|
||||
|
||||
As réplicas que compartilham o mesmo `DATA_DIR` devem usar a mesma arquitetura de CPU; fixe implantações com várias réplicas em nós compatíveis usando afinidade de nós. Réplicas amd64/arm64 mistas precisam de volumes de dados separados e implantações independentes do SnapOtter.
|
||||
|
||||
O tempo de execução preciso mantém uma geração ativa e limpa seu cache de download após a ativação. Para esta versão, uma primeira instalação precisa temporariamente de aproximadamente 620-720 MiB para o arquivo mais teste, e uma atualização pode atingir um pico próximo a 1,2 GiB enquanto a geração antiga permanece ativa. O instalador calcula o requisito exato do índice assinado e das gerações atuais antes de fazer download ou extrair e falha antecipadamente se o volume de dados for muito pequeno.
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
@@ -353,7 +366,6 @@ Consulte a [lista completa de formatos](/pt-BR/guide/supported-formats) para det
|
||||
|
||||
- **Redimensionamento consciente de conteúdo** trava em imagens grandes (>5 MP) devido a uma limitação no binário caire. Funciona bem com imagens menores.
|
||||
- **Decodificação HEIF** leva de 13 a 23 segundos. HEIC (a variante da Apple) é muito mais rápido, de 0,3 a 0,9 segundos.
|
||||
- **OCR em japonês** falha em CPU devido a um bug do MKLDNN do PaddlePaddle. Funciona em GPU.
|
||||
- **Upscale** expira em CPU para qualquer coisa além de imagens pequenas. GPU é obrigatória para uso prático.
|
||||
- O aprimoramento de rosto **CodeFormer** é significativamente mais lento que o GFPGAN (53s vs 2s em GPU). GFPGAN é recomendado para a maioria dos casos de uso.
|
||||
|
||||
@@ -434,6 +446,26 @@ O erro de inicialização nomeia o UID exato a usar, então o caminho mais rápi
|
||||
| `SESSION_DURATION_HOURS` | `168` | Tempo de vida da sessão de login (7 dias) |
|
||||
| `CORS_ORIGIN` | (vazio) | Origens permitidas separadas por vírgula, ou vazio para mesma origem |
|
||||
|
||||
### Proxy de saída e CA privada {#outbound-proxy-and-private-ca}
|
||||
|
||||
O contêiner oficial permite o suporte de proxy de ambiente do Node. Se SnapOtter precisar acessar o repositório de tempo de execução OCR ou outros serviços HTTPS por meio de um proxy corporativo, configure `HTTPS_PROXY` (e `HTTP_PROXY` quando necessário). Configure `NO_PROXY` para uma lista separada por vírgula de hosts que devem ser acessados diretamente, como Postgres, Redis e armazenamento de objeto interno.
|
||||
|
||||
Se o proxy ou um serviço interno for assinado por uma autoridade de certificação privada, monte o certificado CA somente leitura e aponte `NODE_EXTRA_CA_CERTS` para ele. O arquivo deve existir quando o processo do Node for iniciado:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
environment:
|
||||
HTTPS_PROXY: http://proxy.example.internal:3128
|
||||
HTTP_PROXY: http://proxy.example.internal:3128
|
||||
NO_PROXY: postgres,redis,minio,localhost,127.0.0.1
|
||||
NODE_EXTRA_CA_CERTS: /etc/snapotter/custom-ca.pem
|
||||
volumes:
|
||||
- ./company-ca.pem:/etc/snapotter/custom-ca.pem:ro
|
||||
```
|
||||
|
||||
Mantenha as credenciais de proxy fora do arquivo Compose (por exemplo, em um arquivo ou segredo `.env` protegido). Não desative a verificação TLS: o índice OCR assinado autentica os metadados de lançamento, enquanto a validação TLS normal ainda protege o transporte e todas as outras solicitações de saída.
|
||||
|
||||
## Verificação de Saúde {#health-check}
|
||||
|
||||
O contêiner inclui uma verificação de saúde embutida:
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
description: "Tags de imagem Docker do SnapOtter, benchmarks de GPU, fixação de versão e suporte multiplataforma para AMD64 e ARM64."
|
||||
i18n_source_hash: 148b3608e11a
|
||||
i18n_provenance: human
|
||||
i18n_output_hash: 5f53a19b9daf
|
||||
i18n_source_hash: fda322e78b4b
|
||||
i18n_provenance: human
|
||||
---
|
||||
|
||||
# Imagem Docker {#docker-image}
|
||||
@@ -41,7 +41,6 @@ Testado em uma NVIDIA RTX 4070 (12 GB de VRAM) com um retrato JPEG de 572x1024.
|
||||
| Remoção de fundo (isnet) | 2.457ms | 1.137ms | 2,2x |
|
||||
| Upscale 2x | 350ms | 309ms | 1,1x |
|
||||
| Upscale 4x | 910ms | 310ms | 2,9x |
|
||||
| OCR (PaddleOCR) | 137ms | 94ms | 1,5x |
|
||||
| Desfoque de rosto | 139ms | 122ms | 1,1x |
|
||||
|
||||
#### Inicialização a frio (primeira requisição após o início do contêiner) {#cold-start-first-request-after-container-start}
|
||||
@@ -50,7 +49,8 @@ Testado em uma NVIDIA RTX 4070 (12 GB de VRAM) com um retrato JPEG de 572x1024.
|
||||
|------|-----|-----|---------|
|
||||
| Remoção de fundo | 22.286ms | 4.792ms | 4,7x |
|
||||
| Upscale 2x | 3.957ms | 2.318ms | 1,7x |
|
||||
| OCR (PaddleOCR) | 1.469ms | 1.090ms | 1,3x |
|
||||
|
||||
OCR não está incluído na comparação CUDA. Tanto a camada Tesseract integrada quanto as camadas RapidOCR/ONNX opcionais usam CPU, inclusive quando o contêiner tem acesso NVIDIA GPU.
|
||||
|
||||
### Verificação de integridade do CUDA {#cuda-health-check}
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
description: "Instale o SnapOtter com Docker em um único comando. Inclui configuração de Docker Compose, build a partir do código-fonte e uma visão geral completa das features."
|
||||
i18n_source_hash: 4536d4558b8e
|
||||
i18n_provenance: machine
|
||||
i18n_output_hash: 8584b5780f52
|
||||
i18n_source_hash: 24724b5595b2
|
||||
i18n_provenance: human
|
||||
---
|
||||
|
||||
# Primeiros Passos {#getting-started}
|
||||
@@ -32,7 +32,7 @@ Para detalhes sobre o que é coletado, veja [O que o SnapOtter coleta](/pt-BR/gu
|
||||
:::
|
||||
|
||||
::: tip Aceleração NVIDIA CUDA
|
||||
Adicione `--gpus all` para remoção de fundo, upscaling, OCR, aprimoramento de rosto e restauração acelerados por NVIDIA CUDA:
|
||||
Adicione `--gpus all` para remoção de fundo, aumento de escala, aprimoramento de rosto e restauração acelerados por NVIDIA CUDA. OCR permanece baseado em CPU e funciona na mesma imagem com ou sem acesso GPU:
|
||||
|
||||
```bash
|
||||
docker run -d --name SnapOtter -p 1349:1349 --gpus all -v SnapOtter-data:/data snapotter/snapotter:latest
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user