description:"KI-Engine-Referenz mit allen lokalen ML-Werkzeugen. Hintergrundentfernung, Hochskalierung, OCR, Gesichtserkennung, Fotorestaurierung und mehr."
Das `@snapotter/ai`-Paket koordiniert native Tools und Python-Laufzeiten für lokale ML-Vorgänge. Die meisten ML-Tools verwenden einen dauerhaften Python sidecar für schnelle Warmstarts. OCR ist absichtlich getrennt: `fast` ruft die native Tesseract-Binärdatei auf, während `balanced` und `best` ein dediziertes persistentes JSONL dispatcher verwenden, das an die aktive unveränderliche RapidOCR-Generation unter `/data/ai/v3` angeheftet ist. Jede Anfrage enthält einen generation lease. Während eines Upgrades führt SnapOtter vor der Aktivierung einen smoke test für den Kandidaten aus, wechselt atomar zum neuen dispatcher und leert dann die alte Generation vor garbage collection.
NVIDIA CUDA wird automatisch erkannt und von Laufzeiten verwendet, die es unterstützen. OCR verwendet CPU auf jedem Host, einschließlich Systemen mit NVIDIA-GPUs, und vermeidet CUDA und Treiberkopplung für dieses Tool.
Eine iGPU-Beschleunigung von Intel/AMD über VA-API, Quick Sync oder OpenCL wird für KI-Inferenz derzeit nicht unterstützt. Das Durchreichen von `/dev/dri` in einen Container beschleunigt diese Python-Sidecar-Werkzeuge nicht, sofern keine CUDA-fähige NVIDIA-GPU verfügbar ist.
19 KI-Werkzeuge im Python-Sidecar über vier Modalitäten hinweg (Bild, Audio, Video, Dokument), plus 2 Werkzeuge mit optionalen KI-Fähigkeiten. Alle Modelle laufen lokal - nach dem ersten Modell-Download ist kein Internet erforderlich.
Fast OCR unterstützt `auto`, `en`, `de`, `es`, `fr`, `zh` und `ja`, aber kein Koreanisch (`ko`). Koreanisch benötigt das genaue OCR-Paket und `balanced` oder `best`. Das Paket läuft in offiziellen Linux-amd64- und arm64-Containern, auch auf NVIDIA-Hosts weiterhin auf der CPU. Nicht unterstützte Systeme erhalten einen eindeutigen Kompatibilitätsfehler und keinen stillen Rückfall auf `fast`. Koreanisch mit `fast` oder dem alten Alias `tesseract` wird vor dem Einreihen mit `FEATURE_INCOMPATIBLE` und `fast-korean-unsupported` abgelehnt.
Ein separates "docs"-Dispatcher-Profil ersetzt die KI-Zulassungsliste durch Skripte zur Dokumentenverarbeitung (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) und überspringt die aufwendigen ML-Importe.
**Zeitüberschreitungen:** 300 s standardmäßig; OCR und die BiRefNet-Hintergrundentfernung erhalten 600 s.
## Feature-Bundles {#feature-bundles}
KI-Modelle werden nach gemeinsamem Abhängigkeits-Stack gebündelt, nicht als ein Archiv pro Werkzeug. Ein Feature-Bundle kann mehrere Werkzeuge aktivieren, wenn diese dieselbe Modellfamilie, dieselben Python-Wheels oder dieselben nativen Bibliotheken verwenden. Das hält das Release-Docker-Image kleiner und vermeidet doppelte Kopien derselben Modelle für Hintergrund-Matting, Gesichtserkennung, OCR, Restaurierung und Sprache.
Das Docker-Image liefert die Anwendung sowie die gemeinsame Laufzeitumgebung. Große Modellarchive werden bei Bedarf in das dauerhafte `/data/ai`-Volume heruntergeladen und dann von jedem Werkzeug wiederverwendet, das sie benötigt. Wenn ein Bundle bereits installiert ist, weil ein anderes Werkzeug es benötigt hat, lädt das Aktivieren eines neuen abhängigen Werkzeugs dieses Bundle nicht erneut herunter.
Die meisten KI-Tools erfordern ein oder mehrere Funktionspakete, bevor sie ausgeführt werden können. Die Admin-Benutzeroberfläche installiert diese per Tool über `POST /api/v1/admin/tools/:toolId/features/install`, das die vollständige Bundle-Liste auflöst, bereits installierte Bundles überspringt und nur die fehlenden Downloads in die Warteschlange stellt. Wenn Sie beispielsweise Passport Photo auf einer neuen Instanz aktivieren, werden die Warteschlangen `background-removal` und `face-detection` angezeigt. Wenn Sie es aktivieren, nachdem die Hintergrundentfernung bereits installiert ist, werden nur Warteschlangen angezeigt `face-detection`. OCR ist die Ausnahme, da `fast` kein Paket benötigt; Installieren Sie die optionale genaue Laufzeit über die Benutzeroberfläche oder `POST /api/v1/admin/features/ocr/install`.
Werkzeuge mit bundleübergreifenden Abhängigkeiten:
| Werkzeug | Erforderliche Bundles | Grund |
|------|------------------|-----|
| `passport-photo` | `background-removal`, `face-detection` | Entfernt den Hintergrund und verwendet dann Gesichtslandmarken, um den Zuschnitt gemäß den Regeln für Pass- und Ausweisfotos auszurichten. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Erkennt Gesichter, bevor es GFPGAN oder CodeFormer zur Verbesserung der ausgewählten Gesichtsbereiche ausführt. |
Ein Tool ist nur verfügbar, wenn alle erforderlichen Bundles installiert sind, mit Ausnahme von OCR: Die integrierte `fast`-Stufe bleibt auch ohne das optionale OCR-Paket verfügbar. Teilinstallationen sind gültig und werden inkrementell verarbeitet: Installierte Bundles werden wiederverwendet, fehlende Bundles werden als Downloads angezeigt und Installationen in der Warteschlange werden einzeln ausgeführt, sodass die freigegebene Python-Umgebung nicht gleichzeitig geändert wird.
Das genaue OCR-Paket ist eine plattformspezifische Laufzeit für den offiziellen Linux amd64- oder Linux arm64-Container. Der amd64-Build verwendet Python 3.12; Der arm64-Build verwendet Python 3.11. Beide Builds führen RapidOCR über ONNX Runtime s `CPUExecutionProvider` aus, sodass dasselbe Paket auf Nur-CPU- und NVIDIA Docker-Hosts funktioniert. Die genaue Laufzeit erfordert mindestens 4 GiB effektiven Speicher: das konfigurierte Container-cgroup-Limit, andernfalls Host-Speicher. Ein System unterhalb dieses signierten Kompatibilitätsminimums wird vor dem Download abgelehnt. Diese Anforderung gilt nicht für integrierte Fast OCR. Bare-metal-Builds werden abgelehnt, da ihre libc und Python ABI nicht sicher abgeleitet werden können. Schnelles OCR bleibt verfügbar, wenn der Host Tesseract und Ghostscript bereitstellt.
Das optionale Artefakt ist je nach Architektur etwa 208–234 MiB komprimiert und 409–488 MiB extrahiert. Der signierte Index bindet die genauen komprimierten und extrahierten Bytezahlen, die vom Installationsprogramm erzwungen werden. Das integrierte Tesseract fügt etwa 25 MiB zum offiziellen Image hinzu und benötigt keine Dateien in `/data/ai`.
Die Online-Installation ruft einen signierten Release-Index und das genaue inhaltsadressierte Artefakt für die aktuelle Plattform ab. SnapOtter überprüft die Indexsignatur von Ed25519, die Artefaktgröße, den SHA-256-Digest, die Modell-Digests, Pfade, Dateimodi und bereitgestellten smoke test, bevor die neue Generation atomar aktiviert wird. Bei einer fehlgeschlagenen Installation bleibt die vorherige fehlerfreie Generation aktiv.
Laden Sie für eine Air-Gap-Installation sowohl das `ocr-runtime-index.json` der Version als auch das passende OCR-Laufzeitarchiv in `POST /api/v1/admin/features/import` hoch, indem Sie mehrteilige Felder mit den Namen `index` und `archive` verwenden. Beim Offline-Import werden dieselben Signatur-, Hash-, Extraktions-, Kompatibilitäts- und Rauchtestprüfungen angewendet wie bei der Online-Installation. Ein Archiv ohne seinen vertrauenswürdigen signierten Index wird abgelehnt.
**Modelle:** Tesseract (`fast`); RapidOCR mit kleinen PP-OCRv6-Modellen (`balanced`); PP-OCRv6 mittlere Modelle mit kalibrierter Variantenbewertung (`best`)
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dynamisch | Wenn `quality` und `engine` fehlen, wählt SnapOtter die höchste verfügbare Stufe in dieser Reihenfolge: `best`, `balanced`, `fast`. Für Koreanisch wird `fast` nie gewählt; es wird `best`, dann `balanced` verwendet oder ein Installations- bzw. Kompatibilitätsfehler der genauen Laufzeit zurückgegeben. |
| `enhance` | Boolescher Wert | Tierabhängig | Verbessern Sie den lokalen Kontrast. Fast wendet es direkt an; Genaue Stufen behalten die Variante nur bei, wenn die kalibrierte Bewertung OCR verbessert. Standardmäßig ist „Best“ aktiviert |
| `engine` | Zeichenfolge | - | Veralteter Kompatibilitätsalias. Ordnet `tesseract``fast` und den alten `paddleocr`-Wert `balanced` zu; PaddlePaddle wird nicht geladen |
Gibt extrahierten Text plus Herkunftsmetadaten zurück: Engine, angeforderte und tatsächliche Qualität, Gerät, Anbieter, Verschlechterungsstatus, Warnungen und ggf. genaue Laufzeit-/Modellversionen. Explizite Qualitätsanforderungen fallen nie auf eine andere Ebene zurück. Wenn `balanced` oder `best` nicht verfügbar ist, gibt API `FEATURE_NOT_INSTALLED` oder `FEATURE_INCOMPATIBLE` zurück, anstatt `fast` stillschweigend auszuführen.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dynamisch | Wenn `quality` und `engine` fehlen, wählt SnapOtter die höchste verfügbare Stufe in dieser Reihenfolge: `best`, `balanced`, `fast`. Für Koreanisch wird `fast` nie gewählt; es wird `best`, dann `balanced` verwendet oder ein Installations- bzw. Kompatibilitätsfehler der genauen Laufzeit zurückgegeben. |
| `enhance` | Boolescher Wert | Tierabhängig | Verbessern Sie den lokalen Kontrast. Fast wendet es direkt an; Genaue Stufen behalten die Variante nur bei, wenn die kalibrierte Bewertung OCR verbessert. Standardmäßig ist „Best“ aktiviert |
| `engine` | Zeichenfolge | - | Veralteter Kompatibilitätsalias. Ordnet `tesseract``fast` und den alten `paddleocr`-Wert `balanced` zu; PaddlePaddle wird nicht geladen |
Die gleiche No-Downgrade-Regel gilt für PDF OCR. PDF Seiten werden vor der Erkennung gerastert und eine Anfrage kann höchstens 50 Seiten auswählen.
| `quality` | number (1-100) | `90` | Ausgabequalität |
## Fotorestaurierung {#photo-restoration}
**Werkzeug-Route:**`restore-photo`
Mehrstufige Pipeline für alte oder beschädigte Fotos: Erkennung und Reparatur von Kratzern/Rissen, Gesichtsverbesserung, Rauschunterdrückung und optionale Kolorierung.
| Parameter | Typ | Standard | Beschreibung |
|-----------|------|---------|-------------|
| `scratchRemoval` | boolean | `true` | Kratzer und Risse erkennen und reparieren |
Zweiphasiger Ablauf: analysieren (Gesicht erkennen + Hintergrund entfernen), dann generieren (zuschneiden, skalieren, kacheln). Unterstützt über 37 Länder in 6 Regionen.
### Phase 1: Analysieren {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Nimmt eine Bilddatei entgegen (multipart). Gibt Gesichtslandmarkendaten, eine Base64-Vorschau und Bildabmessungen zurück.
Die Maske wird als **zweiter Dateibestandteil** gesendet (Feldname `mask`), nicht als Base64. Weiße Pixel in der Maske kennzeichnen die zu entfernenden Bereiche. Die Einstellungen `format` und `quality` werden als Formularfelder auf oberster Ebene gesendet.
Behebt "unecht transparente" PNGs, bei denen der Hintergrund entfernt wurde, aber Fransen, Halos oder halbtransparente Artefakte zurückgeblieben sind. Verwendet das hochauflösende Matting-Modell von BiRefNet, um einen sauberen Alphakanal zu erzeugen, und wendet anschließend eine konfigurierbare Defringe-Verarbeitung an, um Farbverunreinigungen entlang der Kanten zu entfernen.
**OOM-Fallback-Kette:** Überschreitet das BiRefNet HR-Matting den verfügbaren Speicher, greift das Werkzeug automatisch auf `birefnet-general` und dann auf `u2net` zurück.
| Parameter | Typ | Standard | Beschreibung |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Stärke des Kanten-Defringe zur Entfernung von Farbverunreinigungen |
## Werkzeuge mit optionalen KI-Fähigkeiten {#tools-with-optional-ai-capabilities}
Die folgenden Werkzeuge sind keine Python-Sidecar-Werkzeuge, nutzen aber KI-Funktionen, wenn bestimmte Optionen aktiviert sind.
### Bildverbesserung {#image-enhancement}
**Werkzeug-Route:**`image-enhancement`
**Engine:** Analysebasiert (Sharp-Histogramm und -Statistik)
Analysiert das Bild und wendet automatische Korrekturen für Belichtung, Kontrast, Weißabgleich, Sättigung, Schärfe und Rauschen an. Unterstützt szenenspezifische Modi.
| `deepEnhance` | boolean | `false` | KI-Rauschentfernung über SCUNet aktivieren (erfordert das `upscale-enhance`-Bundle) |
Ein zusätzlicher Analyse-Endpunkt ist unter `POST /api/v1/tools/image/image-enhancement/analyze` verfügbar, der die erkannten Korrekturen zurückgibt, ohne sie anzuwenden.
