مرجع REST API#

توفر منصة Ultralytics واجهة REST API للوصول برمجيًا إلى مجموعات البيانات والصور والمشاريع والنماذج والتدريب وعمليات التصدير وعمليات النشر.

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

نظرة عامة على API#

تُنظَّم API حول موارد المنصة الأساسية:

graph LR
    A[API Key]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    B -->|images| G[Images]:::proc
    C -->|contains| D[Models]:::proc
    B -->|train on| D
    D -->|deploy| E[Deployments]:::proc
    D -->|export| F[Exports]:::proc

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

المصادقة#

تتطلب معظم المسارات مفتاح API. كما تقبل المسارات التي تتيح الوصول إلى محتوى عام — مثل قراءة مجموعة بيانات أو مشروع أو نموذج عام، أو إدراج صور مجموعة بيانات عامة، أو تنفيذ الاستدلال على نموذج عام، أو البحث في «استكشاف» — الطلبات المجهولة، وتعيد ببساطة مزيدًا من النتائج عند توفير مفتاح.

الحصول على مفتاح API#

1. انتقل إلى Settings > API Keys
2. انقر على Add Key، واترك Ultralytics محددًا كمزوّد، وأدخل اسمًا، ثم انقر على Create Key
3. انسخ المفتاح المُنشأ

راجع مفاتيح API للاطلاع على التعليمات التفصيلية.

ترويسة التفويض#

أدرج مفتاح API الخاص بك على هيئة رمز حامل:

Authorization: Bearer YOUR_API_KEY

مثال#

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/account/summary

عنوان URL الأساسي#

تستخدم جميع مسارات API ما يلي:

https://platform.ultralytics.com/api

مسارات الموارد#

تُعرَف معظم الموارد بالأسماء المقروءة للبشر نفسها التي تظهر في عناوين URL للمنصة، لا بمعرّفات قاعدة البيانات:

• يشير {owner} إلى اسم مستخدم شخصي أو معرّف مساحة عمل لفريق: من 4 إلى 32 حرفًا، بأحرف وأرقام صغيرة، مع واصلات مفردة بين المقاطع.
• تتبع {dataset} و{project} و{model} و{deployment} النمط نفسه باستخدام الأحرف الصغيرة والواصلات، وبحد أقصى 128 حرفًا.
• إن {imageId} و{exportId} و{agentId} معرّفات سداسية عشرية بطول 24 حرفًا تعيدها API.
• تؤدي إعادة تسمية مورد عبر PATCH إلى تغيير name المعروض واسم URL معًا، ويعيد الرد اسم URL الحالي لتتمكن من مواصلة استخدامه.

حدود المعدل#

تفرض API حدودًا باستخدام نافذة متحركة لكل مفتاح API. ويندرج كل مسار ضمن فئة واحدة، ولكل فئة عدّاد مستقل؛ لذا فإن 20 طلب تنبؤ لا تستهلك الحد الافتراضي المخصص لك.

للمسارات المتاحة عبر منصة Platform في المتصفح فقط، مثل إتمام الدفع وإدارة الفريق، حدودها الخاصة التي لا تنطبق على حركة المرور باستخدام مفاتيح API.

عند تقييد المعدل، تُرجع API الرمز 429 مع الترويسات ونص JSON:

Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z

{
    "error": "Rate limit exceeded, wait 12s",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

نقاط نهاية مخصصة (غير محدودة)#

لا تخضع نقاط النهاية المخصصة لحدود معدل مفاتيح API الخاصة بالمنصة عند استدعاء serviceUrl الخاص بعملية النشر مباشرةً (على سبيل المثال، https://predict-abc123.run.app/predict). ويعتمد معدل النقل عندئذٍ على إعدادات الخدمة المنشورة.

تنسيق الاستجابة#

استجابات النجاح#

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

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

تتضمن قوائم الموارد واستجابات الإنشاء والاستنساخ وبعض عمليات القراءة، مثل عمليات النشر والتخزين وسلة المهملات، أيضًا region (us أو eu أو ap)، وهي منطقة التخزين الخاصة بمساحة العمل تلك.

استجابات الأخطاء#

كل استجابة خطأ هي كائن JSON يتضمن رسالة error:

{
    "error": "Dataset not found"
}

التقسيم إلى صفحات#

يعتمد أسلوب تقسيم الصفحات على المجموعة:

API مجموعات البيانات#

أنشئ مجموعات بيانات الصور المصنفة لتدريب نماذج YOLO، واستعرضها وأدرها. راجع وثائق مجموعات البيانات.

سرد مجموعات البيانات#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

يُرجع مجموعات البيانات العامة الخاصة بالمالك، بالإضافة إلى مجموعات البيانات الخاصة عندما يتيح مفتاحك عرض مساحة العمل تلك.

معلمات الاستعلام:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets/acme-vision?limit=10&includeSamples=false"

الاستجابة:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

الحصول على مجموعة بيانات#

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

يُرجع كائن مجموعة البيانات الكامل ضمن المفتاح dataset، بما في ذلك classNames وsplits وversions وsource وكائن metadata الذي يحدده المستخدم. أثناء معالجة استيراد يضم 10,000 صورة أو أكثر، يتلقى المحررون أيضًا processingProgress مع stage وpercent، وعند توفرها، processed وtotal وobjects (عناصر التخزين السحابي التي جرى فحصها).

إنشاء مجموعة بيانات#

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

النص:

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

يؤدي استخدام معرّف dataset موجود بالفعل في مساحة العمل، بما في ذلك معرّف موجود في سلة المهملات، إلى إرجاع 409.

الاستجابة (201):

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

تحديث مجموعة بيانات#

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

النص (تحديث جزئي):

{
    "name": "Warehouse Safety",
    "description": "New description",
    "visibility": "public",
    "metadata": { "location": "factory-2", "reviewed": true }
}

الحقول المقبولة: name وdescription وvisibility وmetadata وtags وclassNames وclassColors وformat وtask وlicense وiconColor وiconLetter وstarred وblurFaces وkptSkeletonId (لتعيين قالب هيكل عظمي لوضعية إلى مجموعة بيانات وضعية)، وinitializeClassNames (يُرجع التحديث 409 ما لم تكن مجموعة البيانات بلا فئات أو تعليقات توضيحية بعد). أرسل كائن metadata فارغًا ({}) لمسح البيانات الوصفية المخصصة. يقتصر طول مفاتيح البيانات الوصفية على 128 حرفًا، ويقتصر طول الكائن المتسلسل على 500,000 حرف.

الاستجابة:

{
    "success": true,
    "dataset": "warehouse-safety"
}

يؤدي تغيير الاسم إلى تغيير اسم عنوان URL، لذا استخدم قيمة dataset المُعادة في الطلبات اللاحقة.

حذف مجموعة بيانات#

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

ينقل مجموعة البيانات إلى سلة المهملات، حيث يمكن استعادتها خلال 30 يومًا.

استنساخ مجموعة بيانات#

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

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

النص الاختياري (جميع الحقول اختيارية):

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

الاستجابة (201): id وowner وdataset وname وimageCount وclassCount وregion. تُرجع مجموعات البيانات المرتبطة بمصدر تخزين متصل 409 لأن ملفاتها لا تُنسخ.

تنزيل تصدير مجموعة بيانات#

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

يُرجع عنوان URL موقّعًا لتنزيل ملف NDJSON. احذف v لتصدير الحالة الحالية لمجموعة البيانات، مع إعادة استخدام التصدير المخزّن مؤقتًا إذا لم يحدث أي تغيير منذ إنشائه.

معلمات الاستعلام:

الاستجابة:

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

يؤدي طلب إصدار محدد إلى إرجاع downloadUrl وversion بدلًا من cached.

إنشاء إصدار لمجموعة بيانات#

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

ينشئ إصدارًا مرقمًا غير قابل للتغيير من مجموعة البيانات. يتطلب ذلك صلاحية المحرر. اضبط download على false لحفظ الإصدار دون إعداد تنزيل NDJSON؛ وعندئذٍ يُحذف downloadUrl. تقبل SDK القيمة download من ultralytics-platform>=0.1.73.

النص (اختياري):

{
    "description": "Added 500 training images",
    "download": true
}

الاستجابة:

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

تكون قيمة reused هي true عندما تطابق مجموعة البيانات إصدارًا موجودًا، كأن يحدث ذلك مباشرةً بعد استعادتها، ويُعاد ذلك الإصدار بدلًا من إنشاء إصدار جديد، مع تحديث وصفه عند إرسال وصف.

تحديث وصف الإصدار#

PATCH /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

النص:

{
    "version": 2,
    "description": "Fixed mislabeled classes"
}

الاستجابة: {"ok": true}

استعادة إصدار مجموعة بيانات#

POST /api/datasets/{owner}/{dataset}/restore

Python SDK: client.datasets.restore(owner, dataset, version=...)

يعيد إنشاء الصور والتعليقات التوضيحية والفئات من إصدار محفوظ، دون نسخ وحدات بايت الصور.

النص:

{
    "version": 2
}

الاستجابة: {"version": 2, "imageCount": 1000}

مقارنة إصدارات مجموعات البيانات#

GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}

Python SDK: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)

