README_fa.md

English | 简体中文 | 繁體中文 | 한국어 | Español | 日本語 | हिन्दी | Русский | Português | తెలుగు | Français | Deutsch | Italiano | Tiếng Việt | العربية | اردو | বাংলা | فارسی |

مدل‌های از پیش آموزش‌دیده‌ی پیشرفته برای استنتاج (Inference) و آموزش (Training)

کتابخانه Transformers به عنوان بستر اصلی برای تعریف و پیاده‌سازی برترین مدل‌های یادگیری ماشین در حوزه‌های م��ن، بینایی ماشین، صوت، ویدئو و مدل‌های چندوجهی شناخته می‌شود. این کتابخانه ابزاری جامع است که تمامی مراحل، از آموزش (Training) تا استنت��ج (Inference) را به‌خوبی پوشش می‌دهد.

این کتابخانه با یکپارچه‌سازی تعریف مدل‌ها، استانداردی واحد در سراسر اکوسیستم هوش مصنوعی ایجاد کرده است. Transformers نقش یک نقطهٔ اتصال مرکزی را ایفا می‌کند؛ به این معنا که اگر تعریف مدلی در آن پشتیبانی شود، بلافاصله با اکثر چارچوب‌های آموزش (مانند Axolotl، Unsloth، DeepSpeed و PyTorch-Lightning)، موتورهای استنتاج (مانند vLLM، SGLang و TGI) و کتابخانه‌های مدل‌سازی مکمل (مانند llama.cpp و mlx) که همگی از استانداردهای تعریف مدل در Transformers پیروی می‌کنند، سازگار خواهد بود.

ما متعهد می‌شویم که از مدل‌های جدید و پیشرفته پشتیبانی کنیم و استفاده از آن‌ها را همگانی‌تر کنیم؛ با این هدف که تعریف مدل‌هایشان ساده، قابل‌سفارشی‌سازی و کارآمد باشد.

بیش از 1M+ model checkpoints مربوط به Transformers در Hugging Face Hub وجود دارد که می‌توانید از آن‌ها استفاده کنید.

امروز Hub را کاوش کنید تا یک مدل پیدا کنید و با کمک Transformers فوراً کار خود را آغاز کنید.

نصب

یک محیط مجازی (virtual environment) با استفاده از venv یا uv بساز و آن را فعال کن. uv یک مدیر سریع پکیج و پروژهٔ پایتون است که با Rust نوشته شده.

# venv
python -m venv .my-env
source .my-env/bin/activate
# uv
uv venv .my-env
source .my-env/bin/activate

برای نصب این کتابخانه، به Python 3.10+ و PyTorch 2.4+ نیاز دارید. نصب می‌تواند از طریق pip یا uv انجام شود:

# pip
pip install "transformers[torch]"

# uv
uv pip install "transformers[torch]"

اگر می‌خواهید جدیدترین تغییرات کتابخانه را داشته باشید یا قصد مشارکت (contribute) در پروژه را دارید، می‌توانید Transformers را از سورس (source) نصب کنید. با این حال، جدیدترین نسخه ممکن است پایدار (stable) نباشد. اگر با خطایی برخورد کردید، با خیال راحت یک Issue در گیت‌هاب باز کنید:

git clone https://github.com/huggingface/transformers.git
cd transformers

# pip
pip install '.[torch]'

# uv
uv pip install '.[torch]'

شروع سریع (Quickstart)

با استفاده از Pipeline API می‌توانید خیلی سریع کار با Transformers را شروع کنید.

پایپ لاین (Pipeline) یک کلاس سطح‌بالا برای انجام استنتاج (Inference) است که از کار با متن، صدا، تصویر و وظایف چندوجهی (multimodal) پشتیبانی می‌کند. این ابزار به‌طور خودکار مراحل پیش‌پردازش ورودی را انجام می‌دهد و خروجی مناسب را برمی‌گرداند.

برای شروع، یک pipeline بسازید و مشخص کنید از چه مدلی برای تولید متن استفاده شود. مدل به‌صورت خودکار دانلود و در حافظهٔ کش (cache) ذخیره می‌شود تا در اجراهای بعدی بتوان به‌راحتی دوباره از آن استفاده کرد.

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
pipeline("the secret to baking a really good cake is ")
[{'generated_text': 'the secret to baking a really good cake is 1) to use the right ingredients and 2) to follow the recipe exactly. the recipe for the cake is as follows: 1 cup of sugar, 1 cup of flour, 1 cup of milk, 1 cup of butter, 1 cup of eggs, 1 cup of chocolate chips. if you want to make 2 cakes, how much sugar do you need? To make 2 cakes, you will need 2 cups of sugar.'}]

برای چت کردن با یک مدل، الگوی استفاده یکسان است. تنها تفاوت این است که شما باید یک تاریخچه چت (ورودی به Pipeline) بین خود و سیستم ایجاد کنید.

