آموزش اجرای مدل‌های Hugging Face روی GPU Server

Hugging Face بزرگ‌ترین مخزن مدل‌های هوش مصنوعی متن‌باز است: مدل‌های زبانی، تولید تصویر، تشخیص گفتار، دسته‌بندی متن و هزاران مدل دیگر. در این راهنما اجرای مدل‌های Hugging Face روی GPU Server را گام‌به‌گام انجام می‌دهیم: آماده‌سازی محیط، دانلود مدل، اجرای آن با کتابخانه Transformers، بهینه‌سازی حافظه و سرعت و در نهایت مسیر انتقال به محیط عملیاتی.

پیش‌نیازها

• یک سرور GPU با کارت NVIDIA و Ubuntu، با درایور نصب‌شده. خروجی nvidia-smi باید کارت را نشان دهد؛ نصب درایور در نصب Ollama روی سرور GPU توضیح داده شده است.
• VRAM کافی برای مدل؛ محاسبه در VRAM مورد نیاز هوش مصنوعی.
• فضای دیسک برای مدل‌ها: یک مدل ۷ میلیاردی در BF16 حدود ۱۵ گیگابایت حجم دارد.

گام ۱: آماده‌سازی محیط پایتون

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

sudo apt install -y python3-venv
python3 -m venv ~/hf-env
source ~/hf-env/bin/activate
pip install --upgrade pip
pip install torch
pip install transformers accelerate bitsandbytes huggingface_hub

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

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

گام ۲: توکن Hugging Face و مدل‌های دارای مجوز

برخی مدل‌ها، مثل خانواده Llama و Gemma، قبل از دانلود نیاز به پذیرش مجوز در صفحه مدل دارند. پس از پذیرش، از تنظیمات حساب Hugging Face یک توکن با دسترسی Read بسازید و روی سرور وارد کنید:

hf auth login

در نسخه‌های قدیمی‌تر کتابخانه، دستور معادل huggingface-cli login است. توکن را در کد یا مخزن Git قرار ندهید؛ می‌توانید آن را با متغیر محیطی HF_TOKEN هم تعیین کنید.

گام ۳: دانلود مدل

مدل‌ها به‌طور خودکار در اولین اجرا دانلود می‌شوند، اما دانلود جداگانه کنترل بیشتری می‌دهد:

hf download Qwen/Qwen2.5-7B-Instruct

مدل‌ها در ~/.cache/huggingface/hub ذخیره می‌شوند. اگر دیسک اصلی کوچک است، با متغیر HF_HOME مسیر را به دیسک بزرگ‌تر منتقل کنید. اگر دانلود قطع شد، اجرای دوباره دستور، دانلود را از همان نقطه ادامه می‌دهد. در صورت اختلال در دسترسی به Hugging Face از برخی شبکه‌ها، می‌توانید مدل را روی سرور دیگری دانلود و پوشه آن را منتقل کنید.

گام ۴: اجرای مدل زبانی با Transformers

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "Qwen/Qwen2.5-7B-Instruct"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

messages = [
    {"role": "system", "content": "به زبان فارسی و دقیق پاسخ بده."},
    {"role": "user", "content": "تفاوت CPU و GPU در پردازش هوش مصنوعی را در دو پاراگراف توضیح بده."},
]
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt"
).to(model.device)

outputs = model.generate(inputs, max_new_tokens=512, do_sample=True, temperature=0.7)
print(tokenizer.decode(outputs[0][inputs.shape[-1]:], skip_special_tokens=True))

نکات این کد:

• apply_chat_template پیام‌ها را در قالب گفتگوی مخصوص همان مدل قرار می‌دهد. بدون آن، مدل‌های Instruct پاسخ ضعیف‌تری می‌دهند.
• torch.bfloat16 حافظه را نسبت به FP32 نصف می‌کند و روی کارت‌های نسل Ampere و جدیدتر پشتیبانی سخت‌افزاری دارد.
• device_map="auto" مدل را روی GPU، و اگر چند کارت دارید بین آن‌ها، توزیع می‌کند.
• فقط توکن‌های جدید چاپ می‌شوند، نه پرامپت ورودی.

بهینه‌سازی حافظه

اگر مدل در VRAM جا نمی‌شود، با bitsandbytes آن را هنگام بارگذاری به ۴ بیت کوانتایز کنید:

from transformers import BitsAndBytesConfig

quant = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
)
model = AutoModelForCausalLM.from_pretrained(model_id, quantization_config=quant, device_map="auto")

این روش حافظه وزن‌ها را حدود ۷۰ درصد کاهش می‌دهد. برای سرویس‌دهی سریع‌تر، نسخه‌های از پیش کوانتایزشده AWQ یا GPTQ همان مدل در Hugging Face معمولاً گزینه بهتری هستند. مقایسه فرمت‌ها در Quantization چیست.

توجه: اگر VRAM کافی نباشد، device_map="auto" بخشی از لایه‌ها را روی RAM سیستم می‌گذارد. مدل اجرا می‌شود، اما بسیار کند. با print(model.hf_device_map) بررسی کنید همه لایه‌ها روی GPU هستند.

افزایش سرعت

• SDPA و FlashAttention: Transformers به‌طور پیش‌فرض از پیاده‌سازی بهینه Attention در PyTorch استفاده می‌کند. نصب بسته flash-attn و تعیین attn_implementation="flash_attention_2" روی کارت‌های Ampere و جدیدتر، به‌خصوص در متن‌های طولانی، سرعت را بیشتر می‌کند.
• Batch: اگر چند ورودی دارید، آن‌ها را با هم پردازش کنید تا GPU بهتر استفاده شود.
• موتور سرویس‌دهی: کتابخانه Transformers برای آزمایش و پژوهش عالی است، اما برای سرویس‌دهی به کاربران، موتورهایی مثل vLLM چند برابر سریع‌ترند و همان مدل‌های Hugging Face را مستقیماً اجرا می‌کنند.

مدل‌های غیرمتنی

کتابخانه pipeline اجرای بسیاری از وظایف دیگر را ساده می‌کند. مثلاً تبدیل گفتار فارسی به متن با Whisper:

from transformers import pipeline

asr = pipeline("automatic-speech-recognition", model="openai/whisper-large-v3",
               torch_dtype=torch.float16, device=0)
print(asr("meeting.mp3", generate_kwargs={"language": "persian"})["text"])

برای تولید تصویر از کتابخانه diffusers و برای Embedding متن (جستجوی معنایی) از sentence-transformers استفاده کنید.

از آزمایش تا محیط عملیاتی

1. مدل را در Transformers آزمایش کنید و کیفیت آن را روی داده‌های واقعی بسنجید.
2. برای سرویس‌دهی، همان مدل را با vLLM و API سازگار با OpenAI اجرا کنید.
3. API را پشت Nginx با HTTPS و کلید API قرار دهید؛ روش آن در ساخت OpenAI-Compatible API امن.
4. اگر به مدیریت ساده‌تر نیاز دارید، نسخه GGUF مدل را با Ollama اجرا کنید؛ مقایسه در Ollama یا vLLM.

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