کتابخانه Transformers عملاً استاندارد صنعت برای کار با مدل‌های ازپیش‌آموزش‌دیده است. با چند خط کد می‌توانید تحلیل احساسات، ترجمه، خلاصه‌سازی، پاسخ به پرسش و تولید متن را روی مدل‌های فارسی اجرا کنید، بدون اینکه معماری ترنسفورمر را از صفر پیاده‌سازی کنید. اگر تا حالا فقط با APIهای آماده کار کرده‌اید، اینجا دقیقاً همان نقطه‌ای است که کنترل را به دست می‌گیرید: مدل را خودتان انتخاب می‌کنید، روی داده خودتان تنظیم دقیق می‌کنید و خروجی را کامل می‌فهمید. در این آموزش از نصب تا اولین پروژه کامل، همه‌چیز مرحله‌به‌مرحله و با کدهای قابل اجرا پیش می‌رود.

آموزش Transformers در پایتون در یک نگاه

Transformers یک چارچوب آماده برای اجرا و آموزش مدل‌های هوش مصنوعی است که کار سنگین توکن‌سازی، بارگذاری وزن‌ها و آماده‌سازی ورودی را با چند خط کد انجام می‌دهد. برای شروع فقط Python 3.10 به بالا، PyTorch 2.5 به بالا، یک محیط مجازی و دسترسی به یک مدل آماده روی Hugging Face لازم دارید. بقیه مسیر را گام‌به‌گام در ادامه همین صفحه توضیح داده‌ایم.

فهرست مطالب

پیش‌نیازها و ساخت محیط مجازی
گام اول: نصب PyTorch و Transformers
اولین مثال کد: تحلیل احساسات با Pipeline
خط لوله چه کاری انجام می‌دهد؟
توکنایزر چیست و چرا متن فارسی حساس است؟
تولید متن با مدل‌های زبانی فارسی
آموزش و تنظیم دقیق یک مدل کوچک با Trainer
اشتباهات رایج در کار با Transformers
نکات امنیتی و کنترل منابع
مسیر ادامه یادگیری
سوالات متداول
جمع‌بندی

پیش‌نیازها و ساخت محیط مجازی

Transformers روی Python 3.10 به بالا و PyTorch 2.5 به بالا تست شده است. قبل از هر چیز مطمئن شوید محیط ایزوله دارید؛ نصب سراسری کتابخانه‌های سنگین یادگیری ماشین معمولاً بعد از چند پروژه به یک محیط شکسته تبدیل می‌شود. اگر قبلاً با آموزش uv در پایتون کار کرده‌اید، همان ابزار در چند ثانیه محیط را می‌سازد؛ در غیر این صورت python -m venv هم کار می‌کند.

uv venv .env
source .env/bin/activate

در ویندوز به‌جای خط دوم از .env\Scripts\activate استفاده کنید. اگر کارت گرافیک انویدیا دارید، پیش از نصب وجود درایور را چک کنید:

nvidia-smi

گام اول: نصب PyTorch و Transformers

مستندات رسمی، نصب با PyTorch را به‌صورت یک بسته پیشنهاد می‌کنند. اگر فقط روی CPU کار می‌کنید، نصب نسخه سبک PyTorch مصرف دانلود را به‌شدت کم می‌کند:

# نصب معمولی با پشتیبانی GPU
uv pip install "transformers[torch]"

# نسخه سبک فقط برای CPU
uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers

حالا صحت نصب را با یک تست یک‌خطی بررسی کنید. اگر خروجی زیر را گرفتید، همه‌چیز آماده است:

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

اولین مثال کد: تحلیل احساسات با Pipeline

ساده‌ترین راه شروع، استفاده از pipeline است. یک تابع آماده که ورودی خام می‌گیرد و خروجی قابل استفاده تحویل می‌دهد. برای فارسی، به‌جای مدل انگلیسی پیش‌فرض، یک مدل چندزبانه را صریح معرفی می‌کنیم:

from transformers import pipeline

classifier = pipeline(
    "sentiment-analysis",
    model="cardiffnlp/twitter-xlm-roberta-base-sentiment",
)

result = classifier("این محصول خیلی باکیفیت و مقرون‌به‌صرفه بود")
print(result)

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

خط لوله چه کاری انجام می‌دهد؟

پشت این یک خط کد، سه مرحله اتفاق می‌افتد که دانستنشان به شما اجازه می‌دهد مشکل را دقیق عیب‌یابی کنید:

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

دو پارامتر را زود بیاموزید چون تقریباً همیشه لازم می‌شوند: device که مشخص می‌کند مدل روی GPU اجرا شود یا CPU، و batch_size که پردازش چند نمونه هم‌زمان را ممکن می‌کند. برای فهرست‌های بلند، فعال کردن دسته‌بندی معمولاً سرعت را چند برابر می‌کند.