الاستجابة (مختصرة):

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

يظهر summary في الصفحة الأولى فقط، ويتضمن الإجماليات الدقيقة، بالإضافة إلى header الذي يسرد الفئات المضافة أو المحذوفة أو المعاد تسميتها وحقول مجموعة البيانات الأخرى التي تختلف. تكون قيمة change لكل عنصر هي added أو removed أو modified (مع fields المتغير) أو moved (تغيّر التقسيم)، ويتضمن labelsRemoved تسميات الصور المحذوفة. مرّر nextCursor، عند وجوده، بوصفه cursor للصفحة التالية. عند استخدام hash، تكون الاستجابة versions: الصورة كما يخزنها كل إصدار، مع تسمياتها وimageUrl موقّع. يصلح كلا الترتيبين؛ إذ يؤدي تبديل base وhead إلى الإبلاغ عن صورة محذوفة على أنها مضافة. تخضع المقارنات لحد المعدل الافتراضي، كما تُقيّد الطلبات التي لا تتضمن hash بما يصل إلى 10 طلبات في الدقيقة لكل مستخدم ومجموعة بيانات، بصرف النظر عن مفتاح API المُستخدم لإرسالها.

الحصول على إحصاءات مجموعة البيانات#

GET /api/datasets/{owner}/{dataset}/class-stats

Python SDK: client.datasets.class_stats(owner, dataset)

يعرض أعداد التعليقات التوضيحية لكل فئة، ومخططات الصور والتعليقات التوضيحية، والخرائط الحرارية. تُؤخذ عينات من مجموعات البيانات الكبيرة، وفي هذه الحالة، يوضّح sampleSize عدد الصور التي أسهمت في النتائج.

الاستجابة (مختصرة):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "forklift"],
    "cached": true,
    "sampleSize": null
}

إدارة الفئات#

دمج الفئات (إعادة تعيين التعليقات التوضيحية إلى فئة مستهدفة، ثم إزالة الفئات المصدر):

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

حذف الفئات (تُحذف تعليقاتها التوضيحية، وتتناقص معرّفات الفئات المتبقية):

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

تعيد كلتا العمليتين success، وclassNames وclassColors المحدّثين، وملخصًا بالتغييرات (mergedClassIds وtargetClassId، أو deletedClassIds وdeletedAnnotations).

إعادة توزيع الأقسام#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

يعيد توزيع الصور عشوائيًا بين الأقسام. يجب أن يبلغ مجموع النسب المئوية الثلاث 100.

{
    "train": 80,
    "val": 20,
    "test": 0
}

الاستجابة: success، وأعداد splits الناتجة، وmodified (عدد الصور المنقولة).

تضمينات مجموعة البيانات#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK: client.datasets.embeddings(owner, dataset)، وclient.datasets.create_embeddings(owner, dataset)، وclient.datasets.delete_embeddings(owner, dataset)

يعيد GET ملخص التحليل (analyzedAt، وembeddingsCount، وlatestImageAt، وactiveJob). يضع POST تحليل التضمينات في قائمة الانتظار ويعيد 202 مع jobId. يُلغي DELETE المهمة النشطة ويعيد معرّف المهمة الملغاة أو null.

تجميع الصور#

GET /api/datasets/{owner}/{dataset}/images/clustering

Python SDK: client.datasets.clustering(owner, dataset)

يعيد تخطيط UMAP ثنائي الأبعاد الناتج عن تحليل مكتمل، مقسّمًا إلى صفحات باستخدام offset وlimit (القيمة الافتراضية والحد الأقصى 50,000). يتضمن كل إدخال id، وumapX، وumapY، وcluster، وsplit، وclassIds، وwidth، وheight، وbytes، وlabelCount، وlabeled، وmissing. يشير cluster إلى الجزيرة المرئية للنقطة، مرتبة حسب الحجم (0 = الأكبر، و-1 = متناثرة)، أو null للتخطيطات التي حُلّلت قبل إضافة التجميع.

سرد النماذج المدرّبة على مجموعة بيانات#

GET /api/datasets/{owner}/{dataset}/models

Python SDK: client.datasets.models(owner, dataset)

الاستجابة:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

