اجرای مدل‌های GGUF به‌صورت محلی: Ollama، llama.cpp و vLLM

یک فایل .gguf دانلود کرده‌اید و نمی‌دانید چطور اجرایش کنید؟ سریع‌ترین مسیر: ollama run hf.co/<repo>:Q4_K_M — Ollama فایل GGUF را مستقیم از Hugging Face می‌کشد و سرو می‌کند. GGUF همان فرمت تک‌فایلی مدل است که llama.cpp معرفی کرد و حالا همه ابزارهای LLM محلی زبانش را می‌فهمند؛ یعنی همان فایل در Ollama، llama.cpp، LM Studio، Jan و (با چاشنی احتیاط) vLLM اجرا می‌شود. این راهنما هر اجراکننده را با دستورهای قابل کپی پوشش می‌دهد، می‌گوید چطور برای VRAM تان کوانت درست را انتخاب کنید و خطاهای بارگذاری‌ای را مرور می‌کند که واقعاً به آن‌ها می‌خورید.

فایل GGUF چیست؟

GGUF (GGML Universal File) یک فرمت ظرف برای مدل‌های زبانیِ کوانتیزه‌شده است. یک فایل وزن‌ها، توکنایزر و متادیتای مدل را دارد — دانلود دیگری در کار نیست، غار تنظیمات هم در میان نیست. وزن‌های داخلش کوانتیزه هستند: از اعداد اعشاری 16 بیتی به اعداد صحیح 4 بیتی (یا کمتر) فشرده شده‌اند؛ برای همین یک مدل 9 میلیاردی که با precision کامل حدود 18 گیگابایت می‌خواهد، به‌شکل فایل Q4 در حدود 5.5 گیگابایت جا می‌شود و روی یک کارت گرافیک گیمینگ یا حتی CPU اجرا می‌شود.

دو چیز درباره نام یک فایل GGUF مهم است:

1. مدل پایه — gemma-3-4b-it-GGUF یک Gemma 3 4B فاین‌تیون‌شده است که به GGUF صادر شده.
2. برچسب کوانت — Q4_K_M، Q8_0، IQ4_XS و رفقایشان می‌گویند وزن‌ها با چه شدتی فشرده شده‌اند. پایین‌تر درباره انتخابش می‌گویم.

آیا Ollama می‌تواند مدل‌های GGUF را اجرا کند؟

بله — GGUF فرمت بومی Ollama است و از 2024 می‌تواند مدل را مستقیم از Hugging Face بکشد، بدون اینکه شما حتی یک فایل را لمس کنید:

# Pull a GGUF quant directly from Hugging Face and chat with it
ollama run hf.co/bartowski/gemma-2-9b-it-GGUF:Q4_K_M

# The quant tag after the colon picks the file inside the repo
ollama run hf.co/ggml-org/gemma-3-4b-it-GGUF:Q8_0

خودتان یک فایل .gguf دانلود کرده‌اید؟ یک Modelfile به آن اشاره بدهید:

# Modelfile — one line is enough
FROM ./gemma-2-9b-it-Q4_K_M.gguf

ollama create gemma9b -f Modelfile
ollama run gemma9b

Ollama انتقال به GPU را خودش تصمیم می‌گیرد و روی پورت 11434 یک API سازگار با OpenAI می‌گذارد، پس هر ابزاری که آن زبان را حرف می‌زند می‌تواند از مدل استفاده کند. بهایش کنترل است: انتخاب نمی‌کنید چند لایه به GPU برود.

چگونه یک فایل GGUF را در llama.cpp اجرا کنیم؟

llama.cpp زادگاه GGUF است — آن فرمت برای همین پروژه ساخته شده — پس پشتیبانی اینجا عمیق‌ترین و تازه‌ترین است. باینری llama-server هم یک رابط چت می‌دهد هم endpoint سازگار با OpenAI:

# Download straight from Hugging Face (picks a matching GGUF for your machine)
llama-server -hf ggml-org/gemma-3-4b-it-GGUF --port 8080

# Or run a file you already have, with full GPU offload
llama-server -m ./gemma-2-9b-it-Q4_K_M.gguf -ngl 99 --port 8080

-ngl 99 تعداد 99 لایه را روی GPU می‌فرستد؛ آن را پایین‌تر از ظرفیت VRAM تان تنظیم کنید و باقی لایه‌ها روی CPU می‌مانند. همین پیچ انتقالِ جزئی، ابرقدرت llama.cpp است — یک مدل 9B با offload کردن 20 لایه از 48 روی کارت 6 گیگابایتی هم درست کار می‌کند، فقط کندتر. برای prompt تک‌ضربی به‌جای سرور، llama-server را با همان فلگ -m با llama-cli عوض کنید.

LM Studio همان موتور است پشت یک رابط گرافیکی دسکتاپ: فایل .gguf را در پوشه مدل‌هایش بیندازید (یا داخل خود برنامه در Hugging Face جست‌وجو کنید) و دکمه بارگذاری را بزنید. درباره خود انتخاب ابزار، مقایسه Ollama و LM Studio می‌گوید کدام را زیر مدل‌هایتان بگذارید.

کدام کوانتیزاسیون GGUF را دانلود کنیم؟

پاسخ پیش‌فرض: Q4_K_M. نقطه شیرین انجمن است — با فاصله یک تا دو درصد از کیفیتِ precision کامل، با تقریباً یک‌چهارم حجم. نردبان، از بزرگ به کوچک:

