Hugging Face چیست؟ راهنمای انتخاب و دانلود امن مدل‌های هوش مصنوعی
در این راهنمای عملی با Hugging Face Hub، Model Card، Dataset و Spaces آشنا می‌شوید، مدل مناسب را با فیلترهای واقعی انتخاب می‌کنید و فایل‌ها را با Revision ثابت، Token کم‌اختیار و کنترل امنیتی دانلود می‌کنید.
Hugging Face یک پلتفرم و اکوسیستم برای کار با مدل‌ها، Datasetها و برنامه‌های یادگیری ماشین است. بخش مرکزی آن Hugging Face Hub نام دارد؛ جایی که هر مدل یا Dataset در یک Repository نسخه‌دار نگه‌داری می‌شود و می‌تواند Model Card، فایل‌های وزن، پیکربندی، License، تاریخچه Commit و نمونه استفاده داشته باشد.
وجود هزاران مدل آماده، شروع پروژه را سریع می‌کند؛ اما انتخاب مدل از روی تعداد Download یا یک Demo جذاب کافی نیست. فایل وزن می‌تواند بسیار بزرگ، ناسازگار، دارای License محدود یا در قالبی پرخطر باشد. در این مقاله یاد می‌گیرید چگونه Repository معتبر را پیدا کنید، Model Card را بخوانید، Revision را ثابت نگه دارید، Token را امن مدیریت کنید و قبل از اجرای کد Community، خطرها را کاهش دهید.
Hugging Face چیست و چه بخش‌هایی دارد؟
Hub از Repositoryهای مدل، Dataset و Space تشکیل شده است. Repository مدل فایل‌های وزن، Tokenizer، Configuration و مستندات را نگه می‌دارد. Dataset Repository داده و اسکریپت یا Metadata مربوط به آن را ارائه می‌کند. Space یک برنامه قابل اجرا برای نمایش Demo، Portfolio یا ابزار مبتنی بر مدل است و می‌تواند با Gradio، Docker یا Static HTML ساخته شود.
| بخش | چه چیزی دارد؟ | پرسش مهم پیش از استفاده |
|---|---|---|
| Models | وزن، پیکربندی، Tokenizer و Model Card | این مدل برای Task و Runtime من مناسب است؟ |
| Datasets | داده، Schema، Viewer و Dataset Card | مجوز و کیفیت داده برای هدف من کافی است؟ |
| Spaces | Demo و برنامه اجراشده | کد Space چه داده‌ای دریافت و کجا ارسال می‌کند؟ |
| Organizations | Repositoryهای یک تیم یا شرکت | آیا این حساب واقعاً ناشر رسمی مدل است؟ |
| Collections | فهرست مرتب‌شده از چند Artifact | آیا Collection رسمی و به‌روز است؟ |
شناسه Repository را درست بخوانید
شناسه‌ای مانند Qwen/Qwen3-8B از Owner و نام Repository تشکیل می‌شود. دو Repository با نام مدل مشابه اما Owner متفاوت می‌توانند فایل، Quantization، License و حتی رفتار متفاوت داشته باشند. همیشه شناسه کامل را ثبت کنید؛ نوشتن «مدل Qwen» یا «مدل Llama» برای بازتولید نتیجه کافی نیست.
ناشر رسمی، Fork و مدل Community
ناشر رسمی معمولاً Organization شناخته‌شده، لینک متقابل از وب‌سایت محصول و تاریخچه منسجم دارد. Fork یا Quant Community ممکن است کاملاً مفید باشد، اما باید منبع پایه، روش تبدیل، ابزار Quantization و Hash فایل را توضیح دهد. Badge یا تعداد Like به‌تنهایی اثبات امنیت نیست.
- Owner و لینک رسمی پروژه را تطبیق دهید.
- تاریخچه Commit و تغییر فایل‌های اصلی را ببینید.
- Model Card و License را پیش از دانلود بخوانید.
- فرمت فایل و نیاز به اجرای Remote Code را بررسی کنید.
- Issueهای باز مرتبط با امنیت، کیفیت و ناسازگاری را مرور کنید.
چگونه مدل مناسب را در Hugging Face پیدا کنیم؟
جست‌وجو را با Task شروع کنید: Text Generation، Image Classification، Automatic Speech Recognition، Embedding یا Image-to-Text. سپس Library، زبان، License، اندازه و فرمت را محدود کنید. انتخاب «محبوب‌ترین مدل» بدون توجه به Task می‌تواند فایل بزرگی بدهد که اصلاً خروجی موردنیاز شما را تولید نمی‌کند.
پنج فیلتر تصمیم‌ساز
- Task: مدل برای چه ورودی و خروجی آموزش دیده است؟
- Language: زبان هدف در Model Card یا ارزیابی‌ها وجود دارد؟
- Library: Transformers، Diffusers، sentence-transformers یا Runtime دیگری لازم است؟
- License: استفاده پژوهشی، تجاری و بازتوزیع چه شرایطی دارد؟
- Size: فایل، RAM، VRAM و Context با دستگاه یا سرور سازگار است؟
پس از فیلتر، دو یا سه نامزد بسازید و همه را با Dataset آزمون یکسان بسنجید. رتبه Leaderboard عمومی، کیفیت فارسی یا داده تخصصی سازمان شما را تضمین نمی‌کند.
| معیار | نشانه قابل قبول | علامت هشدار |
|---|---|---|
| Model Card | هدف، محدودیت، داده و مثال روشن | فقط ادعای تبلیغاتی بدون روش آزمون |
| License | فایل License مشخص و سازگار با پروژه | License خالی، مبهم یا متناقض |
| Files | فرمت استاندارد و اندازه قابل پیش‌بینی | فایل اجرایی ناشناس یا Pickle بدون توضیح |
| Revision | Commit قابل ثبت و تاریخچه قابل بررسی | وابستگی دائمی به آخرین نسخه متغیر |
| Evaluation | داده، نسخه و روش ارزیابی توضیح داده شده | عدد Benchmark بدون Context |
| Community | Issueهای فنی و پاسخ‌های نگهدارنده | گزارش‌های امنیتی بی‌پاسخ |
Model Card را چگونه بخوانیم؟
Model Card شناسنامه فنی و رفتاری مدل است. دنبال بخش‌های Intended Use، Limitations، Training Data، Evaluation، Bias، License و How to Use بگردید. اگر یک بخش وجود ندارد، نبود آن را به معنی نبود خطر تلقی نکنید؛ فقط یعنی اطلاعات کافی منتشر نشده است.
ادعا را از شرایط آزمون جدا نکنید
یک امتیاز Benchmark بدون نسخه مدل، Prompt، Dataset و تنظیم Generation ارزش محدودی دارد. اگر Model Card می‌گوید مدل در کدنویسی قوی است، زبان و Repository خودتان را آزمایش کنید. اگر مدل چندزبانه است، نمونه فارسی و معیار انسانی لازم دارید.
Base و Instruct را اشتباه نگیرید
مدل Base برای ادامه آموزش و تکمیل متن خام مناسب‌تر است. مدل Instruct یا Chat با قالب گفتگو برای پیروی از دستور آماده شده است. استفاده از Chat Template اشتباه می‌تواند نتیجه را خراب کند، حتی اگر وزن درست دانلود شده باشد.
دانلود مدل با hf CLI
Hugging Face ابزار رسمی hf را برای کار با Hub ارائه می‌کند. برای Repository عمومی معمولاً Token لازم نیست. ابتدا ابزار را در محیط مجازی پروژه نصب و نسخه را بررسی کنید. دانلود فایل‌های بسیار بزرگ را در درایوی با فضای کافی انجام دهید.
python -m venv .venv.\.venv\Scripts\Activate.ps1python -m pip install --upgrade huggingface_hubhf --help # شناسه نمونه را با Repository انتخاب‌شده جایگزین کنیدhf download OWNER/MODEL_NAMEدانلود کل Repository ممکن است چندین فایل Variant یا Weight بزرگ را دریافت کند. اگر فقط Configuration یا Tokenizer لازم است، فایل مشخص را بگیرید. پیش از دانلود، فهرست Files و اندازه هرکدام را بررسی کنید.
چرا باید Revision را ثابت کنیم؟
دانلود بدون Revision معمولاً آخرین وضعیت Repository را می‌گیرد. اگر Owner فایل را تغییر دهد، Build هفته بعد می‌تواند وزن یا Configuration دیگری دریافت کند. برای محیط قابل تکرار، Commit Hash تأییدشده را ثبت کنید و همان Revision را در کد دانلود بدهید.
from huggingface_hub import snapshot_download path = snapshot_download( repo_id="OWNER/MODEL_NAME", revision="FULL_COMMIT_SHA", local_dir="models/selected-model",) print(path)بهتر است علاوه بر Commit، نسخه کتابخانه، Python، Driver و تنظیمات Inference را ثبت کنید. بازتولید فقط با وزن مدل ممکن نیست؛ Chat Template، Tokenizer و پارامترهای Generation نیز نتیجه را تغییر می‌دهند.
امنیت فایل مدل: Pickle، Safetensors و Remote Code
بعضی قالب‌های Serialization می‌توانند هنگام Load کد اجرا کنند. مستندات Hugging Face درباره خطر اجرای کد دلخواه در فایل Pickle هشدار می‌دهد و توصیه می‌کند مدل را از کاربران یا Organizationهای مورد اعتماد بگیرید. Hub فایل‌ها را با Malware و Pickle Scanner بررسی می‌کند، اما Scanner جای اعتماد به ناشر و بازبینی را نمی‌گیرد.
Safetensors چه کمکی می‌کند؟
Safetensors برای نگه‌داری Tensorها بدون رفتار اجرایی Pickle طراحی شده است. وقتی Model Card و Runtime پشتیبانی می‌کنند، این فرمت سطح خطر Load را کاهش می‌دهد. با این حال فایل امن به معنی مدل امن نیست؛ License، داده آموزشی، Prompt Injection و رفتار خروجی مسائل جدا هستند.
trust_remote_code را خودکار فعال نکنید
برخی Repositoryها برای کلاس سفارشی به اجرای کد Remote نیاز دارند. فعال‌کردن این گزینه یعنی کد Repository در محیط شما اجرا می‌شود. قبل از آن، Revision را Pin، فایل‌های Python را بازبینی و محیط اجرا را Isolate کنید. در سیستم دارای Secret یا دسترسی Production این گزینه نباید آزمایشی روشن شود.
| ریسک | کنترل پیشنهادی | چرا کافی نیست؟ |
|---|---|---|
| Pickle مخرب | ترجیح Safetensors و ناشر معتبر | سایر کدهای Repository هنوز باید بررسی شوند. |
| تغییر ناگهانی فایل | Pin کردن Commit SHA | Commit انتخابی نیز باید معتبر باشد. |
| Remote Code | بازبینی و اجرای Isolated | Dependencyها می‌توانند زنجیره تأمین جدا داشته باشند. |
| مدل تغییر‌یافته | ثبت Base Model و روش Quant | کیفیت و رفتار باید مستقل آزمون شود. |
| License نامشخص | خواندن فایل License و Model Card | شرایط داده و کاربرد مقصد هم اهمیت دارد. |
Hugging Face Token را امن مدیریت کنید
برای دانلود Repository عمومی معمولاً احراز هویت لازم نیست. Token زمانی لازم می‌شود که با Repository خصوصی یا Gated کار کنید، فایل Push کنید یا از سرویسی دارای سهمیه استفاده کنید. Token را با کمترین Scope بسازید و برای هر محیط یا Automation جدا نگه دارید.
ابزار رسمی فرمان hf auth login را ارائه می‌کند. در CI یا Space، Token را از Secret Store یا متغیر امن بخوانید. قرار دادن Token در Notebook عمومی، Git، Screenshot یا آرگومان خط فرمان می‌تواند آن را افشا کند.
- Token فقط خواندنی را برای دانلود انتخاب کنید.
- Token توسعه‌دهنده و Production را جدا کنید.
- Secret را داخل کد، README یا فایل نمونه Commit نکنید.
- اگر افشا شد، فوراً Revoke و جایگزین کنید.
- Repository و Organizationهایی را که Token دسترسی دارد دوره‌ای بازبینی کنید.
Cache مدل‌ها را مدیریت کنید
فایل‌های Hub معمولاً در Cache محلی نگه‌داری می‌شوند تا دانلود تکراری کاهش یابد. چند Revision یک مدل می‌تواند فضای زیادی مصرف کند. پیش از پاک‌سازی، مشخص کنید کدام پروژه به کدام Snapshot وابسته است. حذف کور Cache ممکن است Build آفلاین یا محیط دیگر را خراب کند.
در محیط سازمانی، محل Cache، سهمیه دیسک و سیاست Backup را تعریف کنید. فایل وزن معمولاً از منبع قابل بازیابی است، اما Manifest داخلی شامل Repository ID، Commit، Hash، License و زمان دریافت ارزش نگه‌داری دارد.
Hugging Face Spaces چیست؟
Spaces برای میزبانی Demoهای یادگیری ماشین ساخته شده است. Repository کد دارد و با هر Push می‌تواند Rebuild شود. حالت Public کد و برنامه را برای همه قابل مشاهده می‌کند؛ حالت Private کد و App را محدود می‌کند و Protected در طرح‌های مربوط، کد خصوصی و برنامه قابل دسترس ایجاد می‌کند.
Variable با Secret فرق دارد
مستندات رسمی تأکید می‌کند Variable برای تنظیم غیرحساس و Secret برای Token، API Key یا Credential است. Variable عمومی است و هنگام Duplicate نیز منتقل می‌شود. Secret از Settings قابل خواندن نیست و به Space کپی‌شده منتقل نمی‌شود.
در Static Space، منطق سمت Browser اجرا می‌شود و هیچ Secret واقعی نباید به JavaScript Client داده شود. اگر برنامه به کلید خصوصی نیاز دارد، Backend کنترل‌شده یا Space مبتنی بر سرور طراحی کنید.
Space عمومی را برنامه امن فرض نکنید
یک Demo عمومی می‌تواند داده ورودی را ذخیره یا به سرویس دیگری ارسال کند. قبل از وارد کردن سند شخصی، کد Repository، سیاست حریم خصوصی و Network Requestها را بررسی کنید. برای داده حساس، محیط خودتان را Deploy کنید.
سناریوی عملی: انتخاب مدل فارسی برای خلاصه‌سازی
فرض کنید می‌خواهید گزارش‌های فارسی را خلاصه کنید. ابتدا Task را Text Generation یا Summarization تعریف و سه مدل Instruct دارای اشاره روشن به فارسی انتخاب کنید. برای هر مدل، License، اندازه، فرمت و Runtime را ثبت کنید.
- یک مجموعه ده‌تایی از متن‌های مجاز و نماینده پروژه بسازید.
- برای هر متن پاسخ مرجع یا چک‌لیست Fact تهیه کنید.
- همه مدل‌ها را با Prompt و تنظیم یکسان اجرا کنید.
- صحت عدد، نام، تاریخ، پوشش نکات و زبان طبیعی را امتیاز دهید.
- زمان اولین Token، سرعت و مصرف حافظه را جدا ثبت کنید.
- کوچک‌ترین مدلی را انتخاب کنید که معیار کیفیت را پاس می‌کند.
- Repository ID و Commit همان مدل را در Manifest پروژه Pin کنید.
اگر مدل انتخابی Qwen است، راهنمای انتخاب و اجرای محلی Qwen تفاوت نسخه‌ها، Quantization و آزمون فارسی را توضیح می‌دهد.
اشتباه‌های رایج در Hugging Face
انتخاب فقط بر اساس Download
Download بالا می‌تواند نتیجه قدمت یا استفاده کتابخانه‌ای باشد. Task، License، زبان و کیفیت روی داده شما معیار تصمیم‌اند.
استفاده از latest در Production
آخرین Revision می‌تواند بدون تغییر کد شما عوض شود. Commit را Pin و ارتقا را با Review و آزمون انجام دهید.
اعتماد کامل به Scanner
Scanner لایه مفیدی است اما همه حمله‌های زنجیره تأمین یا رفتار مخرب را تضمینی کشف نمی‌کند. ناشر، فرمت، کد و محیط اجرا را مستقل کنترل کنید.
قرار دادن Token در Notebook
Notebook به‌راحتی Share یا Commit می‌شود. Token را در Secret Manager نگه دارید و Scope و عمر آن را محدود کنید.
اجرای Space ناشناس با داده واقعی
Demo برای آزمایش عمومی ساخته شده است. اطلاعات مشتری یا فایل محرمانه را تا زمان بررسی کد و مقصد داده وارد نکنید.
چک‌لیست دانلود و اجرای امن
- Task و معیار پذیرش پیش از جست‌وجو مشخص شده است.
- Owner و Repository ID کامل با منبع رسمی تطبیق دارد.
- Model Card، License و محدودیت‌ها خوانده شده‌اند.
- اندازه فایل و نیاز RAM و VRAM بررسی شده است.
- فرمت وزن و وضعیت Security Scan کنترل شده است.
- Remote Code فقط پس از بازبینی و در محیط Isolated اجرا می‌شود.
- Commit SHA و نسخه کتابخانه‌ها ثبت شده‌اند.
- Token کم‌اختیار و خارج از کد نگه‌داری می‌شود.
- مدل با داده واقعی و مجاز پروژه ارزیابی شده است.
- برای ارتقا، Rollback به Revision قبلی وجود دارد.
برای اجرای ساده مدل‌های دریافت‌شده روی ویندوز، مقاله نصب Ollama و اجرای امن مدل محلی مسیر Runtime و API localhost را توضیح می‌دهد.
جمع‌بندی
Hugging Face Hub فقط یک سایت دانلود مدل نیست؛ یک سامانه Repository برای مدل، Dataset و Demo است. استفاده حرفه‌ای یعنی شناسه کامل، Model Card، License، Revision و فرمت فایل را بخوانید و انتخاب را با Task واقعی بسنجید.
برای امنیت، Safetensors و ناشر معتبر را ترجیح دهید، Pickle و Remote Code را محتاطانه بررسی کنید، Token را کم‌اختیار نگه دارید و در Production به latest وابسته نباشید. برای یادگیری پروژه‌محور هوش مصنوعی و ساخت Portfolio با مدل‌های معتبر، مسیرهای آموزشی خانه برنامه نویسان البرز را بررسی کنید.