سرد صور مجموعة البيانات#

GET /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.images(owner, dataset)

معلمات الاستعلام:

الاستجابة:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

الحصول على الصور المحددة#

POST /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

يعيد بنية الصور نفسها لما يصل إلى 1,000 معرّف صورة مُقدّم، ويقبل معلمات التصفية وعناوين URL نفسها المستخدمة في عملية السرد.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

نسخ الصور أو نقلها#

POST /api/datasets/{owner}/{dataset}/images/adopt

Python SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)

ينسخ ما يصل إلى 1,000 صورة من مجموعات بيانات أخرى إلى هذه المجموعة، كما يفعل التطبيق عند النسخ واللصق، ويعيد العدد adopted.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

يحافظ تعيين release أو classMapping على الوسوم والتقسيمات من مجموعات البيانات التي يمكنك تعديلها: إذ ينسخ release: false الصور، بينما ينقلها release: true من مجموعة بيانات المصدر. يؤدي إغفال الحقلين إلى استيراد صور train بلا وسوم، وكذلك النسخ من مصدر للقراءة فقط؛ أما النقل من مصدر للقراءة فقط فيعيد 403. تُتجاوز الصور الموجودة؛ وعند الحفاظ على الوسوم والتقسيمات، يُتحقق من التكرارات ضمن تقسيم الوجهة. تُطابق الفئات بحسب الاسم، مع تجاهل حالة الأحرف للأسماء التي يتجاوز طولها حرفين؛ ويعيد 422 فئات المصدر التي لا يقابلها تطابق في unmatchedClasses، ويعيّن classMapping كل فئة إلى فهرس فئة أو اسم فئة جديدة أو null لإسقاط وسومها. تعني 409 أن الوجهة مجموعة بيانات متصلة أو أن المصدر أو الوجهة مشغول. عند الحفاظ على الوسوم والتقسيمات، تؤدي أيضًا المهام غير المتوافقة أو قنوات الصور أو إعدادات الوضعية أو مقاييس العمق إلى إرجاع 409، حتى للصور التي لا تحتوي على وسوم.

استيعاب بيانات مجموعة البيانات#

POST /api/datasets/{owner}/{dataset}/ingest

Python SDK: client.datasets.ingest(owner, dataset, body=...)

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

ترتبط جلسات الرفع بمجموعة بيانات بواسطة assetId المُمرّر إلى POST /api/upload/signed-url، ويرفض الاستيعاب الجلسة التابعة لمجموعة بيانات مختلفة.

المتن (الأرشيف المُحمّل):

