Hugging Face Token: كيفية إنشاء وحفظ واستخدام الرمز

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

ما يفوضه الرمز بالفعل

ثلاثة أشياء، عمليًا: تنزيل الملفات من المستودعات الخاصة أو المقيدة، ودفع الملفات إلى المستودعات التي يمكنك الكتابة إليها، واستدعاء مقدمو استنتاجات النماذج كرمز حامل. أوزان النماذج العامة لا تحتاج إلى أي رمز على الإطلاق — hf download gpt2 config.json يعمل بدون مصادقة.

تصف Hugging Face الرمز في الوثائق بأنه قابل للاستخدام «بدلاً من كلمة المرور" لـ git والمصادقة الأساسية، وهذا هو النموذج الذي يجب أن تتذكره: إنها بيانات اعتماد، وليس مفتاح API مرتبط بمنتج واحد.

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

الوظيفة	الأذونات	استخدمه لـ
قراءة	الوصول للقراءة إلى كل مستودع يمكنك قراءته بالفعل، بما في ذلك المستودعات الخاصة التي تملكها أنت أو مؤسساتك	تنزيل الأوزان المحمية، تشغيل الاستدلال، دفاتر الملاحظات
كتابة	كل شيء قراءة يفعله Hugging Face، بالإضافة إلى الوصول للكتابة إلى المستودعات التي يمكنك الكتابة إليها	دفع نقاط تفتيش، تعديل بطاقات النموذج، أشغال التدريب التي تقوم برفع البيانات
تفصيلي جدًّا	فقط الموارد والأذونات المحددة التي تختارها	تطبيقات الإنتاج، CI، أي شيء مشاركة مع فريق

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

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

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

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

تسجيل الدخول من المحطة الطرفية

واجهة سطر الأوامر المرسلة مع huggingface_hub تسمى hf. ثبت وسجل الدخول:

pip install huggingface_hub
hf auth login

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

ملاحظة حول التسمية: البرامج التعليمية الأقدم تستخدم huggingface-cli loginتم إعادة تنظيم مجموعة الأوامر ضمن hf auth ...والتهجئة التي تقبلها آلتك تعتمد على huggingface_hub الإصدار المثبت — قم بتشغيل hf --help لمعرفة ما لديك بالفعل.

الأمر	ما الذي يفعله
hf auth login --token $HF_TOKEN	تسجيل دخول غير تفاعلي، آمن للبرامج النصية
hf auth login --token $HF_TOKEN --add-to-git-credential	يكتب أيضًا الرمز إلى مساعد بيانات اعتماد git الخاص بك
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	حذف رمز مخزن واحد (حذف الكل بدون العلم)
hf env	يفرغ مسار الرمز، وما إذا كان الرمز محفوظًا، ومساعدات git المكونة

مرر الرمز عبر $HF_TOKEN بدلاً من كتابة السلسلة الحرفية — توصي المستندات ضد لصق الرموز الخام في أسطر الأوامر حيث يمكن لسجل shell وسجلات CI التقاطها.

حيث يتم تخزين الرمز

يعيش رموز مسماة متعددة في ملف stored_tokens النشط حاليًا يتم مراآته إلى ملف عادي رمز يقع كلاهما ضمن HF_HOMEوالذي يأتي بشكل افتراضي إلى ~/.cache/huggingface.

Linux

~/.cache/huggingface/token و ~/.cache/huggingface/stored_tokens. إذا XDG_CACHE_HOME تم تعيينه و HF_HOME لم يتم تعيينه، تصبح القاعدة $XDG_CACHE_HOME/huggingface بدلاً من ذلك.

macOS

نفس Linux: ~/.cache/huggingface/tokenلا يستخدم Hugging Face ~/Library/Caches هنا، فلا تبحث هناك.

ويندوز

