مفاتيح API#

تتيح مفاتيح API في Ultralytics Platform وصولًا برمجيًا آمنًا للتدريب عن بُعد والاستدلال والأتمتة. أنشئ مفاتيح بأسماء محددة، مشفرة باستخدام AES-256-GCM، لاستخدامات مختلفة.

إنشاء مفتاح API#

أنشئ مفتاح API جديدًا:

1. انتقل إلى Settings > API Keys
2. انقر على Add Key واختر Ultralytics موفرًا للخدمة
3. أدخل اسمًا للمفتاح (مثل "Training Server")
4. انقر على Create Key

اسم المفتاح#

امنح مفتاحك اسمًا وصفيًا:

• training-server - لأجهزة التدريب عن بُعد
• ci-pipeline - لتكامل CI/CD
• local-dev - للتطوير المحلي

عرض المفتاح#

بعد إنشاء المفتاح، سيظهر في مربع حوار التأكيد:

مفاتيح موفري الخدمات للوكلاء والتعليقات التوضيحية#

يخزّن تبويب Settings > API Keys نفسه أيضًا مفاتيح موفري النماذج الخارجيين التي تستخدمها الوكلاء والنماذج المدفوعة في التعليقات التوضيحية الموجّهة بالفئات؛ وتستخدم التعليقات التوضيحية المفتاح المحفوظ في مساحة عمل مجموعة البيانات. ولا يمكن إضافة هذه المفاتيح أو استبدالها أو إزالتها إلا لمالك مساحة العمل؛ أما أعضاء الفريق فيمكنهم معرفة موفري الخدمات المتصلين. اطلب من المالك توصيل أي موفر خدمة غير متصل. لتوصيل موفر خدمة بصفتك المالك:

1. انقر على Add Key.
2. اختر موفر الخدمة المطابق لنموذج اللغة أو النموذج متعدد الوسائط للغة والرؤية في سير عملك، أو نموذج التعليقات التوضيحية الذي تريد تشغيله.
3. الصق مفتاح API الخاص بموفر الخدمة في API Key، ثم انقر على Save Key. يفتح رابط Get an API key في مربع الحوار صفحة مفاتيح موفر الخدمة.

لا يُستخدم مفتاح Ultralytics للمصادقة لدى موفري النماذج الخارجيين. تُحتسب تكلفة استخدام موفر الخدمة على الحساب المرتبط بالمفتاح المحفوظ. استخدم عنصر التحرير في صف المفتاح لاستبدال مفتاح موفر الخدمة.

تنسيق المفتاح#

تتبع مفاتيح API هذا التنسيق:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• البادئة: يعرّف ul_ مفاتيح Ultralytics
• المتن: 40 محرفًا سداسيًا عشريًا عشوائيًا
• الإجمالي: 43 محرفًا

أمان المفاتيح#

• تُخزَّن المفاتيح مشفرة باستخدام AES-256-GCM، ولا تُخزَّن أبدًا كنص عادي
• تُستخدم الأحرف الـ11 الأولى (ul_ بالإضافة إلى 8 محارف سداسية عشرية) كبادئة للعرض، ما يتيح التعرف على المفتاح دون كشفه

استخدام مفاتيح API#

متغير البيئة#

عيّن مفتاحك كمتغير بيئة:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

واجهة سطر أوامر YOLO#

تحقّق من المفتاح واحفظه باستخدام واجهة سطر أوامر YOLO على Python>=3.11:

yolo login YOUR_API_KEY

أزِل المفتاح المحفوظ باستخدام yolo logout.

ترويسات HTTP#

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

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

أو مرّره إلى SDK الخاص بـ Python (pip install "ultralytics-platform>=0.1.45")، الذي يقرأ ULTRALYTICS_API_KEY أو المفتاح المحفوظ بواسطة yolo login عند إغفال api_key:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

راجع مرجع REST API للاطلاع على جميع نقاط النهاية المتاحة.

التدريب عن بُعد#

فعّل تدفق المقاييس باستخدام مفتاحك.

ثبّت حزمة Ultralytics أو حدّثها على Python>=3.11 قبل البدء:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

راجع التدريب السحابي للاطلاع على الدليل الكامل للتدريب عن بُعد.

