آموزش وارد کردن مدل GGUF به Ollama
با استفاده از Modelfile مدلهای GGUF را به Ollama اضافه کنید. این راهنما نحوه رفع مشکل نمایش کاراکترهای نامفهوم ناشی از عدم تطابق Chat Template را به صورت گامبهگام توضیح میدهد.
دو روش برای وارد کردن مدل GGUF به Ollama
دو روش برای وارد کردن مدل GGUF به Ollama وجود دارد و انتخاب روش مناسب به محل فعلی فایل بستگی دارد. اگر مدل در مخزن Hugging Face قرار دارد، یک دستور ollama run آن را دریافت و اجرا میکند، بدون اینکه نیازی به Modelfile باشد. اگر فایل .gguf از قبل روی دیسک سرور شما موجود است، یک Modelfile دو خطی بنویسید و ollama create را اجرا کنید.
هر دو مسیر به یک نتیجه ختم میشوند: یک مدل نامگذاریشده در کتابخانه محلی Ollama که ollama run و API مربوط به Ollama میتوانند آن را سرویسدهی کنند. از روش اول زمانی استفاده کنید که شخص دیگری فایل را منتشر کرده است. از روش دوم زمانی استفاده کنید که خودتان مدل را کوانتیزه کردهاید، فایل از طریق scp یا rsync به دست شما رسیده است، یا دستگاه امکان دسترسی به Hugging Face را ندارد.
فایل GGUF یک باینری واحد است که وزنها، توکنایزر و متادیتای مدل را در کنار هم نگه میدارد. این فرمتی است که llama.cpp میخواند و از آنجایی که Ollama بر پایه llama.cpp ساخته شده، تقریباً برای هر مدل متنبازی یک نسخه تبدیلشده به GGUF توسط جامعه کاربری وجود دارد. Ollama پوشهای از وزنهای .safetensors را مستقیماً بارگذاری نمیکند، بنابراین مرحله تبدیل به همین دلیل وجود دارد.
تمام موارد زیر فرض میکنند که Ollama از قبل نصب شده و سرویس آن در حال اجرا است. اگر اینطور نیست، با نصب Ollama روی VPS شروع کنید و سپس به اینجا بازگردید. ابتدا ollama list را اجرا کنید. اگر به جای خطای اتصال، جدولی (حتی خالی) برگرداند، یعنی سرور فعال است و بقیه این راهنما کار خواهد کرد.
روش اول: اجرای یک GGUF از Hugging Face بدون Modelfile
Ollama میتواند یک فایل GGUF را مستقیماً از مخزن Hugging Face دریافت کند. دستور مورد نظر، مسیر مخزن با پیشوند hf.co/ است:
ollama run hf.co/{username}/{repository}هر دو عبارت hf.co و huggingface.co به عنوان نام دامنه کار میکنند. یک مثال واقعی از مستندات Hugging Face:
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUFاجرای اول فایل را دانلود میکند، بنابراین prompt چت تا پایان دانلود ظاهر نمیشود. پس از آن، مدل در کتابخانه محلی شما قرار میگیرد و سریع اجرا میشود. یک ترمینال دوم باز کنید و ollama list را اجرا کنید تا نامی که مدل با آن ذخیره شده است را ببینید. آن نام، کل رشته hf.co/... به همراه تگ آن است که تایپ کردنش هر بار طولانی است. یک نام مستعار کوتاه برای آن انتخاب کنید:
ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llamaاین روش فقط روی مخازنی کار میکند که واقعاً حاوی فایلهای GGUF هستند. مخزنی که فقط وزنهای .safetensors را منتشر میکند، چیزی برای دریافت توسط Ollama ندارد و شما باید مرحله تبدیل که در ادامه توضیح داده شده است را انجام دهید.
Ollama کدام کوانتیزاسیون را انتخاب میکند؟
مستندات Ollama در Hugging Face که در تاریخ 25 August 2026 مطالعه شد، در مورد پیشفرض صریح است: «بهطور پیشفرض، طرح کوانتیزاسیون Q4_K_M در صورت وجود در مخزن مدل استفاده میشود. اگر موجود نباشد، ما بهطور پیشفرض یکی از انواع کوانت معقول موجود در مخزن را انتخاب میکنیم.» بنابراین مخزنی که ده نوع کوانت منتشر میکند، Q4_K_M را به شما میدهد و مخزنی که فاقد Q4_K_M باشد، انتخابی را به شما میدهد که Ollama از طرف شما انجام داده است. پیش از تکیه بر آن صفحه، دوباره آن را مطالعه کنید، زیرا پیشفرضها تغییر میکنند.
با افزودن کوانت مورد نظر به عنوان یک تگ، آن را درخواست کنید:
ollama run hf.co/{username}/{repository}:{quantization}ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.ggufنام کوانتیزاسیون به بزرگی و کوچکی حروف حساس نیست، بنابراین :iq3_m و :IQ3_M یک معنی دارند. شما همچنین میتوانید نام دقیق فایل را به عنوان تگ وارد کنید که در صورت مبهم بودن نامهای کوتاه در یک مخزن، روشی ایمن است. تگ باید نام فایلی باشد که در آن مخزن وجود دارد، بنابراین تب Files and versions را باز کنید و پیش از تایپ کردن، نامهای واقعی فایلها را بخوانید. اینکه کدام کوانت را میخواهید، پرسشی در مورد حافظه و کیفیت است و تفاوت بین Q4، Q8 و FP16 این مبادله را بهدرستی پوشش میدهد.
مسیر دوم: وارد کردن یک فایل .gguf از دیسک خودتان
هنگامی که فایل از قبل روی سرور موجود است، به یک Modelfile نیاز دارید. این فایل میتواند تنها یک خط باشد. یک دایرکتوری بسازید، Modelfile را در آن قرار دهید و FROM را به فایل مورد نظر ارجاع دهید:
mkdir -p ~/models/my-model
cd ~/models/my-modelFROM /home/you/models/my-model-Q4_K_M.ggufآن را با نام Modelfile ذخیره کنید و سپس مدل را بسازید:
ollama create my-modelollama create بهصورت پیشفرض فایلی به نام Modelfile را در دایرکتوری جاری میخواند. زمانی که فایل شما نام دیگری دارد یا در جای دیگری قرار گرفته است، از -f استفاده کنید، همانطور که در ollama create my-model -f /home/you/models/my-model/Modelfile آمده است. برای مشاهده این فلگ و مقدار پیشفرض آن در build خود، ollama create --help را اجرا کنید. مسیر در FROM میتواند مطلق باشد یا نسبت به Modelfile سنجیده شود، بنابراین اگر هر دو در یک دایرکتوری باشند، FROM ./my-model-Q4_K_M.gguf کار میکند. استفاده از مسیر مطلق، ابهام را بهطور کامل برطرف میکند.
پیش از اعتماد به نتیجه، آن را بررسی کنید:
ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."ollama list اکنون باید شامل my-model باشد. ollama show my-model معماری، تعداد پارامترها، طول کانتکست و کوانتیزاسیونی که Ollama از متادیتای خودِ فایل خوانده است را چاپ میکند. بهجای اعتماد به نام فایل، این مقادیر را بخوانید، زیرا نام فایل رشتهای است که توسط یک شخص بهصورت دستی تایپ شده است. اگر مدل به prompt آزمایشی شما با زبان عادی پاسخ داد و سپس متوقف شد، عملیات وارد کردن موفقیتآمیز بوده است. اگر اینطور نیست، به بخش قالب (template) در ادامه بروید، زیرا تقریباً همیشه علت مشکل همین است.
یک نکته درباره فضای دیسک: ollama create فایل GGUF را بهجای ارجاع به محل اصلی، در مخزن مدلهای Ollama کپی میکند. وزنهای مدل تا زمانی که فایل اصلی را حذف نکنید، دو بار روی دیسک اشغال فضا میکنند. پس از اینکه ollama run my-model بهدرستی کار کرد، فایل منبع را حذف کنید یا آن را در جایی نگه دارید که هزینه فضای ذخیرهسازی دوبرابر نپردازید. محل نگهداری مدلها توسط Ollama روی دیسک ساختار آن و نحوه جابهجاییاش را توضیح میدهد.
چه زمانی --quantize اعمال میشود و چه زمانی خیر
ollama create دارای یک فلگ --quantize است و تنها برای یک مورد کاربرد دارد: مدل منبع در فرمت FP16 یا FP32 باشد که به معنای وزنهای با دقت کامل (full precision) است. مستندات وارد کردن Ollama، مقدار q8_0 بهعلاوه واریانتهای k-means یعنی q4_K_S و q4_K_M را بهعنوان مقاصد پشتیبانیشده فهرست میکند.
ollama create --quantize q4_K_M my-modelاین فلگ را برای فایلی که از قبل کوانتیزه شده است، استفاده نکنید. یک .gguf که در نامش Q4_K_M یا Q5_K_S دارد، قبلاً این مرحله را پشت سر گذاشته است و فلگ مذکور کاری برای انجام دادن ندارد. کوانتیزاسیون یک تبدیل یکطرفه از دقت بالا به پایین است، بنابراین مسیری از Q4 به Q8 وجود ندارد. اگر منبع شما یک مخزن Hugging Face از فایلهای .safetensors است، ابتدا آن را با convert_hf_to_gguf.py از مخزن llama.cpp تبدیل کنید (که ابزار پیشنهادی مستندات Ollama است) و سپس فایل GGUF خروجی آن اسکریپت را وارد کنید. ارتباط Ollama و llama.cpp توضیح میدهد که چرا اسکریپت تبدیل متعلق به پروژه دیگری است.
چرا یک فایل GGUF واردشده، خروجی نامفهوم میدهد یا متوقف نمیشود؟
این همان شکستی است که اکثر آموزشهای واردسازی (import) از آن میگذرند و دقیقاً همان مشکلی است که با آن مواجه خواهید شد. علائم آن شبیه به خرابی مدل است. توکنهای کنترلی بهصورت متن قابلمشاهده در پاسخ ظاهر میشوند، رشتههایی مانند <|im_start|>assistant یا <|end|>. مدل پاسخ میدهد، سپس یک پرسش کاربری جدید مینویسد و به آن هم پاسخ میدهد. تولید متن تا زمانی که Ctrl+C را فشار ندهید، ادامه مییابد.
مدل سالم است. قالب چت (chat template) اشتباه است. قالب چت پوششی است که پیام شما را به همان توالی توکنی تبدیل میکند که مدل با آن آموزش دیده است، با نشانگرهای خاص خود برای مشخص کردن پایان پرامپت سیستم و شروع نوبت کاربر. Ollama یکی را برای شما انتخاب میکند: مستندات میگویند یک قالب «بهطور خودکار از لیستی از قالبهای پرکاربرد انتخاب خواهد شد»، که بر اساس متادیتای داخلی tokenizer.chat_template ذخیرهشده در فایل GGUF است. وقتی آن متادیتا موجود نباشد یا با هیچکدام از موارد لیست مطابقت نداشته باشد، یک قالب عمومی دریافت میکنید. در نتیجه، مدل پرامپتی را میبیند که با هیچچیز در آموزشهایش شباهت ندارد، بنابراین هرگز به نشانگر پایاننوبتی که برای توقف روی آن آموزش دیده است، نمیرسد.
آنچه Ollama واقعاً انتخاب کرده است را چاپ کنید:
ollama show --template my-model
ollama show --modelfile my-modelیک قالب خالی یا آشکارا عمومی، این موضوع را تأیید میکند. قالب را خودتان در Modelfile بنویسید:
FROM /home/you/models/my-model-Q4_K_M.gguf
TEMPLATE """{{ if .System }}<|system|>
{{ .System }}<|end|>
{{ end }}{{ if .Prompt }}<|user|>
{{ .Prompt }}<|end|>
{{ end }}<|assistant|>
{{ .Response }}<|end|>"""
PARAMETER stop "<|end|>"با استفاده از ollama create my-model بازسازی کنید و همان پرامپت تست را دوباره ارسال کنید. پارامتر stop شبکه ایمنی شماست: این پارامتر به Ollama میگوید که وقتی آن رشته ظاهر شد، تولید متن را قطع کند، که حتی در حین تنظیم خودِ قالب، علامت «هرگز متوقف نمیشود» را از بین میبرد. اگر پاسخ همچنان ادامه یافت زیرا هیچکدام از نشانگرهایی که نام بردید ظاهر نشد، یک سقف برای num_predict آن را در تعداد توکن مشخصی، صرفنظر از آنچه قالب تولید میکند، قطع میکند.
قالب باید یک Go template باشد، نه یک Jinja template. مستندات Hugging Face مستقیماً به این موضوع اشاره دارد و اهمیت آن به این دلیل است که فیلد tokenizer.chat_template در مخزن اصلی مدل، حاوی Jinja است. کپی کردن بدون تغییر آن کار نمیکند. نحو (syntax) در Ollama سه متغیر دارد: {{ .System }} برای پرامپت سیستم، {{ .Prompt }} برای پیام کاربر، و {{ .Response }} برای پاسخ مدل. نشانگرهای نوبت واقعی مدل را در کارت مدل یا tokenizer_config.json آن پیدا کنید، سپس آنها را بهصورت دستی به آن نحو Go بازنویسی کنید.
یک میانبر، بخش بزرگی از این کار را ذخیره میکند. بسیاری از مدلها از فرمت پرامپت مشترکی استفاده میکنند، بنابراین اگر مدل دیگری در کتابخانه شما از همان فرمت استفاده میکند، دستور ollama show --template را روی آن اجرا کنید و آنچه چاپ میشود را کپی کنید.
فایلهای template، system و params در مخزن Hugging Face
مسیر Hugging Face همان کنترلهایی را ارائه میدهد که فایلهای موجود در مخزن فراهم میکنند، نه دستورالعملهای داخل Modelfile. اگر مالک مخزن هستید یا کوانت (quant) خود را منتشر میکنید، آنها را در آنجا اضافه کنید تا هر ollama run hf.co/... آنها را دریافت کند.
- فایلی با نام
templateشامل قالب Go است. همان قانون برقرار است: Go، نه Jinja. - فایلی با نام
systemشامل پرامپت سیستم (system prompt) است. - فایلی با نام
paramsشامل پارامترهای نمونهبرداری (sampling parameters) است و باید حتماً با فرمت JSON باشد.
یک فایل params حداقلی:
{
"stop": ["<|end|>"],
"temperature": 0.7
}زمانی که مالک مخزن نیستید، نمیتوانید این فایلها را اضافه کنید. مدل را یک بار Pull کنید، سپس ollama show --modelfile hf.co/... را اجرا کنید تا آنچه به شما داده شده است استخراج شود و آن خروجی را به عنوان یک Modelfile ذخیره کنید. خط FROM آن به blobای اشاره میکند که Ollama قبلاً دانلود کرده است، بنابراین شما خطوط TEMPLATE و PARAMETER را ویرایش کرده و ollama create را اجرا میکنید تا یک نسخه محلی ثابت بدون دانلود مجدد بسازید. این روش استاندارد برای اصلاح کوانتهای معیوب دیگران است.
نحوه وارد کردن یک مخزن خصوصی GGUF
یک مخزن خصوصی به کلید SSH مربوط به Ollama در حساب Hugging Face شما نیاز دارد. روش مستند برای این مسیر، بهجای استفاده از API token، از یک کلید SSH استفاده میکند؛ بنابراین توکنی که در حال حاضر دارید، دسترسی به آن را فراهم نمیکند.
کلید عمومی را چاپ کنید. در سرور لینوکسی که Ollama با اسکریپت رسمی روی آن نصب شده است، سرویس با کاربر ollama اجرا میشود، بنابراین کلید در دایرکتوری home همان کاربر قرار دارد:
sudo cat /usr/share/ollama/.ollama/id_ed25519.pubاگر ollama serve را شخصاً با حساب کاربری خود اجرا میکنید، مسیر آن بهجای آن ~/.ollama/id_ed25519.pub است. کل خط را کپی کنید، تنظیمات حساب Hugging Face خود را در https://huggingface.co/settings/keys باز کنید و آن را به عنوان یک کلید SSH جدید اضافه کنید. پس از آن، دستور معمول برای مخازن خصوصی شما کار خواهد کرد:
ollama run hf.co/{username}/{repository}اگر پس از افزودن کلید، عملیات pull همچنان با خطا مواجه شد، احتمالاً فایل اشتباهی را چاپ کردهاید. سرور عملیات دانلود را انجام میدهد و کلید مخصوص به خود را ارائه میکند؛ سروری که توسط systemd شروع شده باشد، هرگز فایل ~/.ollama کاربر شما را نمیخواند، بنابراین کلیدی که در دایرکتوری home شما قرار دارد، همان کلیدی نیست که Hugging Face مشاهده میکند.
آیا مدل روی VPS شما جا میشود؟
عددی که این موضوع را تعیین میکند، حجم فایل روی دیسک بهعلاوه حافظه مورد نیاز برای context window است. وزنهای مدل تقریباً به همان اندازهای که در فایل اشغال کردهاند در حافظه بارگذاری میشوند و تخصیص حافظه برای context نیز به آن اضافه میشود که با افزایش تعداد توکنهای مجاز، رشد میکند. دستور ollama list را اجرا کنید تا حجم ثبتشده توسط Ollama برای مدل را بخوانید، آن را با free -h روی سرور مقایسه کنید و مقداری فضای خالی برای سیستمعامل و سایر سرویسهای در حال اجرا در نظر بگیرید. اگر ترجیح میدهید این محاسبات را روی یک مدل واقعی مشاهده کنید، اجرای Nemotron 3.5 Lightning روی VPS تگ دقیق برای دریافت مدل، رم مورد نیاز و اینکه آیا یک سرور بدون GPU پاسخگو هست یا خیر را مشخص میکند.
بخش context همان چیزی است که معمولاً فراموش میشود. مدلی که با پنجره پیشفرض بارگذاری میشود، ممکن است پس از افزایش num_ctx با شکست مواجه شود، زیرا میزان تخصیص حافظه با پنجرهای که درخواست کردهاید مقیاس میشود. تنظیم num_ctx و هزینه آن در حافظه محاسبات مربوط به اندازهگیری را توضیح میدهد. وقتی مجموع حافظه بیش از حد زیاد باشد، راهحل معمول استفاده از یک quant کوچکتر از همان مدل است؛ موضوعی که در مقایسه Q4 در برابر Q8 بررسی شده است.
شکست در این حالت کاملاً مشهود است. در یک VPS بدون GPU، قابلیت out of memory killer در هسته سیستمعامل، پردازش را متوقف میکند و journalctl -u ollama -n 50 به همراه dmesg این توقف را نشان میدهند. در سروری که دارای GPU است، ollama ps ستونی با نام PROCESSOR چاپ میکند که به شما میگوید آیا مدل بارگذاریشده در حافظه GPU قرار گرفته، در حافظه سیستم است یا بین هر دو تقسیم شده است. مدلی که به حافظه سیستم سرریز شده باشد همچنان پاسخ میدهد، اما بهکندی. اندازهگیری توکن بر ثانیه مفهوم «کندی» را به عددی تبدیل میکند که میتوانید بین quantهای مختلف مقایسه کنید.
بررسی آنچه وارد کردهاید
پس از هر بار وارد کردن (import)، این چهار دستور را به همین ترتیب اجرا کنید:
ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."دستور ollama list وجود مدل را تأیید کرده و اندازهای که Ollama ثبت کرده است را نمایش میدهد. دستور ollama show تأیید میکند که Ollama متادیتای مورد نیاز خود را از فایل GGUF استخراج کرده است. دستور ollama show --modelfile مشخص میکند که مدل واقعاً از چه قالب (template) و پارامترهایی استفاده خواهد کرد؛ این همان بررسی است که پیش از مواجهه کاربران شما با خروجیهای نامعتبر، خطاهای احتمالی را شناسایی میکند. پرامپت آزمایشی کل زنجیره را تست میکند، زیرا مدلی که قالب آن دچار مشکل باشد، حتی در کوتاهترین درخواستها نیز شکست میخورد. هنگامی که پاسخ این پرامپت بدون مشکل دریافت شد، نامی که به مدل دادهاید همان نامی است که باید به هر ابزار دیگری که با API مدل Ollama در ارتباط است معرفی کنید، از جمله یک عامل برنامهنویسی که به سرور شما متصل است. برای حذف یک واردسازی ناموفق از ollama rm my-model استفاده کنید و سپس دوباره آن را بسازید. این دستور نسخه کپیشده در Ollama را حذف میکند و فایل منبع شما در .gguf دستنخورده باقی میماند.
FAQ
آیا میتوانم یک فایل GGUF را بدون نوشتن Modelfile به Ollama وارد کنم؟
بله، زمانی که فایل در یک مخزن Hugging Face قرار دارد. ollama run hf.co/{username}/{repository} آن را مستقیماً دریافت و اجرا میکند و ollama run hf.co/{username}/{repository}:{quantization} یک کوانتایز (quant) خاص را انتخاب میکند. Modelfile تنها برای .gguf که از قبل روی دیسک شما قرار دارد مورد نیاز است و در آن صورت میتواند تنها شامل یک خط FROM /path/to/file.gguf و به دنبال آن ollama create my-model باشد.
وقتی کوانتایز خاصی را مشخص نمیکنم، Ollama کدام نسخه را دانلود میکند؟
مستندات Hugging Face که در تاریخ 25 اوت 2026 مطالعه شد، بیان میکند که اگر آن کوانتایز در مخزن موجود باشد، از Q4_K_M استفاده میشود و در غیر این صورت، Ollama یک نوع کوانتایز معقول موجود در مخزن را انتخاب میکند. برای کنترل این موضوع، تگی مانند :Q8_0 را اضافه کنید. با استفاده از ollama show <model> تأیید کنید که دقیقاً چه چیزی دریافت کردهاید؛ این دستور کوانتایز را از متادیتای فایل استخراج میکند، نه از نام آن.
چرا مدل واردشدهٔ من تکرار میشود یا تولید متن را متوقف نمیکند؟
قالب چت (chat template) با مدل مطابقت ندارد. Ollama بهطور خودکار یک قالب را از متادیتای tokenizer.chat_template داخل GGUF انتخاب میکند و زمانی که آن متادیتا موجود نباشد یا شناسایی نشود، یک قالب عمومی (generic wrapper) دریافت میکنید؛ بنابراین مدل هرگز نشانگر پایان نوبت (end-of-turn marker) که برای آن آموزش دیده است را نمیبیند. قالب فعلی را با ollama show --template <model> چاپ کنید، سپس یک بلوک TEMPLATE و یک خط PARAMETER stop به Modelfile اضافه کرده و دوباره ollama create را اجرا کنید. آن را به عنوان یک Go template بنویسید. قالب Jinja از مخزن اصلی کار نخواهد کرد.
آیا باید از --quantize روی فایل GGUF که دانلود کردهام استفاده کنم؟
خیر. --quantize یک منبع FP16 یا FP32 را در طول ollama create تبدیل میکند و فایلی که نام آن از قبل دارای کوانتایزی مانند Q4_K_M است، قبلاً تبدیل شده است. دقت (precision) با کوانتایز مجدد قابل بازیابی نیست و راهی برای بازگشت به عقب وجود ندارد. تنها زمانی از این پرچم استفاده کنید که خودتان فایلهای safetensors را به یک GGUF با دقت کامل تبدیل کردهاید و اکنون نسخه کوچکتری میخواهید.
چگونه یک مخزن GGUF خصوصی را pull کنم؟
کلید عمومی SSH مربوط به Ollama را به حساب کاربری Hugging Face خود اضافه کنید. آن را با sudo cat /usr/share/ollama/.ollama/id_ed25519.pub در یک نصب استاندارد لینوکس، یا از ~/.ollama/id_ed25519.pub زمانی که سرور را با کاربر خود اجرا میکنید چاپ کنید، سپس آن را در صفحه تنظیمات کلید SSH حساب خود اضافه کنید. پس از آن، ollama run hf.co/{username}/{repository} روی مخازن خصوصی خودتان و مخازنی که در سازمانی متعلق به آن هستید، کار میکند.