Hugging Face چیست؟ آموزش Hub، Transformers و اجرای مدل هوش مصنوعی با پایتون

اگر درباره مدل‌های متن‌باز هوش مصنوعی، مدل‌های زبانی بزرگ، پردازش زبان طبیعی یا یادگیری ماشین مطالعه کرده باشید، احتمالاً بارها با نام Hugging Face یا هاگینگ فیس روبه‌رو شده‌اید.

Hugging Face یکی از مهم‌ترین پلتفرم‌های اکوسیستم هوش مصنوعی است. توسعه‌دهندگان، پژوهشگران و شرکت‌ها می‌توانند مدل‌ها، مجموعه‌داده‌ها و اپلیکیشن‌های هوش مصنوعی را در آن پیدا، منتشر و آزمایش کنند.

در هاگینگ فیس می‌توانید:

• مدل‌های هوش مصنوعی را جست‌وجو کنید.
• فایل‌های یک مدل را دانلود کنید.
• مدل را روی کامپیوتر یا سرور خود اجرا کنید.
• از مدل‌های آماده برای متن، تصویر، صوت و ویدئو استفاده کنید.
• مجموعه‌داده‌های عمومی را دریافت کنید.
• اپلیکیشن‌های آزمایشی ساخته‌شده با مدل‌ها را مشاهده کنید.
• مدل یا دیتاست خود را منتشر کنید.
• از کتابخانه Transformers برای اجرای مدل‌ها استفاده کنید.
• مدل را برای یک وظیفه خاص فاین‌تیون (Fine-tune) کنید.

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

هاگینگ فیس چیست؟

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

بخش شناخته‌شده این اکوسیستم، Hugging Face Hub نام دارد. Hub را می‌توان مخزنی برای مدل‌ها، مجموعه‌داده‌ها و اپلیکیشن‌های هوش مصنوعی در نظر گرفت.

Hugging Face Hub از چند بخش اصلی تشکیل شده است:

در کنار Hub، کتابخانه‌هایی مانند Transformers، Datasets، Tokenizers، Accelerate، Diffusers و PEFT نیز در این اکوسیستم توسعه یافته‌اند.

هاگینگ فیس چگونه تلفظ می‌شود؟

Hugging Face معمولاً در فارسی به شکل‌های زیر نوشته می‌شود:

• هاگینگ فیس
• هاجینگ فیس
• Hugging Face

شکل رایج‌تر در محتوای فارسی «هاگینگ فیس» است. برای سئوی بهتر، استفاده طبیعی از هر دو شکل فارسی و انگلیسی در متن مناسب است.

Hugging Face Hub چیست؟

Hugging Face Hub یک پلتفرم میزبانی و اشتراک‌گذاری منابع هوش مصنوعی است. هر مدل یا دیتاست معمولاً در یک Repository جداگانه قرار می‌گیرد.

Repository مدل ممکن است شامل این فایل‌ها باشد:

• وزن‌های مدل
• فایل پیکربندی
• Tokenizer
• Vocabulary
• Generation Config
• فایل‌های پردازش تصویر یا صوت
• کدهای تکمیلی
• Model Card
• اطلاعات مجوز
• نمونه کد

Repository ID معمولاً از نام مالک و نام مخزن تشکیل می‌شود:

ORGANIZATION_OR_USERNAME/MODEL_NAME

برای مثال:

distilbert/distilbert-base-uncased-finetuned-sst-2-english

این مقدار یک Hugging Face Repository ID است و نباید آن را با Model ID مورد استفاده در API درواره اشتباه گرفت.

تفاوت Repository ID با Model ID درواره

این دو شناسه ممکن است شبیه یکدیگر به نظر برسند، اما الزاماً یکسان نیستند.

برای اجرای محلی یک مدل ممکن است از این مقدار استفاده کنید:

model="distilbert/distilbert-base-uncased-finetuned-sst-2-english"

اما هنگام استفاده از API درواره باید Model ID را مستقیماً از صفحه مدل‌های درواره دریافت کنید:

{
  "model": "YOUR_MODEL_ID"
}

نام تجاری مدل همیشه با شناسه قابل استفاده در API یکسان نیست.

مهم‌ترین کتابخانه‌های هاگینگ فیس

Transformers

کتابخانه Transformers برای دریافت، بارگذاری، اجرا و آموزش مدل‌های مبتنی بر معماری Transformer استفاده می‌شود.

این کتابخانه از وظایف مختلفی پشتیبانی می‌کند:

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

Datasets

کتابخانه Datasets برای دریافت، پردازش و استفاده از مجموعه‌داده‌ها طراحی شده است.

با این کتابخانه می‌توانید:

• دیتاست را دانلود کنید.
• داده را به‌صورت Streaming بخوانید.
• داده را فیلتر یا تبدیل کنید.
• بخش Train، Validation و Test را مدیریت کنید.
• دیتاست خود را در Hub منتشر کنید.

Tokenizers

