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."
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.
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`.
Um perfil de despachante "docs" separado substitui a lista de permissões de IA por scripts de processamento de documentos (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) e pula as importações pesadas de ML.
**Tempos limite:** 300 s por padrão; OCR e remoção de fundo com BiRefNet recebem 600 s.
## Pacotes de Recursos {#feature-bundles}
Os modelos de IA são empacotados por pilha de dependências compartilhada, e não um arquivo por ferramenta. Um pacote de recursos pode habilitar várias ferramentas quando elas usam a mesma família de modelos, os mesmos wheels Python ou as mesmas bibliotecas nativas. Isso mantém a imagem Docker de lançamento menor e evita armazenar cópias duplicadas dos mesmos modelos de matting de fundo, detecção de rostos, OCR, restauração e fala.
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.
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`.
| `transcription` | ~600 MB | modelos de fala para texto faster-whisper | transcribe-audio, auto-subtitles |
Ferramentas com dependências entre pacotes:
| Ferramenta | Pacotes necessários | Por quê |
|------|------------------|-----|
| `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 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.
| `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. |
| `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 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.
| `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. |
| `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.
| `quality` | number (1-100) | `90` | Qualidade de codificação da saída |
## Remoção de Olhos Vermelhos {#red-eye-removal}
**Rota da ferramenta:**`red-eye-removal`
Detecta marcos faciais, localiza as regiões dos olhos e corrige a saturação excessiva no canal vermelho.
| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `sensitivity` | number (0-100) | `50` | Limiar de detecção de pixels vermelhos |
| `strength` | number (0-100) | `70` | Força da correção |
| `format` | string | - | Substituição do formato de saída (opcional) |
| `quality` | number (1-100) | `90` | Qualidade de saída |
## Restauração de Fotos {#photo-restoration}
**Rota da ferramenta:**`restore-photo`
Pipeline de múltiplas etapas para fotos antigas ou danificadas: detecção e reparo de arranhões/rasgos, realce de rosto, remoção de ruído e colorização opcional.
| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `scratchRemoval` | boolean | `true` | Detectar e reparar arranhões e rasgos |
| `faceEnhancement` | boolean | `true` | Aplicar passada de realce de rosto |
| `fidelity` | number (0-1) | `0.7` | Força do realce de rosto (maior = mais conservador) |
| `denoise` | boolean | `true` | Aplicar passada de remoção de ruído |
| `denoiseStrength` | number (0-100) | `25` | Força da remoção de ruído |
| `colorize` | boolean | `false` | Colorir após a restauração |
| `colorizeStrength` | number (0-100) | `85` | Intensidade da colorização |
## Foto para Passaporte {#passport-photo}
**Rota da ferramenta:**`passport-photo`
**Modelos:** marcos faciais do MediaPipe + remoção de fundo com BiRefNet
Fluxo de trabalho em duas fases: analisar (detectar rosto + remover fundo) e depois gerar (recortar, redimensionar, distribuir em grade). Suporta mais de 37 países em 6 regiões.
### Fase 1: Analisar {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Aceita um arquivo de imagem (multipart). Retorna os dados dos marcos faciais, uma pré-visualização em base64 e as dimensões da imagem.
A máscara é enviada como uma **segunda parte de arquivo** (nome do campo `mask`), não como base64. Pixels brancos na máscara indicam áreas a apagar. As configurações `format` e `quality` são enviadas como campos de formulário de nível superior.
| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `file` | file | (obrigatório) | Imagem de origem (multipart) |
| `mask` | file | (obrigatório) | Imagem da máscara (multipart, nome do campo `mask`, branco = apagar) |
| `format` | `"srt"` \| `"vtt"` | `"srt"` | Formato de saída da legenda |
## Corretor de Transparência PNG {#png-transparency-fixer}
**Rota da ferramenta:**`transparency-fixer`
**Modelo:** matting HR do BiRefNet (resolução 2048x2048)
Corrige PNGs de "falsa transparência" onde o fundo foi removido, mas deixou franjas, halos ou artefatos semitransparentes. Usa o modelo de matting de alta resolução do BiRefNet para produzir um canal alfa limpo e depois aplica um processamento de remoção de franjas configurável para eliminar a contaminação de cor ao longo das bordas.
**Cadeia de fallback em caso de OOM:** Se o matting HR do BiRefNet exceder a memória disponível, a ferramenta recorre automaticamente a `birefnet-general` e depois a `u2net`.
| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Força da remoção de franjas nas bordas para eliminar contaminação de cor |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Formato da imagem de saída |
| `removeWatermark` | boolean | `false` | Aplicar pré-processamento de remoção de marca d'água (filtro de mediana) |
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
## Ferramentas com Capacidades Opcionais de IA {#tools-with-optional-ai-capabilities}
As ferramentas a seguir não são ferramentas do sidecar Python, mas usam recursos de IA quando certas opções estão habilitadas.
### Realce de Imagem {#image-enhancement}
**Rota da ferramenta:**`image-enhancement`
**Motor:** baseado em análise (histograma e estatísticas do Sharp)
Analisa a imagem e aplica correções automáticas de exposição, contraste, balanço de branco, saturação, nitidez e ruído. Suporta modos específicos de cena.
| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Modo de cena para ajustar as correções |
| `intensity` | number (0-100) | `50` | Força geral da correção |
| `deepEnhance` | boolean | `false` | Ativar remoção de ruído por IA via SCUNet (requer o pacote `upscale-enhance`) |
Um endpoint de análise adicional está disponível em `POST /api/v1/tools/image/image-enhancement/analyze`, que retorna as correções detectadas sem aplicá-las.
### Redimensionamento com Reconhecimento de Conteúdo (Seam Carving) {#content-aware-resize-seam-carving}
**Rota da ferramenta:**`content-aware-resize`
**Motor:** binário Go `caire` (não Python - sem benefício de GPU)
Redimensiona imagens de forma inteligente removendo costuras de baixa energia, preservando o conteúdo importante.
| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `width` | number | - | Largura alvo |
| `height` | number | - | Altura alvo |
| `protectFaces` | boolean | `false` | Proteger as regiões de rosto detectadas (requer o pacote `face-detection`) |
| `blurRadius` | number (0-20) | `4` | Desfoque prévio para o cálculo de energia |
| `sobelThreshold` | number (1-20) | `2` | Limiar de sensibilidade das bordas |