{
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

المتن (الأرشيف البعيد أو NDJSON):

{
    "sourceUrl": "https://example.com/my-dataset.zip"
}

المتن (استيراد التسميات في عملية استيعاب لاحقة):

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

المتن (إرفاق بيانات وصفية لكل صورة):

{
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

يجب أن تطابق مفاتيح البيانات الوصفية المسار الموحّد داخل الأرشيف، بما في ذلك المجلدات. في عمليات استيراد NDJSON، يمكن لكل سجل أن يتضمن كائن metadata خاصًا به، وله الأولوية على إدخال imageMetadata المطابق. الحد الأقصى لمسارات الأرشيف هو 1,024 حرفًا، ولمفاتيح البيانات الوصفية ذات المستوى الأعلى 128 حرفًا، ولكل كائن بيانات وصفية — وكذلك خريطة imageMetadata كاملة — 500,000 حرف بعد التسلسل.

الاستجابة (201):

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D["POST /api/upload/complete (optional)"]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/ingest"]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

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

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

واجهة برمجة الصور#

افحص صور مجموعة البيانات وعلّق عليها وانقلها واحذفها باستخدام معرّف الصورة المكوّن من 24 حرفًا. راجع وثائق التعليقات التوضيحية.

الحصول على صورة#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

يعيد الكائن metadata (مخصص، يحدده المستخدم)، وproperties (اسم الملف، والتجزئة، والأبعاد، والقسم، والأعداد، والطوابع الزمنية)، وlabels، وclassNames لمجموعة البيانات.

تحديث صورة#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

يستبدل إما التعليقات التوضيحية أو البيانات الوصفية المخصصة — أرسل أحد الشكلين، لا كليهما.

المتن (التعليقات التوضيحية):

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

المتن (البيانات الوصفية):

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

حذف صورة#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

يحذف صورة واحدة وتعليقاتها التوضيحية نهائيًا.

إضافة تعليقات توضيحية تلقائيًا إلى صورة#

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

يشغّل النموذج على الصورة ويعيد التعليقات التوضيحية المتوقعة. لا يحفظ هذه التعليقات — اكتب النتائج مرة أخرى باستخدام PATCH /api/images/{imageId} عندما تكون راضيًا عنها.

الاستجابة: success، وpredictions (كائنات التعليقات التوضيحية)، وconfidences (درجات بمحاذاة الفهارس، وفارغة للنماذج الموجّهة بالفئات)، وmodelUsed، وinferenceTime؛ وللنماذج الموجّهة بالفئات partial (true عندما لا يعيد خرج النموذج التوليدي المقتطع سوى المربعات المكتملة)، ولنماذج المزوّدين المدفوعين cost اختياري (التكلفة المقدرة للمزوّد بالدولار الأمريكي والمحمّلة على مفتاح المزوّد، ويُحذف عند عدم توفر تقدير). يعيد نموذج YOLO الذي لا تتطابق فئاته مع مجموعة البيانات 422، وكذلك النموذج الموجّه بالفئات عند استخدامه مع مجموعة بيانات غير مخصصة للكشف أو تضم عددًا خارج النطاق من 1 إلى 200 فئة، وكذلك نموذج المزوّد المدفوع الذي لا يتوفر له مفتاح مزوّد محفوظ في الإعدادات > مفاتيح API ضمن مساحة عمل مجموعة البيانات (code: missing_provider_api_key). يتضمن خطأ المزوّد رسالة المزوّد: 422 عندما يجيب المزوّد بـ400 أو 401 أو 403 أو 404 (مفتاح أو نموذج أو طلب مرفوض)، و429 عند بلوغ حد المعدل، و503 لأي خطأ آخر لدى المزوّد. تعيد مجموعات بيانات العمق 400، وكذلك مجموعات البيانات الموجودة على تخزين متصل أو التي تضم أكثر من 3 قنوات صور 409.

العثور على صور مشابهة#

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

يعيد ما يصل إلى 24 صورة images متشابهة بصريًا من مجموعات البيانات العامة ومجموعات بياناتك ومجموعات بيانات فريقك، وتأتي كل صورة مع score (من 0 إلى 1)، وthumbnailUrl موقّع، ومصدر dataset (owner، وdataset، وlicense). تُستثنى الصور الموجودة أصلًا في مجموعة بيانات المصدر ونسخ صورة الاستعلام. يتطلب ذلك مفتاح API لديه صلاحية عرض الصورة؛ وإذا لم تكن الصورة قد حُوّلت إلى تضمين بعد، فسيُنشأ تضمين لها أولًا، ويعني 503 فشل هذا الإعداد، لذا أعد المحاولة.

إضافة تعليقات توضيحية تلقائيًا إلى مجموعة بيانات#

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)

يحفظ إصدارًا من مجموعة البيانات، ثم يضع تشغيلًا في قائمة الانتظار لوضع تسميات على صور مجموعة البيانات غير المصنفة باستخدام النموذج، ويعيد 202. يقبل المتن الحقول modelId وconfidence وiou وclassMapping نفسها التي تقبلها نقطة النهاية الخاصة بصورة واحدة، بالإضافة إلى includeAnnotated (القيمة الافتراضية false) لإضافة تعليقات توضيحية أيضًا إلى الصور التي تحمل تسميات بالفعل. يكشف النموذج الموجّه بالفئات عن فئات مجموعة البيانات دون درجات ثقة، ويحتاج نموذج المزوّد المدفوع إلى مفتاح مزوّد محفوظ في مساحة عمل مجموعة البيانات ضمن الإعدادات > مفاتيح API (422، وcode: missing_provider_api_key، قبل قبول التشغيل). لا تُعدّل التسميات الموجودة أبدًا، وتُحتسب تكلفة التشغيل بحسب الصور التي يعالجها فعليًا. يعني 402 أن الرصيد لا يغطي التكلفة المقدرة، ويعني 409 أن مجموعة البيانات غير جاهزة أو لا تحتوي على صور متبقية لإضافة تعليقات توضيحية إليها أو أن تشغيلًا آخر قيد التنفيذ، ويعني 422 أن مجموعة البيانات لا تحتوي على فئات، أو أن نموذجًا موجّهًا بالفئات استُخدم مع مجموعة بيانات غير مخصصة للكشف أو تضم عددًا خارج النطاق من 1 إلى 200 فئة: أنشئ الفئات باستخدام نقطة نهاية الفئات قبل استدعاء نقطة النهاية هذه، كما تفعل خطوة تعيين الفئات في التطبيق قبل بدء التشغيل.

يعيد GET على المسار نفسه (client.datasets.batch(owner, dataset)) التشغيل الجاري وتقدمه، أو آخر تشغيل مكتمل حتى إغلاقه؛ وتتضمن قيمة results لهذا التشغيل partialImages عندما احتفظ تشغيل النموذج التوليدي بالمربعات المكتملة فقط من الخرج المقتطع؛ ويُلغي DELETE (client.datasets.delete_batch(owner, dataset)) تشغيلًا جاريًا، أو يسوّي الفوترة ويغلق الملخص المكتمل.

تقوم نقطة النهاية نفسها بتمويه الوجوه باستخدام "operation": "blur" وconfidence (الافتراضي 0.25) وboxScale (من 0.5 إلى 1.5، والافتراضي 1)؛ ويحدّ imageId التشغيل بصورة واحدة. لا تنشئ أي إصدار ولا تغيّر التسميات مطلقًا. أرسل "preview": true لمعالجة ما يصل إلى ست صور دون تغييرها، ثم أرسل jobId المُعاد باعتباره previewJobId وبالإعدادات نفسها للتطبيق؛ ولا يمكن إعادة استخدام معاينة مطبّقة، وستُعاد 409 عند محاولة ذلك. أثناء انتظار معاينة، مرّر معرّفها بوصفه previewJobId إلى DELETE للتخلص منها.

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

نقل الصور دفعة واحدة#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

ينقل ما يصل إلى 1,000 صورة من مجموعة بيانات إلى قسم مختلف.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

تعيد تعارضات أسماء الملفات أو المحتوى 409 إلى أن تختار سياسة conflictPolicy موحّدة للسلة من بين skip أو keep_both أو replace. تعرض الاستجابة modifiedCount وskippedCount وtargetSplit.

حذف الصور دفعة واحدة#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

يحذف ما يصل إلى 1,000 صورة من مجموعة بيانات واحدة، ويعيد deletedCount وdeletedImageIds.

الحصول على عناوين URL موقّعة للصور#

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

يعيد عناوين URL موقّعة مؤقتة لما يصل إلى 100 معرّف صورة من مجموعة بيانات واحدة.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

الاستجابة: urls وthumbnails وdepths (معاينات أهداف العمق لصور العمق المقترنة)، وكلها مفهرسة حسب معرّف الصورة.

واجهة برمجة المشاريع#

نظّم نماذجك في مشاريع. ينتمي كل نموذج إلى مشروع واحد. راجع وثائق المشاريع.

سرد المشاريع#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

معلمات الاستعلام:

الحصول على مشروع#

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

يعيد كائن project، ومصفوفة models التي تتضمن ملخصات لكل نموذج (الحالة، والمقاييس، والعصور، والأوزان، ومعاملات التدريب)، وisOwner. مرّر search (بحد أقصى 200 حرف) لتصفية models حسب اسم النموذج أو البيانات الوصفية.

إنشاء مشروع#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

الاستجابة (201): id، وowner، وproject، وregion.

يؤدي استخدام معرّف project موجود بالفعل في مساحة العمل، بما في ذلك معرّف موجود في سلة المهملات، إلى إرجاع 409.

تحديث مشروع#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

الحقول المقبولة: name، description، visibility، metadata، tags، license، archived، iconColor، iconLetter، viewPreferences، وstarred.

{
    "metadata": { "department": "research", "program": "inspection" }
}

أرسل كائنًا فارغًا metadata ({}) لمسحه. تستخدم البيانات الوصفية للمشروع حدودًا مماثلة لبيانات المجموعة الوصفية: مفتاحًا من 128 حرفًا وكائنًا متسلسلًا من 500,000 حرف.

حذف المشروع#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

ينقل المشروع ونماذجه إلى المهملات، مع إرجاع cascadedModels، ويحذف عمليات النشر الخاصة بها نهائيًا. لا تؤدي استعادة المشروع إلى استعادة عمليات النشر. تعني 502 أن تنظيف عمليات النشر لم يكتمل؛ وتظل النماذج في المهملات إلى أن ينجح التنظيف.

استنساخ المشروع#

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

ينسخ مشروعًا يمكن الوصول إليه ونماذجه المكتملة. يقبل نص الطلب الاختياري project وname وdescription وvisibility وlicense، ووجهةً owner.

واجهة API للنماذج#

إدارة نماذج YOLO المدرّبة — عرض المقاييس، وتنزيل الأوزان، وتشغيل الاستدلال، ومراقبة التدريب. راجع وثائق النماذج.

عرض النماذج في مشروع#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

معلمات الاستعلام:

الحصول على نموذج#

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

معلمات الاستعلام:

تتضمن الاستجابة الافتراضية الكائن model — الحالة، والمهمة، والمقاييس، وtrainArgs، وtrainResults، وclassNames، وcomputeCost، وmetadata، وغير ذلك — بالإضافة إلى isOwner.

إنشاء نموذج#

POST /api/models

Python SDK: client.models.create(body=...)

ينشئ سجلًا لنموذج غير مدرّب، يمكنك إرفاق الأوزان به أو تدريبه.

الاستجابة (201): id، owner، project، model، region.

تحديث نموذج#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

تشمل الحقول المقبولة name وdescription وcolor وmetadata وstatus وlicense وdatasetSlug وtrainArgs وtrainResults وepochs وbestEpoch وbestFitness وversion وtrainingError وstarred. يؤدي تمرير projectId وحده إلى نقل النموذج إلى مشروع آخر للمالك نفسه؛ وتُرجع الاستجابة slug للنموذج في الوجهة، وrenamed: true إذا كان ذلك الاسم اللطيف مستخدمًا هناك بالفعل، و409 ما دام النموذج لا يزال قيد التدريب.

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

تُعد metadata المخصصة مستقلة عن الحقول التي يديرها التدريب، مثل trainArgs وenvironment وtrainResults، وتخضع لحدود الحجم نفسها المطبقة على البيانات الوصفية للمجموعات.

حذف النموذج#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

ينقل النموذج إلى سلة المهملات لمدة 30 يومًا، ويحذف نهائيًا جميع عمليات النشر التي تستخدمه، بما في ذلك عمليات الاستبدال المعلّقة. لا تؤدي استعادة النموذج إلى استعادة عمليات النشر.

تنزيل ملفات النموذج#

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

يعيد عناوين URL موقّعة قصيرة الأجل لأوزان النموذج.

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

العثور على صور مشابهة لأسوأ صور التحقق#

GET /api/models/{owner}/{project}/{model}/similar-images

Python SDK: client.models.find_similar_training_images(owner, project, model)

يعيد ما يصل إلى 100 من images، بالتنسيق نفسه المتبع في العثور على صور مشابهة، والتي تشبه صور التحقق التي حقق فيها تشغيل التدريب أسوأ النتائج، مع استبعاد الصور الموجودة بالفعل في مجموعة بيانات التدريب. مرّر hashes (قائمة مفصولة بفواصل، بحد أقصى 100) للبحث انطلاقًا من مجموعة فرعية من تلك الصور الأسوأ. يتطلب ذلك مفتاح API يتيح الوصول إلى مساحة عمل النموذج. تكون القائمة فارغة إذا لم يسجل التشغيل نتائج لكل صورة، كما تعني 404 أيضًا أن تضمينات الصور الأسوأ لم تُنشأ بعد: شغّل تضمينات مجموعة البيانات على مجموعة بيانات التدريب أولًا.

استنساخ النموذج#

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

ينسخ نموذجًا يمكن الوصول إليه إلى مشروع موجود.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

تشغيل الاستدلال#

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

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

نموذج متعدد الأجزاء:

قدّم إما file أو source. وتقبل نماذج العمق أيضًا bits (8 أو 12 أو 16) لتحديد تكميم PNG لخريطة العمق. تُرجع الطلبات التي تتجاوز حدود الإدخال الخاصة بالخدمة 413.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/predict

الاستجابة:

يتضمن كل إدخال في images القيم shape وspeed وresults، إضافةً إلى محتوى PNG في semantic_mask أو depth لمهام التنبؤ الكثيف. وتكون قيم العمق pixel × max / divisor، مع قاسم 255 لخريطة 8 بت الافتراضية و65535 عندما تكون bits تساوي 12 أو 16. يعرض الكائن metadata عدد الصور، وأسماء فئات النموذج، وأزمنة تنفيذ الوظائف، والمهمة، وإصدارات الخدمة. لا تُعاد أبدًا مسارات النماذج الداخلية.

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "classNames": ["person", "forklift"],
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

التحقق من تقدم التدريب#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

يعيد job متضمنًا الحالة، والتقدم في العصور التدريبية، والتوقيت، وتفاصيل الحوسبة، ووسيطات التدريب، ومقاييس العصور التدريبية، وتفاصيل آمنة عن الأخطاء؛ أو يعيد null إذا لم يسبق تدريب النموذج. يمكن قراءة النماذج الموجودة في مشاريع عامة دون مصادقة.

إلغاء التدريب#

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

ينهي مثيل الحوسبة قيد التشغيل ويضع علامة إلغاء على المهمة. يُرجع 409 عندما لا يكون التدريب نشطًا.

واجهة API للتدريب#

ابدأ تدريب YOLO على وحدات GPU سحابية وراقب التقدم في الوقت الفعلي. راجع وثائق التدريب السحابي.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

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

الحصول على مدى توفر GPU#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

يعيد حالة المخزون الحالية مرتبة حسب معرّف GPU. الخدمة عامة ولا تتطلب المصادقة؛ مرّر managed=true لتضمين سعة التدريب المُدارة، التي تتطلب مفتاح API.

بدء التدريب#

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://acme-vision/datasets/warehouse",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

الاستجابة:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

يعيد التدريب 402 عندما يكون رصيدك الائتماني منخفضًا جدًا، و503 عندما لا تتوفر سعة لوحدة GPU المطلوبة.

واجهة API للتصدير#

حوّل النماذج إلى تنسيقات محسّنة مثل ONNX وTensorRT وCoreML وLiteRT للنشر على الأجهزة الطرفية. راجع وثائق النشر.

عرض عمليات التصدير#

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

معلمات الاستعلام:

إنشاء عملية تصدير#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

لا يدعم كل تنسيق سوى الخيارات الواردة في عمود الوسيطات بجدول التصدير أدناه: إذا كانت قيمة batch أو dynamic أو opset أو simplify أو workspace أو optimize غير افتراضية لتنسيق لا يدعمها، فسيُرجع 400. عمليات التصدير imx متاحة بصيغة INT8 فقط، وتدعم نماذج الكشف والتقسيم والتصنيف وتقدير الوضعية؛ أما نماذج YOLO26 وأحجام YOLOv8 أو YOLO11 غير nano فتعيد 400.

الاستجابة (201): id وformat وstatus (queued أو running) وregion وgpuType لعمليات التصدير إلى TensorRT. تعيد عملية تصدير مكافئة قيد التنفيذ بالفعل 409.

التنسيقات المدعومة:

استخدم وسيط format من جدول التصدير المشترك أدناه. تنسيق المصدر هو PyTorch، وليس هدف تصدير عبر API.

يعتمد nms=None على المخرجات الأولية لإجراء NMS خارجي. اضبط nms=False لتحديد رأس متاح خالٍ من NMS؛ وتعود التنسيقات غير المدعومة إلى مسار المخرجات الأصلي الخاص بها. تحدد إدخالات nms أعلاه التنسيقات التي يمكنها تضمين NMS باستخدام nms=True.

الحصول على حالة التصدير#

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

يعيد الكائن export مع status وformat وargs وgpuType (لـ TensorRT فقط) والطوابع الزمنية، وعند الاكتمال، كائن file الذي يتضمن size وdownloadUrl وdownloadFilename.

إلغاء عملية تصدير أو حذفها#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

يلغي عملية تصدير نشطة أو يحذف عملية مكتملة وملفها. توضح الاستجابة الإجراء الذي تم:

{
    "success": true,
    "action": "cancelled"
}

واجهة API لعمليات النشر#

انشر النماذج على نقاط نهاية استدلال مخصصة مع فحوصات السلامة والمراقبة. راجع وثائق نقاط النهاية.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action start| C
    C -->|delete| E[Deleted]:::error
    D -->|delete| E
    C -->|predict| F[Inference Results]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

عرض عمليات النشر#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

معلمات الاستعلام:

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

إنشاء عملية نشر#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

النص:

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

الاستجابة (201): id وdeployment وstatus (creating) وmessage وregion.

الحصول على عملية نشر#

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

يعيد كائن deployment مع status وstatusMessage وregion وserviceUrl وresources وmetadata المخصص، بالإضافة إلى camera وcameraApplying للمالك.

تحديث عملية نشر#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

أرسل أحد هذه النصوص:

{ "name": "Edge 1 (primary)" }

يغيّر إعادة التسمية قيمة deployment في URL إلى مقطع URL مشتق من الاسم الجديد، وتُعاد هذه القيمة باسم deployment؛ ويعيد المسار القديم 404، بينما يظل serviceUrl كما هو. يمحو الكائن الفارغ metadata البيانات الوصفية المخصصة. يؤدي الاستبدال إلى نشر مراجعة جديدة مع الحفاظ على معرّف عملية النشر والمنطقة وعنوان URL لنقطة النهاية؛ وتظل المراجعة الحالية نشطة إذا فشل النشر. يجب أن يكون النموذج البديل نموذجًا مكتملًا بأوزان يمكن لمفتاحك الوصول إليها. يحفظ إجراء الكاميرا كاميرا RTSP أو RTSPS تُبقيها نقطة نهاية جاهزة ذات موارد مخصصة قيد التشغيل للاستدلال (راجع كاميرا تعمل في الخلفية)؛ وتزيلها "url": null، وكذلك إعادة الحجم إلى الحجم الافتراضي، كما أن حفظ كاميرا على نقطة نهاية ذات الحجم الافتراضي يعيد 403. يعيد تغيير الكاميرا 202 مع status وready أثناء تطبيقه: استعلم عن عملية النشر إلى أن تصبح cameraApplying غير true، ثم تحقّق من camera؛ ويُبقي التغيير الفاشل الكاميرا السابقة ويضبط statusMessage. تعيد العمليات المكتملة 200 مع status وready أو stopped؛ أما العمليات الأخرى التي لا تزال قيد النشر فتعيد 202 مع deploying أو stopping.

حذف النشر#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

يزيل نقطة نهاية الاستدلال نهائياً.

فحص الحالة#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

يرسل طلبات تحقق إلى نقطة النهاية وينشّطها، ويُرجع healthy وlatencyMs ورمز status من الخدمة الأصلية.

تشغيل الاستدلال على عملية نشر#

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

يوجّه صورة أو فيديو عبر نقطة النهاية المخصصة. تتطابق مواصفات الطلب والاستجابة مع استدلال النموذج. لا تُمرر تدفقات الكاميرا عبر وسيط؛ أرسلها إلى عنوان URL لنقطة النهاية كما هو موضح في الاستدلال المباشر بالكاميرا.

نموذج متعدد الأجزاء:

الحصول على المقاييس#

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

معلمات الاستعلام:

تتضمن الاستجابة الكاملة summary (إجمالي الطلبات ومعدل الأخطاء ومتوسط زمن الاستجابة وقيم p50/p95/p99) وtimeSeries (الطلبات والأخطاء وزمن الاستجابة ووحدة المعالجة المركزية والذاكرة وعدد المثيلات). وتعيد استجابة المخطط المصغر requests24h (أعداد الطلبات بالساعة؛ وتُحذف الساعات التي لم تتضمن طلبات) وtotalRequests وerrorRate وavgLatencyMs (متوسط أزمنة الاستجابة P95 بالساعة). عند استخدام view=overview، يحتوي summary على totalRequests وerrorRate وp95LatencyMs، ويحتوي timeSeries على requests وerrors وlatencyP95.

الحصول على السجلات#

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

معلمات الاستعلام:

واجهة برمجة تطبيقات الوكلاء#

احفظ سير عمل الوكلاء وأدِره. تخزّن واجهة برمجة التطبيقات تعريفات الوكلاء؛ وتبدأ عمليات التشغيل من لوحة الوكلاء، حيث يفتح https://platform.ultralytics.com/agents?workflow={id} وكيلاً محفوظاً. تتطلب طرائق Python SDK ultralytics-platform>=0.1.74.

تقبل كل عملية معلّمة استعلام اختيارية باسم owner تحدد اسم المستخدم لمساحة عمل تنتمي إليها (الافتراضي: مساحة عملك). يتطلب عرض القوائم صلاحية المشاهدة؛ ويتطلب الحفظ والحذف صلاحية التحرير.

عرض الوكلاء#

GET /api/workflows

Python SDK: client.agents.list()

تعرض الاستجابة ما يصل إلى 100 وكيل ضمن workflows، مرتبة من الأحدث تحديثاً إلى الأقدم، ويتضمن كل منها id وusername وname وversion وcreatedAt وupdatedAt. ويؤدي طلب id أيضاً إلى إرجاع graph الخاص بالوكيل.

حفظ وكيل#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

أرسل version: 0 لإنشاء وكيل. لتحديث وكيل، أرسل id وversion اللذين أعادتهما آخر عملية عرض قائمة أو حفظ؛ ويؤدي استخدام version قديم إلى إرجاع 409، لذا اعرض قائمة الوكلاء مجدداً ثم أعد المحاولة. وتؤدي بنية الرسم البياني التي تشكل اتصالاتها دورة أو تمنح كتلة أكثر من مُدخل واحد إلى إرجاع 400.

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

تعيد الاستجابة id الخاص بالوكيل، وversion الجديد، وerrors: الكتل التي ستضع لوحة العمل علامة عليها، مثل كتلة Dataset التي لم تُحدَّد لها مجموعة بيانات. يُحفظ الوكيل في كلتا الحالتين. راجع openapi.json للاطلاع على جميع أنواع الكتل وإعداداتها.

حذف وكيل#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

يحذف الوكيل ويلغي عمليات التشغيل النشطة الخاصة به. لا تظهر الوكلاء المحذوفة في سلة المحذوفات، ولا يمكن استعادتها.

واجهة برمجة تطبيقات سلة المحذوفات#

اعرض المشاريع ومجموعات البيانات والنماذج المحذوفة حذفاً مبدئياً، واستعدها أو احذفها نهائياً. تُحذف العناصر تلقائياً بعد 30 يوماً. راجع وثائق سلة المحذوفات.

عرض سلة المحذوفات#

GET /api/trash

Python SDK: client.lifecycle.trash()

معلمات الاستعلام:

تتضمن الاستجابة items (ويتضمن كل عنصر منها daysRemaining) وtotal وpage وlimit وtotalPages وsummary الذي يحتوي على الإجماليات حسب النوع. وعند استخدام id، تُرجع الاستجابة بدلاً من ذلك resources: النماذج المتأثرة وعمليات النشر التي سيُحذف كل منها نهائياً.

استعادة عنصر#

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

تؤدي استعادة مشروع أيضاً إلى استعادة النماذج التي نُقلت إلى سلة المحذوفات معه، ويُبلّغ عنها في restoredModels.

الحذف نهائياً#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

حذف عنصر واحد:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

أو إفراغ سلة المحذوفات بأكملها:

{
    "all": true
}

تُبلغ الاستجابة عن deletedCount، بالإضافة إلى cascadedModels وsurvivingDeployments عند الاقتضاء.

واجهة برمجة تطبيقات الرفع#

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

الحصول على عنوان URL موقّع للرفع#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

النص:

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

الاستجابة:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z",
    "headers": { "x-goog-if-generation-match": "0" }
}