مدل زبانی مستقیماً متن خام را پردازش نمی‌کند. ابتدا متن به واحدهای کوچک‌تر به نام توکن (Token) تبدیل می‌شود.

کتابخانه Tokenizers این مرحله را با سرعت بالا انجام می‌دهد.

Diffusers

کتابخانه Diffusers برای مدل‌های مولد مبتنی بر Diffusion کاربرد دارد؛ مانند:

• تولید تصویر از متن
• ویرایش تصویر
• Inpainting
• Image-to-Image
• برخی مدل‌های صوت و ویدئو

Accelerate

کتابخانه Accelerate اجرای مدل و فرایند آموزش روی سخت‌افزارهای مختلف را ساده‌تر می‌کند.

برای مثال می‌تواند در مدیریت این موارد کمک کند:

• CPU
• یک GPU
• چند GPU
• Mixed Precision
• اجرای توزیع‌شده

PEFT

PEFT مخفف Parameter-Efficient Fine-Tuning است و برای فاین‌تیون کم‌هزینه‌تر مدل‌ها استفاده می‌شود.

روش‌هایی مانند LoRA و QLoRA به‌جای تغییر همه پارامترهای مدل، بخش کوچک‌تری از پارامترها را آموزش می‌دهند.

huggingface_hub

کتابخانه huggingface_hub رابط پایتونی و خط فرمان برای ارتباط با Hub است.

با آن می‌توانید:

• مدل و دیتاست جست‌وجو کنید.
• فایل دانلود کنید.
• Repository بسازید.
• فایل آپلود کنید.
• اطلاعات Model Card را بخوانید.
• Cache محلی را مدیریت کنید.

Hugging Face Spaces چیست؟

Spaces بخشی از Hugging Face است که برای ساخت و میزبانی Demo و اپلیکیشن‌های هوش مصنوعی استفاده می‌شود.

بسیاری از Spaces با ابزارهای زیر ساخته می‌شوند:

• Gradio
• Streamlit
• Docker
• رابط‌های سفارشی

برای مثال، سازنده یک مدل تولید تصویر می‌تواند رابطی بسازد که کاربر پرامپت وارد کند و نتیجه را مستقیماً ببیند.

Space لزوماً خود مدل نیست. معمولاً یک رابط یا اپلیکیشن است که به مدل متصل شده است.

Model Card چیست؟

Model Card صفحه توضیحات و مستندات یک مدل است. قبل از دانلود یا استفاده از مدل باید این صفحه را مطالعه کنید.

اطلاعات مهم Model Card می‌تواند شامل موارد زیر باشد:

• نام و نسخه مدل
• معماری
• تعداد پارامترها
• زبان‌های پشتیبانی‌شده
• وظیفه اصلی
• قالب ورودی
• قالب خروجی
• Context Window
• سخت‌افزار موردنیاز
• روش اجرای مدل
• نتایج Benchmark
• محدودیت‌ها
• دیتاست آموزشی
• مجوز استفاده
• مثال کد
• نسخه کتابخانه‌های موردنیاز

صرف محبوب‌بودن یک مدل یا زیادبودن تعداد دانلود آن برای انتخاب کافی نیست. باید مشخص شود مدل برای وظیفه، زبان و سخت‌افزار شما مناسب است.

چگونه مدل مناسب پیدا کنیم؟

در صفحه Models می‌توانید مدل‌ها را بر اساس معیارهای مختلف فیلتر کنید.

فیلترهای مهم عبارت‌اند از:

• Task
• Library
• Language
• License
• Model Size
• Framework
• Dataset
• Sort
• معماری

انتخاب بر اساس Task

ابتدا باید وظیفه مدل را مشخص کنید.

انتخاب بر اساس زبان

مدلی که روی متن انگلیسی عملکرد خوبی دارد، الزاماً برای فارسی مناسب نیست.

در Model Card بررسی کنید:

• آیا فارسی در زبان‌های پشتیبانی‌شده ذکر شده است؟
• آیا نمونه فارسی وجود دارد؟
• آیا مدل چندزبانه است؟
• Tokenizer با متن فارسی چگونه رفتار می‌کند؟
• ارزیابی فارسی ارائه شده است یا خیر؟

انتخاب بر اساس اندازه

هرچه مدل بزرگ‌تر باشد، معمولاً حافظه و توان پردازشی بیشتری نیاز دارد.

تعداد پارامترها تنها معیار کیفیت نیست. یک مدل کوچک که برای وظیفه خاصی آموزش دیده ممکن است از یک مدل عمومی بزرگ، سریع‌تر و مناسب‌تر باشد.

پیش‌نیاز اجرای مدل با پایتون

برای اجرای مثال‌ها به این موارد نیاز دارید:

• Python نسخه 3.10 یا جدیدتر
• pip
• فضای دیسک کافی
• حافظه RAM متناسب با مدل
• اینترنت برای دانلود اولیه
• GPU برای مدل‌های سنگین‌تر

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

مرحله اول: ساخت پروژه

یک پوشه جدید بسازید:

mkdir huggingface-python-guide
cd huggingface-python-guide

محیط مجازی ایجاد کنید:

در Linux و macOS:

python3 -m venv .venv
source .venv/bin/activate

در Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

مرحله دوم: نصب Transformers

برای مثال‌های متنی، کتابخانه‌های زیر را نصب کنید:

pip install torch transformers huggingface_hub

در صورت نیاز به پردازش دیتاست:

pip install datasets

فایل requirements.txt:

torch
transformers
huggingface_hub
datasets

نصب پیشنهادی huggingface_hub در یک محیط مجازی نیز در مستندات رسمی نصب توصیه شده است.

مرحله سوم: بررسی PyTorch و GPU

فایل check_device.py را بسازید:

import torch

print("PyTorch version:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())

if torch.cuda.is_available():
    print("GPU:", torch.cuda.get_device_name(0))
else:
    print("Running on CPU")

اجرا کنید:

python check_device.py

اگر نتیجه زیر نمایش داده شود، برنامه از GPU سازگار با CUDA استفاده نمی‌کند:

CUDA available: False
Running on CPU

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

Pipeline در Transformers چیست؟

Pipeline یکی از ساده‌ترین روش‌های اجرای مدل در Transformers است.

Pipeline مراحل زیر را در یک رابط ساده ترکیب می‌کند:

1. دریافت ورودی
2. Tokenization یا Preprocessing
3. اجرای مدل
4. Post-processing
5. تولید خروجی قابل استفاده در پایتون

طبق مستندات رسمی Pipeline، این رابط برای وظایف متن، تصویر، صوت و چندوجهی قابل استفاده است.

ساختار کلی:

from transformers import pipeline

classifier = pipeline(
    task="text-classification",
    model="HUGGINGFACE_REPOSITORY_ID",
)

result = classifier("Input text")
print(result)

پروژه اول: تحلیل احساسات متن

فایل sentiment.py را بسازید:

from transformers import pipeline

MODEL_REPOSITORY_ID = (
    "distilbert/distilbert-base-uncased-finetuned-sst-2-english"
)

classifier = pipeline(
    task="sentiment-analysis",
    model=MODEL_REPOSITORY_ID,
)

texts = [
    "This application is fast and easy to use.",
    "The latest update made the experience worse.",
]

results = classifier(texts)

for text, result in zip(texts, results):
    print("Text:", text)
    print("Label:", result["label"])
    print("Score:", round(result["score"], 4))
    print()

برنامه را اجرا کنید:

python sentiment.py

در اولین اجرا، فایل‌های مدل دانلود و در Cache محلی ذخیره می‌شوند. اجراهای بعدی معمولاً از فایل‌های Cache استفاده می‌کنند.

خروجی تقریبی:

Text: This application is fast and easy to use.
Label: POSITIVE
Score: 0.9998

Text: The latest update made the experience worse.
Label: NEGATIVE
Score: 0.9995

این مدل برای انگلیسی آموزش دیده است. برای تحلیل متن فارسی باید مدلی را انتخاب کنید که فارسی یا زبان‌های چندگانه را پشتیبانی کند.

تعیین صریح دستگاه اجرا

در Pipeline می‌توانید دستگاه را مشخص کنید.

برای CPU:

classifier = pipeline(
    task="sentiment-analysis",
    model=MODEL_REPOSITORY_ID,
    device=-1,
)

برای اولین GPU:

classifier = pipeline(
    task="sentiment-analysis",
    model=MODEL_REPOSITORY_ID,
    device=0,
)

پیش از انتخاب device=0 مطمئن شوید PyTorch به GPU دسترسی دارد.

پردازش گروهی یا Batch

ارسال چند ورودی به شکل Batch می‌تواند از اجرای جداگانه آن‌ها مناسب‌تر باشد:

texts = [
    "The interface is excellent.",
    "The program is difficult to use.",
    "The response time is acceptable.",
]

results = classifier(
    texts,
    batch_size=3,
)

for text, result in zip(texts, results):
    print(text, result)

اندازه مناسب Batch به حافظه دستگاه، طول متن و اندازه مدل بستگی دارد. Batch بسیار بزرگ می‌تواند باعث خطای کمبود حافظه شود.

پروژه دوم: استفاده مستقیم از Tokenizer و Model

Pipeline برای شروع ساده است، اما گاهی به کنترل بیشتری نیاز دارید.

در این حالت می‌توانید از کلاس‌های Auto استفاده کنید:

import torch
from transformers import (
    AutoModelForSequenceClassification,
    AutoTokenizer,
)

MODEL_REPOSITORY_ID = (
    "distilbert/distilbert-base-uncased-finetuned-sst-2-english"
)

tokenizer = AutoTokenizer.from_pretrained(
    MODEL_REPOSITORY_ID
)

model = AutoModelForSequenceClassification.from_pretrained(
    MODEL_REPOSITORY_ID
)

text = "The application is useful and responsive."

inputs = tokenizer(
    text,
    return_tensors="pt",
    truncation=True,
)

with torch.no_grad():
    outputs = model(**inputs)

probabilities = torch.softmax(
    outputs.logits,
    dim=-1,
)

predicted_id = int(
    probabilities.argmax(dim=-1).item()
)

label = model.config.id2label[predicted_id]
score = float(
    probabilities[0, predicted_id].item()
)

print(
    {
        "label": label,
        "score": round(score, 4),
    }
)

در این مثال:

• AutoTokenizer متن را به توکن تبدیل می‌کند.
• AutoModelForSequenceClassification معماری مناسب را بارگذاری می‌کند.
• مدل Logit تولید می‌کند.
• Softmax مقدارها را به احتمال تبدیل می‌کند.
• برچسب نهایی از id2label خوانده می‌شود.

تفاوت Pipeline با AutoClass

برای شروع، Pipeline انتخاب مناسبی است. وقتی به کنترل Tokenization، Batch، Tensor یا خروجی خام نیاز داشتید، سراغ AutoClass بروید.

پروژه سوم: اجرای مدل زبانی Chat

مدل‌های Chat معمولاً با یک قالب مکالمه یا Chat Template کار می‌کنند.

نمونه عمومی:

import torch
from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
)

