آموزش کامل و عملی Hugging Face: از نصب تا فاین‌تیون و استقرار (قدم‌به‌قدم)

در مقالهٔ پیشین با زیست‌بومِ Hugging Face آشنا شدیم. حالا وقتِ کارِ عملی است. این آموزش یک مسیرِ کاملِ گام‌به‌گام است که شما را از «نصبِ اولین کتابخانه» تا «فاین‌تیونِ یک مدل و استقرارِ آن به‌صورتِ یک اپلیکیشنِ زنده» می‌رساند — با کدِ واقعی و قابلِ اجرا. اگر پایتون را در حدِ متوسط بلدید، همه‌چیز آماده است. بزن بریم.

گام ۱: نصب و آماده‌سازیِ محیط

پیش از هر چیز، بستهٔ اصلی و همراهانش را نصب کنید. توصیه می‌شود این کار را در یک محیطِ مجازی (virtualenv یا conda) انجام دهید:

pip install transformers datasets accelerate

# برای فاین‌تیون سبک و کارآمد
pip install peft

# برای ساخت رابط و استقرار
pip install gradio huggingface_hub

کتابخانهٔ transformers برای مدل‌ها، datasets برای داده، و accelerate برای اجرای بهینه روی GPU است. راهنمای رسمیِ نصب را در صفحهٔ نصبِ Transformers ببینید. برای اجرای واقعیِ مدل‌های عمیق، داشتنِ یک GPU (مثلاً از طریق Google Colab رایگان) تجربه را بسیار روان‌تر می‌کند.

گام ۲: ساختِ حساب و توکنِ دسترسی

برای دانلودِ برخی مدل‌ها و به‌ویژه برای انتشارِ مدل، به یک حساب و «توکنِ دسترسی» نیاز دارید. ابتدا در Hugging Face ثبت‌نام کنید، سپس از تنظیماتِ توکن‌ها یک توکن بسازید (برای انتشار، نوعِ Write). آنگاه در ترمینال وارد شوید:

huggingface-cli login
# یا در کد:
from huggingface_hub import login
login(token="hf_xxx")  # توکن خود را در متغیر محیطی نگه دارید، نه داخل کد!

نکتهٔ امنیتی: هرگز توکن را مستقیم داخلِ کدِ منتشرشده ننویسید؛ آن را در متغیرِ محیطی (مثل HF_TOKEN) نگه دارید.

گام ۳: اولین اجرا با pipeline (ساده‌ترین راه)

تابعِ pipeline کلِ زنجیرهٔ پیش‌پردازش، اجرا و پس‌پردازش را در یک خط جمع می‌کند. چند مثالِ کاربردی:

from transformers import pipeline

# تحلیل احساسات
sent = pipeline("sentiment-analysis")
print(sent("This tutorial is fantastic!"))

# تولید متن
gen = pipeline("text-generation", model="gpt2")
print(gen("Artificial intelligence is", max_new_tokens=30))

# پرسش‌وپاسخ
qa = pipeline("question-answering")
print(qa(question="Where is HF used?", context="Hugging Face is used worldwide."))

هر بار که مدلی را نام ببرید، به‌طور خودکار از Hub دانلود و کش می‌شود. همین سادگی، دلیلِ محبوبیتِ این کتابخانه است.

گام ۴: کنترلِ دقیق‌تر با AutoTokenizer و AutoModel

وقتی به کنترلِ بیشتری نیاز دارید، به‌جای pipeline مستقیماً از کلاس‌های Auto استفاده کنید. توکنایزر متن را به عدد تبدیل می‌کند و مدل خروجی را تولید می‌کند:

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

name = "distilbert-base-uncased-finetuned-sst-2-english"
tokenizer = AutoTokenizer.from_pretrained(name)
model = AutoModelForSequenceClassification.from_pretrained(name)

