الاستدلال#

توفر Ultralytics Platform استدلالًا عبر المتصفح لاختبار النماذج المدرّبة، ونقاط نهاية مخصصة للوصول البرمجي.

علامة تبويب التنبؤ#

يتضمن كل نموذج ذي أوزان علامة تبويب Predict للاستدلال عبر المتصفح:

1. انتقل إلى نموذجك
2. انقر على علامة التبويب Predict
3. حمّل صورة أو استخدم مثالًا أو افتح كاميرا الويب
4. راجع طبقة العرض الخاصة بالمهمة وملخص التنبؤ والتوقيت والاستجابة الأولية

تُظهر النماذج التي لا تحتوي على أوزان حالة فارغة بدلًا من ذلك — درّب النموذج أو حمّل الأوزان أولًا.

طرق الإدخال#

تدعم لوحة التنبؤ طرق إدخال متعددة:

graph LR
    A[Upload Image]:::start --> D[Auto-Inference]:::proc
    B[Example Image]:::start --> D
    C[Webcam Capture]:::start --> D
    D --> E[Results + Overlays]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

تحميل صورة#

اسحب صورة وأفلتها أو انقر لتحميلها:

• التنسيقات المدعومة: JPEG، PNG، WebP، AVIF، HEIC، JP2، TIFF، BMP
• الحجم الأقصى: 10 MB
• الاستدلال التلقائي: تظهر النتائج تلقائيًا بعد التحميل

صور الأمثلة#

تعرض لوحة التنبؤ ما يصل إلى صورتين تجريبيتين من مجموعة البيانات المرتبطة بنموذجك، مع تفضيل التقسيم val، ثم test، ثم train. إذا لم تكن هناك مجموعة بيانات مرتبطة، تُستخدم الصور الافتراضية:

بالنسبة إلى نماذج OBB، تُعرض بدلًا من ذلك صور جوية لقوارب ومطار.

كاميرا الويب#

حدّد كاميرا الويب أعلى منطقة الصورة لبدء بث مباشر من الكاميرا:

1. امنح إذن الوصول إلى الكاميرا عند ظهور المطالبة
2. انقر على معاينة الفيديو لالتقاط إطار
3. يُجرى الاستدلال تلقائيًا على الإطار الملتقط
4. انقر على العودة إلى كاميرا الويب للرجوع إلى البث المباشر

في علامة التبويب Predict لعملية النشر الخاصة بك، تنفّذ كاميرا الويب الاستدلال باستمرار بدلًا من ذلك. راجع الاستدلال المباشر بالكاميرا.

عرض النتائج#

تعرض نتائج الاستدلال المخرجات المناسبة لمهمة النموذج: مربعات أو أقنعة أو نقاط رئيسية أو مربعات موجّهة أو درجات تصنيف أو تغطية دلالية أو خريطة عمق. تستخدم نتائج الكائنات ألوان الفئات الخاصة بمجموعة البيانات عند توفرها. وتعرض اللوحة أيضًا توقيتات المعالجة المسبقة والاستدلال والمعالجة اللاحقة والشبكة.

تعرض لوحة النتائج ما يلي:

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

معلمات الاستدلال#

اضبط سلوك الاستدلال باستخدام أشرطة التمرير الثلاثة أسفل الصورة (تعرض نماذج العمق حجم الصورة فقط):

عتبة الثقة#

تصفية التنبؤات حسب الثقة:

• أعلى (0.5+): تنبؤات أقل وأكثر موثوقية
• أقل (0.1-0.25): تنبؤات أكثر، مع بعض التشويش
• الافتراضي (0.25): توازن مناسب لمعظم حالات الاستخدام

عتبة IoU#

التحكم في الكبت غير الأقصى:

• أعلى (0.7+): السماح بمزيد من الصناديق المتداخلة
• أقل (0.3-0.5): كبت الاكتشافات المتداخلة بصرامة أكبر
• الافتراضي (0.7): سلوك NMS متوازن لمعظم حالات الاستخدام

التنبؤ بالنشر#

تتضمن كل نقطة نهاية مخصصة قيد التشغيل علامة تبويب Predict في صفحة النشر الخاصة بها. تستخدم هذه العلامة خدمة الاستدلال الخاصة بالنشر بدلاً من خدمة التنبؤ المشتركة، ما يتيح لك اختبار نقطة النهاية المنشورة من المتصفح.