MODEL_REPOSITORY_ID = "YOUR_HUGGINGFACE_REPOSITORY_ID"

tokenizer = AutoTokenizer.from_pretrained(
    MODEL_REPOSITORY_ID
)

model = AutoModelForCausalLM.from_pretrained(
    MODEL_REPOSITORY_ID,
    torch_dtype="auto",
    device_map="auto",
)

messages = [
    {
        "role": "system",
        "content": "شما یک دستیار فارسی دقیق هستید.",
    },
    {
        "role": "user",
        "content": "Hugging Face را کوتاه توضیح بده.",
    },
]

input_ids = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    output_ids = model.generate(
        input_ids,
        max_new_tokens=300,
        do_sample=True,
        temperature=0.7,
        top_p=0.9,
    )

generated_ids = output_ids[
    0,
    input_ids.shape[-1]:,
]

answer = tokenizer.decode(
    generated_ids,
    skip_special_tokens=True,
)

print(answer)

مقدار زیر را با Repository ID مدل انتخابی جایگزین کنید:

YOUR_HUGGINGFACE_REPOSITORY_ID

پیش از اجرا بررسی کنید:

• مدل دارای Chat Template باشد.
• معماری آن با AutoModelForCausalLM سازگار باشد.
• RAM یا VRAM کافی داشته باشید.
• نسخه Transformers موردنیاز نصب باشد.
• شرایط استفاده مدل با پروژه شما سازگار باشد.

همه مدل‌های Text Generation الزاماً Chat Model نیستند. اگر مدل Chat Template نداشته باشد، باید ورودی را مطابق قالب معرفی‌شده در Model Card بسازید.

معنی پارامترهای تولید متن

max_new_tokens

حداکثر تعداد توکن جدید:

max_new_tokens=300

این مقدار طول ورودی را محاسبه نمی‌کند و فقط خروجی جدید را محدود می‌کند.

temperature

میزان تنوع احتمالی پاسخ:

temperature=0.7

برای خروجی دقیق‌تر می‌توان مقدار پایین‌تری انتخاب کرد.

top_p

مدل تنها مجموعه‌ای از توکن‌های محتمل را در نظر می‌گیرد که مجموع احتمال آن‌ها به مقدار top_p برسد:

top_p=0.9

do_sample

اگر فعال باشد، تولید از Sampling استفاده می‌کند:

do_sample=True

برای خروجی پایدارتر می‌توانید Sampling را غیرفعال کنید:

do_sample=False

در این حالت استفاده از Temperature و Top-p ممکن است اثری نداشته باشد.

دانلود مدل با huggingface_hub

برای دانلود یک فایل مشخص:

from huggingface_hub import hf_hub_download

file_path = hf_hub_download(
    repo_id="YOUR_HUGGINGFACE_REPOSITORY_ID",
    filename="config.json",
)

print(file_path)

برای دانلود Snapshot کامل Repository:

from huggingface_hub import snapshot_download

folder_path = snapshot_download(
    repo_id="YOUR_HUGGINGFACE_REPOSITORY_ID",
)

print(folder_path)

کتابخانه huggingface_hub فایل‌ها را دانلود و در Cache محلی نگهداری می‌کند. راهنمای کامل این قابلیت در مستندات دانلود فایل از Hub موجود است.

استفاده از خط فرمان hf

پس از نصب huggingface_hub، ابزار خط فرمان hf در دسترس قرار می‌گیرد.

نمایش راهنما:

hf --help

دانلود Repository کامل:

hf download YOUR_HUGGINGFACE_REPOSITORY_ID

دانلود یک فایل مشخص:

hf download \
  YOUR_HUGGINGFACE_REPOSITORY_ID \
  config.json

دانلود در یک پوشه مشخص:

hf download \
  YOUR_HUGGINGFACE_REPOSITORY_ID \
  --local-dir ./models/my-model

دانلود یک Revision مشخص:

hf download \
  YOUR_HUGGINGFACE_REPOSITORY_ID \
  --revision REVISION_NAME

طبق راهنمای رسمی CLI، دستور hf download در پشت صحنه از همان توابع دانلود کتابخانه Hub استفاده می‌کند.

Revision چیست؟

یک Repository ممکن است در طول زمان تغییر کند. اگر همیشه نسخه اصلی یا main را دانلود کنید، فایل مدل ممکن است در آینده تغییر کند.

برای پروژه قابل تکرار بهتر است Revision مشخصی تعیین کنید:

tokenizer = AutoTokenizer.from_pretrained(
    MODEL_REPOSITORY_ID,
    revision="COMMIT_HASH_OR_TAG",
)

model = AutoModelForSequenceClassification.from_pretrained(
    MODEL_REPOSITORY_ID,
    revision="COMMIT_HASH_OR_TAG",
)

این کار کمک می‌کند محیط آزمایش و Production از نسخه یکسان استفاده کنند.

Cache مدل‌ها کجاست؟

فایل‌های دریافت‌شده معمولاً در Cache محلی Hugging Face ذخیره می‌شوند. مسیر دقیق به سیستم‌عامل و تنظیمات محیط بستگی دارد.

در بسیاری از سیستم‌ها مسیر پیش‌فرض زیر استفاده می‌شود:

~/.cache/huggingface/

می‌توانید مسیر اصلی را با متغیر محیطی تغییر دهید:

export HF_HOME="/data/huggingface"

در Windows PowerShell:

$env:HF_HOME="D:\huggingface-cache"

مدل‌های بزرگ می‌توانند فضای دیسک زیادی اشغال کنند. ظرفیت Cache را کنترل و فقط فایل‌های غیرضروری را با ابزارهای رسمی مدیریت کنید.

جزئیات ساختار Cache در راهنمای Hugging Face Cache توضیح داده شده است.

ورود به هاگینگ فیس

برای مدل‌های عمومی معمولاً همیشه به ورود نیاز ندارید. برای Repository خصوصی یا Gated باید احراز هویت انجام شود.

ورود با CLI:

hf auth login

توکن را در کد قرار ندهید:

token = "hf_xxxxxxxxx"

بهتر است از احراز هویت CLI یا متغیر محیطی استفاده کنید.

در .gitignore نیز فایل‌های حاوی Secret را قرار دهید:

.env
.venv/
__pycache__/
models/

Gated Model چیست؟

برخی مدل‌ها Gated هستند؛ یعنی پیش از دانلود باید:

1. وارد حساب Hugging Face شوید.
2. صفحه مدل را باز کنید.
3. شرایط ارائه‌شده را مطالعه کنید.
4. درخواست دسترسی ارسال کنید.
5. پس از دریافت دسترسی، احراز هویت انجام دهید.

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

استفاده از کتابخانه Datasets

کتابخانه را نصب کنید:

pip install datasets

نمونه دریافت دیتاست:

from datasets import load_dataset

dataset = load_dataset(
    "imdb",
    split="train[:100]",
)

print(dataset)
print(dataset[0])

نمایش ستون‌ها:

print(dataset.column_names)

دریافت چند ردیف:

for row in dataset.select(range(3)):
    print(row["text"][:200])
    print("Label:", row["label"])
    print()

بخش train[:100] فقط صد رکورد اول را دریافت می‌کند و برای آزمایش اولیه مناسب است.

Streaming دیتاست

برای دیتاست‌های بزرگ می‌توانید داده را به‌صورت Streaming بخوانید:

from datasets import load_dataset

dataset = load_dataset(
    "imdb",
    split="train",
    streaming=True,
)

for index, row in enumerate(dataset):
    print(row["text"][:150])

    if index == 4:
        break

در این روش لازم نیست کل دیتاست قبل از شروع پردازش روی دیسک دانلود شود.

اجرای محلی مدل چه مزایایی دارد؟

اجرای مدل روی سخت‌افزار خودتان می‌تواند این مزایا را داشته باشد:

• کنترل بیشتر روی محیط اجرا
• امکان استفاده بدون فراخوانی API پس از دانلود
• دسترسی به خروجی‌های داخلی مدل
• امکان فاین‌تیون و تغییر وزن‌ها
• امکان اجرای مدل‌های تخصصی
• کنترل بیشتر روی نسخه و وابستگی‌ها
• مناسب برای پژوهش و آزمایش معماری

اما این روش هزینه‌ها و پیچیدگی‌های خاص خود را دارد:

• نیاز به RAM و VRAM
• دانلود فایل‌های بزرگ
• نصب Driver و کتابخانه
• مدیریت نسخه‌ها
• مدیریت Cache
• نگهداری سرور
• مقیاس‌پذیری
• مانیتورینگ
• زمان راه‌اندازی
• بهینه‌سازی Inference