inputs = tokenizer("I love working with AI!", return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
pred = logits.argmax(-1).item()
print(model.config.id2label[pred])  # POSITIVE

گام ۵: کار با دیتاست‌ها

برای آموزش یا ارزیابی به داده نیاز دارید. کتابخانهٔ Datasets بارگذاری را به یک خط تبدیل می‌کند:

from datasets import load_dataset

dataset = load_dataset("imdb")
print(dataset["train"][0])

# توکنایز کردن کل دیتاست به‌صورت کارآمد
def tok(batch):
    return tokenizer(batch["text"], truncation=True, padding="max_length")

tokenized = dataset.map(tok, batched=True)

می‌توانید دیتاستِ خودتان (CSV، JSON یا فایل‌های محلی) را هم به‌سادگی بارگذاری کنید؛ کافی است مسیرِ فایل را به load_dataset بدهید.

گام ۶: فاین‌تیونِ حرفه‌ای — ارزان و سریع با LoRA

حالا به بخشِ جذاب می‌رسیم: تطبیقِ یک مدل با دادهٔ خودتان. روشِ کلاسیک استفاده از Trainer است. اما فاین‌تیونِ کاملِ مدل‌های بزرگ گران است؛ برای همین از PEFT و روشِ LoRA استفاده می‌کنیم که فقط بخشِ کوچکی از پارامترها را آموزش می‌دهد و هزینه و حافظه را چند برابر کم می‌کند:

from peft import LoraConfig, get_peft_model
from transformers import TrainingArguments, Trainer

lora = LoraConfig(r=8, lora_alpha=16, target_modules=["q_lin", "v_lin"],
                  lora_dropout=0.05, task_type="SEQ_CLS")
model = get_peft_model(model, lora)
model.print_trainable_parameters()  # تنها ~۱٪ پارامترها آموزش می‌بینند

args = TrainingArguments(output_dir="out", num_train_epochs=2,
                         per_device_train_batch_size=8, learning_rate=2e-4,
                         eval_strategy="epoch", push_to_hub=False)

trainer = Trainer(model=model, args=args,
                  train_dataset=tokenized["train"].select(range(2000)),
                  eval_dataset=tokenized["test"].select(range(500)))
trainer.train()

همین چند خط، یک فاین‌تیونِ کاملِ کاربردی است. برای مطالعهٔ عمیق‌تر، فصلِ آموزشِ Trainer در دورهٔ رسمی منبعِ فوق‌العاده‌ای است.

گام ۷: انتشارِ مدل روی Hub

مدلِ آموزش‌دیده را می‌توانید با یک دستور روی Hub منتشر کنید تا هم بکاپ داشته باشید و هم دیگران (یا سرورِ تولیدتان) بتوانند از آن استفاده کنند:

model.push_to_hub("my-username/my-persian-classifier")
tokenizer.push_to_hub("my-username/my-persian-classifier")

راهنمای کاملِ آپلود در مستنداتِ انتشارِ مدل آمده است. فراموش نکنید یک «Model Card» خوب بنویسید؛ همان چیزی که کاربرد و محدودیت‌های مدل را شفاف می‌کند.

گام ۸: استقرار — از یک اپِ Gradio تا Inference API

یک مدل تا وقتی که کسی نتواند از آن استفاده کند، ارزشی ندارد. دو مسیرِ سریع برای استقرار:

الف) رابطِ تعاملی با Gradio و Spaces

با Gradio در چند خط یک رابطِ وب بسازید و آن را روی Spaces میزبانی کنید:

import gradio as gr
clf = pipeline("sentiment-analysis", model="my-username/my-persian-classifier")

def predict(text):
    r = clf(text)[0]
    return f"{r['label']} ({r['score']:.2f})"

gr.Interface(fn=predict, inputs="text", outputs="text").launch()

ب) فراخوانی از راه دور با Inference API

برای استفاده در محصولِ واقعی، مدل را با InferenceClient از راهِ دور صدا بزنید — بدونِ نیاز به بارگذاریِ مدل روی سرورِ خودتان:

from huggingface_hub import InferenceClient
client = InferenceClient(token="hf_xxx")
out = client.text_generation("هوش مصنوعی آینده را", model="gpt2", max_new_tokens=20)
print(out)

برای بارِ کاریِ سنگینِ تولیدی، Text Generation Inference (TGI) سروینگِ بهینه را روی زیرساختِ خودتان فراهم می‌کند.

گام ۹: نمونهٔ فارسی — تحلیلِ متنِ فارسی

برای پروژه‌های فارسی، از مدل‌های بومیِ آموزش‌دیده روی زبانِ فارسی استفاده کنید. برای مثال، خانوادهٔ ParsBERT و مدل‌های HooshvareLab نقطهٔ شروعِ عالی‌اند:

from transformers import pipeline

# نمونهٔ پرکردنِ جای خالی به زبان فارسی
fa = pipeline("fill-mask", model="HooshvareLab/bert-fa-base-uncased")
print(fa("پایتخت ایران [MASK] است."))

با همین الگو می‌توانید تحلیلِ احساساتِ نظراتِ مشتری، دسته‌بندیِ تیکت‌های پشتیبانی یا موتورِ جست‌وجوی معناییِ فارسی بسازید.

اشتباهات رایجی که باید از آن‌ها پرهیز کنید

• نادیده‌گرفتنِ مجوزِ مدل: همیشه بخشِ License در Model Card را بخوانید؛ برخی مدل‌ها برای استفادهٔ تجاری محدودیت دارند.
• قراردادنِ توکن در کد: توکن را در متغیرِ محیطی نگه دارید، نه در سورس.
• فاین‌تیونِ کاملِ بی‌مورد: اغلب LoRA کافی است و ده‌ها برابر ارزان‌تر تمام می‌شود.
• فراموشیِ ارزیابی: بدونِ مجموعهٔ تست و سنجه، نمی‌دانید مدلتان واقعاً بهتر شده یا نه.

نقشهٔ راهِ یادگیریِ ادامه

پس از تسلط بر این مسیر، پیشنهاد می‌کنیم دورهٔ رایگانِ NLP هاگینگ‌فیس را کامل بگذرانید، سپس سراغِ ساختِ عامل‌های هوشمند با smolagents و بهینه‌سازیِ استقرار بروید. یادگیریِ عملی با ساختِ یک پروژهٔ واقعی — مثلِ یک دستیارِ فارسی — سریع‌ترین راهِ تسلط است.

جمع‌بندی

دیدیم که با Hugging Face می‌توان در چند ساعت از «هیچ» به «یک مدلِ فاین‌تیون‌شده و مستقرشده» رسید: نصب، احراز هویت، اجرا با pipeline، کنترلِ دقیق با AutoModel، کار با داده، فاین‌تیونِ ارزان با LoRA، انتشار روی Hub و استقرار با Gradio یا Inference API. قدمِ بعدی، ساختنِ یک پروژهٔ واقعی است. اگر می‌خواهید این مسیر را برای سازمانتان — با انتخابِ درستِ مدل، فاین‌تیونِ اختصاصی روی دادهٔ شما و استقرارِ امن — به‌صورتِ حرفه‌ای طی کنید، تیمِ دیباچین کنارِ شماست.

پرسش‌های متداول

منابع معتبر و مطالعهٔ بیشتر

• راهنمای نصب Transformers
• شروع سریع (Quicktour)
• دورهٔ رایگان NLP هاگینگ‌فیس
• مستندات PEFT و LoRA
• راهنمای Inference با huggingface_hub
• ساخت رابط با Gradio

نقش دیباچین

در دیباچین این راهکارها را از ارزیابی و طراحی تا پیاده‌سازی و پشتیبانی برای سازمان شما اجرا می‌کنیم؛ از انتخاب معماری و مدل مناسب تا استقرار امن و پایش مستمر. برای مشاورهٔ اولیهٔ رایگان با ما تماس بگیرید یا پروفایل و خدمات دیباچین را ببینید.