رمز Hugging Face: كيفية إنشائه وتخزينه واستخدامه

رمز Hugging Face هو رمز وصول للمستخدم يُحقِّق هويتك — سواء كنت تستخدم جهاز كمبيوتر، أو نص برمجي، أو مهمة CI — أمام منصة Hugging Face Hub. ويمكنك إنشاء هذا الرمز في إعدادات حسابك ضمن علامة التبويب رموز الوصول رموز الوصولقراءة, كتابة أو تفصيلي جدًّااختيار دور (مثل) hf auth login ثم تشغيل الأمر HF_TOKEN وإدخال الرمز أو تعيين المتغير hf_....

ما الذي يصرّح به الرمز فعليًّا

ثلاثة أمور عمليًّا: تنزيل ملفات من مستودعات خاصة أو خاضعة للتحكم، ورفع ملفات إلى مستودعات لديك صلاحية الكتابة فيها، واستدعاء واجهات برمجة التطبيقات (APIs) باستخدام الرمز كـ "bearer token". أما أوزان النماذج العامة فلا تتطلب أي رمز على الإطلاق — إذ يعمل الأمر مقدمو استنتاجات النماذج كرمز مُصدَّق (bearer token). ولا تتطلب أوزان النماذج العامة رمزًا على الإطلاق — hf download gpt2 config.json بدون الحاجة إلى المصادقة.

توضّح وثائق Hugging Face أن الرمز يمكن استخدامه "مقابل كلمة المرور" في سياقات git والمصادقة الأساسية، وهذه هي الفكرة الذهنية الصحيحة: فالرمز يُعدّ بيانات اعتماد (credential)، وليس مفتاح واجهة برمجة تطبيقات (API key) مربوطًا بمنتج واحد.

أنواع الرموز الثلاثة

الوظيفة	منح	استخدمه لـ
قراءة	الوصول للقراءة إلى كل المستودعات التي يمكنك قراءتها بالفعل، بما في ذلك المستودعات الخاصة التي تملكها أنت أو منظماتك	تنزيل الأوزان المُقيَّدة، وتشغيل الاستنتاج (inference)، والدفاتر (notebooks)
كتابة	كل شيء قراءة يفعله، بالإضافة إلى صلاحية الكتابة على المستودعات التي يحق لك الكتابة فيها	رفع نقاط التحقق (checkpoints)، وتحرير بطاقات النماذج (model cards)، وتشغيل عمليات التدريب التي تقوم برفع المخرجات
تفصيلي جدًّا	فقط الموارد والصلاحيات المحددة التي تختارها يدويًّا	التطبيقات الإنتاجية، وبيئات التكامل المستمر (CI)، وأي شيء يُشارك مع الفريق

توصي هاغينغ فيس صراحةً باستخدام الرموز المُفصَّلة (fine-grained tokens) في بيئات الإنتاج، وذلك لأن نطاق الضرر الناتج عن تسريب رمزٍ واحدٍ يكون أصغر، ويمكن مشاركته داخل المنظمة دون تعريض الحساب بأكمله للخطر. ومن النماذج النموذجية في بيئة الإنتاج: أن يقوم عضو واحد في المنظمة بطلب الوصول إلى نموذج مقيد، ثم ينشئ رمزًا مُفصَّلًا يمنح صلاحية القراءة فقط للمستودع المعني ذلك المستودع فقط.

إنشاء رمز خطوة بخطوة

1. سجِّل الدخول، ثم انقر على أيقونة ملفك الشخصي (في الزاوية العلوية اليمنى) → الإعدادات.
2. افتح رموز الوصول علامة التبويب — الرابط المباشر huggingface.co/settings/tokens.
3. انقر رمز جديد.
4. سمِّه وفقًا للجهاز أو التطبيق الذي سيحتفظ به (مثلlaptop-read, ci-push) وليس وفقًا لاسمك الشخصي. والممارسة الموصى بها وثائقيًّا هي إنشاء رمز واحد لكل استخدام، حتى تتمكن من إلغاء أحدها دون تعطيل البقية.
5. اختر الدور. وللرموز المُفصَّلة، حدد الصلاحيات الفردية التي تريدها.
6. انسخ القيمة فورًا. وبعد ذلك، لن تتمكن لاحقًا سوى من حذف الرمز أو تحديثه من نفس الصفحة عبر زر إدارة.

