SnapOtter/apps/docs/fr/tools/image/ocr.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
Extrayez le texte des images localement avec Tesseract intégré ou le runtime RapidOCR haute précision en option.	526588702ae3	0d453b49db02	human

OCR / Extraction de texte

Extrayez le texte des images sans envoyer l'image à un service externe. Le niveau fast intégré utilise Tesseract. Les niveaux optionnels balanced et best utilisent RapidOCR avec les modèles PP-OCR ONNX épinglés.

::: info Compatibilité de l’OCR coréen L’OCR rapide prend en charge auto, en, de, es, fr, zh et ja, mais pas le coréen (ko). Le coréen nécessite le pack OCR précis et balanced ou best. Le pack fonctionne dans les conteneurs Linux amd64 et arm64 officiels, y compris sur les hôtes NVIDIA où l’OCR reste exécuté sur le CPU. Un système non pris en charge reçoit une erreur de compatibilité explicite, sans repli silencieux vers fast. Le coréen avec fast ou l’alias historique tesseract est refusé avant la mise en file avec FEATURE_INCOMPATIBLE et fast-korean-unsupported. :::

Point de terminaison API

POST /api/v1/tools/image/ocr

Traitement : L’OCR est toujours asynchrone. Après validation et mise en file d’attente, le point de terminaison renvoie immédiatement 202 Accepted avec un jobId. Suivez le flux de progression SSE de la tâche jusqu’à son événement final complete ou failed ; le result d’un événement réussi contient les champs OCR.

Pack OCR précis : Runtime ocr en option (environ 208-234 MiB à télécharger et 409-488 MiB installés, selon la cible). fast ne nécessite pas ce pack ; le programme d'installation vérifie les tailles exactes liées par l'index signé.

Paramètres

Paramètre	Type	Requis	Défaut	Description
file	file	Oui	-	Fichier image (en plusieurs parties), jusqu'à 512 MiB encodés et 40 mégapixels décodés ; une limite inférieure de téléchargement par l'opérateur s'applique toujours
quality	string	Non	Dynamique	Niveau de qualité : fast (Tesseract), balanced (RapidOCR avec les petits modèles PP-OCRv6) ou best (les modèles PP-OCRv6 moyens de plus haute précision avec une variante de notation calibrée)
language	string	Non	"auto"	Indication de langue : auto, en, de, fr, es, zh, ja, ko
enhance	boolean	Non	Dépend du niveau	Améliorer le contraste local avant la reconnaissance. Fast l'applique directement ; Equilibré et Meilleur conservent la variante uniquement lorsque la notation calibrée améliore le résultat. La valeur par défaut est true pour best et false pour fast/balanced
engine	string	Non	-	Alias ​​de compatibilité obsolète. Utilisez plutôt quality. tesseract correspond à fast ; la valeur paddleocr héritée est mappée à balanced mais ne charge pas PaddlePaddle

Lorsque quality et engine sont omis, SnapOtter choisit le meilleur niveau disponible dans cet ordre : best, balanced, fast. Pour le coréen, fast n’est jamais choisi : best, puis balanced sont utilisés, sinon une erreur d’installation ou de compatibilité du moteur précis est renvoyée.

Exemple de requête

curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
  -F "file=@document.png" \
  -F 'settings={"quality":"best","language":"en","enhance":true}'

Réponse acceptée (202)

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

Progression et résultat (SSE)

Connectez-vous à GET /api/v1/jobs/{jobId}/progress avec le jobId renvoyé par la réponse 202 (ou le clientJobId fourni). Gardez le flux ouvert jusqu’à l’événement final complete ou failed. Une trame finale réussie contient la sortie OCR dans result :

{
  "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.2.0",
    "modelVersion": "PP-OCRv6-best-v1-medium"
  }
}

Les échecs de traitement arrivent dans le champ error de l’événement final failed ; ils ne sont pas renvoyés sous forme de réponse HTTP 422 après la mise en file d’attente.

Remarques

• fast est toujours disponible dans les images SnapOtter prises en charge. balanced et best nécessitent le pack OCR précis en option.
• Tesseract intégré ajoute environ 25 MiB à l'image officielle. Le pack précis est stocké dans /data/ai, et non intégré à l'image.
• Le pack précis est publié pour les conteneurs officiels Linux amd64 et arm64. Il utilise délibérément le fournisseur CPU de ONNX Runtime, y compris sur les hôtes NVIDIA, il ne dépend donc pas des bibliothèques CUDA ou de la compatibilité GPU. Les installations bare-metal sources et prédéfinies utilisent Fast OCR à moins qu'elles ne fournissent leur propre environnement d'exécution compatible.
• Le result final réussi contient à la fois le texte extrait dans text et un artefact .txt téléchargeable dans downloadUrl.
• SnapOtter honore un niveau explicitement demandé. Si balanced ou best n'est pas disponible, API renvoie 501 avec FEATURE_NOT_INSTALLED ou FEATURE_INCOMPATIBLE ; il ne rétrograde jamais silencieusement la demande à un autre niveau.
• Un résultat vide réussi reste un résultat vide. Les échecs d'exécution renvoient une erreur au lieu de réessayer avec un moteur de qualité inférieure.
• Le result final réussi signale à la fois requestedQuality et actualQuality, ainsi que les versions du moteur, de l'appareil, du fournisseur, de l'exécution et du modèle, ainsi que tous les avertissements.
• Prend en charge les formats d'entrée HEIC/HEIF, RAW, TGA, PSD, EXR et HDR via un décodage automatique.
• Les entrées codées surdimensionnées renvoient 413. Les images de plus de 40 mégapixels et les réponses OCR dépassant leurs limites de sortie sont rejetées au lieu d'être partiellement traitées.