ارفع الملف باستخدام طلب PUT إلى uploadUrl، مع استخدام Content-Type نفسه الذي حددته، وإرسال جميع الترويسات المُعادة ضمن headers. تظل عناوين URL الخاصة برفع مجموعات البيانات صالحة لمدة 12 ساعة، وتُستخدم للإنشاء فقط: يؤدي إرسال PUT مرة أخرى إلى عنوان URL نفسه إلى إرجاع 412، كما يؤدي إرسال PUT دون الترويسات المُعادة إلى إرجاع 400.

إكمال الرفع#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

الاستجابة: success وكائن file الذي يتضمن size وcontentType. بالنسبة إلى النماذج، يؤدي ذلك إلى إرفاق الأوزان؛ أما أرشيفات مجموعات البيانات، فاستدعِ ingest بعد ذلك لبدء المعالجة.

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

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

اربط حسابات Google Cloud Storage أو Amazon S3 أو Azure Blob Storage للقراءة فقط، واستعرض محتوياتها كمصادر لمجموعات البيانات. راجع وثائق التكاملات.

يتطلب اكتشاف التخزين وربطه صلاحية مسؤول مساحة العمل وخطة Pro أو Enterprise (وإلا فستكون 403)؛ ويتطلب عرض التكاملات واستعراض الكائنات صلاحية التحرير.

