الاستدلال

توفر Ultralytics Platform واجهة برمجة تطبيقات (API) للاستدلال لاختبار النماذج المدربة. استخدم علامة التبويب Predict المستندة إلى المتصفح للتحقق السريع أو REST API للوصول البرمجي.

علامة تبويب التنبؤ (Predict)

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

1. انتقل إلى نموذجك
2. انقر فوق علامة التبويب Predict
3. قم بتحميل صورة، أو استخدم مثالاً، أو افتح كاميرا الويب الخاصة بك
4. شاهد التوقعات فوراً مع تراكبات مربعات الإحاطة (Bounding Boxes)

طرق الإدخال

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

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

    style D fill:#2196F3,color:#fff
    style E fill:#4CAF50,color:#fff

تحميل الصورة

السحب والإفلات أو النقر للتحميل:

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

أمثلة على الصور

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

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

كاميرا الويب

انقر فوق بطاقة كاميرا الويب لبدء بث مباشر للكاميرا:

1. امنح إذن الوصول للكاميرا عند الطلب
2. انقر فوق معاينة الفيديو لالتقاط إطار
3. يتم تشغيل الاستدلال تلقائياً على الإطار الملتقط
4. انقر مرة أخرى لإعادة تشغيل كاميرا الويب

عرض النتائج

يعرض الاستدلال النتائج:

• مربعات إحاطة (BBox) مع تسميات الفئات كتراكبات SVG
• درجات الثقة لكل اكتشاف
• ألوان الفئات من لوحة ألوان مجموعة البيانات الخاصة بك (أو لوحة ألوان Ultralytics الافتراضية)
• تفصيل السرعة: وقت المعالجة الأولية، الاستدلال، المعالجة اللاحقة، ووقت الشبكة

تظهر لوحة النتائج:

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

اضبط سلوك الاكتشاف باستخدام المعاملات في قسم Parameters القابل للطي:

عتبة الثقة

تصفية التوقعات حسب الثقة:

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

عتبة IoU

التحكم في قمع الحد الأقصى غير (NMS):

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

تنبؤ النشر (Deployment Predict)

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

REST API

الوصول إلى الاستدلال برمجياً:

المصادقة

قم بتضمين مفتاح API الخاص بك في الطلبات:

Authorization: Bearer YOUR_API_KEY

نقطة النهاية

POST https://platform.ultralytics.com/api/models/{modelId}/predict

الطلب

import requests

url = "https://platform.ultralytics.com/api/models/MODEL_ID/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

response = requests.post(url, headers=headers, files=files, 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,
        "functionTimeCall": 0.018,
        "model": "model.pt",
        "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}
}

الفواتير

الاستنتاج المشترك (علامة التبويب Predict ونقطة النهاية /api/models/{id}/predict) مشمول بدون تكلفة إضافية في جميع الخطط. لا توجد رسوم لكل طلب مقابل الاستنتاج المشترك.

بالنسبة لأحمال العمل الإنتاجية التي تتطلب إنتاجية أعلى، قم بنشر نقطة نهاية مخصصة.

حدود المعدل

يخضع الاستنتاج المشترك لحد معدل يبلغ 20 طلباً في الدقيقة لكل مفتاح API. عند تجاوز الحد، تُرجع واجهة برمجة التطبيقات الرمز 429 مع رأس Retry-After. راجع مرجع حد المعدل الكامل لجميع فئات نقاط النهاية.

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

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

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

هل يمكنني تشغيل الاستنتاج على فيديو؟

كلا طريقتي الاستنتاج تقبلان ملفات الفيديو:

• نقاط النهاية المخصصة تقبل ملفات الفيديو مباشرة. التنسيقات المدعومة (حتى 100 ميجابايت): ASF و AVI و GIF و M4V و MKV و MOV و MP4 و MPEG و MPG و TS و WEBM و WMV. تتم معالجة كل إطار على حدة وتُرجع النتائج لكل إطار. راجع نقاط النهاية المخصصة للحصول على التفاصيل.
• الاستنتاج المشترك (/api/models/{id}/predict) يستخدم نفس خدمة التنبؤ ويقبل نفس تنسيقات الفيديو. ومع ذلك، فإن علامة التبويب Predict في المتصفح ضمن واجهة المستخدم تقوم بتحميل الصور فقط — استخدم REST API مباشرة أو نقطة نهاية مخصصة لسير عمل الفيديو. نقطة النهاية المشتركة تخضع أيضاً لـ حد 20 طلباً/دقيقة، لذا تعد نقاط النهاية المخصصة الخيار الأفضل لأحمال عمل الفيديو الثقيلة.

كيف أحصل على الصورة المشروحة؟

تُرجع واجهة برمجة التطبيقات توقعات بتنسيق JSON. للتصور:

1. استخدم التوقعات لرسم المربعات محلياً
2. استخدم طريقة plot() الخاصة بـ Ultralytics:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
results = model("image.jpg")
results[0].save("annotated.jpg")

راجع توثيق وضع Predict للحصول على واجهة برمجة تطبيقات النتائج الكاملة وخيارات التصور.

ما هو الحد الأقصى لحجم الصورة؟

• حد التحميل: 10 ميجابايت
• موصى به: أقل من 5 ميجابايت لاستنتاج سريع
• تغيير الحجم التلقائي: يتم تغيير حجم الصور إلى معلمة Image Size المحددة

يتم تغيير حجم الصور الكبيرة تلقائياً مع الحفاظ على نسبة العرض إلى الارتفاع.

هل يمكنني تشغيل استنتاج الدفعات (batch)؟

تقوم واجهة برمجة التطبيقات الحالية بمعالجة صورة واحدة لكل طلب. بالنسبة للدفعات:

1. أرسل طلبات متزامنة
2. استخدم نقطة نهاية مخصصة لإنتاجية أعلى
3. فكر في الاستنتاج المحلي للدفعات الكبيرة

import concurrent.futures

import requests

url = "https://predict-abc123.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
images = ["img1.jpg", "img2.jpg", "img3.jpg"]

def predict(image_path):
    with open(image_path, "rb") as f:
        return requests.post(url, headers=headers, files={"file": f}).json()

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(predict, images))