• Q8_0 — تقریباً بی‌اتلاف؛ اگر VRAM تان 8.5 بیت به ازای هر وزن را بدون اینکه متوجه شود می‌خورد، ازش استفاده کنید.
• Q6_K / Q5_K_M — یک پله کوچک‌تر، برای مدل‌های 30B به بالا همچنان عالی.
• Q4_K_M — پیش‌فرض. برای مدل‌های 7 تا 14B، اینجاست که کیفیت به ازای هر گیگابایت به اوج می‌رسد.
• IQ4_XS / Q3_K_M — برای ازدحام‌دادن یک مدل بزرگ روی کارت کوچک؛ افت کیفیت محسوس می‌شود.
• Q2_K و پایین‌تر — آخرین چاره؛ مدل وسط جمله شروع می‌کند به تباه شدن به ورمالیات.

قاعده سرانگشتی جا شدن: حجم فایل به گیگابایت به‌علاوه حدود 1 تا 2 گیگابایت سربار context باید در VRAM تان جا شود. یک فایل Q4_K_M با حجم 4.7 گیگابایت از مدل 9B روی کارت 8 گیگابایتی راحت است. مدل کوچک‌تر با کوانت بالاتر را به مدل بزرگ‌تر با کوانت افتضاح ترجیح دهید — یک 4B با Q8 معمولاً یک 9B با Q2 را می‌برد.

GGUF در مقابل Safetensors: به کدام فرمت نیاز دارید؟

Safetensors فرمت بایگانیِ کوانتیزه‌نشده است — وزن‌های full-precision برای آموزش، فاین‌تیون و ابزارهایی مثل transformers و ComfyUI. GGUF فرمت کوانتیزه و قابل اجرا برای inference روی سخت‌افزار خودتان است. نمی‌توانید یک GGUF را فاین‌تیون کنید و نمی‌توانید فایل safetensors را بدون تبدیل در Ollama یا llama.cpp اجرا کنید (کارِ اسکریپت convert_hf_to_gguf.py در llama.cpp دقیقاً همین تبدیل است). قاعده: آموزش یا پایپ‌لاین تصویر → safetensors؛ چت و سرو محلی → GGUF. اگر جست‌وجویتان «gguf vs safetensors» بوده، همین تقسیم کل جواب است.

کدام اجراکننده GGUF را استفاده کنید؟

اجراکننده	مناسب برای	نصب	انتقال به GPU	API سازگار با OpenAI
Ollama	سرویس نصب‌شده و بی‌دردسر	یک‌خطی با curl	خودکار	بله (:11434/v1)
llama.cpp	بیشترین کنترل، تازه‌ترین قابلیت‌ها	بیلد یا مدیریت بسته	پیچ دستی -ngl	بله (llama-server)
LM Studio	رابط گرافیکی، مرور مدل‌ها	دانلود اپ	خودکار	بله (سرور محلی)
vLLM	سرو‌دادن چندکاربره batch شده	pip install vllm	خودکار	بله (بومی)

اگر می‌خواهید در بوت بالا بیاید و از دید خارج شود Ollama را بردارید — من همین را روی homelab خودم دارم که مدل‌ها را به همه‌چیز روی شبکه سرو می‌کند. اگر قابلیتی را می‌خواهید همان روز عرضه (معماری‌های جدید اول آنجا فرود می‌آیند) یا کنترل حافظه در حد لایه، llama.cpp را بردارید. برای رابط گرافیکی، LM Studio. vLLM را فقط وقتی بردارید که یک مدل باید به هم‌زمان چند کاربر سرو بدهد — پشتیبانی GGUF اش کار می‌کند ولی در برابر فرمت‌های بومی‌اش درجه دو حساب می‌شود.

چرا مدل GGUF من بارگذاری نمی‌شود؟

چهار خطایی که بیشتر موارد را پوشش می‌دهند:

1. unknown model architecture — فایل GGUF معماری‌ای را استفاده می‌کند که runtime شما از آن قدیمی‌تر است (مدل‌های جدید MoE و بینایی مدام فرود می‌آیند). Ollama را به‌روز کنید یا llama.cpp را دوباره بیلد بزنید؛ راه‌حل دیگری وجود ندارد.
2. کمبود حافظه موقع بارگذاری — کوانت برای VRAM به‌علاوه context تان بزرگ است. یک پله پایین بروید (Q4_K_M → Q3_K_M)، -ngl را کم کنید، یا با -c 4096 context را کوچک کنید.
3. دانلود ناقص / خراب — بارگذاری GGUF با خطای magic-number یا متادیتا شکست می‌خورد. دوباره دانلود کنید و با SHA256 نشان‌داده‌شده در صفحه Hugging Face مقایسه کنید.
4. ollama run ./model.gguf قبول نمی‌کند — طبیعی است: run در Ollama نام مدل می‌گیرد نه مسیر فایل. از مسیر Modelfile که بالاتر نشان دادم استفاده کنید.

یک زاویه آخر که دانستنش می‌ارزد: endpoint محلی GGUF با ابزارهای کدنویسیِ ایجنت‌محور جفت خوبی می‌سازد — یک کلاینت سازگار با OpenAI را به آن اشاره بدهید و هزینه completionها فقط برق می‌شود. بهترین LLMهای محلی برای کدنویسی وقتی لوله‌کشی این راهنما درست شد، آزموده کدام مدل‌ها سزاوار آن جایگاه‌اند.

و وقتی بحث انتخاب runtime شد، مقایسه llama.cpp و Ollama را بخوانید — حاصل یک هفته استفاده سر‌به‌سر، و بده‌بستان‌ها همان چیزی نیست که READMEها القا می‌کنند.