چه زمانی از API استفاده کنیم؟

استفاده از API زمانی مناسب است که:

• نمی‌خواهید وزن مدل را دانلود کنید.
• سخت‌افزار GPU در اختیار ندارید.
• می‌خواهید سریع MVP بسازید.
• میزان مصرف شما متغیر است.
• به چند مدل مختلف نیاز دارید.
• نمی‌خواهید زیرساخت Inference را مدیریت کنید.
• مقیاس‌پذیری برای شما مهم است.
• ترجیح می‌دهید بر توسعه محصول تمرکز کنید.

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

مقایسه اجرای محلی و API درواره

این دو روش رقیب مطلق یکدیگر نیستند. بسیاری از تیم‌ها برای پژوهش و آزمایش از مدل محلی و برای محصول نهایی یا مدل‌های بزرگ‌تر از API استفاده می‌کنند.

اتصال پایتون به API درواره

کتابخانه موردنیاز:

pip install openai python-dotenv

فایل .env:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL_ID=YOUR_MODEL_ID

فایل .gitignore:

.env
.venv/
__pycache__/

نمونه کد:

import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

api_key = os.getenv("DARVAREH_API_KEY")
model_id = os.getenv("DARVAREH_MODEL_ID")

if not api_key:
    raise RuntimeError(
        "متغیر DARVAREH_API_KEY تنظیم نشده است."
    )

if not model_id:
    raise RuntimeError(
        "متغیر DARVAREH_MODEL_ID تنظیم نشده است."
    )

client = OpenAI(
    api_key=api_key,
    base_url="https://api.darvareh.ir/v1",
)

response = client.chat.completions.create(
    model=model_id,
    messages=[
        {
            "role": "system",
            "content": (
                "شما یک دستیار فارسی دقیق و کاربردی هستید."
            ),
        },
        {
            "role": "user",
            "content": (
                "تفاوت اجرای محلی مدل با استفاده از API را توضیح بده."
            ),
        },
    ],
    temperature=0.2,
    max_tokens=800,
)

print(response.choices[0].message.content)

در این روش:

• مدل روی کامپیوتر شما دانلود نمی‌شود.
• سخت‌افزار Inference را مدیریت نمی‌کنید.
• با Model ID مدل موردنظر را انتخاب می‌کنید.
• نتیجه در قالب پاسخ API دریافت می‌شود.

برای دریافت آخرین Model IDها و قیمت‌ها به صفحه مدل‌های درواره مراجعه کنید.

ترکیب مدل محلی و API

در یک پروژه واقعی می‌توان از معماری ترکیبی استفاده کرد.

برای مثال:

• طبقه‌بندی ساده با مدل محلی کوچک
• تولید پاسخ با مدل بزرگ از طریق API
• ساخت Embedding محلی
• استفاده از API برای Reasoning
• پردازش اولیه داده به‌صورت محلی
• خلاصه‌سازی نهایی با مدل API

نمونه منطق ساده:

def choose_execution_method(
    task: str,
    text_length: int,
) -> str:
    local_tasks = {
        "sentiment",
        "simple_classification",
    }

    if task in local_tasks and text_length < 2000:
        return "local"

    return "api"

سپس:

method = choose_execution_method(
    task="sentiment",
    text_length=len(user_text),
)

if method == "local":
    result = local_classifier(user_text)
else:
    result = call_darvareh_api(user_text)

این معماری می‌تواند هزینه، سرعت و کیفیت را متناسب با نوع وظیفه مدیریت کند.

خطاهای رایج هاگینگ فیس

خطای کمبود حافظه

نشانه رایج:

CUDA out of memory

راهکارهای احتمالی:

• انتخاب مدل کوچک‌تر
• کاهش Batch Size
• کاهش طول ورودی
• کاهش max_new_tokens
• بستن فرایندهای دیگر GPU
• استفاده از Precision مناسب
• استفاده از API به‌جای اجرای محلی مدل بزرگ

دانلود مدل بسیار کند است

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

همچنین بررسی کنید:

• فضای دیسک کافی وجود دارد.
• Cache در مسیر مناسبی قرار دارد.
• دانلود قبلی ناقص نمانده است.
• Repository به احراز هویت نیاز ندارد.

خطای Repository Not Found

موارد زیر را بررسی کنید:

• Repository ID درست نوشته شده باشد.
• بزرگ و کوچک بودن حروف رعایت شده باشد.
• Repository حذف یا تغییر نام نداده باشد.
• مدل خصوصی نباشد.
• برای مدل Gated دسترسی دریافت شده باشد.

خطای Tokenizer

ممکن است مدل به Tokenizer خاص، نسخه جدید Transformers یا گزینه‌های معرفی‌شده در Model Card نیاز داشته باشد.

ابتدا Model Card و فایل config.json را بررسی کنید.

خطای Chat Template

اگر این خط اجرا نشود:

tokenizer.apply_chat_template(...)