يتم حل المسار من دليل منزلك: C:Users<you>.cachehuggingfacetokenهناك حيلتان خاصتان بـ Windows تستحقان المعرفة. أولاً، ذاكرة التخزين المؤقت للنموذج تستخدم الوصلات الرمزية، التي تتطلب Developer Mode أو shell إداري؛ بدونها تحصل على تحذير وملفات مكررة على القرص، يمكن إسكاتها باستخدام HF_HUB_DISABLE_SYMLINKS_WARNING=1ثانيًا، إذا أشرت HF_HUB_CACHE إلى NAS مشترك مع أجهزة Linux، اضبط HF_HUB_DISABLE_SYMLINKS=1 — الوصلات الرمزية المكتوبة على Linux لا يمكن الوثوق بها على Windows.

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

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

هناك مشكلتان. هذه المتغيرات تُقرأ في import time من huggingface_hub، لذا تعيين أحدها بعد الاستيراد لا يؤثر — أعد تشغيل النواة. و hf auth logout لا يمكنه تسجيل خروجك من توكن يتم توفيره عبر HF_TOKEN؛ يجب عليك إلغاء تعيين المتغير.

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

استنساخ المستودعات الكبيرة عبر HTTPS يطلب كلمة مرور — قدّم التوكن، وليس كلمة مرور حسابك:

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

لتجنب إعادة الكتابة، قم بتسجيل الدخول باستخدام --add-to-git-credential، الذي يسلّم التوكن إلى المساعد المُعد لديك (store على Linux، Keychain على macOS، Windows Credential Manager على Windows). تأكد مما هو متصل باستخدام hf env، الذي يطبع Configured git credential helpers سطر.

استخدام الرمز للاستدلال المستضاف

نفس التوكن هو بيانات اعتماد الحامل لموفري الاستدلال، الذي يكشف نقطة نهاية متوافقة مع 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"}]}'

لهذا المسار، توكن دقيق الحبيبات مع صلاحية إجراء طلبات إلى مقدّمي الاستنتاجات هو الأنسب. في الفواتير، ينشر Hugging Face رصيد شهري قدره $0.10 للحسابات المجانية، $2.00 للـ PRO، و$2.00 لكل مقعد لفرق ومنظمات Enterprise، ثم الدفع حسب الاستخدام بأسعار موفر الخدمة الخاصة به بدون زيادة HF. يمكن لفرق ومنظمات Enterprise تركيز الفواتير بإرسال X-HF-Bill-To: my-org-name كرأس بينما يحتفظ كل عضو بتوكنه الخاص.

هذه الأرصدة تنتهي بسرعة بأسعار نماذج الحدود — نموذج بسعر Claude Opus 5 بـ $5.00 مدخل / $25.00 مخرج لكل 1M توكن يحرق $2.00 تقريباً في 80k توكن مخرج. النماذج المفتوحة الأوزان من رتبة مختلفة تماماً: Llama 3.3 70B تعمل بـ $0.10 مدخل / $0.32 مخرج لكل 1M توكن، و Llama 3.1 8B $0.02 مدخل / $0.03 مخرج. نموذج حاسبة تكلفة واجهة برمجة التطبيقات (API) مقابل حجم التوكن الخاص بك قبل توصيل توكن بأي شيء يحتوي على حلقة.

النماذج المقيدة: الرمز ضروري لكن غير كافٍ

بالنسبة للمستودعات المقيّدة — معظم إصدارات 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)؛ وتحقق باستخدام الأمر hf env
اختفاء نماذجك الخاصة من القائمة	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 مُفعَّل	مرر العلم token=True قم بتعيينه صراحةً (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، أو خادوم الاستنتاج. وعند تدوير رمز مشترك، يتوقف عمل جميع المستخدمين له فورًا؛ أما عند تدوير رمز خاص بكل جهاز، فيتوقف عمل جهاز واحد فقط.

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

Only for gated or private weights. Public ungated models download anonymously, and Ollama’s registry needs no credentials — see the دليل تثبيت Ollama. وسواء كان استخدام النموذج محليًّا أم عبر واجهة برمجة التطبيقات (API) يُعدّ عادةً سؤالاً اقتصاديًّا؛ حيث إن حاسبة المقارنة بين الاستضافة الذاتية وواجهة برمجة التطبيقات (API) يحدد الرقم الذي يُعاد فيه تحقيق التعادل التكالفي.

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

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

المصادر

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

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