مفاتيح API#

توفر مفاتيح واجهة برمجة التطبيقات الخاصة بـ Ultralytics Platform إمكانية وصول برمجية آمنة للتدريب عن بُعد، والاستدلال، والتمكين الآلي. أنشئ مفاتيح مسماة بتشفير AES-256-GCM لحالات الاستخدام المختلفة.

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

إنشاء مفتاح API جديد:

1. اذهب إلى الإعدادات > مفاتيح API
2. انقر على إنشاء مفتاح (Create Key)
3. أدخل اسماً للمفتاح (على سبيل المثال، "خادم التدريب")
4. انقر على إنشاء مفتاح (Create Key)

اسم المفتاح#

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

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

عرض المفتاح#

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

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

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

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

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

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

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

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

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

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

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

التحقق من المفتاح وحفظه باستخدام YOLO CLI:

yolo login YOUR_API_KEY

قم بإزالة المفتاح المحفوظ باستخدام yolo logout.

رؤوس HTTP#

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

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

أو قم بتمريره إلى Python SDK (pip install "ultralytics-platform>=0.1.5")، الذي يقرأ أيضاً ULTRALYTICS_API_KEY:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

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

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

قم بتمكين بث المقاييس باستخدام مفتاحك.

قم بتثبيت أو تحديث حزمة Ultralytics قبل البدء:

pip install -U ultralytics

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

راجع Cloud Training للحصول على دليل التدريب الشامل عن بُعد.

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

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

تم سرد كافة المفاتيح في علامة التبويب Settings > API Keys:

تعرض كل بطاقة مفتاح اسم المفتاح، وقيمة المفتاح القابلة للنسخ، ووقت الإنشاء النسبي، وزر الإلغاء.

إلغاء المفتاح#

إلغاء مفتاح تم اختراقه أو لم تعد بحاجة إليه:

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

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

إذا تم اختراق مفتاح ما:

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

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

ترتبط مفاتيح API بمساحة العمل النشطة حالياً:

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

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

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

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

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

افعل#

• قم بتخزين المفاتيح في متغيرات البيئة
• استخدم مفاتيح منفصلة لبيئات مختلفة
• قم بإلغاء المفاتيح غير المستخدمة على الفور
• قم بتدوير المفاتيح بشكل دوري
• استخدم أسماء وصفية لتحديد أغراض المفاتيح

لا تفعل#

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

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

قم بتدوير المفاتيح بشكل دوري لأغراض أمنية:

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

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

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

Error: Invalid API key

الحلول:

1. تحقق من نسخ المفتاح بشكل صحيح (بما في ذلك البادئة ul_)
2. تأكد من أن المفتاح لم يتم إلغاؤه
3. تأكد من تعيين متغير البيئة
4. تأكد من أنك تستخدم 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. استخدم dedicated endpoint عندما تحتاج إلى سعة استدلال معزولة

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