ممکن است مدل Chat Template نداشته باشد. قالب موردنیاز را از Model Card دریافت کنید یا مدلی را انتخاب کنید که برای Chat منتشر شده باشد.

خروجی مدل نامفهوم است

علل احتمالی:

• Prompt با قالب آموزشی مدل مطابقت ندارد.
• مدل Chat نیست.
• زبان فارسی را به‌خوبی پشتیبانی نمی‌کند.
• Temperature بیش از حد بالا است.
• مدل برای وظیفه دیگری آموزش دیده است.
• Tokenizer یا Special Tokenها درست تنظیم نشده‌اند.
• نسخه یا Revision نامناسب بارگذاری شده است.

اجرای مدل روی CPU بسیار کند است

مدل‌های زبانی بزرگ محاسبات زیادی نیاز دارند. برای CPU یکی از این گزینه‌ها را در نظر بگیرید:

• مدل کوچک‌تر
• نسخه Quantized سازگار
• کاهش طول Context
• کاهش خروجی
• استفاده از Runtime بهینه
• استفاده از API درواره

چگونه حافظه موردنیاز مدل را تخمین بزنیم؟

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

تقریب ساده برای وزن‌ها:

حافظه تقریبی وزن‌ها =
تعداد پارامترها × تعداد بایت هر پارامتر

برای نمونه:

• FP32 تقریباً ۴ بایت برای هر پارامتر
• FP16 یا BF16 تقریباً ۲ بایت
• INT8 تقریباً ۱ بایت
• چهار بیت تقریباً نیم بایت

یک مدل ۷ میلیارد پارامتری در FP16 فقط برای وزن‌ها تقریباً به این مقدار حافظه نیاز دارد:

7,000,000,000 × 2 bytes
≈ 14 GB

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

در Ghost بهتر است چنین محاسباتی را داخل Code Block قرار دهید تا با ویرایشگر سازگار بماند.

Quantization چیست؟

Quantization یا کوانتیزه‌سازی روشی برای کاهش دقت عددی وزن‌های مدل و در نتیجه کاهش مصرف حافظه است.

نسخه‌های رایج:

• ۸ بیت
• ۴ بیت
• قالب‌های مخصوص Runtimeهای محلی

مزایا:

• مصرف حافظه کمتر
• امکان اجرای مدل بزرگ‌تر
• سرعت مناسب‌تر در برخی سخت‌افزارها

محدودیت‌ها:

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

Quantization همیشه باعث سریع‌ترشدن مدل نمی‌شود. نتیجه به سخت‌افزار، Runtime و قالب مدل بستگی دارد.

نکات انتخاب مدل برای فارسی

هنگام انتخاب مدل فارسی یا چندزبانه این موارد را آزمایش کنید:

• درک سؤال فارسی
• تولید متن طبیعی
• حفظ نیم‌فاصله و نشانه‌گذاری
• درک اعداد فارسی و انگلیسی
• توانایی دنبال‌کردن دستور فارسی
• خلاصه‌سازی متن رسمی
• درک متن محاوره‌ای
• تولید JSON با محتوای فارسی
• عملکرد روی متن ترکیبی فارسی و انگلیسی
• تعداد توکن مصرفی برای متن فارسی

بهتر است یک مجموعه آزمایشی کوچک بسازید:

PERSIAN_TEST_PROMPTS = [
    "این متن را خلاصه کن.",
    "سه عنوان رسمی پیشنهاد بده.",
    "اطلاعات را به JSON تبدیل کن.",
    "خطای کد زیر را توضیح بده.",
    "تفاوت API و SDK چیست؟",
]

پاسخ مدل‌ها را با معیارهای ثابت مقایسه کنید:

• دقت
• خوانایی
• پیروی از دستور
• سرعت
• مصرف حافظه
• هزینه
• ثبات قالب خروجی

چک‌لیست انتخاب مدل از هاگینگ فیس

پیش از دانلود مدل بررسی کنید:

• Task مدل با نیاز شما یکسان است.
• زبان فارسی یا زبان موردنظر پشتیبانی می‌شود.
• Model Card کامل است.
• اندازه فایل‌ها با فضای دیسک شما سازگار است.
• RAM یا VRAM کافی دارید.
• معماری توسط Transformers پشتیبانی می‌شود.
• نمونه کد قابل اجرا وجود دارد.
• Revision مشخص شده است.
• محدودیت‌های مدل مطالعه شده‌اند.
• مجوز مدل با نوع استفاده شما سازگار است.
• مدل به کد سفارشی ناشناس نیاز ندارد.
• Benchmarkها با وظیفه واقعی شما مرتبط‌اند.
• مدل روی داده آزمایشی خودتان ارزیابی شده است.

چک‌لیست آماده‌سازی اجرای محلی