عرض التكاملات#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

تعيد integrations، ويحتوي كل عنصر منها على id وprovider وcredentialIdentity وtargets وcreatedAt. لا تُعاد بيانات اعتماد مطلقاً.

اكتشاف المواقع#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

يعرض الحاويات أو الدلاء التي يمكن قراءتها باستخدام بيانات الاعتماد المقدمة، من دون حفظها.

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

الاستجابة: {"targets": ["my-bucket", "another-bucket"]}

ربط التخزين#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

تستخدم بيانات الاعتماد البنى نفسها المستخدمة في الاكتشاف، مع مصفوفة targets مطلوبة تتضمن أسماء من 1 إلى 50 حاوية أو دلو. وتُرجع 201 مع التكامل المخزّن. تُرفض بيانات اعتماد S3 المؤقتة (ASIA access keys).

استعراض الكائنات#

GET /api/integrations/buckets/{id}/objects

Python SDK: client.storage_integrations.objects(id, target=...)

معلمات الاستعلام:

تعيد entries (وتكون قيمة كل kind إما folder أو file) ومعها cursor اختياري للصفحة التالية.

إلغاء ربط التخزين#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

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

واجهة برمجة تطبيقات استيراد مجموعات البيانات#

استورد مجموعات البيانات من خدمات جهات خارجية. راجع تكامل Roboflow.

