رموز وصول المستخدم

ما هي رموز وصول المستخدم؟

تُعد رموز وصول المستخدم الطريقة المفضلة لمصادقة تطبيق أو دفتر ملاحظات على خدمات Hugging Face. يمكنك إدارة رموز الوصول الخاصة بك في الإعدادات.

تتيح رموز الوصول للتطبيقات ودفاتر الملاحظات (notebooks) تنفيذ إجراءات محددة تحددها نطاقات الأدوار المعروضة فيما يلي:

• fine-grained: يمكن استخدام الرموز المميزة التي تحمل هذا الدور لمنح وصول دقيق إلى موارد محددة، مثل نموذج معين أو نماذج ضمن منظمة معينة. يُعد هذا النوع من الرموز المميزة مفيدًا في بيئات الإنتاج، إذ يمكنك استخدام رمزك المميز دون مشاركة الوصول إلى جميع مواردك.

• read: يمكن استخدام الرموز المميزة بدور القراءة فقط لمنح وصول للقراءة إلى المستودعات التي يمكنك قراءتها. ويشمل ذلك المستودعات العامة والخاصة التي تملكها أنت أو منظمة أنت عضو فيها. استخدم هذا الدور إذا كنت بحاجة فقط إلى قراءة المحتوى من Hugging Face Hub (مثلًا عند تنزيل النماذج الخاصة أو تنفيذ الاستدلال).

• write: تمنح الرموز ذات هذا الدور صلاحيات كتابة إضافية على المستودعات التي تملك صلاحيات كتابة عليها. استخدم هذا الرمز إذا كنت بحاجة إلى إنشاء محتوى أو دفعه إلى مستودع (مثلًا، عند تدريب نموذج أو تعديل بطاقة نموذج).

إذا كنت عضوًا في منظمة بدور القراءة/الكتابة/الإدارة، فستتمكن رموز وصول المستخدم الخاصة بك من قراءة/كتابة الموارد وفقًا لصلاحيات الرمز (قراءة/كتابة) وعضوية المنظمة (قراءة/كتابة/إدارة).

كيف تُدار رموز وصول المستخدم؟

لإنشاء رمز وصول، انتقل إلى إعداداتك ثم انقر على تبويب رموز الوصول. انقر على زر رمز جديد لإنشاء رمز وصول مستخدم جديد.

اختر دورًا واسمًا لرمزك، وها أنت جاهز للانطلاق!

يمكنك حذف رموز وصول المستخدم وتحديثها بالنقر على زر Manage.

كيف تستخدم رموز وصول المستخدم؟

تتوفر طرق عديدة لاستخدام رمز وصول المستخدم (User Access Token) للوصول إلى Hugging Face Hub، مما يمنحك المرونة التي تحتاجها لبناء تطبيقات رائعة فوقه.

يمكن أن تكون رموز وصول المستخدم:

• يُستخدم بديلًا عن كلمة المرور للوصول إلى Hugging Face Hub باستخدام git أو المصادقة الأساسية.
• يُمرَّر كـ رمز حامل عند استدعاء مزودي الاستدلال.
• المستخدمة في مكتبات Python الخاصة بـ Hugging Face، مثل transformers أو datasets:

from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

حاول ألا تسرّب رمزك! فمع أنه يمكنك دائمًا تدويره، إلا أن أي شخص سيكون قادرًا على قراءة مستودعاتك الخاصة أو الكتابة فيها خلال تلك الفترة، وهذا أمر سيئ. راجع إلغاء رمز مسرّب إذا كان رمزك قد تعرّض للكشف.

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

ننصحك بإنشاء رمز وصول واحد لكل تطبيق أو استخدام. على سبيل المثال، يمكنك استخدام رمز منفصل لـ:

• جهاز محلي.
• دفتر Colab.
• خادم استنتاج مخصص رائع.

بهذه الطريقة، يمكنك إبطال رمز واحد دون التأثير على استخداماتك الأخرى.

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

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

لخطوط أنابيب CI/CD

إذا كنت بحاجة فقط إلى الوصول من سير عمل CI/CD (GitHub Actions، GitLab CI، CircleCI، …)، يمكنك تجنب تخزين رمز وصول كسر CI بالكامل. راجع الناشرون الموثوقون، الذي يستبدل رمز الهوية الخاص بمزود CI الخاص بك (OpenID Connect (OIDC)) برمز Hub قصير العمر في بداية كل تشغيل — إما على نطاق المستودع (لنشر النماذج أو مجموعات البيانات أو Spaces أو الأنوية، أو لجلبها للقراءة فقط) أو على نطاق المستخدم (لقراءة المستودعات المقيدة التي لديك وصول إليها والحصول على حدود معدل حسابك).