• محیط مجازی ساخته شده است.
• نسخه Python مناسب است.
• PyTorch درست نصب شده است.
• دسترسی GPU بررسی شده است.
• فضای Cache کافی است.
• Repository ID درست است.
• Tokenizer و Model با یک Revision بارگذاری می‌شوند.
• طول ورودی محدود شده است.
• Batch Size کنترل شده است.
• Timeout دانلود در نظر گرفته شده است.
• مدل ابتدا با چند ورودی کوچک آزمایش شده است.
• مصرف RAM و VRAM اندازه‌گیری شده است.
• خروجی مدل قبل از استفاده نهایی ارزیابی می‌شود.

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

Hugging Face چیست؟

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

آیا هاگینگ فیس رایگان است؟

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

آیا همه مدل‌های هاگینگ فیس رایگان هستند؟

خیر. عمومی‌بودن صفحه مدل الزاماً به‌معنای آزادبودن هر نوع استفاده نیست. بعضی مدل‌ها Gated، خصوصی یا دارای شرایط خاص هستند.

آیا برای اجرای مدل به GPU نیاز داریم؟

برای مدل‌های کوچک، CPU می‌تواند کافی باشد. مدل‌های بزرگ‌تر معمولاً برای سرعت قابل قبول به GPU و حافظه بیشتر نیاز دارند.

Transformers چیست؟

Transformers کتابخانه‌ای برای بارگذاری، اجرا و آموزش مدل‌های مبتنی بر Transformer در وظایف متن، تصویر، صوت و چندوجهی است.

Pipeline چیست؟

Pipeline یک رابط سطح بالا در Transformers است که مراحل آماده‌سازی ورودی، اجرای مدل و پردازش خروجی را ساده می‌کند.

تفاوت هاگینگ فیس و درواره چیست؟

Hugging Face Hub مخزنی برای مدل‌ها، دیتاست‌ها و Demoهای هوش مصنوعی است. درواره زیرساخت API برای دسترسی یکپارچه به مدل‌های هوش مصنوعی ارائه می‌کند. یکی بیشتر نقش اکوسیستم انتشار و توسعه مدل دارد و دیگری دسترسی API به مدل‌ها را برای اپلیکیشن ساده می‌کند.

اجرای محلی بهتر است یا API؟

برای پژوهش، فاین‌تیون و کنترل مستقیم مدل، اجرای محلی مناسب است. برای ساخت سریع محصول، حذف نیاز به GPU و استفاده از مدل‌های مختلف، API می‌تواند گزینه ساده‌تری باشد.

چگونه یک مدل فارسی پیدا کنیم؟

فیلتر Language را بررسی و Model Card را مطالعه کنید. سپس مدل را با مجموعه‌ای از متن‌های واقعی فارسی ارزیابی کنید. صرف ذکر Multilingual بودن برای اطمینان از کیفیت فارسی کافی نیست.

Model ID درواره را از کجا بگیریم؟

Model IDهای قابل استفاده در API در صفحه مدل‌های درواره نمایش داده می‌شوند.

آیا می‌توان مدل Hugging Face را مستقیماً در مرورگر اجرا کرد؟

برخی مدل‌ها را می‌توان با Transformers.js یا Runtimeهای مرورگر اجرا کرد، اما اندازه مدل، حافظه دستگاه و قابلیت‌های مرورگر محدودیت ایجاد می‌کنند.

آیا دانلود مدل فقط یک‌بار انجام می‌شود؟

فایل‌ها معمولاً در Cache ذخیره می‌شوند و در اجرای بعدی دوباره دانلود نمی‌شوند؛ مگر اینکه Revision تغییر کند، Cache پاک شود یا فایل موردنیاز وجود نداشته باشد.

جمع‌بندی

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

در این آموزش یاد گرفتیم:

• Hugging Face Hub چگونه کار می‌کند.
• Models، Datasets و Spaces چه تفاوتی دارند.
• Model Card را چگونه بررسی کنیم.
• Transformers و Pipeline چیست.
• مدل را با پایتون اجرا کنیم.
• Tokenizer و AutoModel را مستقیماً به کار ببریم.
• فایل‌های مدل را با huggingface_hub دانلود کنیم.
• Cache و Revision را مدیریت کنیم.
• دیتاست را با کتابخانه Datasets بخوانیم.
• اجرای محلی مدل را با API مقایسه کنیم.
• از API درواره برای استفاده بدون مدیریت زیرساخت مدل بهره ببریم.

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

برای شروع، در درواره ثبت‌نام کنید، API Key بسازید و مدل مناسب پروژه را از صفحه مدل‌ها انتخاب کنید.

مقالات مرتبط

• راهنمای کامل مدل‌های هوش مصنوعی
• آموزش هوش مصنوعی با پایتون و ساخت پروژه واقعی
• Fine-Tuning چیست؟ آموزش LoRA و QLoRA
• Embedding چیست و چه کاربردی دارد؟
• Qwen چیست؟ معرفی مدل‌های هوش مصنوعی کوئن
• Llama چیست؟ معرفی مدل‌های هوش مصنوعی متا
• درواره چیست؟ معرفی پلتفرم API هوش مصنوعی
• آموزش دریافت API Key هوش مصنوعی

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.