مرجع محرك الذكاء الاصطناعي

تقوم حزمة @snapotter/ai بتنسيق الأدوات الأصلية وأوقات تشغيل Python لعمليات ML المحلية. تستخدم معظم أدوات ML Python sidecar المستمر لبدء التشغيل الدافئ السريع. OCR منفصل عمدا: يستدعي fast ثنائي Tesseract الأصلي، بينما يستخدم balanced وbest JSONL dispatcher المستمر المخصص والمثبت على جيل RapidOCR النشط غير القابل للتغيير ضمن /data/ai/v3. يحمل كل طلب generation lease. أثناء الترقية، يقوم SnapOtter بتشغيل smoke test على المرشح قبل التنشيط، ويتحول تلقائيًا إلى dispatcher الجديد، ثم يستنزف الجيل القديم قبل garbage collection.

يتم اكتشاف NVIDIA CUDA تلقائيًا ويتم استخدامه في أوقات التشغيل التي تدعمه. يستخدم OCR CPU على كل مضيف، بما في ذلك الأنظمة التي تحتوي على وحدات معالجة الرسومات NVIDIA، مع تجنب CUDA واقتران برنامج التشغيل لهذه الأداة.

تسريع وحدة معالجة الرسومات المدمجة من Intel/AMD عبر VA-API أو Quick Sync أو OpenCL غير مدعوم لاستدلال الذكاء الاصطناعي حاليًا. تعيين /dev/dri داخل حاوية لا يسرّع أدوات Python الجانبية هذه ما لم تتوفر وحدة معالجة رسومات NVIDIA قادرة على تشغيل CUDA.

19 أداة ذكاء اصطناعي تعمل عبر Python الجانبية موزّعة على أربع طرائق (صورة، وصوت، وفيديو، ومستند)، بالإضافة إلى أداتين ذواتَي قدرات ذكاء اصطناعي اختيارية. تعمل جميع النماذج محليًا، ولا حاجة للإنترنت بعد التنزيل الأولي للنموذج.

توافق 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.

البنية المعمارية

