`@snapotter/ai`-paketet koordinerar inbyggda verktyg och Python-körtider för lokala ML-operationer. De flesta ML-verktyg använder en ihållande Python sidecar för snabba varma starter. OCR är avsiktligt separat: `fast` anropar den ursprungliga binära Tesseract, medan `balanced` och `best` använder en dedikerad beständig JSONL dispatcher fästad till den aktiva oföränderliga RapidOCR-generationen under `/data/ai/v3`. Varje begäran innehåller en generation lease. Under en uppgradering kör SnapOtter en smoke test på kandidaten före aktivering, växlar atomärt till den nya dispatcher och dränerar sedan den gamla generationen före garbage collection.
NVIDIA CUDA upptäcks automatiskt och används av körtider som stöder det. OCR använder CPU på varje värd, inklusive system med NVIDIA GPU:er, och undviker CUDA och drivrutinskoppling för detta verktyg.
Acceleration via Intel/AMD-iGPU genom VA-API, Quick Sync eller OpenCL stöds inte för AI-inferens idag. Att mappa `/dev/dri` in i en container accelererar inte dessa Python-sidecar-verktyg om inte en CUDA-kapabel NVIDIA-GPU finns tillgänglig.
19 Python-sidecar-AI-verktyg över fyra modaliteter (bild, ljud, video, dokument), plus 2 verktyg med valfria AI-funktioner. Alla modeller körs lokalt - ingen internetuppkoppling krävs efter den första nedladdningen av modellerna.
Snabb OCR stöder `auto`, `en`, `de`, `es`, `fr`, `zh` och `ja`, men inte koreanska (`ko`). Koreanska kräver det exakta OCR-paketet och `balanced` eller `best`. Paketet fungerar i officiella Linux amd64- och arm64-containrar, även på NVIDIA-värdar där OCR fortsätter köras på CPU. System som inte stöds får ett uttryckligt kompatibilitetsfel och faller aldrig tyst tillbaka till `fast`. Koreanska med `fast` eller det äldre aliaset `tesseract` avvisas före köläggning med `FEATURE_INCOMPATIBLE` och `fast-korean-unsupported`.
En separat "docs"-dispatcherprofil ersätter AI-tillåtelselistan med skript för dokumentbearbetning (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) och hoppar över tunga ML-importer.
**Tidsgränser:** 300 s som standard; OCR och BiRefNet-bakgrundsborttagning får 600 s.
## Funktionspaket {#feature-bundles}
AI-modeller paketeras efter delad beroendestack, inte ett arkiv per verktyg. Ett funktionspaket kan aktivera flera verktyg när de använder samma modellfamilj, Python-wheels eller inbyggda bibliotek. Detta håller den utgivna Docker-avbildningen mindre och undviker att lagra dubbletter av samma modeller för bakgrundsmattning, ansiktsdetektering, OCR, restaurering och tal.
Docker-avbildningen levereras med applikationen plus den gemensamma körtidsmiljön. Stora modellarkiv laddas ned vid behov till den beständiga volymen `/data/ai` och återanvänds sedan av alla verktyg som behöver dem. Om ett paket redan är installerat eftersom ett annat verktyg behövde det, laddas det paketet inte ned igen när ett nytt beroende verktyg aktiveras.
De flesta AI-verktyg kräver ett eller flera funktionspaket innan de kan köras. Administratörsgränssnittet installerar dessa med hjälp av `POST /api/v1/admin/tools/:toolId/features/install`, vilket löser hela paketlistan, hoppar över paket som redan är installerade och köar endast de saknade nedladdningarna. Till exempel, aktivering av Passfoto på en ny instans köer `background-removal` och `face-detection`; aktivera det efter att bakgrundsborttagning redan är installerat köer endast `face-detection`. OCR är undantaget eftersom `fast` inte behöver något pack; installera dess valfria exakta körtid genom UI eller `POST /api/v1/admin/features/ocr/install`.
| `passport-photo` | `background-removal`, `face-detection` | Tar bort bakgrunden och använder sedan ansiktslandmärken för att beskära bilden enligt reglerna för pass- och ID-foton. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Detekterar ansikten innan GFPGAN- eller CodeFormer-förbättring körs på de valda ansiktsregionerna. |
Ett verktyg är endast tillgängligt när alla dess nödvändiga buntar är installerade, förutom OCR: dess inbyggda `fast`-nivå förblir tillgänglig utan det valfria OCR-paketet. Delinstallationer är giltiga och hanteras inkrementellt: installerade paket återanvänds, saknade paket visas som nedladdningar och installationer i kö körs en i taget så att den delade Python-miljön inte ändras samtidigt.
Det exakta OCR-paketet är en plattformsspecifik körtid för den officiella Linux amd64- eller Linux arm64-behållaren. amd64-bygget använder Python 3.12; arm64-bygget använder Python 3.11. Båda byggen kör RapidOCR genom ONNX Runtime:s `CPUExecutionProvider`, så samma paket fungerar på endast CPU- och NVIDIA Docker-värdar. Den exakta körtiden kräver minst 4 GiB effektivt minne: den konfigurerade behållarens cgroup-gräns, annars värdminne. Ett system under det signerade kompatibilitetsminimum avvisas före nedladdning. Detta krav gäller inte för inbyggd Fast OCR. Bare-metal-builds avvisas eftersom deras libc och Python ABI inte kan härledas säkert; Snabb OCR förblir tillgänglig när värden tillhandahåller Tesseract och Ghostscript.
Den valfria artefakten är cirka 208-234 MiB komprimerad och 409-488 MiB extraherad, beroende på arkitektur. Det signerade indexet binder de exakta komprimerade och extraherade byteantalerna som upprätthålls av installationsprogrammet. Inbyggd Tesseract lägger till cirka 25 MiB till den officiella bilden och behöver inga filer i `/data/ai`.
Onlineinstallation hämtar ett signerat releaseindex och den exakta innehållsadresserade artefakten för den aktuella plattformen. SnapOtter verifierar Ed25519 indexsignatur, artefaktstorlek, SHA-256 sammanfattning, modellsammandrag, sökvägar, fillägen och iscensatta smoke test innan den nya generationen atomärt aktiveras. En misslyckad installation lämnar den tidigare friska generationen aktiv.
För installation med luftgap, ladda upp både releasens `ocr-runtime-index.json` och matchande OCR runtime-arkiv till `POST /api/v1/admin/features/import` med hjälp av flerdelade fält som heter `index` och `archive`. Offlineimport tillämpar samma signatur-, hash-, extraktions-, kompatibilitets- och röktestkontroller som onlineinstallation; ett arkiv utan dess betrodda signerade index avvisas.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dynamisk | När `quality` och `engine` utelämnas väljer SnapOtter den bästa tillgängliga nivån i ordningen `best`, `balanced`, `fast`. För koreanska väljs aldrig `fast`; `best`, sedan `balanced` används, annars returneras installations- eller kompatibilitetsfelet för den exakta körmiljön. |
| `enhance` | booleskt | Tierberoende | Förbättra den lokala kontrasten. Fast applicerar det direkt; exakta nivåer behåller varianten endast när kalibrerad poängsättning förbättrar OCR. Standard på för Best |
| `engine` | sträng | - | Utfasat kompatibilitetsalias. Mappar `tesseract` till `fast` och det äldre `paddleocr`-värdet till `balanced`; den laddar inte PaddlePaddle |
Returnerar extraherad text plus härkomstmetadata: motor, begärd och faktisk kvalitet, enhet, leverantör, försämringstillstånd, varningar och korrekt körtid/modellversioner när tillämpligt. Explicita kvalitetsförfrågningar faller aldrig tillbaka till en annan nivå. Om `balanced` eller `best` är otillgängliga, returnerar API `FEATURE_NOT_INSTALLED` eller `FEATURE_INCOMPATIBLE` istället för att köra `fast` tyst.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dynamisk | När `quality` och `engine` utelämnas väljer SnapOtter den bästa tillgängliga nivån i ordningen `best`, `balanced`, `fast`. För koreanska väljs aldrig `fast`; `best`, sedan `balanced` används, annars returneras installations- eller kompatibilitetsfelet för den exakta körmiljön. |
| `enhance` | booleskt | Tierberoende | Förbättra den lokala kontrasten. Fast applicerar det direkt; exakta nivåer behåller varianten endast när kalibrerad poängsättning förbättrar OCR. Standard på för Best |
| `engine` | sträng | - | Utfasat kompatibilitetsalias. Mappar `tesseract` till `fast` och det äldre `paddleocr`-värdet till `balanced`; den laddar inte PaddlePaddle |
Samma regel om ingen nedgradering gäller för PDF OCR. PDF sidor rastreras före igenkänning, och en begäran kan välja högst 50 sidor.
| `quality` | number (1-100) | `90` | Utdatakvalitet |
## Fotorestaurering {#photo-restoration}
**Verktygsrutt:**`restore-photo`
Pipeline i flera steg för gamla eller skadade foton: detektering och reparation av repor/revor, ansiktsförbättring, brusreducering och valfri kolorering.
Arbetsflöde i två faser: analysera (detektera ansikte + ta bort bakgrund) och sedan generera (beskär, ändra storlek, lägg i rutmönster). Stöder 37+ länder över 6 regioner.
### Fas 1: Analysera {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Tar emot en bildfil (multipart). Returnerar data om ansiktslandmärken, en base64-förhandsvisning och bilddimensioner.
Masken skickas som en **andra fildel** (fältnamn `mask`), inte som base64. Vita pixlar i masken anger områden som ska raderas. Inställningarna `format` och `quality` skickas som formulärfält på toppnivå.
Åtgärdar "falskt transparenta" PNG-filer där bakgrunden togs bort men lämnade kvar fransning, glorior eller halvtransparenta artefakter. Använder BiRefNets högupplösta mattningsmodell för att producera en ren alfakanal och tillämpar sedan konfigurerbar defringe-bearbetning för att ta bort färgkontaminering längs kanterna.
**Reservkedja vid minnesbrist:** Om BiRefNet HR-matting överskrider tillgängligt minne faller verktyget automatiskt tillbaka till `birefnet-general`, sedan till `u2net`.
| Parameter | Typ | Standard | Beskrivning |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Styrka på kant-defringe för att ta bort färgkontaminering |
En ytterligare analysslutpunkt finns tillgänglig på `POST /api/v1/tools/image/image-enhancement/analyze` som returnerar de detekterade korrigeringarna utan att tillämpa dem.