لمنظمات المؤسسات

إذا كانت مؤسستك بحاجة إلى إصدار الرموز البرمجية للأعضاء برمجياً دون الحاجة إلى قيام كل مستخدم بإنشاء رمزه الخاص، فراجع OAuth Token Exchange. هذه الميزة المخصصة لخطة المؤسسات مثالية لبناء منصات داخلية، أو خطوط CI/CD، أو تكاملات مخصصة تحتاج إلى الوصول إلى موارد Hugging Face نيابةً عن أعضاء المؤسسة.

سحب رمز تم تسريبه

إذا تسرّب أحد رموزك الخاصة، احذفه أو حدّثه من تبويب رموز الوصول في إعداداتك.

إذا وجدتَ رمز وصول Hugging Face خاصاً بشخص آخر، يمكنك إبطاله باستخدام نقطة النهاية POST /api/credentials/revoke. لا تحتاج إلى أي صلاحيات على الحساب أو المؤسسة التي يملك الرمز.

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

يمكنك تمرير عدة قيم رموز في مصفوفة credentials في استدعاء واحد، وهو ما يسهّل خطوط الأنابيب التي تفحص الأسرار وتقارير النتائج على دفعات.

يتم تعطيل كل رمز مُقدَّم يطابق رمزًا موجودًا فورًا ويتوقف عن العمل في كل مكان — على عكس إلغاء الصلاحية على مستوى المنظمة، الذي يقطع وصول الرمز إلى منظمة واحدة فقط. يُبلَّغ مالك الرمز عبر البريد الإلكتروني ويحتاج إلى إنشاء رمز جديد لاستعادة الوصول.

يستجيب نقطة النهاية دائمًا بـ 202 Accepted، سواءً كانت أي من الرموز التي قمت بإرسالها موجودة أم لا، لذا لا يمكن استخدام استجابتها لاستكشاف ما إذا كان الرمز صالحًا. إعادة إرسال الرمز نفسه أمر غير ضار: فالتكرار في الاستدعاءات لا يؤدي إلى أي شيء، ولا يتم إشعار المالك إلا مرة واحدة.

لتجنّب تسرّب قيم الرموز في سجلّ الطرفية أو السجلات، قم بتمريرها عبر متغيرات البيئة أو الملفات، وتجنّب لصق الرموز الخام مباشرةً في سطر الأوامر.

رموز في المنظمات التي لديها سياسات لإدارة الرموز

يمكن للمنظمات التي تشترك في باقات Team وEnterprise فرض سياسات رموز (Tokens) تؤثر على طريقة عمل رموزك عند الوصول إلى موارد تلك المنظمة.

عندما يتطلب رمزك موافقة (منظمات الفريق والمؤسسات)

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

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

إذا كنت مسؤولاً في المنظمة، فإن الرموز الدقيقة التي تنشئها ضمن نطاق تلك المنظمة تُعتمد تلقائيًا — ولا يلزم إجراء مراجعة.

عند رفض رمزك (منظمات الفريق والمؤسسات)

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

عند محاولة استخدام رمز مرفوض مقابل موارد المنظمة، ستحصل على خطأ 403.

عندما يتم إلغاء صلاحية رمزك (منظمات المؤسسات)

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

عند محاولة استخدام رمز تم سحبه ضد موارد المنظمة، ستحصل على خطأ 403 مع الرسالة: “تم سحب رمزك من قبل مسؤول المنظمة، ولم يعد بإمكانك الوصول إلى موارد المنظمة. يرجى التواصل معهم لمزيد من المعلومات.”

لا يؤثر السحب إلا على المنظمة التي قامت به. يستمر الرمز في العمل بشكل طبيعي لجميع الموارد الأخرى التي تم تحديد نطاقه لها.

عندما تسمح مؤسستك فقط برمزات دقيقة (منظمات الفريق والمؤسسات)

إذا كانت مؤسستك قد وضعت سياسة تتطلب الرموز الدقيقة، فسيتم رفض رموز القراءة/الكتابة مع خطأ 403 عند استخدامها على موارد تلك المؤسسة.