SnapOtter/apps/docs/ar/api/ai.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
مرجع محرك الذكاء الاصطناعي مع جميع أدوات التعلم الآلي المحلية. إزالة الخلفية، وتحسين الدقة، وقراءة النصوص (OCR)، واكتشاف الوجوه، وترميم الصور، والمزيد.	778d92965216	aa9a56cdddc7	human

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

تقوم حزمة @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 الجانبية موزّعة على أربع طرائق (صورة، وصوت، وفيديو، ومستند)، بالإضافة إلى أداتين ذواتَي قدرات ذكاء اصطناعي اختيارية. تعمل جميع النماذج محليًا، ولا حاجة للإنترنت بعد التنزيل الأولي للنموذج.

::: 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. :::

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

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	تطبيق معالجة مسبقة لإزالة العلامة المائية (مرشّح وسيط)

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	فرض إخراج مربّع