توکنایزر چیست و چرا متن فارسی حساس است؟

مدل متن خام نمی‌خواند؛ او عدد می‌خواند. توکنایزر رشته را به شناسه‌های عددی تبدیل می‌کند و یک واژه ممکن است به چند توکن بشکند. در فارسی این شکستن بیشتر است، چون واژه‌های مرکب و نیم‌فاصله‌ها طول توکن را بالا می‌برند:

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-multilingual-cased")
encoded = tokenizer("سلام دنیا!", return_tensors="pt")

print(tokenizer.convert_ids_to_tokens(encoded["input_ids"][0]))
print(encoded["input_ids"].shape)

اگر طول ورودی از سقف مدل بیشتر شود، با truncation=True و برای دسته‌ای از متن‌ها با padding=True هم‌طول‌سازی کنید. نکته مهم: توکنایزر باید دقیقاً متعلق به همان مدلی باشد که بارگذاری کرده‌اید؛ ترکیب توکنایزر یک مدل با مدل دیگر، بی‌سروصدا خروجی غلط می‌دهد.

تولید متن با مدل‌های زبانی فارسی

وقتی به تولید متن می‌رسید، دیگر با یک طبقه‌بند ساده طرف نیستید و باید پارامترهای رمزگشایی را کنترل کنید. این اسکریپت یک مدل فارسی کوچک را روی GPU می‌ماند و در صورت نبود کارت گرافیک به CPU برمی‌گردد:

import torch
from transformers import pipeline, AutoTokenizer, AutoModelForCausalLM

model_id = "Qwen/Qwen2.5-0.5B-Instruct"
device = 0 if torch.cuda.is_available() else -1
dtype = torch.bfloat16 if torch.cuda.is_available() else torch.float32

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, dtype=dtype)

generator = pipeline("text-generation", model=model, tokenizer=tokenizer, device=device)

out = generator(
    "در سه جمله توضیح بده یادگیری ماشین چیست:",
    max_new_tokens=80,
    do_sample=True,
    temperature=0.7,
    repetition_penalty=1.1,
    return_full_text=False,
)
print(out[0]["generated_text"])

اگر خروجی تکراری و بی‌معنا شد، اول temperature را کم و repetition_penalty را بالا ببرید. برای خروجی قطعی و قابل تکرار (مثلاً تست واحد) به‌جای do_sample=True مقدار False بگذارید.

آموزش و تنظیم دقیق یک مدل کوچک با Trainer

وقتی مدل آماده با داده شما جور نبود، سراغ تنظیم دقیق می‌روید. کلاس Trainer حلقه آموزش، دسته‌بندی، ارزیابی و ذخیره checkpoint را مدیریت می‌کند و شما فقط مدل و داده را می‌دهید:

from datasets import load_dataset
from transformers import AutoTokenizer, AutoModelForSequenceClassification, Trainer, TrainingArguments

tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased")
dataset = load_dataset("stanfordnlp/imdb", split="train[:5000]")

def prepare(batch):
    return tokenizer(batch["text"], truncation=True, padding="max_length", max_length=256)

dataset = dataset.map(prepare, batched=True)
model = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased", num_labels=2)

args = TrainingArguments(
    output_dir="runs/imdb",
    num_train_epochs=1,
    per_device_train_batch_size=8,
    logging_steps=50,
)

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=dataset,
    processing_class=tokenizer,
)
trainer.train()

نمودار کاهش loss در طول epochها بهترین معیار شماست تا بفهمید نرخ یادگیری و تعداد epochها منطقی انتخاب شده‌اند؛ اگر با نمودارسازی در پایتون راحت نیستی، راهنمای آموزش Matplotlib در پایتون دقیقاً همین کار را ساده می‌کند. اگر سیستم شما ضعیف است، به‌جای تنظیم دقیق کامل، از مدل‌های کوچک‌تر یا روش‌های کم‌مصرف‌تر مثل LoRA استفاده کنید.

اشتباهات رایج در کار با Transformers

نصب سراسری بدون محیط مجازی: بعد از دو پروژه، نسخه PyTorch با پروژه قبلی تداخل پیدا می‌کند و خطاهای گنگ می‌بینید.
انتخاب مدلی که مجوزش را نپذیرفته‌اید: دانلود مدل‌های دروازه‌دار بدون توکن Hugging Face خطای دسترسی می‌دهد.
فراموشی پارامتر device: بدون تعیین دستگاه، مدل بزرگ روی CPU اجرا می‌شود و پاسخ‌گویی ساعت‌ها طول می‌کشد.
توکنایزر ناسازگار با مدل: خروجی بی‌معنا تولید می‌کند ولی هیچ خطایی نمی‌دهد.
نادیده‌گرفتن حافظه: هر مدل در پوشه کش روی دیسک ذخیره می‌شود و در چند ماه ده‌ها گیگابایت اشغال می‌کند.
آموزش روی متن خیلی بلند: اگر max_length را با توجه به طول واقعی داده انتخاب نکنید، بخش زیادی از داده بی‌صدا حذف می‌شود.

