description:"Riferimento del motore AI con tutti gli strumenti ML locali. Rimozione dello sfondo, upscaling, OCR, rilevamento dei volti, restauro fotografico e altro ancora."
Il pacchetto `@snapotter/ai` coordina gli strumenti nativi e i runtime Python per le operazioni ML locali. La maggior parte degli strumenti ML utilizzano un Python sidecar persistente per avviamenti a caldo rapidi. OCR è intenzionalmente separato: `fast` richiama il binario nativo Tesseract, mentre `balanced` e `best` utilizzano una JSONL dispatcher persistente dedicata fissata alla generazione RapidOCR immutabile attiva sotto `/data/ai/v3`. Ogni richiesta contiene un generation lease. Durante un aggiornamento, SnapOtter esegue un smoke test sul candidato prima dell'attivazione, passa atomicamente al nuovo dispatcher, quindi scarica la vecchia generazione prima di garbage collection.
NVIDIA CUDA viene rilevato automaticamente e utilizzato dai runtime che lo supportano. OCR utilizza CPU su ogni host, inclusi i sistemi con GPU NVIDIA, evitando CUDA e l'accoppiamento dei driver per questo strumento.
Oggi l'accelerazione tramite iGPU Intel/AMD con VA-API, Quick Sync o OpenCL non è supportata per l'inferenza AI. Mappare `/dev/dri` in un container non accelera questi strumenti del sidecar Python a meno che non sia disponibile una GPU NVIDIA compatibile con CUDA.
19 strumenti AI del sidecar Python distribuiti su quattro modalità (immagine, audio, video, documento), più 2 strumenti con funzionalità AI opzionali. Tutti i modelli vengono eseguiti in locale, senza bisogno di connessione a internet dopo il download iniziale del modello.
OCR veloce supporta `auto`, `en`, `de`, `es`, `fr`, `zh` e `ja`, ma non il coreano (`ko`). Il coreano richiede il pacchetto OCR accurato e `balanced` o `best`. Il pacchetto funziona nei container Linux amd64 e arm64 ufficiali, inclusi gli host NVIDIA, dove l’OCR resta sulla CPU. I sistemi non supportati ricevono un errore di compatibilità esplicito e non passano mai silenziosamente a `fast`. Il coreano con `fast` o con l’alias legacy `tesseract` viene rifiutato prima dell’accodamento con `FEATURE_INCOMPATIBLE` e `fast-korean-unsupported`.
Un profilo dispatcher "docs" separato sostituisce l'allowlist AI con script per l'elaborazione dei documenti (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) e salta gli import ML pesanti.
**Timeout:** 300 s di default; OCR e rimozione dello sfondo con BiRefNet ottengono 600 s.
## Bundle di funzionalità {#feature-bundles}
I modelli AI sono raggruppati per stack di dipendenze condivise, non con un archivio per ogni strumento. Un bundle di funzionalità può abilitare più strumenti quando questi usano la stessa famiglia di modelli, gli stessi wheel Python o le stesse librerie native. Questo mantiene più piccola l'immagine Docker di rilascio ed evita di conservare copie duplicate degli stessi modelli di matting dello sfondo, rilevamento dei volti, OCR, restauro e riconoscimento vocale.
L'immagine Docker include l'applicazione più il runtime comune. Gli archivi di modelli di grandi dimensioni vengono scaricati su richiesta nel volume persistente `/data/ai`, poi riutilizzati da ogni strumento che ne ha bisogno. Se un bundle è già installato perché un altro strumento ne aveva bisogno, abilitare un nuovo strumento dipendente non scarica di nuovo quel bundle.
La maggior parte degli strumenti di intelligenza artificiale richiedono uno o più pacchetti di funzionalità prima di poter essere eseguiti. L'interfaccia utente di amministrazione li installa tramite lo strumento tramite `POST /api/v1/admin/tools/:toolId/features/install`, che risolve l'elenco completo dei bundle, salta i bundle già installati e mette in coda solo i download mancanti. Ad esempio, abilitando Passport Photo su una nuova istanza si accodano `background-removal` e `face-detection`; abilitandolo dopo la rimozione dello sfondo è già installata solo la coda `face-detection`. OCR è l'eccezione perché `fast` non necessita di alcun pacchetto; installa il suo runtime accurato opzionale tramite l'interfaccia utente o `POST /api/v1/admin/features/ocr/install`.
| `passport-photo` | `background-removal`, `face-detection` | Rimuove lo sfondo, poi usa i landmark del volto per inquadrare il ritaglio secondo le regole delle foto per passaporto e documenti di identità. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Rileva i volti prima di eseguire il miglioramento GFPGAN o CodeFormer sulle regioni facciali selezionate. |
Uno strumento è disponibile solo quando sono installati tutti i bundle richiesti, ad eccezione di OCR: il livello `fast` integrato rimane disponibile senza il pacchetto OCR opzionale. Le installazioni parziali sono valide e vengono gestite in modo incrementale: i bundle installati vengono riutilizzati, i bundle mancanti vengono visualizzati come download e le installazioni in coda vengono eseguite una alla volta in modo che l'ambiente Python condiviso non venga modificato contemporaneamente.
Il pacchetto OCR accurato è un runtime specifico della piattaforma per il contenitore ufficiale Linux amd64 o Linux arm64. La build amd64 utilizza Python 3.12; la build arm64 utilizza Python 3.11. Entrambe le build eseguono RapidOCR tramite `CPUExecutionProvider` di ONNX Runtime, quindi lo stesso pacchetto funziona solo su host CPU e NVIDIA Docker. Il runtime accurato richiede almeno 4 GiB di memoria effettiva: il limite cgroup del contenitore configurato, altrimenti memoria host. Un sistema al di sotto del minimo di compatibilità firmato viene rifiutato prima del download. Questo requisito non si applica al modello Fast OCR integrato. Le build Bare-metal vengono rifiutate perché i relativi libc e Python ABI non possono essere dedotti in modo sicuro; OCR veloce rimane disponibile quando l'host fornisce Tesseract e Ghostscript.
L'artefatto opzionale è di circa 208-234 MiB compresso e 409-488 MiB estratto, a seconda dell'architettura. L'indice firmato associa l'esatto conteggio dei byte compressi ed estratti imposti dal programma di installazione. Tesseract integrato aggiunge circa 25 MiB all'immagine ufficiale e non necessita di file in `/data/ai`.
L'installazione online recupera un indice di rilascio firmato e l'esatto artefatto indirizzato al contenuto per la piattaforma corrente. SnapOtter verifica la firma dell'indice Ed25519, la dimensione dell'artefatto, il digest SHA-256, i digest del modello, i percorsi, le modalità file e lo smoke test messo in scena prima di attivare atomicamente la nuova generazione. Un'installazione non riuscita lascia attiva la precedente generazione integra.
Per l'installazione con air gap, caricare sia l'archivio runtime `ocr-runtime-index.json` della versione che l'archivio runtime OCR corrispondente su `POST /api/v1/admin/features/import` utilizzando campi multiparte denominati `index` e `archive`. L'importazione offline applica gli stessi controlli di firma, hash, estrazione, compatibilità e test del fumo dell'installazione online; un archivio senza il suo indice firmato attendibile viene rifiutato.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinamico | Quando `quality` e `engine` sono omessi, SnapOtter sceglie il livello migliore disponibile nell’ordine `best`, `balanced`, `fast`. Per il coreano non sceglie mai `fast`: usa `best`, poi `balanced`, oppure restituisce l’errore di installazione o compatibilità del runtime accurato. |
| `enhance` | booleano | Dipendente dal livello | Migliora il contrasto locale. Fast lo applica direttamente; i livelli accurati mantengono la variante solo quando il punteggio calibrato migliora OCR. L'impostazione predefinita è Migliore |
| `engine` | corda | - | Alias di compatibilità deprecato. Mappa `tesseract` su `fast` e il valore `paddleocr` legacy su `balanced`; non carica PaddlePaddle |
Restituisce il testo estratto più i metadati di provenienza: motore, qualità richiesta ed effettiva, dispositivo, provider, stato di degrado, avvisi e versioni runtime/modello accurate, ove applicabile. Le richieste esplicite di qualità non ricadono mai su un altro livello. Se `balanced` o `best` non è disponibile, API restituisce `FEATURE_NOT_INSTALLED` o `FEATURE_INCOMPATIBLE` invece di eseguire `fast` in modalità silenziosa.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinamico | Quando `quality` e `engine` sono omessi, SnapOtter sceglie il livello migliore disponibile nell’ordine `best`, `balanced`, `fast`. Per il coreano non sceglie mai `fast`: usa `best`, poi `balanced`, oppure restituisce l’errore di installazione o compatibilità del runtime accurato. |
| `enhance` | booleano | Dipendente dal livello | Migliora il contrasto locale. Fast lo applica direttamente; i livelli accurati mantengono la variante solo quando il punteggio calibrato migliora OCR. L'impostazione predefinita è Migliore |
| `engine` | corda | - | Alias di compatibilità deprecato. Mappa `tesseract` su `fast` e il valore `paddleocr` legacy su `balanced`; non carica PaddlePaddle |
La stessa regola di non downgrade si applica a PDF OCR. Le pagine PDF vengono rasterizzate prima del riconoscimento e una richiesta può selezionare un massimo di 50 pagine.
| `quality` | number (1-100) | `90` | Qualità di codifica dell'output |
## Rimozione degli occhi rossi {#red-eye-removal}
**Route dello strumento:**`red-eye-removal`
Rileva i landmark del volto, individua le regioni degli occhi e corregge la sovrasaturazione del canale rosso.
| Parametro | Tipo | Predefinito | Descrizione |
|-----------|------|---------|-------------|
| `sensitivity` | number (0-100) | `50` | Soglia di rilevamento dei pixel rossi |
| `strength` | number (0-100) | `70` | Intensità della correzione |
| `format` | string | - | Override del formato di output (opzionale) |
| `quality` | number (1-100) | `90` | Qualità di output |
## Restauro fotografico {#photo-restoration}
**Route dello strumento:**`restore-photo`
Pipeline multi-step per foto vecchie o danneggiate: rilevamento e riparazione di graffi/strappi, miglioramento dei volti, denoising e colorizzazione opzionale.
| Parametro | Tipo | Predefinito | Descrizione |
|-----------|------|---------|-------------|
| `scratchRemoval` | boolean | `true` | Rileva e ripara graffi e strappi |
| `faceEnhancement` | boolean | `true` | Applica un passaggio di miglioramento dei volti |
| `fidelity` | number (0-1) | `0.7` | Intensità del miglioramento dei volti (più alto = più conservativo) |
| `denoise` | boolean | `true` | Applica un passaggio di denoising |
| `denoiseStrength` | number (0-100) | `25` | Intensità del denoising |
| `colorize` | boolean | `false` | Colorizza dopo il restauro |
| `colorizeStrength` | number (0-100) | `85` | Intensità della colorizzazione |
## Foto per passaporto {#passport-photo}
**Route dello strumento:**`passport-photo`
**Modelli:** landmark del volto MediaPipe + rimozione dello sfondo BiRefNet
Flusso di lavoro in due fasi: analisi (rilevamento del volto + rimozione dello sfondo) poi generazione (ritaglio, ridimensionamento, disposizione a griglia). Supporta oltre 37 paesi in 6 regioni.
### Fase 1: Analisi {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Accetta un file immagine (multipart). Restituisce i dati dei landmark del volto, un'anteprima base64 e le dimensioni dell'immagine.
| `maxFileSizeKb` | number | `0` | Dimensione massima del file in KB (0 = nessun limite) |
| `dpi` | number (72-1200) | `300` | DPI di output |
| `customWidthMm` | number | - | Larghezza personalizzata in mm (sovrascrive le specifiche del paese) |
| `customHeightMm` | number | - | Altezza personalizzata in mm (sovrascrive le specifiche del paese) |
| `zoom` | number (0.5-3) | `1` | Fattore di zoom |
| `adjustX` | number | `0` | Regolazione della posizione orizzontale |
| `adjustY` | number | `0` | Regolazione della posizione verticale |
| `landmarks` | object | (obbligatorio) | Landmark dalla Fase 1 |
| `imageWidth` | number | (obbligatorio) | Larghezza dell'immagine dalla Fase 1 |
| `imageHeight` | number | (obbligatorio) | Altezza dell'immagine dalla Fase 1 |
## Cancellazione di oggetti (Inpainting) {#object-erasing-inpainting}
**Route dello strumento:**`erase-object`
**Modello:** LaMa tramite ONNX Runtime
La maschera viene inviata come **seconda parte del file** (fieldname `mask`), non come base64. I pixel bianchi nella maschera indicano le aree da cancellare. Le impostazioni `format` e `quality` vengono inviate come campi form di primo livello.
Corregge i PNG "a falsa trasparenza" in cui lo sfondo è stato rimosso ma ha lasciato bordi frastagliati, aloni o artefatti semi-trasparenti. Usa il modello di matting ad alta risoluzione di BiRefNet per produrre un canale alfa pulito, poi applica un'elaborazione di defringe configurabile per rimuovere la contaminazione cromatica lungo i bordi.
**Catena di fallback OOM:** Se il matting HR BiRefNet supera la memoria disponibile, lo strumento ricade automaticamente su `birefnet-general`, poi su `u2net`.
| Parametro | Tipo | Predefinito | Descrizione |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Intensità del defringe dei bordi per rimuovere la contaminazione cromatica |
## Strumenti con funzionalità AI opzionali {#tools-with-optional-ai-capabilities}
I seguenti strumenti non sono strumenti del sidecar Python ma usano funzionalità AI quando determinate opzioni sono abilitate.
### Miglioramento delle immagini {#image-enhancement}
**Route dello strumento:**`image-enhancement`
**Motore:** basato su analisi (istogramma e statistiche di Sharp)
Analizza l'immagine e applica correzioni automatiche per esposizione, contrasto, bilanciamento del bianco, saturazione, nitidezza e rumore. Supporta modalità specifiche per scena.
| Parametro | Tipo | Predefinito | Descrizione |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Modalità scena per la messa a punto delle correzioni |
| `intensity` | number (0-100) | `50` | Intensità complessiva della correzione |
| `deepEnhance` | boolean | `false` | Abilita la rimozione AI del rumore tramite SCUNet (richiede il bundle `upscale-enhance`) |
Un endpoint di analisi aggiuntivo è disponibile su `POST /api/v1/tools/image/image-enhancement/analyze` che restituisce le correzioni rilevate senza applicarle.