Node.js Tool Route
      |
      v
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
 +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
 |
 +-- Isolated OCR runtime (persistent JSONL dispatcher)
 |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
 |
 `-- Python dispatcher (persistent process, "ai" profile)
      |
      |-- remove_bg.py        (rembg / BiRefNet)
      |-- upscale.py          (RealESRGAN)
      |-- inpaint.py          (LaMa ONNX)
      |-- outpaint.py         (LaMa canvas expansion)
      |-- detect_faces.py     (MediaPipe)
      |-- face_landmarks.py   (MediaPipe landmarks)
      |-- enhance_faces.py    (GFPGAN / CodeFormer)
      |-- colorize.py         (DDColor)
      |-- noise_removal.py    (SCUNet / tiered denoising)
      |-- red_eye_removal.py  (landmark + color analysis)
      |-- restore.py          (scratch repair + enhancement + denoising)
      |-- transcribe.py       (faster-whisper speech-to-text)
      +-- install_feature.py  (on-demand bundle installer)

يستبدل ملف تعريف موزّع "docs" منفصل قائمةَ السماح الخاصة بالذكاء الاصطناعي بنصوص معالجة المستندات (doc_pagecount، doc_health، doc_flatten، doc_redact، doc_text، doc_to_word، doc_metadata، doc_html_pdf) ويتجاوز عمليات استيراد التعلم الآلي الثقيلة.

المهل الزمنية: 300 ثانية افتراضيًا؛ وتحصل قراءة النصوص (OCR) وإزالة الخلفية بـ BiRefNet على 600 ثانية.

حزم الميزات

تُحزَّم نماذج الذكاء الاصطناعي حسب حزمة التبعيات المشتركة، وليس أرشيفًا واحدًا لكل أداة. يمكن لحزمة الميزات أن تُفعّل عدة أدوات عندما تستخدم العائلة نفسها من النماذج، أو حزم Python (wheels)، أو المكتبات الأصلية. يبقي هذا صورة Docker الخاصة بالإصدار أصغر ويتجنب تخزين نسخ مكررة من نماذج تنعيم الخلفية، واكتشاف الوجوه، وقراءة النصوص، والترميم، والكلام نفسها.

تشحن صورة Docker التطبيقَ إضافةً إلى وقت التشغيل المشترك. تُنزَّل أرشيفات النماذج الكبيرة عند الطلب إلى وحدة التخزين الدائمة /data/ai، ثم تُعاد استخدامها من قِبل كل أداة تحتاجها. إذا كانت الحزمة مثبّتة بالفعل لأن أداة أخرى احتاجتها، فإن تفعيل أداة جديدة معتمدة عليها لا يُعيد تنزيل تلك الحزمة.

تتطلب معظم أدوات الذكاء الاصطناعي حزمة ميزات واحدة أو أكثر قبل أن تتمكن من التشغيل. تقوم واجهة المستخدم الإدارية بتثبيت تلك عن طريق الأداة من خلال POST /api/v1/admin/tools/:toolId/features/install، الذي يحل قائمة الحزم الكاملة، ويتخطى الحزم المثبتة بالفعل، ويضع التنزيلات المفقودة فقط في قائمة الانتظار. على سبيل المثال، تمكين صورة جواز السفر في قائمة انتظار المثيلات الجديدة background-removal وface-detection؛ تمكينه بعد تثبيت بالفعل قوائم الانتظار إزالة الخلفية فقط face-detection. OCR هو الاستثناء لأن fast لا يحتاج إلى حزمة؛ قم بتثبيت وقت التشغيل الدقيق الاختياري من خلال واجهة المستخدم أو POST /api/v1/admin/features/ocr/install.

الحزمة	الحجم	مجموعة التبعيات المشتركة	الأدوات التي تستخدمها
`background-removal`	4-5 GB	تنعيم الخلفية rembg / BiRefNet	remove-background, passport-photo, transparency-fixer, background-replace, blur-background
`face-detection`	200-300 MB	اكتشاف الوجوه والمعالم في MediaPipe	blur-faces, red-eye-removal, smart-crop
`object-eraser-colorize`	1-2 GB	الرسم الداخلي/الخارجي بـ LaMa و DDColor	erase-object, colorize, ai-canvas-expand
`upscale-enhance`	5-6 GB	RealESRGAN و GFPGAN / CodeFormer وإزالة التشويش	upscale, enhance-faces, noise-removal
`photo-restoration`	4-5 GB	مسار إصلاح الخدوش والترميم	restore-photo
`ocr`	~208-234 MiB تنزيل / ~409-488 MiB مثبتة	اختياري RapidOCR 3.9.1، ONNX Runtime 1.20.1، ونماذج PP-OCR المثبتة	ocr وocr-pdf (`balanced` و`best` فقط)
`transcription`	~600 MB	نماذج تحويل الكلام إلى نص faster-whisper	transcribe-audio, auto-subtitles

أدوات ذات تبعيات عبر عدة حزم:

الأداة	الحزم المطلوبة	السبب
`passport-photo`	`background-removal`، `face-detection`	يزيل الخلفية، ثم يستخدم معالم الوجه لتأطير القص وفق قواعد صور جواز السفر والهوية.
`enhance-faces`	`upscale-enhance`، `face-detection`	يكتشف الوجوه قبل تشغيل تحسين GFPGAN أو CodeFormer على مناطق الوجه المحددة.

تتوفر الأداة فقط عند تثبيت جميع الحزم المطلوبة، باستثناء OCR: تظل طبقة fast المضمنة متاحة بدون حزمة OCR الاختيارية. عمليات التثبيت الجزئية صالحة ويتم التعامل معها بشكل متزايد: تتم إعادة استخدام الحزم المثبتة، وتظهر الحزم المفقودة كتنزيلات، ويتم تشغيل عمليات التثبيت الموضوعة في قائمة الانتظار واحدًا تلو الآخر حتى لا يتم تعديل بيئة Python المشتركة بشكل متزامن.

التثبيت الدقيق لوقت تشغيل OCR

تعد حزمة OCR الدقيقة بمثابة وقت تشغيل خاص بالمنصة لحاوية Linux amd64 أو Linux arm64 الرسمية. يستخدم الإصدار amd64 Python 3.12؛ يستخدم الإصدار arm64 Python 3.11. يعمل كلا الإصدارين على تشغيل RapidOCR من خلال ONNX Runtime's CPUExecutionProvider، لذا فإن نفس الحزمة تعمل على وحدة المعالجة المركزية (CPU) فقط ومضيفي NVIDIA Docker. يتطلب وقت التشغيل الدقيق ما لا يقل عن 4 GiB من الذاكرة الفعالة: الحد الأقصى للحاوية التي تم تكوينها cgroup، خلاف ذلك الذاكرة المضيفة. يتم رفض النظام الموجود أسفل الحد الأدنى من التوافق الموقع قبل التنزيل. لا ينطبق هذا المتطلب على Fast OCR المدمج. تم رفض إصدارات Bare-metal لأنه لا يمكن استنتاج libc و Python ABI بشكل آمن؛ يظل OCR السريع متاحًا عندما يوفر المضيف Tesseract و Ghostscript.

يكون المنتج الاختياري حوالي 208-234 MiB مضغوطًا و409-488 MiB مستخرجًا، اعتمادًا على البنية. يربط الفهرس الموقع عدد البايتات المضغوطة والمستخرجة بدقة والذي يفرضه المثبت. يضيف Tesseract المدمج حوالي 25 MiB إلى الصورة الرسمية ولا يحتاج إلى ملفات في /data/ai.

يجلب التثبيت عبر الإنترنت فهرس الإصدار الموقع والمحتوى المحدد الذي يتناوله النظام الأساسي الحالي. يتحقق SnapOtter من توقيع فهرس Ed25519، وحجم القطعة الأثرية، وملخص SHA-256، وملخصات النموذج، والمسارات، وأوضاع الملفات، و smoke test المرحلي قبل تنشيط الجيل الجديد ذريًا. يؤدي التثبيت الفاشل إلى ترك الجيل السليم السابق نشطًا.

للتثبيت الهوائي، قم بتحميل كل من ocr-runtime-index.json الخاص بالإصدار وأرشيف وقت تشغيل OCR المطابق إلى POST /api/v1/admin/features/import باستخدام حقول متعددة الأجزاء تسمى index وarchive. يطبق الاستيراد دون اتصال نفس عمليات التحقق من التوقيع والتجزئة والاستخراج والتوافق واختبار الدخان مثل التثبيت عبر الإنترنت؛ يتم رفض الأرشيف الذي لا يحتوي على الفهرس الموقع الموثوق به.

إزالة الخلفية

مسار الأداة: remove-background
النموذج: rembg مع BiRefNet (الافتراضي) أو متغيرات U2-Net

المعامل	النوع	الافتراضي	الوصف
`model`	نص	-	متغير النموذج (تجاوز اختياري)
`backgroundType`	نص	`"transparent"`	أحد: `transparent`، `color`، `gradient`، `blur`، `image`
`backgroundColor`	نص	-	لون سداسي عشري لخلفية موحّدة
`gradientColor1`	نص	-	لون التدرّج الأول
`gradientColor2`	نص	-	لون التدرّج الثاني
`gradientAngle`	رقم	-	زاوية التدرّج بالدرجات
`blurEnabled`	منطقي	-	تفعيل تأثير طمس الخلفية
`blurIntensity`	رقم (0-100)	-	شدة الطمس
`shadowEnabled`	منطقي	-	تفعيل الظل المُسقَط على الموضوع
`shadowOpacity`	رقم (0-100)	-	تعتيم الظل
`outputFormat`	نص	-	تنسيق الإخراج: `png` أو `webp` أو `avif`
`edgeRefine`	عدد صحيح (0-3)	-	مستوى تنقيح الحواف
`decontaminate`	منطقي	-	إزالة تسرّب الألوان من الحواف

استبدال الخلفية

مسار الأداة: background-replace
النموذج: rembg / BiRefNet (مشترك مع remove-background)

يزيل الخلفية ويستبدلها بلون موحّد أو تدرّج لوني.

المعامل	النوع	الافتراضي	الوصف
`backgroundType`	`"color"` \| `"gradient"`	`"color"`	وضع الخلفية
`color`	نص	`"#ffffff"`	لون الخلفية السداسي العشري (عندما يكون `backgroundType` هو `color`)
`gradientColor1`	نص	-	لون التدرّج السداسي العشري الأول
`gradientColor2`	نص	-	لون التدرّج السداسي العشري الثاني
`gradientAngle`	عدد صحيح (0-360)	`180`	زاوية التدرّج بالدرجات
`feather`	عدد صحيح (0-20)	`0`	نصف قطر تنعيم الحواف
`format`	`"png"` \| `"webp"`	`"png"`	تنسيق الإخراج

طمس الخلفية

مسار الأداة: blur-background
النموذج: rembg / BiRefNet (مشترك مع remove-background)

يطمس الخلفية مع إبقاء الموضوع حادًا.

المعامل	النوع	الافتراضي	الوصف
`intensity`	عدد صحيح (1-100)	`50`	شدة الطمس
`feather`	عدد صحيح (0-20)	`0`	نصف قطر تنعيم الحواف
`format`	`"png"` \| `"webp"`	`"png"`	تنسيق الإخراج

تحسين دقة الصورة

مسار الأداة: upscale
النموذج: RealESRGAN (مع الرجوع إلى Lanczos عند عدم التوفر)

المعامل	النوع	الافتراضي	الوصف
`scale`	رقم	`2`	عامل تحسين الدقة
`model`	نص	`"auto"`	متغير النموذج
`faceEnhance`	منطقي	`false`	تطبيق مرور تحسين الوجه بـ GFPGAN
`denoise`	رقم	`0`	قوة إزالة التشويش
`format`	نص	`"auto"`	تجاوز تنسيق الإخراج
`quality`	رقم	`95`	جودة الإخراج (1-100)

قراءة النصوص (OCR) / استخراج النص

مسار الأداة: ocr
النماذج: Tesseract (fast)؛ RapidOCR مع نماذج PP-OCRv6 الصغيرة (balanced)؛ الطرازات المتوسطة PP-OCRv6 مع تسجيل متغير مُعاير (best)

المعامل	النوع	الافتراضي	الوصف
`quality`	`"fast"` \| `"balanced"` \| `"best"`	متحرك	عند حذف `quality` و`engine`، يختار SnapOtter أعلى مستوى متاح بالترتيب: `best` ثم `balanced` ثم `fast`. لا تختار اللغة الكورية `fast` أبداً؛ بل تستخدم `best` ثم `balanced`، أو تُرجع خطأ تثبيت أو توافق لوقت التشغيل الدقيق.
`language`	نص	`"auto"`	اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko`
`enhance`	منطقية	تعتمد على الطبقة	تحسين التباين المحلي. سريع يطبقه مباشرة؛ تحافظ الطبقات الدقيقة على المتغير فقط عندما يؤدي تسجيل المعايرة إلى تحسين OCR. الإعدادات الافتراضية للأفضل
`engine`	خيط	-	الاسم المستعار للتوافق مهمل. تعيين `tesseract` إلى `fast` وقيمة `paddleocr` القديمة إلى `balanced`؛ لا يتم تحميل PaddlePaddle