Tip

همچنین می‌توانید مستقیماً از خط فرمان با یک مدل چت کنید، مادامی که transformers serve در حال اجرا باشد.

transformers chat Qwen/Qwen2.5-0.5B-Instruct

import torch
from transformers import pipeline

chat = [
    {"role": "system", "content": "You are a sassy, wise-cracking robot as imagined by Hollywood circa 1986."},
    {"role": "user", "content": "Hey, can you tell me any fun things to do in New York?"}
]

pipeline = pipeline(task="text-generation", model="meta-llama/Meta-Llama-3-8B-Instruct", dtype=torch.bfloat16, device_map="auto")
response = pipeline(chat, max_new_tokens=512)
print(response[0]["generated_text"][-1]["content"])

مثال‌های زیر را بسط دهید تا ببینید Pipeline چگونه برای روش‌ها و وظایف مختلف کار می‌کند.

تشخیص خودکار گفتار (ASR):

from transformers import pipeline

pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
{'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.'}

طبقه‌بندی تصویر (Image Classification):

from transformers import pipeline

pipeline = pipeline(task="image-classification", model="facebook/dinov2-small-imagenet1k-1-layer")
pipeline("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
[{'label': 'macaw', 'score': 0.997848391532898},
 {'label': 'sulphur-crested cockatoo, Kakatoe galerita, Cacatua galerita',
  'score': 0.0016551691805943847},
 {'label': 'lorikeet', 'score': 0.00018523589824326336},
 {'label': 'African grey, African gray, Psittacus erithacus',
  'score': 7.85409429227002e-05},
 {'label': 'quail', 'score': 5.502637941390276e-05}]

پاسخگویی بصری به سوالات (Visual Question Answering):

from transformers import pipeline

pipeline = pipeline(task="visual-question-answering", model="Salesforce/blip-vqa-base")
pipeline(
    image="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/idefics-few-shot.jpg",
    question="What is in the image?",
)
[{'answer': 'statue of liberty'}]

چرا باید از Transformers استفاده کنیم؟

1. مدل‌های پیشرفته و آسان برای استفاده:

   • عملکرد بالا در درک و تولید زبان طبیعی، بینایی ماشین، صوت، ویدیو و وظایف چندوجهی (Multimodal).
   • ورود آسان و بدون پیچیدگی برای پژوهشگران، مهندسان و توسعه‌دهندگان. (کاهش سد ورود برای متخصصان)
   • مفاهیم انتزاعی (Abstractions) اندک برای کاربر، به گونه‌ای که تنها با یادگیری سه کلاس اصلی می‌توان از آن استفاده کرد.
   • یک رابط برنامه‌نویسی (API) واحد و یکپارچه برای بهره‌گیری از تمامی مدل‌های پیش‌آموزش‌دیده ما.

2. کاهش هزینه‌های محاسباتی و ردپای کربن:

   • به‌جای آموزش مدل از ابتدا، از مدل‌های از پیش آموزش‌دیده استفاده و آن‌ها را به اشتراک بگذارید.
   • زمان محاسباتی و هزینه‌های تولید را کاهش دهید.
   • ده‌ها معماری مختلف مدل به همراه بیش از یک میلیون چک‌پوینتِ از پیش آموزش‌دیده در تمام حوزه‌های چندوجهی(Multimodal).

3. امکان انتخاب چارچوب مناسب در هر مرحله از چرخه عمر یک مدل:

   • مدل‌های پیشرفته (State‑of‑the‑Art) را تنها با سه خط کد آموزش دهید.
   • یک مدل واحد را به‌دلخواه بین فریم‌ورک‌های PyTorch، JAX و TensorFlow 2.0 جابه‌جا کنید.
   • برای مراحل آموزش، ارزیابی و استقرار در محیط تولید، مناسب‌ترین فریم‌ورک را انتخاب کنید.

4. قابلیت شخصی‌سازی:

   • برای هر معماری مدل، نمونه‌هایی ارائه می‌کنیم تا بتوانید نتایج منتشرشده توسط نویسندگان اصلی آن را بازتولید کنید.
   • اجزای داخلی مدل‌ها تا حد امکان به‌صورت سازگار و یکسان در دسترس قرار داده شده‌اند.
   • فایل‌های مدل را می‌توان برای انجام آزمایش‌های سریع، مستقل از خود کتابخانه نیز استفاده کرد.

چرا نباید از Transformers استفاده کنیم؟

• این کتابخانه یک جع��ه‌ابزار ماژولار برای شبکه‌های عصبی عمومی نیست؛ کدهای مدل‌ها عمداً برای محققان کمتر انتزاعی شده‌اند.
• رابط آموزش (Training API) بهینه‌سازی شده برای مدل‌های Transformers است. برای حلقه‌های عمومی یادگیری ماشین، بهتر است از کتابخانه‌هایی مانند Accelerate استفاده کنید.
• اسکریپت‌های نمونه ممکن است برای موارد استفاده خاص شما نیاز به تغییر و سازگاری داشته باشند.

۱۰۰ پروژه با استفاده از Transformers

مجموعهٔ Transformers تنها یک ابزار برای به‌کارگیری مدل‌های ازپیش‌آموزش‌دیده نیست، بلکه جامعه‌ای از پروژه‌هاست که پیرامون آن و همچنین پیرامون Hugging Face Hub شکل گرفته است. هدف ما این است که این کتابخانه به توسعه‌دهندگان، پژوهشگران، دانشجویان، اساتید، مهندسان و هر فرد دیگری کمک کند تا بتوانند پروژه‌های رؤیایی خود را بسازند.

به‌مناسبت رسیدن تعداد ستاره‌های Transformers به ۱۰۰٬۰۰۰، تصمیم گرفتیم با صفحهٔ
awesome-transformers توجه را به جامعهٔ کاربران جلب کنیم؛ صفحه‌ای که فهرستی از ۱۰۰ پروژهٔ شگفت‌انگیز ساخته‌شده با این کتابخانه را معرفی می‌کند.

در صورتی که صاحب یک پروژه هستید یا از پروژه‌ای استفاده می‌کنید که فکر می‌کنید باید در این فهرست قرار بگیرد، لطفاً یک Pull Request (PR) باز کنید تا آن را به مجموعه اضافه کنیم.

مدل‌های نمونه

شما می‌توانید اکثر مدل‌های ما را مستقیماً در صفحات مخزن مدل آنها آزمایش کنید.

با باز کردن هر یک از بخش‌های زیر، می‌توانید چند نمونه مدل برای کاربردهای مختلف را مشاه��ه کنید.

صدا (Audio)

• دسته‌بندی صدا با CLAP
• تشخیص خودکار گفتار با Parakeet, Whisper, GLM-ASR and Moonshine-Streaming
• شناسایی کلمات کلیدی با Wav2Vec2
• تولید گفتار از گفتار با Moshi
• تبدیل متن به صدا با MusicGen
• تبدیل متن به گفتار با CSM

بینایی ماشین (Computer vision):

• تولید خودکار ماسک با SAM
• تخمین عمق با DepthPro
• دسته‌بندی تصویر با DINO v2
• تشخیص نقاط کلیدی با SuperPoint
• تطبیق نقاط کلیدی با SuperGlue
• تشخیص اشیا با RT-DETRv2
• تخمین وضعیت بدن با VitPose
• بخش‌بندی جامع با OneFormer
• دسته‌بندی ویدیو با VideoMAE

چندوجهی (Multimodal):

• تبدیل صوت یا متن به متن با Voxtral, Audio Flamingo
• پرسش و پاسخ از اسناد با LayoutLMv3
• تبدیل تصویر یا متن به متن با Qwen-VL
• تولید توضیح برای تصویر با BLIP-2
• درک اسناد مبتنی بر OCR با GOT-OCR2
• پرسش و پاسخ از جدول‌ها (Table Question Answering) با TAPAS
• درک و تولید چندوجهی یکپارچه با Emu3
• تبدیل تصویر به متن با Llava-OneVision
• پرسش و پاسخ تصویری (Visual Question Answering) با Llava
• بخش‌بندی ارجاعی در تصویر (Visual Referring Expression Segmentation) با Kosmos-2

پردازش زبان طبیعی (NLP):

• تکمیل واژه‌های حذف‌شده (Masked Word Completion) با ModernBERT
• شناسایی موجودیت‌های نامدار (Named Entity Recognition) با Gemma
• پرسش و پاسخ متنی (Question Answering) با Mixtral
• خلاصه‌سازی متن (Summarization) با BART
• ترجمه خودکار (Translation) با T5
• تولید متن (Text Generation) با Llama
• دسته‌بندی متن (Text Classification) با Qwen

استناد (Citation)

اکنون می‌توانید برای کتابخانهٔ 🤗 Transformers به مقالهٔ منتشرشدهٔ آن استناد کنید.

@inproceedings{wolf-etal-2020-transformers,
    title = "Transformers: State-of-the-Art Natural Language Processing",
    author = "Thomas Wolf and Lysandre Debut and Victor Sanh and Julien Chaumond and Clement Delangue and Anthony Moi and Pierric Cistac and Tim Rault and Rémi Louf and Morgan Funtowicz and Joe Davison and Sam Shleifer and Patrick von Platen and Clara Ma and Yacine Jernite and Julien Plu and Canwen Xu and Teven Le Scao and Sylvain Gugger and Mariama Drame and Quentin Lhoest and Alexander M. Rush",
    booktitle = "Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
    month = oct,
    year = "2020",
    address = "Online",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2020.emnlp-demos.6/",
    pages = "38--45"
}