إدارة المفاتيح#

عرض المفاتيح#

تُدرج جميع المفاتيح في تبويب Settings > API Keys:

يعرض كل صف مفتاح اسم المفتاح وبادئته وتاريخ إنشائه وزرًا لنسخ المفتاح كاملًا وزرًا للإزالة (سلة المهملات).

إبطال مفتاح#

أبطِل مفتاحًا تعرّض للاختراق أو لم تعد بحاجة إليه:

1. اعثر على المفتاح في قسم مفاتيح API
2. انقر على زر الإزالة (سلة المهملات)
3. انقر على Remove Key للتأكيد

إعادة إنشاء مفتاح#

إذا تعرّض مفتاح للاختراق:

1. أنشئ مفتاحًا جديدًا بالاسم نفسه
2. حدّث تطبيقاتك
3. أبطِل المفتاح القديم

مفاتيح API لمساحة العمل#

تُقيَّد مفاتيح API بمساحة العمل النشطة حاليًا:

• مساحة العمل الشخصية: تُستخدم المفاتيح للمصادقة بصفة حسابك الشخصي
• مساحة عمل الفريق: تُستخدم المفاتيح للمصادقة بصفة مالك مساحة عمل الفريق، مع صلاحيات المالك كاملةً في مساحة العمل تلك

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

مفاتيح عمال On Premise#

يؤدي توصيل مضيف On Premise إلى إنشاء مفتاح عامل منفصل. تُدار مفاتيح العمال من تكامل On Premise لا من هذا التبويب، ولا تُدرج مطلقًا مع مفاتيح API الخاصة بك، ويُبطَل المفتاح بفصل المضيف — ما يؤدي أيضًا إلى إلغاء المهام الموجودة في قائمة انتظار ذلك المضيف والمهام قيد التشغيل.

أفضل ممارسات الأمان#

افعل#

• خزّن المفاتيح في متغيرات البيئة
• استخدم مفاتيح منفصلة للبيئات المختلفة
• أبطِل المفاتيح غير المستخدمة على الفور
• غيّر المفاتيح دوريًا
• استخدم أسماء وصفية لتحديد أغراض المفاتيح

لا تفعل#

• لا تُودِع المفاتيح في نظام التحكم بالإصدارات
• لا تشارك المفاتيح بين التطبيقات
• لا تُسجّل المفاتيح في مخرجات التطبيق
• لا تُضمّن المفاتيح في التعليمات البرمجية من جهة العميل

تدوير المفاتيح#

دوّر المفاتيح دوريًا لتعزيز الأمان:

1. أنشئ مفتاحًا جديدًا بالاسم نفسه
2. حدّث التطبيقات لاستخدام المفتاح الجديد
3. تحقق من عمل التطبيقات على نحو صحيح
4. ألغِ المفتاح القديم

استكشاف الأخطاء وإصلاحها#

خطأ: مفتاح غير صالح#

Error: Invalid API key

الحلول:

1. تحقق من نسخ المفتاح على نحو صحيح (بما في ذلك البادئة ul_)
2. تحقق من عدم إلغاء المفتاح
3. تأكد من تعيين متغير البيئة
4. تأكد من استخدام Python>=3.11 وultralytics>=8.4.120

تم رفض الإذن#

Error: Permission denied for this operation

الحلول:

1. تحقق من أنك مالك المورد أو أن لديك صلاحية الوصول المناسبة إلى مساحة العمل
2. تحقق من أن المفتاح تابع لمساحة العمل الصحيحة
3. إذا كنت تدير المفاتيح في مساحة عمل لفريق، فتأكد من أنك مالك مساحة العمل — إذ لا تحصل الأدوار الأخرى على Workspace owner access required
4. أنشئ مفتاحًا جديدًا إذا لزم الأمر

تم تجاوز حد المعدل#

Error: Rate limit exceeded

الحلول:

1. خفّض وتيرة الطلبات — راجع جدول حدود المعدل للاطلاع على الحدود الخاصة بكل فئة
2. طبّق التراجع الأُسّي باستخدام ترويسة Retry-After
3. استخدم نقطة نهاية مخصصة عندما تحتاج إلى سعة استدلال معزولة

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