في نقطة نهاية جاهزة، تُضاف الصور المعالَجة أيضًا إلى علامة تبويب المراقبة. أمثلتها ومخططاتها الإجمالية بيانات مؤقتة وخفيفة تُحفظ في الذاكرة؛ وقد يؤدي إيقاف النموذج أو إعادة تشغيله أو إعادة نشره أو تغيير حجمه أو استبداله إلى مسحها. احفظ الأمثلة في مجموعة بيانات للاحتفاظ بها.

الاستدلال المباشر بالكاميرا#

في علامة التبويب Predict لعملية نشر تملكها، حدّد كاميرا الويب أو كاميرا IP لتشغيل نقطة النهاية على فيديو مباشر:

يستخدم الاستدلال المباشر مفتاح API المرتبط بنقطة النهاية، ولا يمكن تحميله إلا لمالك مساحة العمل؛ أما بالنسبة إلى أعضاء الفريق الآخرين، فتلتقط كاميرا الويب إطارات منفردة ولا تتوفر كاميرا IP، كما هو الحال في علامة التبويب Predict الخاصة بالنموذج. يجب أن تكون كاميرا IP قابلة للوصول من الإنترنت: ترفض نقطة النهاية عناوين الشبكة المحلية مثل 192.168.x.x. تعرض كل نتيجة أحدث إطار، لذا تُتجاوز الإطارات عندما يتأخر الاستدلال. تُطبّق تغييرات أشرطة التمرير على إطار كاميرا الويب التالي، وتُعيد تشغيل بث كاميرا IP. يتوقف الاستدلال المباشر مؤقتًا عندما تكون علامة تبويب المتصفح مخفية. انقر على المعاينة لالتقاط إطار، أو انقر على قطع الاتصال لإيقاف عرض كاميرا IP.

كاميرا تعمل في الخلفية#

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

• الإعدادات: تستخدم الكاميرا التي تعمل في الخلفية دائمًا قيمة الثقة الافتراضية (0.25) وIoU (0.7) وحجم صورة التدريب الخاص بالنموذج؛ ولا تنطبق عليها إعدادات أشرطة التمرير.
• التكلفة: تعمل الكاميرا على المثيل الجاهز لنقطة النهاية دون رسوم إضافية؛ وتُطبق رسوم مدة التشغيل بالساعة سواء أكانت الكاميرا قيد التشغيل أم متوقفة.
• التغييرات: تؤدي إعادة تشغيل الكاميرا أو إيقافها أو التبديل إلى كاميرا أخرى إلى إعادة تشغيل مثيل نقطة النهاية، ما يُبقي نقطة النهاية جاهزة لكنه يمحو بيانات المراقبة المؤقتة.
• الإيقاف: أوقف المفتاح. لا يؤدي قطع الاتصال أو إغلاق الصفحة إلى إيقافها، كما أن تغيير حجم نقطة النهاية إلى الحجم الافتراضي يزيلها. إذا توقفت الكاميرا عن العمل، تواصل نقطة النهاية محاولة إعادة الاتصال.
• دورة حياة نقطة النهاية: يؤدي إيقاف نقطة النهاية إلى إيقاف الكاميرا والرسوم؛ وعند تشغيلها مجددًا، تُستأنف الكاميرا المحفوظة.

تتيح نقاط النهاية ذات الحجم الافتراضي الاستدلال المباشر باستخدام كاميرا الويب وكاميرا IP دون خيار التشغيل في الخلفية. لحفظ كاميرا تعمل في الخلفية عبر API، استخدم إجراء camera الخاص بعملية النشر.

بث النتائج من API#

أرسل عنوان URL من نوع RTSP أو RTSPS بوصفه source، مع الترويسة Accept: text/event-stream، إلى عنوان URL لنقطة نهاية مخصصة لتلقي النتائج على هيئة أحداث يرسلها الخادم:

curl -N -X POST \
  "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -F "source=rtsp://user:password@camera.example.com:554/stream" \
  -F "conf=0.25"

