مفاتيح API#

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

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

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

1. انتقل إلى الإعدادات > مفاتيح API
2. انقر فوق إضافة مفتاح وحدد Ultralytics كمزود
3. أدخل اسمًا للمفتاح (مثلًا: "خادم التدريب")
4. انقر على إنشاء مفتاح

اسم المفتاح#

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

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

عرض المفتاح#

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

مفاتيح المزود للوكلاء#

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

1. انقر فوق إضافة مفتاح.
2. حدد المزود المطابق للغة أو نموذج الرؤية واللغة الخاص بسير عملك.
3. الصق مفتاح API الخاص بهذا المزود في مفتاح API، ثم انقر فوق حفظ المفتاح. يفتح رابط الحصول على مفتاح API في مربع الحوار صفحة مفاتيح المزود.

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

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

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

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

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

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

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

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

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

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

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

التحقق من المفتاح وحفظه باستخدام واجهة سطر الأوامر الخاصة بـ 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/...

أو قم بتمريره إلى حزمة تطوير البرمجيات Python SDK (pip install "ultralytics-platform>=0.1.32")، والتي تقرأ 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. أكّد الإبطال

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

إذا كُشف مفتاح:

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. استخدم نقطة نهاية مخصصة عندما تحتاج إلى سعة استدلال معزولة

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