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

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
استخراج النص من الصور محليا مع المدمج في Tesseract أو الدقة العالية الاختيارية RapidOCR وقت التشغيل.	69c851611013	0d453b49db02	human

التعرّف الضوئي على الحروف / استخراج النص

استخراج النص من الصور دون إرسال الصورة إلى خدمة خارجية. تستخدم طبقة fast المدمجة Tesseract. تستخدم طبقات balanced وbest الاختيارية RapidOCR مع نماذج PP-OCR ONNX المثبتة.

::: info توافق OCR الكوري يدعم Fast OCR اللغات auto وen وde وes وfr وzh وja، لكنه لا يدعم الكورية (ko). تتطلب الكورية حزمة OCR الدقيقة ومستوى balanced أو best. تعمل الحزمة على حاويات Linux amd64 وarm64 الرسمية، بما في ذلك مضيفات NVIDIA حيث يبقى OCR على CPU. تُرجع الأنظمة غير المدعومة خطأ توافق صريحاً ولا تعود بصمت إلى fast. كما يُرفض طلب Korean مع fast أو الاسم القديم tesseract قبل وضعه في قائمة الانتظار، مع FEATURE_INCOMPATIBLE والسبب fast-korean-unsupported. :::

نقطة نهاية الـ API

POST /api/v1/tools/image/ocr

المعالجة: يعمل OCR دائماً بشكل غير متزامن. بعد التحقق ووضع المهمة في قائمة الانتظار، تعيد نقطة النهاية فوراً 202 Accepted مع jobId. اتبع تدفق تقدم SSE للمهمة حتى حدث complete أو failed النهائي؛ يحتوي result في حدث النجاح على حقول OCR.

حزمة OCR الدقيقة: وقت تشغيل ocr اختياري (حوالي 208-234 MiB للتنزيل و409-488 MiB مثبتة، حسب الهدف). fast لا يتطلب هذه الحزمة؛ يتحقق المثبت من الأحجام الدقيقة المرتبطة بالفهرس الموقع.

المعاملات

المعامل	النوع	مطلوب	القيمة الافتراضية	الوصف
file	file	نعم	-	ملف صورة (متعدد الأجزاء)، مشفر حتى 512 MiB و40 ميجابكسل مشفر؛ ولا يزال الحد الأدنى للتحميل الخاص بالمشغل مطبقًا
quality	string	لا	متحرك	مستوى الجودة: fast (Tesseract)، balanced (RapidOCR مع موديلات PP-OCRv6 الصغيرة)، أو best (نماذج PP-OCRv6 المتوسطة عالية الدقة مع تسجيل متغير مُعاير)
language	string	لا	"auto"	تلميح اللغة: auto، en، de، fr، es، zh، ja، ko
enhance	boolean	لا	تعتمد على الطبقة	تحسين التباين المحلي قبل التعرف عليه. سريع يطبقه مباشرة؛ يحتفظ الخيار Balanced وBest بالمتغير فقط عندما يؤدي تسجيل المعايرة إلى تحسين النتيجة. الإعدادات الافتراضية هي true لـ best وfalse لـ fast/balanced
engine	string	لا	-	الاسم المستعار للتوافق مهمل. استخدم quality بدلاً من ذلك. يقوم tesseract بتعيين fast؛ يتم تعيين قيمة paddleocr القديمة إلى balanced ولكنها لا تقوم بتحميل PaddlePaddle

عند حذف quality وengine، يختار SnapOtter أعلى مستوى متاح بالترتيب: best ثم balanced ثم fast. لا تختار اللغة الكورية fast أبداً؛ بل تستخدم best ثم balanced، أو تُرجع خطأ تثبيت أو توافق لوقت التشغيل الدقيق.

مثال على الطلب

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

الاستجابة المقبولة (202)

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

التقدم والنتيجة (SSE)

اتصل بالمسار GET /api/v1/jobs/{jobId}/progress باستخدام jobId الذي أعادته استجابة 202 (أو clientJobId الذي قدمته). أبقِ التدفق مفتوحاً حتى حدث complete أو failed النهائي. يحتوي الإطار النهائي الناجح على ناتج OCR في 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.1.0",
    "modelVersion": "PP-OCRv6-best-v1-medium"
  }
}

تصل حالات فشل المعالجة في الحقل error لحدث failed النهائي؛ ولا تُعاد كاستجابة HTTP 422 بعد وضع المهمة في قائمة الانتظار.

ملاحظات

• fast متاح دائمًا في صور SnapOtter المدعومة. يتطلب balanced وbest حزمة OCR الاختيارية الدقيقة.
• يضيف Tesseract المدمج حوالي 25 MiB إلى الصورة الرسمية. يتم تخزين الحزمة الدقيقة في /data/ai، ولا يتم تخزينها في الصورة.
• تم نشر الحزمة الدقيقة لحاويات Linux amd64 و arm64 الرسمية. يستخدم عمدًا موفر ONNX Runtime الخاص بـ CPU، بما في ذلك على مضيفي NVIDIA، لذلك فهو لا يعتمد على مكتبات CUDA أو توافق GPU. تستخدم عمليات تثبيت bare-metal المصدر والمُنشأة مسبقًا Fast OCR ما لم توفر وقت تشغيل متوافقًا خاصًا بها.
• يتضمن result النهائي الناجح كلاً من النص المستخرج في text وملف .txt قابلاً للتنزيل في downloadUrl.
• SnapOtter يكرم الطبقة المطلوبة بشكل صريح. في حالة عدم توفر balanced أو best، تقوم API بإرجاع 501 مع FEATURE_NOT_INSTALLED أو FEATURE_INCOMPATIBLE؛ ولا يؤدي أبدًا إلى خفض مستوى الطلب بصمت إلى مستوى آخر.
• النتيجة الفارغة الناجحة تبقى نتيجة فارغة. تؤدي حالات الفشل في وقت التشغيل إلى ظهور خطأ بدلاً من إعادة المحاولة باستخدام محرك منخفض الجودة.
• يبلغ result النهائي الناجح عن كل من requestedQuality وactualQuality، بالإضافة إلى المحرك والجهاز والموفر ووقت التشغيل وإصدارات الطراز وأي تحذيرات.
• يدعم صيغ الإدخال HEIC/HEIF وRAW وTGA وPSD وEXR وHDR عبر فك الترميز التلقائي.
• تُرجع المدخلات المشفرة كبيرة الحجم 413. يتم رفض الصور التي يزيد حجمها عن 40 ميجابكسل واستجابات OCR التي تتجاوز حدود الإخراج المحددة الخاصة بها بدلاً من معالجتها جزئيًا.