يتضمن حدث كل إطار images بتنسيق الاستجابة، مع إحداثيات مطبّعة (0-1)، وعنوان URL لبيانات صورة JPEG للإطار باسم preview، وmetadata الذي يتضمن المهمة وأسماء الفئات. ينطبق كل من conf وiou وimgsz فقط، ويستخدم بث عنوان URL لكاميرا نقطة النهاية التي تعمل في الخلفية إعداداتها الافتراضية. الأحداث التي تتضمن status فقط لا تحمل إطارًا، وينهي البث حدث يتضمن رسالة error (تعذرت قراءة الكاميرا أو لم تتمكن نقطة النهاية من تشغيل النموذج). يُغلق البث أيضًا عند إعادة تشغيل نقطة النهاية أو بلوغ الطلب الحد الزمني، لذا أعد الاتصال مع تطبيق تراجع تدريجي عند انتهائه دون خطأ. لا يبث مسار التنبؤ بعملية النشر في Platform API ولا SDK النتائج؛ أرسل طلبات الكاميرا إلى عنوان URL لنقطة النهاية مع مفتاح API المرتبط بها. يعيد طلب كاميرا source دون الترويسة 400.

واجهة برمجة تطبيقات نقطة النهاية المخصصة#

تتضمن بطاقة مستندات API في علامة تبويب النموذج Predict أمثلة لطلبات Python وJavaScript وcURL، مع تعبئة قيم الثقة وIoU وحجم الصورة المضبوطة حاليًا على أشرطة التمرير مسبقًا. يظل عنوان URL والمفتاح عنصرين نائبين إلى أن تنشر النموذج — وينقلك زر نشر بجوار علامات تبويب التعليمات البرمجية إلى علامة تبويب النموذج Deploy. بعد النشر، تعرض علامة تبويب النتيجة المستندات في علامة تبويب Predict بصفحة النشر عنوان URL لنقطة النهاية تلك، ومفتاح API المرتبط بها لمالكي مساحة العمل، ليكونا جاهزين للنسخ والتشغيل.

المصادقة#

أدرج مفتاح API في الطلبات:

Authorization: Bearer YOUR_API_KEY

نقطة النهاية#

تستقبل نقاط النهاية المخصصة الطلبات على عنوان URL الخاص بها:

POST https://YOUR_DEPLOYMENT_URL.run.app/predict

يستخدم الاستدلال المشترك واجهة API للمنصة مع المسار الكامل للنموذج:

POST https://platform.ultralytics.com/api/models/{owner}/{project}/{model}/predict

يقبل كلاهما متن الطلب نفسه multipart/form-data ويُرجعان بنية الاستجابة نفسها. عند استخدام حزمة Python SDK، استخدم client.models.predict(owner, project, model, body=...) للاستدلال المشترك أو client.deployments.predict(owner, deployment, body=...) لنشر مخصص. تستدعي طريقتا SDK واجهة API للمنصة، لذا تنطبق حدود المعدل وحد حجم الطلب فيها. لتجنب هذه الحدود، أرسل الطلب مباشرةً إلى عنوان URL لنقطة نهاية مخصصة كما هو موضح ضمن الطلب. مثال على الاستدلال المشترك:

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
with open("image.jpg", "rb") as f:
    results = client.models.predict("acme-vision", "inspection", "v3", body={"file": f, "conf": 0.25})

الطلب#

import requests

url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

with open("image.jpg", "rb") as image_file:
    response = requests.post(url, headers=headers, files={"file": image_file}, data=data)
print(response.json())

معلمات الطلب#

الاستجابة#

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                },
                {
                    "class": 2,
                    "name": "car",
                    "confidence": 0.87,
                    "box": { "x1": 400, "y1": 200, "x2": 600, "y2": 350 }
                }
            ],
            "speed": {
                "preprocess": 1.2,
                "inference": 12.5,
                "postprocess": 2.3
            }
        }
    ],
    "metadata": {
        "imageCount": 1,
        "classNames": ["person", "bicycle", "car", "..."],
        "functionTimeAlive": 1284.51,
        "functionTimeCall": 0.018,
        "task": "detect",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

حقول الاستجابة#

استجابات خاصة بكل مهمة#

يختلف تنسيق الاستجابة باختلاف المهمة:

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400}
}

حدود المعدل#

يقتصر معدل واجهة API المشتركة للنموذج على 20 طلبًا في الدقيقة لكل مفتاح API أو متصل مسجل الدخول أو عنوان IP مجهول الهوية. ويخضع مسار التنبؤ لنشر المنصة (POST /api/deployments/{owner}/{deployment}/predict) للحد نفسه. عند تقييد المعدل، تُرجع واجهة API 429 مع ترويسة Retry-After. راجع المرجع الكامل لحدود المعدل للاطلاع على جميع فئات نقاط النهاية.

معالجة الأخطاء#

استجابات الأخطاء الشائعة:

الأسئلة الشائعة#