انشر نقطة نهاية واستدعها

الاستدلال المشترك أم نقطة نهاية مخصصة#

يمكن بالفعل استدعاء كل نموذج من خلال واجهة API للاستدلال المشترك في Platform، وهي مناسبة للاختبار. أما حركة المرور الإنتاجية فمكانها نقطة نهاية مخصصة:

إنشاء نقطة النهاية وتحديد حجمها#

افتح علامة التبويب Deploy الخاصة بالنموذج. يقيس متصفحك زمن الاستجابة إلى جميع المناطق الـ42 (14 في الأمريكتين، و13 في أوروبا، و12 في آسيا والمحيط الهادئ، و3 في الشرق الأوسط وأفريقيا)، ثم يرتب الجدول حسب زمن الاستجابة:

انقر على Deploy في الصف الأقرب إلى مواقع عملائك، وراجع وحدة المعالجة المركزية والذاكرة والسعر والاسم المُنشأ (مثل yolo26n-iowa)، ثم انقر على Create Deployment. يمكنك أيضًا البدء من New Deployment في علامة التبويب Deployments ضمن ملفك الشخصي:

حدّد الحجم وفق نمط حركة المرور:

تتيح الخطط 3 (Free) أو 10 (Pro) أو عددًا غير محدود (Enterprise) من عمليات النشر، وتُحتسب نقاط النهاية المتوقفة أيضًا. تقبل نقطة النهاية حركة المرور عندما تظهر شارتها Ready:

مثال عملي: عميل يصمد في بيئة الإنتاج#

لكل نقطة نهاية عنوان URL مثل https://predict-<id>-<hash>-<region>.a.run.app، وتخدم /predict (POST) و/health وصفحة تفاعلية /docs. ولا تقبل إلا مفتاح API المرتبط بها عند الإنشاء؛ ويرى مالكو مساحة العمل هذا المفتاح مُعبأ مسبقًا في علامة التبويب Predict ضمن Docs في عملية النشر، إلى جانب أمثلة Python وJavaScript وcURL. تنفّذ الأمثلة طلبًا واحدًا؛ أما تعليمات الإنتاج، فيجب أن تصمد أيضًا أمام بدء التشغيل البارد والمثيل المشغول:

import os
import time
from collections import Counter

import httpx

URL = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
HEADERS = {"Authorization": f"Bearer {os.environ['ULTRALYTICS_API_KEY']}"}  # the deployment's bound key, server-side only

def predict(client, path, conf=0.25, attempts=4):
    """POST one image; retry timeouts, 429, and 5xx with backoff; fail fast on other errors."""
    for attempt in range(attempts):
        try:
            with open(path, "rb") as f:
                r = client.post(URL, headers=HEADERS, data={"conf": conf}, files={"file": f}, timeout=90)
            if r.status_code < 400:
                return r.json()
            if r.status_code != 429 and r.status_code < 500:
                r.raise_for_status()  # 401 wrong key, 413 too large: retrying won't help
            wait, reason = float(r.headers.get("Retry-After", 2**attempt)), r.status_code
        except httpx.TimeoutException:  # a scaled-to-zero endpoint can take up to a minute to wake
            wait, reason = 2**attempt, "timeout"
        print(f"attempt {attempt + 1}: {reason}, retrying in {wait:.0f} s")
        time.sleep(wait)
    raise RuntimeError(f"endpoint still unavailable after {attempts} attempts")

with httpx.Client() as client:
    response = predict(client, "bus.jpg")
for image in response["images"]:
    counts = Counter(d["name"] for d in image["results"])
    print(f"{sum(counts.values())} objects {dict(counts)} in {image['speed']['inference']:.1f} ms")

اختبرنا ذلك باستخدام بديل محلي يجيب عن 429 مرة واحدة، ثم يعيد نتيجة حقيقية لـYOLO26n تخص bus.jpg بتنسيق استجابة نقطة النهاية:

attempt 1: 429, retrying in 2 s
5 objects {'bus': 1, 'person': 4} in 34.9 ms

فيما يلي القرارات المهمة، سطرًا بسطر:

• timeout=90 يغطي بدء تشغيل بارد قد يستغرق نحو دقيقة؛ فالمهل الزمنية الافتراضية لمعظم عملاء HTTP أقصر بكثير.
• تُعاد المحاولة عند أخطاء 429 و5xx مع مراعاة Retry-After عندما ترسله نقطة النهاية. تخدم كل نقطة نهاية الطلبات من مثيل واحد، وتخفّض الحمل باستخدام 429 عندما تكون مشغولة.
• تؤدي أخطاء 4xx الأخرى إلى الفشل فورًا: يعني 401 أن المفتاح غير صحيح، ويعني 413 أن حجم المحتوى يتجاوز 32 MB؛ ولا يُصلح أي منهما نفسه تلقائيًا.
• تتضمن الاستجابة عنصرًا واحدًا لكل صورة (أو لكل إطار فيديو) في images، ويحتوي كل عنصر على results (class وname وconfidence وbox مع x1 وy1 وx2 وy2) وspeed بالمللي ثانية.

حقول النموذج الاختيارية هي conf (القيمة الافتراضية 0.25)، وiou (0.7)، وimgsz (حجم تدريب النموذج)، وvid_stride للفيديو، وnormalize=true للإحداثيات ضمن النطاق 0–1. ويُكتب أمر cURL المكافئ كسطر لكل حقل:

curl -X POST "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer $ULTRALYTICS_API_KEY" \
  -F "file=@bus.jpg" -F "conf=0.25" -F "iou=0.7" -F "imgsz=640"

إصدار نسخ جديدة دون تغيير عنوان URL#

يستبدل Replace model في صفحة النشر النموذج بنموذج آخر مكتمل من مساحة العمل نفسها. ويواصل النموذج القديم تقديم الخدمة إلى أن يصبح النموذج الجديد جاهزًا؛ كما يظل عنوان URL والمنطقة والمفتاح كما هي، وإذا فشل الطرح، يظل النموذج السابق قيد التشغيل. وللتراجع، نفّذ الإجراء نفسه مع تحديد النموذج السابق، لذا أبقه في المشروع. يغيّر Update configuration الحجم في موضعه، بينما يوقف Stop الفوترة مع الإبقاء على عنوان URL.

تتطلب بعض التغييرات نقطة نهاية جديدة: فالمناطق ثابتة (ويستلزم الانتقال حذف نقطة النهاية وإعادة إنشائها، ما ينتج عنه عنوان URL جديد)، كما أن النطاقات المخصصة غير مدعومة، لذا ضع بوابتك الخاصة أمام نقطة النهاية إذا احتاج المستدعون إلى اسم مضيف ثابت يحمل علامتك التجارية. للتشغيل خارج Platform، صدّر النموذج (التصدير للنشر) أو استضفه بنفسك خلف Triton Inference Server.

مواطن الخلل#