إذا كنت عضوًا في منظمة من نوع Team أو Enterprise تطبّق سياسةً خاصةً للرموز، فقد يدخل الرمز المُفصَّل المُعرَّف ضمن نطاق تلك المنظمة حالة انتظار ( Pending ) إلى أن يوافق عليه أحد المسؤولين — ويظهر في قائمة الرموز رمز ساعة رملية برتقالية بجانبه، وتُرجع طلبات الوصول إلى موارد المنظمة رسالة خطأ 403 حتى يتم الموافقة.

تسجيل الدخول من سطر الأوامر

يأتي سطر الأوامر (CLI) المُضمَّن مع huggingface_hub باسم hf. قم بتثبيته وتسجيل الدخول كما يلي:

pip install huggingface_hub
hf auth login

وبشكل افتراضي، يعمل هذا الآن عبر تدفق جهاز المتصفح (browser device flow): حيث يطبع رابط URL (https://huggingface.co/oauth/device) ورمزًا قصيرًا مثل ABCD-EFGH. وافق عليه عبر المتصفح وسيقوم سطر الأوامر بحفظ رمز باسم oauth-<username> يُجدَّد تلقائيًّا ما دمت تستخدمه باستمرار. أما اختيار خيار لصق رمز وصول فبدلاً من ذلك يتيح لك إدخال رمز قمت بإنشائه يدويًّا.

ملاحظة حول التسمية: تستخدم الدروس القديمة الأمر huggingface-cli login. وقد أُعيد تنظيم مجموعة الأوامر تحت الأمر الجديد hf auth ...، ويعتمد الأمر الذي يقبله جهازك على إصدار حزمة huggingface_hub المثبتة لديك — لذا شغِّل الأمر hf --help لمعرفة ما هو المتاح لديك فعليًّا.

الأمر	ما الذي يفعله
hf auth login --token $HF_TOKEN	تسجيل دخول غير تفاعلي، آمن للاستخدام في البرامج النصية (scripts)
hf auth login --token $HF_TOKEN --add-to-git-credential	يكتب الرمز أيضًا في أداة اعتماد git (git credential helper)
hf auth login --force	إعادة تسجيل الدخول حتى لو كنت قد سجّلت الدخول مسبقًا
hf auth whoami	يُظهر اسم المستخدم والمنظمات التابعة لك؛ ويُرجع خطأً إذا لم تكن مسجل الدخول
hf auth list	يعرض أسماء الرموز المخزنة على الجهاز
hf auth switch --token-name NAME	يُغيّر الرمز النشط
hf auth token	يُظهر الرمز النشط في الإخراج القياسي (stdout)
hf auth logout --token-name NAME	يحذف رمزًا واحدًا من الرموز المخزنة (وإذا لم تُحدِّد العلامة، فيتم حذف جميع الرموز)
بيئة Hugging Face	يُخرج مسار الرمز المميز، ويشير إلى ما إذا كان الرمز المميز محفوظًا أم لا، ويُسرد أدوات git المُهيأة

مرر الرمز المميز عبر $HF_TOKEN بدلًا من إدخال السلسلة النصية الحرفية مباشرةً — فتحذّر الوثائق من لصق الرموز المميزة الأولية في سطور الأوامر، حيث يمكن أن تُسجلها سجلات سجل الأوامر (shell history) وسجلات بيئات التكامل المستمر (CI logs).

مكان تخزين الرمز

توجد رموز مميزة متعددة ذات أسماء مختلفة في ملف يُسمى stored_tokens ؛ أما الرمز المميز النشط حاليًّا فيتم نسخه احتياطيًّا تلقائيًّا إلى ملف بسيط باسم token . وكلا الملفين موجودان ضمن الدليل HF_HOME، الذي يأخذ افتراضيًّا القيمة ~/.cache/huggingface.

لينكس

~/.cache/huggingface/token و ~/.cache/huggingface/stored_tokens. وإذا كانت المتغيرات البيئية XDG_CACHE_HOME مُعرَّفة بينما لم تُعرَّف HF_HOME ، فإن الدليل الأساسي يصبح $XDG_CACHE_HOME/huggingface بدلًا من ذلك.

macOS

نفس الأمر في نظام لينكس: ~/.cache/huggingface/token. ولا تستخدم منصة Hugging Face دليل ~/Library/Caches في هذا السياق، لذا لا تبحث عنه هناك.

ويندوز

يتم حل المسار بدءًا من دليل المستخدم الرئيسي: C:Users<you>.cachehuggingfacetoken. وهناك خاصيتان محددتان لنظام ويندوز يستحقان المعرفة. أولًا، يستخدم ذاكرة التخزين المؤقت للنماذج روابط رمزية (symlinks)، والتي تتطلب تفعيل وضع المطور (Developer Mode) أو تشغيل الصدفة (shell) بصلاحيات المسؤول (admin shell)؛ وفي حال غيابهما، ستظهر لك رسالة تحذير وتُكرَّر الملفات على القرص الصلب، ويمكن كتم هذه الرسالة باستخدام الخيار HF_HUB_DISABLE_SYMLINKS_WARNING=1. ثانيًا، إذا قمت بتوجيه المتغير HF_HUB_CACHE إلى شبكة تخزين (NAS) مشتركة مع أجهزة لينكس، فعليك تعيين المتغير HF_HUB_DISABLE_SYMLINKS=1 — لأن الروابط الرمزية التي تُنشَأ على أنظمة لينكس لا يمكن التنقل عبرها بشكل موثوق على أنظمة ويندوز.

المتغيرات البيئية ذات الأهمية

المتغير	الأثر	افتراضي
HF_TOKEN	يوفّر الرمز المميز؛ ويُعطّل الرمز المميز المحفوظ على القرص الصلب HF_TOKEN_PATH	غير مُعرَّف
المكان الذي يُقرأ منه ويُكتب إليه ملف الرمز المميز	$HF_HOME/token	المجلد الأساسي لملف الرمز المميز وذاكرة التخزين المؤقت
HF_HOME	HF_HUB_DISABLE_IMPLICIT_TOKEN	~/.cache/huggingface
يمنع إرفاق الرمز المميز تلقائيًّا بطلبات القراءة التي لا تحتاجه؛ وبالتالي يُرسل فقط مع طلبات الكتابة	يوقف إرفاق الرمز المميز بطلبات القراءة التي لا تحتاج إليه؛ ويُرسل بعد ذلك فقط لطلبات الكتابة	معطل
اسم بديل قديم (Deprecated alias) — لا يزال يعمل، لكنه لم يعد يحتل الأفضلية على	تحذيران مهمان. تُقرأ هذه المتغيرات البيئية عند HF_TOKEN	—

وقت الاستيراد (import time) لـ ، لذا فإن تعيين أيٍّ منها بعد عملية الاستيراد لن يكون له أي أثر — ويجب إعادة تشغيل النواة (kernel). كما أن الأمر huggingface_hub، لذا فإن تعيينه بعد الاستيراد لا يكون له أي تأثير — يُرجى إعادة تشغيل النواة. و لا يمكنه تسجيل خروجك من رمز مميز تم تزويده عبر ؛ بل يجب عليك إلغاء تعيين المتغير يدويًّا. HF_TOKENإن استنساخ المستودعات الكبيرة عبر بروتوكول HTTPS يطلب كلمة مرور — استخدم الرمز المميز بدلًا من كلمة مرور حسابك:

استخدام الرمز مع git

git clone https://huggingface.co/<user>/<repo> # Username: your-hf-username # Password: hf_...

ولتجنب إعادة إدخال الرمز المميز، سجّل الدخول باستخدام الخيار

--add-to-git-credential ، والذي يُسلّم الرمز المميز إلى أداة مساعدة git المُهيأة لديك (مثل أداةstoreعلى لينكس، أو Keychain على نظام macOS، أو Windows Credential Manager على نظام ويندوز). وللتأكد من الأداة المُهيأة فعليًّا، استخدم الأمر ، الذي يطبع سطرًا يحمل العبارة بيئة Hugging FaceConfigured git credential helpers . السطر.

استخدام الرمز للاستنتاج المُستضاف

نفس الرمز المميز هو بيانات الاعتماد الخاصة بمقدِّمي الاستنتاج (Inference Providers)، الذي يوفِّر نقطة نهاية متوافقة مع OpenAI على https://router.huggingface.co/v1:

curl https://router.huggingface.co/v1/chat/completions 
    -H "Authorization: Bearer $HF_TOKEN" 
    -H 'Content-Type: application/json' 
    -d '{"model": "openai/gpt-oss-120b", "messages": [{"role": "user", "content": "hello"}]}'

للهذا المسار، يكون الرمز المميز الدقيق (fine-grained token) الممنوح له إذن إجراء طلبات إلى مقدّمي الاستنتاجات هو الأنسب تمامًا. أما فيما يتعلَّق بالفوترة، فتُعلِن Hugging Face شهريًّا عن رصيد ائتماني بقيمة 0.10 دولار أمريكي للحسابات المجانية، و2.00 دولار أمريكي للحسابات من نوع PRO، و2.00 دولار أمريكي لكل عضو في المنظمات من نوع Team وEnterprise، ثم تُطبَّق أسعار الدفع حسب الاستخدام (pay-as-you-go) وفقًا لمعدلات المقدِّم نفسه دون أي هامش إضافي من Hugging Face. ويمكن للمنظمات من نوع Team وEnterprise توحيد الفوترة عبر إرسال الرأس X-HF-Bill-To: my-org-name مع الحفاظ على امتلاك كل عضو لرمزه المميز الخاص.

وتتآكل هذه الأرصدة بسرعة عند أسعار النماذج المتقدِّمة — فنموذجٌ يُسعَّر مثل Claude Opus 5 بسعر 5.00 دولار أمريكي لكل مليون رمز مُدخل و25.00 دولار أمريكي لكل مليون رمز مُخرَج يستهلك 2.00 دولار أمريكي تقريبًا في نحو 80 ألف رمز مُخرَج. أما النماذج المفتوحة المصدر (open-weights models) فهي مختلفة تمامًا من حيث الترتيب العددي: إذ يبلغ سعرها Llama 3.3 70B 0.10 دولار أمريكي لكل مليون رمز مُدخل و0.32 دولار أمريكي لكل مليون رمز مُخرَج، بينما يبلغ سعر Llama 3.1 8B 0.02 دولار أمريكي لكل مليون رمز مُدخل و0.03 دولار أمريكي لكل مليون رمز مُخرَج. قم بنمذجة استهلاكك حاسبة تكلفة واجهة برمجة التطبيقات (API) حسب حجم الرموز المميزة التي ستستخدمها قبل دمج أي رمز مميز في كود يتضمَّن حلقة (loop).

النماذج الخاضعة للتحكم (Gated models): الرمز ضروري لكنه غير كافٍ وحده

أما بالنسبة للمستودعات المقفلة (gated repos) — مثل معظم إصدارات Llama وGemma — فإن الرمز المميز الصالح لا يمنح صلاحية الوصول إلا إلى ما سبق أن مُنح لك بالفعل. ووفقًا لـ وثائق النماذج المقفلة في Hugging Face، فإن طلب الوصول نفسه «يمكن تنفيذه فقط من متصفحك»: افتح صفحة النموذج أثناء تسجيل دخولك، وأكمل النموذج، ثم انقر على زر Agree. وقد يكون الموافقة تلقائية أو يدوية، كما يمكن للمؤلفين إلغاء الصلاحية لاحقًا دون إشعار مسبق. وبعد ذلك فقط، hf auth login يُفعِّل الرمز المميز تنزيل النموذج عبر النص البرمجي. وعادةً ما ترى رسالة خطأ 401 عند عدم إرسال أي رمز مميز، ورسالة خطأ أخرى 403 عند إرسال رمز مميز صالح لكن حسابك لا يمتلك صلاحية الوصول.

متى لا تحتاج إلى رمز إطلاقًا

أما أوزان النماذج العامة غير المقفلة (ungated public weights) فتُنزَّل دون الحاجة إلى بيانات اعتماد، وبالتالي غالبًا ما لا يحتاج التكوين المحلي الخالص (purely local stack) إلى أي رمز مميز. Ollama يُجرِّب Ollama عمليات السحب (pulls) من سجله الخاص تمامًا، بينما يستطيع llama.cpp أو LM Studio جلب ملفات GGUF العامة بشكل مجهول (anonymously). وما يحدِّد تكوينك هو سعة الذاكرة، وليس آلية المصادقة: إذ يحتاج نموذج Llama 3.1 بحجم 8B إلى نحو 5 جيجابايت من VRAM عند التكميم (quantization) بـ 4 بت، بينما يحتاج نموذج Llama 3.3 بحجم 70B إلى نحو 40 جيجابايت، في حين أن DeepSeek R1 يحتاج إلى نحو 400 جيجابايت، و Kimi K3 إلى نحو 1.4 تيرابايت — وهي نطاق يتطلَّب استخدام مجموعة خوادم (cluster territory). تحقَّق من متطلباتك مقابل حاسبة الذاكرة VRAM أو جدول متطلبات ذاكرة VRAM الخاصة بكل نموذج.

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

العرض المرضي	السبب الأرجح	إصلاح
401 Unauthorized	لم يُرسل أي رمز مميز، أو تم حذفه من الجانب الخادمي	hf auth whoami؛ أعد تشغيل الأمر hf auth login --force
403 على مستودع مقفل (gated repo)	الرمز المميز سليم، لكن الحساب لا يمتلك صلاحية الوصول	قدِّم طلب الوصول عبر المتصفح على صفحة النموذج
403 مع عبارة «revoked by the organization administrator»	لقد ألغت المنظمة من نوع Enterprise الرمز المميز — الإلغاء دائم	احذفه وأنشئ رمزًا جديدًا
يعمل في واجهة سطر الأوامر (shell)، لكنه يفشل في دفتر الملاحظات (notebook)	HF_TOKEN تم تعيين متغير البيئة بعد استيراد المكتبة، أو أن بيئة النواة (kernel) مختلفة	أعد تشغيل النواة (kernel)؛ وتحقق باستخدام الأمر بيئة Hugging Face
اختفاء نماذجك الخاصة من القائمة	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 مُفعَّل	مرر القيمة تُخبر هذه العلامة المكتبة باستخدام بيانات الاعتماد المخبأة أو المُخزَّنة في متغير البيئة. وفي خطوط أنابيب التكامل والنشر المستمر (CI/CD)، عيّن المتغير قم بتعيينه صراحةً (explicitly)، أو ألغِ تفعيله (unset it)
رفض الرمز المميز للقراءة من قِبل منظمة	سياسة المنظمة تسمح فقط بالرموز المميزة الدقيقة (fine-grained tokens)	أنشئ رمزًا مميزًا دقيقًا (fine-grained token) مُقيَّدًا بهذه المنظمة

في حال تسريب الرمز

احذفه أو حدِّثه من علامة التبويب Access Tokens. وإذا عثرت على رمز مميز لشخص آخر — في مستودع عام، أو في مساحة (Space)، أو في سجل (log) — فيمكنك إبطاله دون امتلاك الحساب، عبر إرسال طلب POST https://huggingface.co/api/credentials/revoke مع جسم JSON يحتوي على {"credentials": ["hf_..."]}. ويتم إيقاف جميع الرموز المطابقة فورًا، ويُرسَل بريد إلكتروني إلى المالك. وتُرجع هذه النقطة النهائية دائمًا رمز الاستجابة 202 Accepted سواء كان الرمز المميز موجودًا أم لا، وبالتالي لا يمكن استغلالها لاختبار ما إذا كان الرمز المميز لا يزال ساري المفعول. أما بالنسبة لأنظمة التكامل المستمر (CI)، فالحل الأفضل هو ألا تخزن رمزًا مميزًا طويل الأمد أصلًا: إذ يقوم نظام Trusted Publishers باستبدال هوية موفر CI الخاص بك (OIDC identity) برمز مميز قصير الأمد لمنصة Hub في كل عملية تشغيل.

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

هل رمز Hugging Face مجاني؟

نعم. لا تترتّب أي تكلفة على إنشاء الرموز بأي مستوى من مستويات الحساب، ولا يوجد حدٌّ موثَّق لعدد الرموز التي يمكن امتلاكها. وتظهر التكاليف فقط عند استخدام الرمز مع موارد حاسوبية مدفوعة — مثل مقدِّمي الاستنتاجات الذين يتجاوزون الاعتمادات الشهرية الممنوحة لك، أو نقاط الاستنتاج (Inference Endpoints)، أو أجهزة Spaces المُرقَّاة، أو المهام (Jobs).

هل تنتهي صلاحية رموز Hugging Face؟

الرموز المميزة التي تنشئها يدويًّا في الإعدادات لا تحمل تاريخ انتهاء صلاحية — بل تبقى سارية حتى تحذفها أو تُحدِّثها. أما الرموز المميزة التي تُنشأ عبر تدفق الجهاز (device flow) في المتصفح أثناء hf auth login فهي الاستثناء الوحيد: فهي تنتهي صلاحيتها، لكنها تتجدد تلقائيًّا طالما واصلت استخدامها.

ما الفرق بين أذونات القراءة والكتابة والتحكم الدقيق؟

قراءة يمكنك تنزيل أي شيء تراه بالفعل، بما في ذلك المستودعات الخاصة. كتابة يُضيف صلاحية النشر (push). تفصيلي جدًّا يبدأ من الصفر ومنح الصلاحيات فقط لما تحدده أنت عبر تحديد الخانات المطلوبة، ولذلك توصي Hugging Face باستخدامه في بيئات الإنتاج، وبعض المؤسسات ترفض أذونات القراءة/الكتابة جملةً وتفصيلًا مع 403.

هل يمكنني استخدام رمز واحد على عدة أجهزة؟

من الناحية التقنية، نعم؛ لكن أفضل ممارسة موثَّقة هي استخدام رمز واحد لكل جهاز أو تطبيق — كجهاز اللابتوب، أو دفتر Colab، أو خادوم الاستنتاج. وعند تدوير رمز مشترك، يتوقف عمل جميع المستخدمين له فورًا؛ أما عند تدوير رمز خاص بكل جهاز، فيتوقف عمل جهاز واحد فقط.

هل أحتاج إلى رمز لتشغيل النماذج محليًّا؟

مخصص فقط للنماذج المقيَّدة أو الخاصة. أما النماذج العامة غير المقيدة فتُنزَّل بشكل مجهول، ولا تتطلب سجلّ Ollama أية بيانات اعتماد — راجع القسم دليل تثبيت Ollama. وسواء كان استخدام النموذج محليًّا أم عبر واجهة برمجة التطبيقات (API) يُعدّ عادةً سؤالاً اقتصاديًّا؛ حيث إن حاسبة المقارنة بين الاستضافة الذاتية وواجهة برمجة التطبيقات (API) يحدد الرقم الذي يُعاد فيه تحقيق التعادل التكالفي.

أين أضع الرمز في Google Colab؟

استخدم لوحة الأسرار في Colab (أيقونة المفتاح) لتخزين الرمز كـ HF_TOKEN بدلًا من تضمينه مباشرةً في خلية ما، ثم فعِّل وصول دفتر الملاحظات إلى هذا الرمز. فدفاتر الملاحظات تُرسل وتُشارك بكثرة أكبر بكثير من ملفات الكود المصدر، والرمز المُلصق في خلية ما ينتقل مع النسخة المُشاركة.

المصادر

• Hugging Face Hub — رموز وصول المستخدمين (الأدوار، أفضل الممارسات، إبطال رمز تسرب، سياسات الرموز التنظيمية)
• huggingface_hub — المتغيرات البيئية (HF_TOKEN, المكان الذي يُقرأ منه ويُكتب إليه ملف الرمز المميز, HF_HOME الافتراضية)
• huggingface_hub — مرجع سطر الأوامر (hf auth التعليمات الفرعية والعلمات)
• مقدمو الاستنتاج — التسعير والفوترة (الاعتمادات الشهرية، X-HF-Bill-To)
• Hugging Face Hub — النماذج المقيدة (طلبات الوصول، عملية الموافقة عبر المتصفح فقط)

أسعار النماذج وأحجام ذاكرة VRAM مستمدة من Convly. قارن القدرات مقابل التكلفة في لوحة تصنيف النماذج اللغوية الكبيرة (LLM).