معاينة استيراد Roboflow#

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

تحوّل مفتاح API الخاص بـ Roboflow إلى خطة استيراد تتضمن تفاصيل مساحة العمل، وnewDatasets التي ستُستورد، وأعداد المشاريع المستوردة مسبقاً (skippedCount) والمشاريع التي لا تتضمن إصدارات أو غير المدعومة أو التي تعذر حلها، وbytesTotal، والسعة المتبقية storage لديك. يُقرأ مفتاح API الخاص بـ Roboflow من متن الطلب ولا يُحفظ.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

الاستيراد من Roboflow#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

يضع مهام إدخال البيانات في قائمة الانتظار لما يصل إلى 500 إصدار محدد من مشاريع Roboflow، باستخدام العناصر المُعادة في المعاينة.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

الاستجابة (201): مصفوفات imported وfailed وskipped. تتطلب عمليات الاستيراد سعة تخزين متاحة، ويجب ألا يتجاوز حجم كل مجموعة بيانات الحد الأقصى لحجم الاستيراد في خطتك.

واجهة برمجة تطبيقات الحساب#

اطّلع على حسابك في Platform ومفاتيحك ومساحة التخزين وملفاتك الشخصية العامة. راجع وثائق الإعدادات.

ملخص الحساب#

GET /api/account/summary

Python SDK: client.account.summary()

تعيد الخطة ورصيد الاعتمادات وأعداد الموارد لمساحة العمل التي أصدرت المفتاح.

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

عرض مفاتيح API#

GET /api/api-keys

Python SDK: client.account.api_keys()

تعيد keys مع keyId وname وkeyPrefix وcreatedAt لمساحة العمل المرتبطة بالمفتاح. لا تتلقى الطلبات الموثّقة بمفتاح API سوى البيانات الوصفية؛ أما القيم الكاملة للمفاتيح فتظهر لمالك مساحة العمل في الإعدادات > مفاتيح API ضمن واجهة مستخدم Platform، حيث تُنشأ المفاتيح وتُلغى أيضاً.

