Hugging Face در ایران؛ رفع خطای دانلود مدل و Token
برای رفع مشکل Hugging Face، خطای دسترسی را با خطای شبکه یکی نگیرید. باز نشدن سایت، 401/403 و دانلودی که وسط کار متوقف میشود سه مسئلهٔ متفاوتاند.
| نشانه | معنی محتمل | اولین اقدام |
|---|---|---|
| سایت باز نمیشود | مرورگر، DNS یا مسیر | پنجرهٔ خصوصی و شبکهٔ دیگر |
401 Unauthorized |
Token یا ورود نامعتبر | حساب و Token را بررسی کنید |
403 Forbidden |
مجوز repository ندارید | وضعیت gated/private را ببینید |
| timeout | مسیر ناپایدار یا فایل بزرگ | cache و CLI رسمی را بهکار بگیرید |
تغییر اتصال نمیتواند مجوز مدل private یا gated صادر کند.
تست مسیر شبکه
صفحهٔ یک مدل عمومی را در پنجرهٔ خصوصی باز کنید. اگر فقط مرورگر اصلی مشکل دارد، افزونه، cookie و cache را بررسی کنید. اگر روی یک اینترنت باز میشود و روی دیگری نه، اتصال سراسری/TUN برقرار کنید تا مرورگر، Python و ترمینال از یک مسیر خارج شوند.
IP و DNS را با ابزارهای تست VPN کنترل و ابتدا یک فایل عمومی کوچک دانلود کنید. سرور را وسط دانلود تغییر ندهید.
public، private و gated چه فرقی دارند؟
مدل public بدون مجوز ویژه دیده میشود. repository خصوصی فقط برای اعضای مجاز است. برای gated model باید در صفحهٔ مدل درخواست دسترسی بدهید و شرایط ناشر را بپذیرید.
مستندات رسمی gated models میگوید درخواست در مرورگر انجام میشود و دانلود برنامهنویسیشده به Token همان حساب نیاز دارد. Token را در notebook عمومی یا Git commit قرار ندهید.
ورود و دانلود با ابزار رسمی
پس از نصب ابزار رسمی، هویت CLI را بررسی کنید:
hf auth login
hf auth whoami
hf download gpt2 config.json
Token را فقط در prompt امن وارد کنید. فرمانها در راهنمای رسمی Hugging Face CLI مستند شدهاند.
در Python برای یک فایل از hf_hub_download استفاده کنید:
from huggingface_hub import hf_hub_download
path = hf_hub_download(repo_id="gpt2", filename="config.json")
print(path)
طبق راهنمای رسمی دانلود، فایلها در cache میمانند تا دوباره دانلود نشوند. برای نسخهٔ مشخص revision و برای مسیر پروژه local_dir کاربرد دارد.
دانلود ناقص را چطور ادامه دهیم؟
cache را بیدلیل پاک نکنید. اول فضای دیسک، permission پوشه و ثبات شبکه را بررسی کنید. ساختار cache رسمی برای استفادهٔ دوباره طراحی شده است.
اگر مرورگر دانلود میکند اما Python نه، احتمالاً مرورگر وارد حساب است و CLI Token ندارد، یا این دو از مسیرهای متفاوت خارج میشوند. با hf auth whoami و یک فایل عمومی کوچک، هویت و مسیر را جدا تست کنید.
خطای Transformers را با خطای Hub اشتباه نگیرید
تابع from_pretrained() پشت صحنه از Hub دانلود میکند، اما بعد از دانلود ممکن است بهدلیل نسخهٔ ناسازگار transformers، کمبود فضای دیسک یا فایل پیکربندی نامعتبر شکست بخورد. اگر فایل در cache کامل است و پاسخ شبکهای تازهای دیده نمیشود، تغییر سرور کمکی نمیکند.
نسخهٔ Python و کتابخانهها، شناسهٔ دقیق repository و revision را ثبت کنید. همان فایل config.json را با hf download بگیرید؛ اگر CLI موفق و کد شکست خورد، مسئله را در dependency و نحوهٔ load دنبال کنید. اگر هر دو timeout شدند، مسیر شبکه و فضای cache را بررسی کنید. این تست کوچک مرز بین مشکل کد و انتقال فایل را روشن میکند.
برای دانلود طولانی:
- فضای آزاد را کنترل کنید.
- یک مسیر کمنوسان انتخاب کنید.
- از
hf downloadیا کتابخانهٔ رسمی استفاده کنید. - سرور را تا پایان ثابت نگه دارید.
- cache سالم را پاک نکنید.
در Colab، cache محلی Runtime دائمی نیست؛ راهنمای Google Colab در ایران را ببینید. اگر timeout فقط روی مسیر مستقیم تکرار میشود، یک اتصال پایدار ابزارهای AI را ابتدا با مدل عمومی کوچک بسنجید.
سؤالات متداول
خطای 401 یعنی VPN خراب است؟
معمولاً نه؛ بیشتر به Token نامعتبر یا نبود احراز هویت مربوط است.
چرا gated model دانلود نمیشود؟
ممکن است درخواست تأیید نشده یا CLI از Token حساب دیگری استفاده کند.
cache را پس از قطع دانلود پاک کنم؟
معمولاً خیر. اول فضا، permission و شبکه را بررسی کنید.
سرور ثابت لازم است؟
الزام حساب نیست، اما تغییر مسیر وسط دانلود میتواند ارتباط را قطع کند.
راهحلهای بالا را انجام دادید و هنوز مشکل باقی است؟
اول با یک کانفیگ سالم رایگان مقایسه کنید؛ اگر مشکل حل شد، بعد پلن مناسب را بخرید