إرجاع النص المستخرج بالإضافة إلى بيانات تعريف المصدر: المحرك، والجودة المطلوبة والفعلية، والجهاز، والموفر، وحالة التدهور، والتحذيرات، وإصدارات وقت التشغيل/الطراز الدقيقة عند الاقتضاء. طلبات الجودة الصريحة لا تعود أبدًا إلى مستوى آخر. في حالة عدم توفر balanced أو best، تقوم API بإرجاع FEATURE_NOT_INSTALLED أو FEATURE_INCOMPATIBLE بدلاً من تشغيل fast بصمت.

قراءة نصوص PDF

مسار الأداة: ocr-pdf
النماذج: نظام الطبقات نفسه المستخدم في قراءة نصوص الصور

يستخرج النص من مستندات PDF الممسوحة ضوئيًا باستخدام قراءة النصوص المدعومة بالذكاء الاصطناعي، صفحة بصفحة.

المعامل	النوع	الافتراضي	الوصف
`quality`	`"fast"` \| `"balanced"` \| `"best"`	متحرك	عند حذف `quality` و`engine`، يختار SnapOtter أعلى مستوى متاح بالترتيب: `best` ثم `balanced` ثم `fast`. لا تختار اللغة الكورية `fast` أبداً؛ بل تستخدم `best` ثم `balanced`، أو تُرجع خطأ تثبيت أو توافق لوقت التشغيل الدقيق.
`language`	نص	`"auto"`	اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko`
`pages`	نص	`"all"`	تحديد الصفحات: `"all"`، `"1-3"`، `"1,3,5"`
`enhance`	منطقية	تعتمد على الطبقة	تحسين التباين المحلي. سريع يطبقه مباشرة؛ تحافظ الطبقات الدقيقة على المتغير فقط عندما يؤدي تسجيل المعايرة إلى تحسين OCR. الإعدادات الافتراضية للأفضل
`engine`	خيط	-	الاسم المستعار للتوافق مهمل. تعيين `tesseract` إلى `fast` وقيمة `paddleocr` القديمة إلى `balanced`؛ لا يتم تحميل PaddlePaddle

تنطبق نفس قاعدة عدم الرجوع إلى الإصدار السابق على PDF OCR. يتم تنقيط صفحات PDF قبل التعرف عليها، ويمكن لطلب واحد تحديد 50 صفحة على الأكثر.

طمس الوجوه / المعلومات الشخصية

مسار الأداة: blur-faces
النموذج: اكتشاف الوجوه بـ MediaPipe

المعامل	النوع	الافتراضي	الوصف
`blurRadius`	رقم (1-100)	`30`	نصف قطر طمس غاوس
`sensitivity`	رقم (0-1)	`0.5`	عتبة ثقة الاكتشاف

تحسين الوجه

مسار الأداة: enhance-faces
النماذج: GFPGAN، CodeFormer

المعامل	النوع	الافتراضي	الوصف
`model`	`"auto"` \| `"gfpgan"` \| `"codeformer"`	`"auto"`	نموذج التحسين
`strength`	رقم (0-1)	`0.8`	قوة التحسين
`sensitivity`	رقم (0-1)	`0.5`	عتبة اكتشاف الوجه
`onlyCenterFace`	منطقي	`false`	تحسين الوجه الأكثر مركزية فقط

التلوين بالذكاء الاصطناعي

مسار الأداة: colorize
النموذج: DDColor (مع الرجوع إلى OpenCV DNN)

يحوّل الصور بالأبيض والأسود أو ذات التدرّج الرمادي إلى ألوان كاملة.

المعامل	النوع	الافتراضي	الوصف
`intensity`	رقم (0-1)	`1.0`	قوة تشبّع الألوان
`model`	`"auto"` \| `"ddcolor"` \| `"opencv"`	`"auto"`	متغير النموذج

إزالة التشويش

مسار الأداة: noise-removal
النموذج: SCUNet (مسار إزالة تشويش متدرّج)

المعامل	النوع	الافتراضي	الوصف
`tier`	`"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"`	`"balanced"`	طبقة المعالجة
`strength`	رقم (0-100)	`50`	قوة إزالة التشويش
`detailPreservation`	رقم (0-100)	`50`	مقدار التفاصيل المراد الحفاظ عليها؛ القيمة الأعلى تُبقي نسيجًا أكثر
`colorNoise`	رقم (0-100)	`30`	قوة تقليل تشويش الألوان
`format`	نص	`"original"`	تنسيق الإخراج: `original`، `png`، `jpeg`، `webp`، `avif`، `jxl`
`quality`	رقم (1-100)	`90`	جودة ترميز الإخراج

إزالة العين الحمراء

مسار الأداة: red-eye-removal

يكتشف معالم الوجه، ويحدد مناطق العينين، ويصحح فرط تشبّع القناة الحمراء.

المعامل	النوع	الافتراضي	الوصف
`sensitivity`	رقم (0-100)	`50`	عتبة اكتشاف البكسل الأحمر
`strength`	رقم (0-100)	`70`	قوة التصحيح
`format`	نص	-	تجاوز تنسيق الإخراج (اختياري)
`quality`	رقم (1-100)	`90`	جودة الإخراج

ترميم الصور

مسار الأداة: restore-photo

مسار متعدد الخطوات للصور القديمة أو التالفة: اكتشاف الخدوش/التمزقات وإصلاحها، وتحسين الوجه، وإزالة التشويش، والتلوين الاختياري.

المعامل	النوع	الافتراضي	الوصف
`scratchRemoval`	منطقي	`true`	اكتشاف الخدوش والتمزقات وإصلاحها
`faceEnhancement`	منطقي	`true`	تطبيق مرور تحسين الوجه
`fidelity`	رقم (0-1)	`0.7`	قوة تحسين الوجه (الأعلى = أكثر تحفظًا)
`denoise`	منطقي	`true`	تطبيق مرور إزالة التشويش
`denoiseStrength`	رقم (0-100)	`25`	قوة إزالة التشويش
`colorize`	منطقي	`false`	التلوين بعد الترميم
`colorizeStrength`	رقم (0-100)	`85`	شدة التلوين

صورة جواز السفر

مسار الأداة: passport-photo
النماذج: معالم الوجه بـ MediaPipe + إزالة الخلفية بـ BiRefNet

سير عمل من مرحلتين: التحليل (اكتشاف الوجه + إزالة الخلفية) ثم التوليد (القص، وتغيير الحجم، والتبليط). يدعم أكثر من 37 دولة عبر 6 مناطق.

المرحلة 1: التحليل

POST /api/v1/tools/image/passport-photo/analyze

يقبل ملف صورة (متعدد الأجزاء). يُرجِع بيانات معالم الوجه، ومعاينة بترميز base64، وأبعاد الصورة.

المرحلة 2: التوليد

POST /api/v1/tools/image/passport-photo/generate

يقبل جسم JSON يحتوي على نتائج المرحلة 1 إضافةً إلى إعدادات التوليد:

المعامل	النوع	الافتراضي	الوصف
`jobId`	نص	(مطلوب)	معرّف المهمة من المرحلة 1
`filename`	نص	(مطلوب)	اسم الملف الأصلي من المرحلة 1
`countryCode`	نص	(مطلوب)	رمز الدولة ISO (مثل `US`، `GB`، `IN`)
`documentType`	نص	`"passport"`	نوع المستند
`bgColor`	نص	`"#FFFFFF"`	لون الخلفية السداسي العشري
`printLayout`	نص	`"none"`	تخطيط الطباعة: `none`، `4x6`، `a4`، `letter`
`maxFileSizeKb`	رقم	`0`	الحد الأقصى لحجم الملف بالكيلوبايت (0 = بلا حد)
`dpi`	رقم (72-1200)	`300`	دقة الإخراج DPI
`customWidthMm`	رقم	-	عرض مخصص بالمليمتر (يتجاوز مواصفات الدولة)
`customHeightMm`	رقم	-	ارتفاع مخصص بالمليمتر (يتجاوز مواصفات الدولة)
`zoom`	رقم (0.5-3)	`1`	عامل التكبير
`adjustX`	رقم	`0`	تعديل الموضع الأفقي
`adjustY`	رقم	`0`	تعديل الموضع الرأسي
`landmarks`	كائن	(مطلوب)	المعالم من المرحلة 1
`imageWidth`	رقم	(مطلوب)	عرض الصورة من المرحلة 1
`imageHeight`	رقم	(مطلوب)	ارتفاع الصورة من المرحلة 1

محو الأجسام (الرسم الداخلي)

مسار الأداة: erase-object
النموذج: LaMa عبر ONNX Runtime

يُرسَل القناع كـجزء ملف ثانٍ (اسم الحقل mask)، وليس بترميز base64. تشير البكسلات البيضاء في القناع إلى المناطق المراد محوها. يُرسَل الإعدادان format وquality كحقول نموذج علوية المستوى.

المعامل	النوع	الافتراضي	الوصف
`file`	ملف	(مطلوب)	الصورة المصدر (متعددة الأجزاء)
`mask`	ملف	(مطلوب)	صورة القناع (متعددة الأجزاء، اسم الحقل `mask`، الأبيض = محو)
`format`	نص	`"auto"`	تنسيق الإخراج: `auto`، `png`، `jpg`، `jpeg`، `webp`، `tiff`، `gif`، `avif`، `heic`، `heif`، `jxl`
`quality`	عدد صحيح (1-100)	`95`	جودة الإخراج

مُسرَّع بـ CUDA عند توفر وحدة معالجة رسومات NVIDIA.

توسيع اللوحة بالذكاء الاصطناعي

مسار الأداة: ai-canvas-expand
النموذج: الرسم الخارجي القائم على LaMa

يوسّع لوحة الصورة في أي اتجاه ويملأ المناطق الجديدة بمحتوى مولّد بالذكاء الاصطناعي يطابق الصورة الموجودة.

المعامل	النوع	الافتراضي	الوصف
`extendTop`	عدد صحيح	`0`	البكسلات المراد تمديدها في الأعلى
`extendRight`	عدد صحيح	`0`	البكسلات المراد تمديدها على اليمين
`extendBottom`	عدد صحيح	`0`	البكسلات المراد تمديدها في الأسفل
`extendLeft`	عدد صحيح	`0`	البكسلات المراد تمديدها على اليسار
`tier`	`"fast"` \| `"balanced"` \| `"high"`	`"balanced"`	طبقة الجودة
`format`	نص	`"auto"`	تنسيق الإخراج: `auto`، `png`، `jpg`، `jpeg`، `webp`، `tiff`، `gif`، `avif`، `heic`، `heif`، `jxl`
`quality`	عدد صحيح (1-100)	`95`	جودة الإخراج

يجب أن يكون اتجاه تمديد واحد على الأقل أكبر من 0.

القص الذكي

مسار الأداة: smart-crop
النموذج: اكتشاف الوجوه بـ MediaPipe (وضع الوجه فقط)

المعامل	النوع	الافتراضي	الوصف
`mode`	نص	`"subject"`	استراتيجية القص: `subject`، `face`، `trim`
`strategy`	`"attention"` \| `"entropy"`	`"attention"`	استراتيجية وضع الموضوع
`width`	عدد صحيح	-	عرض الإخراج
`height`	عدد صحيح	-	ارتفاع الإخراج
`padding`	عدد صحيح (0-50)	`0`	نسبة الحشو حول الموضوع
`facePreset`	نص	`"head-shoulders"`	التأطير المُعَدّ مسبقًا عند `mode=face`
`sensitivity`	رقم (0-1)	`0.5`	عتبة اكتشاف الوجه
`threshold`	عدد صحيح (0-255)	`30`	عتبة اكتشاف الخلفية (وضع التشذيب)
`padToSquare`	منطقي	`false`	حشو النتيجة المُشذَّبة إلى مربع
`padColor`	نص	`"#ffffff"`	لون الخلفية للحشو المربّع
`targetSize`	عدد صحيح	-	الحجم المستهدف للإخراج المحشو (بالبكسل)
`quality`	عدد صحيح (1-100)	-	جودة الإخراج

تُقبَل القيم القديمة mode وهي attention وcontent وتُعيَّن إلى subject وtrim على التوالي.

الإعدادات المسبقة للوجه:

الإعداد المسبق	الأفضل لِـ
`closeup`	لقطات الرأس
`head-shoulders`	صور الملف الشخصي
`upper-body`	LinkedIn / رسمي
`half-body`	الجزء العلوي الكامل من الجسم

نسخ الصوت

مسار الأداة: transcribe-audio
النموذج: faster-whisper

يحوّل الكلام إلى نص. يدعم تنسيقات إخراج النص العادي و SRT و VTT.

المعامل	النوع	الافتراضي	الوصف
`language`	نص	`"auto"`	اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko`، `id`، `th`، `vi`
`outputFormat`	`"txt"` \| `"srt"` \| `"vtt"`	`"txt"`	تنسيق الإخراج

