mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00

Files

T

SnapOtterandGitHub 5f21588f6c chore: prepare the 2.2.0 release (#660 )

Bumps every version surface to 2.2.0, fixes a latent version-coupling bug in the
OCR runtime tests, and stops an absent GPU runner from silently stalling a
release.

Version surfaces: scripts/sync-version.sh covers the 11 workspaces, APP_VERSION,
and the docs release commands across all locales. Root package.json plus the
three surfaces the script never reaches are done by hand: the DOCKERHUB.md banner
and tag table, the docker-tags.md pinning table in 21 locales, and the example
runtimeVersion in tools/image/ocr.md in 21 locales. The release-notes archive step
is deliberately not pre-run, so the notes text stays editable until the release.

Latent bug: runtime-state rejects any runtime whose compatibility.snapotterVersion
is not exactly APP_VERSION, and five fixtures pinned the literal 2.1.0. Since
semantic-release rewrites APP_VERSION on every release, the first PR after any
bump would have gone red for a reason nobody would trace to the release. The
fixtures now derive from APP_VERSION.

GPU runner: sign-ocr-index needs verify-ocr-nvidia on self-hosted hardware, and
the gated manifest job needs ai-bundles, so a missing runner queued instead of
failing and produced no image tags. preflight-gpu-runner claims the same labels
with no dependencies, so it is scheduled first and validates the GPU before the
90-minute build. An API preflight is impossible because listing self-hosted
runners needs Administration:read, which GITHUB_TOKEN cannot hold, so RELEASE.md
carries the maintainer-side check.

2026-07-27 22:09:31 +08:00

7.8 KiB

Raw Blame History

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.2.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 التي تتجاوز حدود الإخراج المحددة الخاصة بها بدلاً من معالجتها جزئيًا.

7.8 KiB Raw Blame History