نکات امنیتی و کنترل منابع

کار با مدل‌های هوش مصنوعی هم همان قواعد امنیتی هر پروژه نرم‌افزاری را دارد. توکن Hugging Face را هرگز داخل کد ننویسید و commit نکنید؛ آن را در متغیر محیطی یا فایل .env نگه دارید. مدل‌هایی که روی حساب شما آپلود شده‌اند می‌توانند کد دلخواه داشته باشند، پس فقط از مخازن معتبر دانلود کنید و گزینه trust_remote_code را بی‌دلیل روشن نکنید.

برای کنترل منابع، متغیر HF_HOME مسیر کش را مشخص می‌کند و می‌توانید آن را روی یک دیسک بزرگ‌تر قرار دهید. اگر پروژه باید کاملاً آفلاین اجرا شود، مدل را یک‌بار در محیط اینترنتی دانلود و سپس با local_files_only=True بارگذاری کنید. در پروژه‌های سازمانی، قبل از ارسال متن کاربران به مدل‌های ابری، تکلیف نگهداری و محرمانگی داده را روشن کنید.

مسیر ادامه یادگیری

بعد از تسلط بر pipeline و Trainer، سه مسیر پرطرفدار پیش روی شماست: کوانتیزه‌سازی برای اجرای مدل‌های بزرگ‌تر روی سخت‌افزار کوچک‌تر، آموزش کم‌هزینه با LoRA و PEFT، و کار با موتورهای استنتاج سریع مثل vLLM برای سرویس‌دهی هم‌زمان به کاربران زیاد. دوره رسمی LLM در Hugging Face هم مسیر ساختارمندی برای حرکت از مدل‌های کوچک به پروژه‌های جدی‌تر فراهم می‌کند. مهم‌تر از همه، پروژه‌های کوچک واقعی بسازید؛ هر پروژه کوچک بیشتر از ده مقاله آموزشی به شما یاد می‌دهد.

سوالات متداول

تفاوت Transformers و PyTorch چیست؟

PyTorch موتور محاسباتی و مدیریت تانسور و گرادیان است؛ Transformers لایه‌ای روی آن که تعریف آماده مدل، توکنایزر، خط لوله و حلقه آموزش را در اختیارتان می‌گذارد. برای کار با مدل‌های آماده، Transformers کافی است و PyTorch زیر آن کار می‌کند.

برای اجرای Transformers کارت گرافیک لازم است؟

خیر. مدل‌های کوچک روی CPU هم اجرا می‌شوند، فقط کندتر. برای مدل‌های چند میلیاردی، کارت گرافیک یا نسخه‌های کوانتیزه‌شده عملاً ضروری است.

مدل‌های فارسی را از کجا پیدا کنم؟

در جست‌وجوی Hugging Face فیلتر زبان فارسی یا تسک مورد نظرتان را بزنید و قبل از دانلود، کارت مدل را ببینید؛ بسیاری از مدل‌های فارسی روی bert-base-multilingual-cased یا خانواده XLM-R ساخته شده‌اند و با آن‌ها به‌خوبی کار می‌کنند.

پوشه کش چرا حافظه دیسک را پر می‌کند؟

هر بار که مدلی را بارگذاری می‌کنید، نسخه‌ای از آن در پوشه کش نگه داشته می‌شود تا دوباره دانلود نشود. مسیر پیش‌فرض در ویندوز داخل C:\Users\username\.cache\huggingface است و با متغیر HF_HOME قابل تغییر است.

چطور مدل را کاملاً آفلاین اجرا کنم؟

یک‌بار با دسترسی به اینترنت مدل را دانلود کنید، سپس با from_pretrained و آرگومان local_files_only=True بارگذاری کنید. برای تجربه راحت‌تر اجرای آفلاین مدل‌های زبانی، می‌توانید از ابزارهای مخصوص این کار هم استفاده کنید.

جمع‌بندی

برای شروع امروز، این چک‌لیست را انجام دهید: محیط مجازی بسازید، transformers[torch] را نصب کنید، تست یک‌خطی نصب را اجرا کنید، با pipeline یک تحلیل احساسات فارسی بگیرید و در نهایت یک مدل کوچک را با Trainer روی یک دیتاست آماده تنظیم دقیق کنید. اگر همین پنج قدم را کامل کنید، ابزارهای حرفه‌ای‌تر بعدی برایتان کاملاً قابل فهم خواهند بود.

آموزش Transformers؛ ساخت اولین مدل هوش مصنوعی با پایتون