الترجمات التلقائية

مسار الأداة: auto-subtitles
النموذج: faster-whisper (يستخرج الصوت من الفيديو، ثم ينسخه)

يولّد ملفات ترجمة من مسار الصوت في الفيديو.

المعامل	النوع	الافتراضي	الوصف
`language`	نص	`"auto"`	اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko`، `id`، `th`، `vi`
`format`	`"srt"` \| `"vtt"`	`"srt"`	تنسيق ملف الترجمة للإخراج

مُصلِح شفافية PNG

مسار الأداة: transparency-fixer
النموذج: تنعيم BiRefNet عالي الدقة (بدقة 2048x2048)

يصلح ملفات PNG "الشفافة الزائفة" حيث أُزيلت الخلفية لكنها تركت وراءها هُدبًا، أو هالات، أو عيوبًا شبه شفافة. يستخدم نموذج التنعيم عالي الدقة من BiRefNet لإنتاج قناة ألفا نظيفة، ثم يطبّق معالجة إزالة هُدب قابلة للتهيئة لإزالة تلوث الألوان على طول الحواف.

سلسلة الرجوع عند نفاد الذاكرة (OOM): إذا تجاوز تنعيم BiRefNet عالي الدقة الذاكرة المتاحة، ترجع الأداة تلقائيًا إلى birefnet-general، ثم إلى u2net.

المعامل	النوع	الافتراضي	الوصف
`defringe`	رقم (0-100)	`30`	قوة إزالة هُدب الحواف لإزالة تلوث الألوان
`outputFormat`	`"png"` \| `"webp"`	`"png"`	تنسيق صورة الإخراج
`removeWatermark`	منطقي	`false`	تطبيق معالجة مسبقة لإزالة العلامة المائية (مرشّح وسيط)

bash

curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
  -H "Authorization: Bearer <token>" \
  -F "file=@fake-transparent.png" \
  -F 'settings={"defringe":30,"outputFormat":"png"}'

أدوات ذات قدرات ذكاء اصطناعي اختيارية

الأدوات التالية ليست أدوات Python جانبية لكنها تستخدم ميزات الذكاء الاصطناعي عند تفعيل خيارات معينة.

تحسين الصورة

مسار الأداة: image-enhancement
المحرك: قائم على التحليل (المدرج التكراري والإحصاءات في Sharp)

يحلّل الصورة ويطبّق تصحيحات تلقائية للتعريض، والتباين، وتوازن الأبيض، والتشبّع، والحدة، والتشويش. يدعم أوضاعًا خاصة بالمشهد.

المعامل	النوع	الافتراضي	الوصف
`mode`	`"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"`	`"auto"`	وضع المشهد لضبط التصحيحات
`intensity`	رقم (0-100)	`50`	قوة التصحيح الإجمالية
`corrections.exposure`	منطقي	`true`	تطبيق تصحيح التعريض
`corrections.contrast`	منطقي	`true`	تطبيق تصحيح التباين
`corrections.whiteBalance`	منطقي	`true`	تطبيق تصحيح توازن الأبيض
`corrections.saturation`	منطقي	`true`	تطبيق تصحيح التشبّع
`corrections.sharpness`	منطقي	`true`	تطبيق تصحيح الحدة
`corrections.denoise`	منطقي	`true`	تطبيق إزالة التشويش
`deepEnhance`	منطقي	`false`	تفعيل إزالة التشويش بالذكاء الاصطناعي عبر SCUNet (يتطلب حزمة `upscale-enhance`)

تتوفر نقطة نهاية تحليل إضافية عند POST /api/v1/tools/image/image-enhancement/analyze تُرجِع التصحيحات المكتشفة دون تطبيقها.

تغيير الحجم المدرك للمحتوى (نحت الأطراف)

مسار الأداة: content-aware-resize
المحرك: ثنائي caire بلغة Go (ليس Python، لا فائدة من وحدة معالجة الرسومات)

يغيّر حجم الصور بذكاء عن طريق إزالة الأطراف منخفضة الطاقة، مع الحفاظ على المحتوى المهم.

المعامل	النوع	الافتراضي	الوصف
`width`	رقم	-	العرض المستهدف
`height`	رقم	-	الارتفاع المستهدف
`protectFaces`	منطقي	`false`	حماية مناطق الوجه المكتشفة (يتطلب حزمة `face-detection`)
`blurRadius`	رقم (0-20)	`4`	طمس مسبق لحساب الطاقة
`sobelThreshold`	رقم (1-20)	`2`	عتبة حساسية الحواف
`square`	منطقي	`false`	فرض إخراج مربّع

الأساسيات

التحسين

التعديلات

العلامة المائية والتراكب

الأدوات المساعدة

التخطيط

التنسيق

أدوات AI

مرجع محرك الذكاء الاصطناعي

البنية المعمارية

حزم الميزات

التثبيت الدقيق لوقت تشغيل OCR

إزالة الخلفية

استبدال الخلفية

طمس الخلفية

تحسين دقة الصورة

قراءة النصوص (OCR) / استخراج النص

قراءة نصوص PDF

طمس الوجوه / المعلومات الشخصية

تحسين الوجه

التلوين بالذكاء الاصطناعي

إزالة التشويش

إزالة العين الحمراء

ترميم الصور

صورة جواز السفر

المرحلة 1: التحليل

المرحلة 2: التوليد

محو الأجسام (الرسم الداخلي)

توسيع اللوحة بالذكاء الاصطناعي

القص الذكي

نسخ الصوت

الترجمات التلقائية

مُصلِح شفافية PNG

أدوات ذات قدرات ذكاء اصطناعي اختيارية

تحسين الصورة

تغيير الحجم المدرك للمحتوى (نحت الأطراف)

مرجع محرك الذكاء الاصطناعي ​

البنية المعمارية ​

حزم الميزات ​

التثبيت الدقيق لوقت تشغيل OCR ​

إزالة الخلفية ​

استبدال الخلفية ​

طمس الخلفية ​

تحسين دقة الصورة ​

قراءة النصوص (OCR) / استخراج النص ​

قراءة نصوص PDF ​

طمس الوجوه / المعلومات الشخصية ​

تحسين الوجه ​

التلوين بالذكاء الاصطناعي ​

إزالة التشويش ​

إزالة العين الحمراء ​

ترميم الصور ​

صورة جواز السفر ​

المرحلة 1: التحليل ​

المرحلة 2: التوليد ​

محو الأجسام (الرسم الداخلي) ​

توسيع اللوحة بالذكاء الاصطناعي ​

القص الذكي ​

نسخ الصوت ​

الترجمات التلقائية ​

مُصلِح شفافية PNG ​

أدوات ذات قدرات ذكاء اصطناعي اختيارية ​

تحسين الصورة ​

تغيير الحجم المدرك للمحتوى (نحت الأطراف) ​

مرجع محرك الذكاء الاصطناعي

البنية المعمارية

حزم الميزات

التثبيت الدقيق لوقت تشغيل OCR

إزالة الخلفية

استبدال الخلفية

طمس الخلفية

تحسين دقة الصورة

قراءة النصوص (OCR) / استخراج النص

قراءة نصوص PDF

طمس الوجوه / المعلومات الشخصية

تحسين الوجه

التلوين بالذكاء الاصطناعي

إزالة التشويش

إزالة العين الحمراء

ترميم الصور

صورة جواز السفر

المرحلة 1: التحليل

المرحلة 2: التوليد

محو الأجسام (الرسم الداخلي)

توسيع اللوحة بالذكاء الاصطناعي

القص الذكي

نسخ الصوت

الترجمات التلقائية

مُصلِح شفافية PNG

أدوات ذات قدرات ذكاء اصطناعي اختيارية

تحسين الصورة

تغيير الحجم المدرك للمحتوى (نحت الأطراف)