التحقق من استخدام التخزين#

GET /api/storage

Python SDK: client.account.storage()

معلمات الاستعلام:

الاستجابة:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

تعرض usage أعداد projects وdatasets وmodels وimages وannotations وdeployments، والبايتات لـ storage. وتعني قيمة limit البالغة -1 أن الحد غير محدود، بينما تمثل percent نسبة مئوية صحيحة من الحد.

الحصول على ملف شخصي عام لمستخدم#

GET /api/users

Python SDK: client.account.profile(username=...)

معلمات الاستعلام:

تعيد الملف الشخصي العام user مع followerCount، ومع isFollowed للجهات المستدعية التي تمت مصادقتها.

متابعة مستخدم أو إلغاء متابعته#

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

{
    "username": "target-user",
    "followed": true
}

الاستجابة: followed وfollowerCount بعد تحديثه.

واجهة API للفوترة#

تحقّق من استخدام الخطة وسجلّ الرصيد. راجع وثائق الفوترة.

عرض الخطة والاستخدام#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

تعرض plan (المعرّف والحالة ودورة الفوترة ونهاية الفترة)، وmetrics (حد التخزين والاستخدام)، وtrainingCredit، وfeatures، وcreditsCents، وعدد المقاعد.

عرض المعاملات#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

معلمات الاستعلام:

تتضمن كل معاملة id، وtype (مثل purchase أو training أو monthly_grant أو refund)، وamountCents، وbalanceAfter، وcreatedAt، وreceiptUrl اختياريًا، وسياق النموذج لرسوم التدريب. لا تُعاد تفاصيل الفوترة الداخلية مطلقًا.

واجهة API للاستكشاف#

ابحث عن المشاريع ومجموعات البيانات العامة التي يشاركها المجتمع، أو ابحث عن الصور بحسب محتواها. راجع وثائق الاستكشاف.

البحث في المحتوى العام#

GET /api/explore/search

Python SDK: client.explore.search()

معلمات الاستعلام:

الاستجابة: projects وdatasets وhasMore. يعيد type=images تطابقاته في images بدلًا من ذلك، بدءًا بأفضل تطابق؛ ويتضمن كل تطابق dataset المصدر وscore للتشابه بقيمة بين 0 و1؛ ويتطلب q ويبحث في مجموعات البيانات العامة، بالإضافة إلى مجموعات بياناتك ومجموعات بيانات الفريق عند إرسال مفتاح API.

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&task=detect&sort=stars&limit=20"

حزمة Python SDK#

يُعدّ ultralytics-platform عميل Python مولّدًا ذا أنواع محددة استنادًا إلى عقد OpenAPI، ويضم طريقة واحدة لكل نقطة نهاية (client.datasets.list، وclient.models.predict، وclient.exports.create، ...). تقبل كل طريقة معلمات المسار موضعيًا، وسائر المدخلات كوسائط كلمات مفتاحية، إضافة إلى timeout وextra_headers الاختياريين لكل طلب.

pip install "ultralytics-platform>=0.1.45" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # ⁨يقرأ ULTRALYTICS_API_KEY أو المفتاح المحفوظ بواسطة yolo login⁩
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

تعرض AsyncPlatform شجرة الموارد نفسها لرمز async/await، وتؤدي الاستجابات غير الناجحة إلى رفع APIError مع status_code وbody وjson بعد تحليله، بينما تؤدي حالات فشل الاتصال إلى رفع APIConnectionError. راجع مستودع SDK للاطلاع على ملف README الكامل.

تكامل Python#

لسير عمل التدريب والاستدلال، استخدم حزمة Ultralytics Python، التي تتولى المصادقة والتحميلات وبث المقاييس في الوقت الفعلي تلقائيًا. في Python 3.11 والإصدارات الأحدث، تثبّت pip install ultralytics أيضًا حزمة SDK المسماة ultralytics-platform. عندما يستهدف model.train(project=...) منصة Platform، تبث استدعاءات التدريب الراجعة الأحداث عبر client.training.metrics() التابعة لحزمة SDK، وتطلب عناوين URL لتحميل نقاط التحقق عبر client.models.upload_checkpoint()، وهما العمليتان POST /api/webhooks/training/metrics وPOST /api/webhooks/models/upload في مستند OpenAPI، لذا لا حاجة إلى استدعائهما بنفسك.

التثبيت والإعداد#

يتطلب التكامل مع Platform Python>=3.11 وultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

تحقّق من التثبيت:

yolo check

المصادقة#

yolo login YOUR_API_KEY

استخدام مجموعات بيانات المنصة#

أشِر إلى مجموعات البيانات باستخدام معرّفات URI من ul://:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# ⁨درّب باستخدام مجموعة بيانات Platform الخاصة بك⁩
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

تنسيق URI:

الإرسال إلى Platform#

أرسل النتائج إلى مشروع على Platform:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# ⁨تُزامَن النتائج تلقائيًا مع Platform⁩
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

ما تتم مزامنته:

• مقاييس التدريب (في الوقت الفعلي)
• أوزان النموذج النهائية
• مخططات التحقق
• مخرجات وحدة التحكم
• مقاييس النظام
• وسيطات التدريب وبيئة المضيف (اسم المضيف ونظام التشغيل وPython والأجهزة وإيداع git وسطر الأوامر)

أمثلة على API#

تحميل نموذج من Platform:

# ⁨نموذجك الخاص⁩
model = YOLO("ul://username/project/model-name")

# ⁨نموذج رسمي⁩
model = YOLO("ul://ultralytics/yolo26/yolo26n")

تنفيذ الاستدلال:

results = model("image.jpg")

# ⁨الوصول إلى النتائج⁩
for r in results:
    boxes = r.boxes  # ⁨مربعات الكشف⁩
    masks = r.masks  # ⁨أقنعة التجزئة⁩
    keypoints = r.keypoints  # ⁨نقاط مفاصل الوضعية⁩
    probs = r.probs  # ⁨احتمالات التصنيف⁩

تصدير النموذج:

# ⁨التصدير إلى ONNX⁩
model.export(format="onnx", imgsz=640, quantize=16)

# ⁨التصدير إلى TensorRT⁩
model.export(format="engine", imgsz=640, quantize=16)

# ⁨التصدير إلى CoreML⁩
model.export(format="coreml", imgsz=640)  # ⁨استخدم imgsz=224 للتصنيف⁩

التحقق:

metrics = model.val(data="ul://username/datasets/my-dataset")

print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")

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