محدود کردن تعداد توکن خروجی در Ollama با num_predict
با تنظیم num_predict در Ollama تعداد توکنهای تولیدی را کنترل کنید. این راهنما اولویت تنظیمات در سه لایه مختلف و نحوه بررسی done_reason برای تشخیص پایان پاسخ را توضیح میدهد.
عملکرد num_predict در Ollama
num_predict گزینهای در Ollama است که تعداد توکنهایی که یک مدل میتواند در هر پاسخ تولید کند را محدود میکند. این گزینه فقط توکنهای خروجی را میشمارد، بنابراین prompt هرگز جزو این محدودیت محاسبه نمیشود. هنگامی که مدل به این سقف برسد، تولید متن در همان نقطه متوقف میشود (گاهی در میان یک کلمه) و پاسخ با مقدار length برای فیلد done_reason بازگردانده میشود.
این تمام عملکرد این قابلیت است. دشواری کار در اینجاست که Ollama سه جای مختلف برای تنظیم این مقدار در اختیار شما میگذارد و تنظیمی که به درخواست نزدیکتر باشد، اولویت دارد. تقریباً تمام گزارشهای مبنی بر «کار نکردن num_predict» ناشی از این است که یک لایه بهطور بیصدا لایه دیگر را بازنویسی میکند.
پارامتر num_predict همان num_ctx نیست
این دو گزینه بیش از هر جفت پارامتر دیگری در Ollama باعث سردرگمی میشوند و این اشتباه، زمان زیادی را برای عیبیابی هدر میدهد.
num_ctx مشخص میکند که مدل چه مقدار میتواند بخواند. این پارامتر اندازه پنجره زمینه (context window) است که شامل پرامپت و تمام محتوای تولیدشده تا آن لحظه میشود. افزایش آن باعث مصرف حافظه بیشتر میشود، زیرا حافظه پنهان کلید/مقدار (key/value cache) که مدل برای آن توکنها نگه میدارد، با بزرگتر شدن پنجره رشد میکند. تعیین اندازه num_ctx برای سختافزار شما یک کار مجزا با حالتهای شکست خاص خود است.
num_predict مشخص میکند که مدل چه مقدار میتواند بنویسد. این یک قانون توقف است، نه یک تخصیص منابع. افزایش آن به جای RAM، زمان اجرای واقعی (wall-clock time) را افزایش میدهد و هیچ فضایی از قبل رزرو نمیشود.
این دو پارامتر در یک نقطه به هم میرسند. توکنهای تولیدشده همزمان با ساخته شدن، درون پنجره زمینه قرار میگیرند. در Ollama v0.40.11، قابلیت جابهجایی زمینه (context shift) برای اکثر مدلها بهصورت پیشفرض فعال است؛ بنابراین در صورت پر شدن پنجره، توکنهای قدیمیتر حذف میشوند و تولید متن ادامه مییابد. اگر این قابلیت غیرفعال باشد (به دلیل ارسال "shift": false در درخواست یا عدم پشتیبانی مدل از جابهجایی)، ممکن است پاسخدهی نه به دلیل رسیدن به سقف تعیینشده، بلکه به دلیل پر شدن پنجره متوقف شود. Ollama در هر دو حالت خطای length را گزارش میکند، بنابراین عددی که این دو را از هم متمایز میکند eval_count است که در ادامه به آن پرداخته شده است.
تنظیم یکباره با Modelfile
یک Modelfile مقدار موردنظر را در مدلی که میسازید، تثبیت میکند. فایل را بنویسید:
FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512سپس آن را build کرده و خروجی ساختهشده را بررسی کنید:
ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-cappedدستور ollama show --parameters برای هر پارامتر ذخیرهشده، یک خط شامل مقدار آن چاپ میکند. اگر num_predict در این خروجی وجود نداشته باشد، مدل هیچ محدودیت (cap) تثبیتشدهای ندارد و مقدار پیشفرض خود Ollama اعمال میشود. دستور ollama show --modelfile qwen3-capped کل تعریف مدل را چاپ میکند که سریعترین راه برای کپی کردن پارامترهایی است که یک مدل موجود از قبل با خود دارد. ایجاد یک مدل محدودشده به این روش تقریباً هیچ فضای دیسک اضافی اشغال نمیکند، زیرا ورودی جدید بهجای کپی کردن، از همان blobهای وزنی که مدل پایه قبلاً دانلود کرده استفاده مجدد میکند؛ دانستن اینکه Ollama آن blobها را کجا نگه میدارد پیش از پر شدن دیسک root در VPS اهمیت دارد.
این لایه برای مقداری که میخواهید همه فراخوانکنندهها (callers) از آن ارثبری کنند، مناسب است. اگر انتظار دارید این مقدار نهایی باشد، این لایه انتخاب اشتباهی است، زیرا چنین نیست.
تنظیم آن برای هر درخواست در شیء options
هر endpoint تولید محتوا یک شیء options دریافت میکند و num_predict درون آن قرار میگیرد:
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:8b",
"prompt": "Explain what a reverse proxy does.",
"stream": false,
"options": { "num_predict": 128 }
}'/api/chat از همان کلید options با همان معنا استفاده میکند. مقداری که در اینجا تعیین میشود، فقط برای همان فراخوانی اعمال میگردد و بر هیچ چیز دیگری تأثیر نمیگذارد. این همان لایهای است که ابزارهای شما از آن استفاده میکنند: یک رابط کاربری چت، یک اسکریپت، یک wrapper برای SDK یا یک عامل برنامهنویسی. همه آنها یک شیء options ارسال میکنند، فارغ از اینکه آیا کادری برای نمایش آن به شما نشان دهند یا خیر.
تنظیم آن برای یک نشست با پارامتر /set
در داخل ollama run، نشست تعاملی گزینهها را برای باقیماندهٔ همان نشست تنظیم میکند:
>>> /set parameter num_predict 256
>>> /show parameters/show parameters آنچه را که نشست با پیام بعدی شما ارسال خواهد کرد چاپ میکند، که سریعترین راه برای تأیید اعمال تغییرات است. این مقدار تا زمانی که /bye را تایپ کنید باقی میماند. برای حفظ آن، /save qwen3-capped نشست فعلی را به همراه پارامترها به عنوان یک مدل جدید ذخیره میکند. هیچچیزی که در اینجا /set میکنید به کلاینت دیگری نمیرسد.
کدام تنظیم اولویت دارد و چرا تنظیمات شما نادیده گرفته میشوند
ترتیب اولویت کوتاه است. گزینههایی که همراه با درخواست ارسال میشوند، بر همه چیز مقدم هستند. یک خط PARAMETER num_predict در Modelfile مدل، تنظیم جایگزینی است که در صورت نبود مقدار در درخواست، استفاده میشود. در صورت نبود هر دو، مقدار پیشفرض داخلی Ollama اعمال میگردد.
/set parameter یک قانون سوم نیست. نشست تعاملی یک کلاینت API است، بنابراین آنچه در آنجا تنظیم میکنید به عنوان options آن درخواست ارسال میشود، و دقیقاً به همین دلیل است که تنظیمات Modelfile را برای آن نشست بازنویسی میکند.
حال این موضوع خطایی را که با آن مواجه هستید توضیح میدهد. شما PARAMETER num_predict 512 را اضافه میکنید، مدل را بازسازی میکنید، اما پاسخها همچنان به هزاران توکن میرسند. تنظیمات شما موجود است و ollama show --parameters صحت آن را تأیید میکند. این تنظیم در هر درخواست بازنویسی میشود، زیرا کلاینت شیء options خاص خود را با عدد مخصوص خود ارسال میکند؛ عددی که احتمالاً ماهها پیش در صفحه تنظیمات وارد کردهاید و فراموش کردهاید. ollama show مدل ذخیرهشده را میخواند. این دستور نمیتواند آنچه را که از طریق HTTP ارسال میشود به شما نشان دهد.
سمت سرور را با یک دستور اثبات کنید. درخواستی بفرستید که پاسخ طولانی تولید کند، سقف را روی مقدار کمی اجبار کنید و دو فیلد را بخوانید:
curl -s http://localhost:11434/api/generate -d '{
"model": "qwen3-capped",
"prompt": "Describe the Linux boot process in detail.",
"stream": false,
"options": { "num_predict": 32 }
}' | jq '.done_reason, .eval_count'یک پاسخ مفصل بسیار فراتر از 32 توکن میرود، بنابراین انتظار "length" و 32 را داشته باشید. اگر jq نصب نیست، ابتدا آن را با sudo apt install -y jq نصب کنید. عدد 32 تضمینشده نیست، زیرا eval_count فقط تعداد توکنهای خروجی است که سرور واقعاً تولید کرده است. اگر مدل زودتر تمام شود، "stop" و تعداد کمتری دریافت میکنید و راهحل آن، پرامپتی است که درخواست محتوای بیشتری میکند. وقتی "length" و 32 را دریافت کردید، مقدار خودِ درخواست بر 512 ذخیرهشده در qwen3-capped غلبه کرده است، که نشان میدهد سرور به گزینههای ارسالی در هر درخواست احترام میگذارد. این به شما نمیگوید که اپلیکیشن شما چه چیزی ارسال میکند، بنابراین جستجو به سمت کلاینت منتقل میشود. برای مشاهده گزارش سرور از یک درخواست، آن را با OLLAMA_DEBUG=1 در محیط اجرا کنید و همزمان با برقراری ارتباط اپلیکیشن، journalctl -u ollama -f را مانیتور کنید.
مقادیر منفی و اعدادی که نباید کپی کنید
num_predict مقادیر منفی را نیز میپذیرد، اما این مقادیر به جای شمارش، نشانگرهای خاص (sentinel) هستند. یک مقدار منفی به معنای «محدودیت اعمال نکن و به تولید ادامه بده» است. مقدار منفی دیگری در گذشته به معنای «پر کردن باقیمانده context» بوده است. تا اکتبر 2026، مستندات Modelfile در Ollama مقدار پیشفرض را -1 یعنی تولید نامحدود ذکر کرده است و نسخههای قدیمیتر همان جدول، مقدار -2 را برای پر کردن context فهرست کرده بودند.
همه این موارد را وابسته به نسخه در نظر بگیرید، زیرا تغییر کردهاند. مستندات برای مدت طولانی مقدار پیشفرض را 128 ذکر میکردند تا اینکه این ورودی به -1 اصلاح شد؛ بنابراین بسیاری از راهنماها هنوز همان عدد قدیمی را تکرار میکنند. رفتار سیستم نیز تغییر کرده است. در Ollama v0.40.11 که نسخه فعلی در 25 اکتبر 2026 است، مدلهای GGUF به یک پردازش بالادستی llama-server سپرده میشوند که به یک بودجه محدود نیاز دارد؛ بنابراین هر مقدار منفی و هر سقفی بالاتر از ده برابر num_ctx، با ده برابر num_ctx جایگزین میشود. بنابراین «نامحدود» در اینجا به معنای 81,920 توکن برای مدل qwen3-capped ذکر شده در بالا است و -2 دیگر رفتاری متفاوت از -1 ندارد. مرجع پارامترهای Modelfile را برای نسخهای که واقعاً اجرا میکنید بخوانید و سپس رفتار آن را با بررسی eval_count در بالا تأیید کنید. مقداری که روی سیستم خودتان تأیید کردهاید، از هر مقداری که در هر جای دیگری (از جمله این پست) میخوانید، معتبرتر است.
چرا طول خروجی هزینه اصلی در یک VPS بدون GPU است
نرمافزار Ollama روی دستگاهی که کنترل آن را در دست دارید رایگان اجرا میشود، بنابراین تولید محلی هرگز مشمول هزینه بر اساس مصرف نیست و پاسخهای طولانی تنها با صرف زمان پرداخت میشوند. فرآیند تولید دارای دو مرحله با سرعتهای بسیار متفاوت است. توکنهای پرامپت (Prompt tokens) بهصورت دستهای و تعداد زیاد در هر لحظه ارزیابی میشوند. توکنهای خروجی (Output tokens) یکییکی تولید میشوند و هر کدام نیازمند یک بار پردازش روی وزنهای مدل هستند. در یک VPS که فقط از CPU استفاده میکند، این پردازش توسط پهنای باند حافظه محدود میشود؛ بنابراین هزینه تولید هر توکن خروجی بسیار بیشتر از هزینه پردازش یک توکن پرامپت است. از آنجا که این مرحله باید تمام وزنهای مورد استفاده توسط توکن را بخواند (در مدلهای متراکم تمام وزنها، و در مدلهای ترکیبی از متخصصان مانند Nemotron 3.5 Lightning که حدود 3B از 30B پارامتر خود را در هر توکن فعال میکند، فقط متخصصان مربوطه)، تعداد بایتهای اشغالشده توسط هر وزن، سقف نرخ توکن شما را تعیین میکند. به همین دلیل است که یک نسخه q4 سریعتر از همان مدل در حالت q8 یا fp16 رمزگشایی میشود.
اگر درخواست پاسخی بدون streaming کنید، اعداد دقیقاً مشخص خواهند بود:
"prompt_eval_count": 11,
"prompt_eval_duration": 13074791,
"eval_count": 18,
"eval_duration": 52479709مدتزمانها به نانوثانیه هستند. در این بلوک، که نمونه پاسخ منتشرشده در مستندات API نرمافزار Ollama تا اکتبر 2026 است (و نه اندازهگیری یک سرور خاص)، 11 توکن پرامپت حدود 0.013 ثانیه زمان بردند، در حالی که 18 توکن خروجی حدود 0.052 ثانیه طول کشیدند. این یعنی تقریباً 1.2 میلیثانیه برای هر توکن پرامپت در مقابل 2.9 میلیثانیه برای هر توکن خروجی؛ بنابراین حتی در یک پاسخ تکخطی، هزینه تولید هر توکن بیش از دو برابر هزینه خواندن هر توکن است و در پاسخهای طولانی، بخش خروجی است که زمان را پر میکند. نرخ تولید شما برابر است با eval_count تقسیم بر eval_duration که به ثانیه تبدیل شده است، و اندازهگیری توکن بر ثانیه روی سختافزار خودتان کاری است که پیش از هر تنظیم دیگری ارزش انجام دادن دارد. این نرخ به همان اندازه که به ماشین بستگی دارد، به مدل نیز وابسته است؛ بنابراین اگر پاسخهای طولانی هزینه اصلی هستند، مدلی که برای رمزگشایی سریع ساخته شده است، مانند Nemotron 3.5 Lightning روی یک VPS، بخشی از زمانی را که در غیر این صورت با محدودیت پایین هدر میرفت، بازمیگرداند.
محاسبات ریاضی بقیه کار را انجام میدهند. با سرعت 8 توکن بر ثانیه، یک پاسخ 2,000 توکنی ماشین را بیش از چهار دقیقه درگیر میکند و مدل هیچ اطلاعی ندارد که شما فقط یک پاراگراف میخواستید. یک مدل استدلالی بخشی از این بودجه را صرف فکر کردن پیش از نوشتن اولین کلمه درخواستی شما میکند و این تفکر نیز مانند هر چیز دیگری، توکن به توکن تولید میشود؛ بنابراین تلاش استدلالی که درخواست میکنید اهرم دیگری بر همان صورتحساب است. برخی مدلها نیز دچار حلقه میشوند و یک عبارت را تا زمانی که چیزی متوقفشان کند، تکرار میکنند. بدون وجود سقف، آن درخواست واحد یک هسته CPU را تا رسیدن به ده برابر num_ctx توکن مشغول نگه میدارد، زیرا تغییر متن (context shift) مانع از پایان یافتن پنجره کامل میشود. num_predict تنظیمی است که این مورد را محدود میکند و در یک VPS کوچک با Ollama که خودتان میزبانی میکنید، جایی که یک درخواست طولانی تمام منابع ماشین را اشغال میکند، اهمیت حیاتی دارد.
خروجی ناقص معمولاً به دلیل محدودیت است، نه خرابی مدل
علائم، شبیه به خرابی مدل به نظر میرسند. پاسخی که در میان جمله متوقف میشود. کدی با فرمت JSON که پارس نمیشود، چون براکت پایانی هرگز ارسال نشده است. واکنش غریزی، مقصر دانستن مدل یا کوانتایزیشن (quantisation) است. ابتدا پاسخ را بخوانید.
done_reason مستقیماً به پرسش پاسخ میدهد. stop یعنی تولید متن پیش از رسیدن به هر محدودیتی پایان یافته است؛ یا به این دلیل که مدل توکن پایان توالی (end-of-sequence) خود را صادر کرده یا خروجی با یکی از رشتههای موجود در گزینه stop شما مطابقت داشته است که پاسخ را در همان نقطه پایان میدهد. length یعنی تولید متن به دلیل تمام شدن فضا قطع شده است. هنگامی که length را مشاهده کردید، eval_count را با سقف (cap) خود مقایسه کنید: تطابق دقیق به این معنی است که num_predict آن را متوقف کرده است، و عدد کوچکتر به این معنی است که پنجره کانتکست (context window) ابتدا پر شده است، که این اتفاق فقط در صورت خاموش بودن context shift رخ میدهد.
هنگام استفاده از استریم (stream)، این فیلدها در آخرین تکه (chunk) میرسند، همان تکهای که حاوی "done": true است. بسیاری از کتابخانههای کلاینت آن تکه را دور میریزند و فقط متن را به کد شما تحویل میدهند؛ به همین دلیل است که همان نقص در داخل یک اپلیکیشن غیرقابل توضیح به نظر میرسد اما در curl کاملاً واضح است. اگر کتابخانهای آن را پنهان میکند، یک درخواست با curl بفرستید تا بفهمید سرور واقعاً چه چیزی گفته است.
یک نکته دیگر میتواند از هدر رفتن یک بعدازظهر جلوگیری کند. افزایش num_predict باعث نمیشود مدل بیشتر بنویسد. این کار فقط یک سقف را برمیدارد. اگر پاسخی در 200 توکن با done_reason از stop پایان یابد، یا مدل تصمیم گرفته که کار تمام شده است یا یکی از رشتههای stop شما مطابقت داشته است، و افزایش سقف هیچ تغییری ایجاد نمیکند. پاسخهای کوتاه با stop مشکل پرامپت یا stop-string هستند. پاسخهای کوتاه با length مشکل سقف (cap) هستند.
انتخاب یک مقدار
- برای چت تعاملی، آن را بدون محدودیت رها کنید و در صورت پاسخهای طولانی و خارج از کنترل، از Ctrl+C برای توقف استفاده کنید. در هر صورت شما در حال مشاهدهٔ صفحه هستید.
- برای هر فرآیند اسکریپتشده، حتماً محدودیت تعیین کنید. یک تولید متن بدون محدودیت در داخل یک حلقه، عاملی است که باعث میشود یک پردازش دستهای (batch job) که باید 10 دقیقه طول بکشد، تا صبح روز بعد همچنان در حال اجرا باقی بماند.
- برای خروجیهای ساختاریافته، سقف را بالاتر از بزرگترین سند معتبری که انتظار دارید تنظیم کنید، سپس
done_reasonازlengthرا به عنوان یک خطای جدی در نظر بگیرید و بهجای تلاش برای پارس کردن خروجی ناقص، دوباره تلاش کنید. - برای یک عامل برنامهنویسی (coding agent)، این مقدار باید در پیکربندی خودِ عامل قرار بگیرد، زیرا عامل در هر درخواست، گزینههای خاص خود را ارسال میکند. اشاره به یک عامل برنامهنویسی در Ollama توضیح میدهد که این تنظیمات کجا قرار دارند.
این سقف، توکنها را میشمارد، نه کلمات و نه کاراکترها؛ بنابراین آن را حدس نزنید. یک پاسخ نمونه بدون محدودیت تولید کنید، eval_count را بخوانید و سقف را با حاشیهٔ اطمینان بالاتر از آن تنظیم کنید. خانوادههای مدل به روشهای متفاوتی توکنبندی میکنند، بنابراین مقداری که برای یک مدل Llama مناسب است، ممکن است پاسخ مشابه را در یک مدل Qwen 3 روی همان VPS ناقص بگذارد.
FAQ
تفاوت بین num_ctx و num_predict در Ollama چیست؟
num_ctx اندازه پنجره کانتکست است و تعیین میکند مدل چقدر میتواند بخواند: پرامپت به علاوه هر چیزی که تاکنون تولید شده است. این پارامتر حافظه مصرف میکند، زیرا کش کلید/مقدار (key/value cache) با آن رشد میکند. num_predict تعیین میکند که مدل در هر پاسخ حداکثر چند توکن میتواند بنویسد. این پارامتر بیشتر از حافظه، زمان مصرف میکند و هیچ فضایی از پیش رزرو نمیشود. توکنهای تولیدشده در هر دو محاسبه میشوند، بنابراین اگر جابهجایی کانتکست (context shift) خاموش باشد، پاسخ ممکن است توسط هر یک از این دو محدود شود.
چرا تنظیمات num_predict من نادیده گرفته میشود؟
زیرا مقداری که با درخواست ارسال میشود، مقدار ذخیرهشده در مدل را بازنویسی میکند. اگر PARAMETER num_predict 512 را در یک Modelfile قرار دهید و سپس آن مدل را از طریق یک رابط کاربری چت یا یک ایجنت برنامهنویسی فراخوانی کنید، کلاینت شیء options خاص خود را ارسال میکند که مقدار آن اولویت دارد. ollama show --parameters همچنان مقدار شما را چاپ میکند، زیرا فقط مدل ذخیرهشده را میخواند و نمیتواند ببیند چه چیزی از طریق HTTP دریافت شده است. یک درخواست با curl و با استفاده از "options": {"num_predict": 32} و یک پرامپت که نیاز به پاسخ طولانی دارد ارسال کنید، سپس done_reason و eval_count را بخوانید. یک length با eval_count برابر با 32 نشان میدهد که مقدار ارسالی در درخواست، مقدار ذخیرهشده را بازنویسی کرده است؛ این تأیید میکند که سرور بهدرستی عمل میکند و مشکل در اپلیکیشن شماست. یک stop با تعداد کمتر، فقط به این معنی است که مدل زودتر کارش تمام شده است، بنابراین با پرامپتی که درخواست پاسخ طولانیتری دارد، دوباره امتحان کنید.
چگونه بفهمم خروجی من توسط num_predict قطع شده است؟
درخواست را با "stream": false ارسال کنید و done_reason را بخوانید. مقدار stop به این معنی است که مدل خودش کار را تمام کرده یا یکی از رشتههای stop شما آن را متوقف کرده است. مقدار length به این معنی است که فضای آن تمام شده است. سپس eval_count را با سقف تعیینشده خود مقایسه کنید: اگر دقیقاً برابر باشند، num_predict آن را متوقف کرده است و اگر eval_count کمتر باشد، پنجره کانتکست ابتدا پر شده است. هنگام استریم، هر دو فیلد در آخرین تکه (chunk) با "done": true ارسال میشوند که بسیاری از کتابخانههای کلاینت قبل از اینکه کد شما آنها را ببیند، حذفشان میکنند.
مقدار پیشفرض num_predict چقدر است؟
آن را از نصب خودتان بخوانید، نه از مقالات. تا اکتبر 2026، مرجع Modelfile در Ollama مقدار پیشفرض را -1 اعلام کرده است، به این معنی که تولید متن محدود نیست. این ورودی پس از یک دوره طولانی که 128 مستند شده بود، اصلاح شد. در Ollama v0.40.11، آن مقدار پیشفرض نامحدود، مانند هر مقدار منفی دیگری، در واقع در ده برابر num_ctx متوقف میشود. مقادیر منفی به عنوان نشانگر (sentinel) عمل میکنند نه به عنوان شمارنده، و نسخههای قدیمیتر همان جدول نیز -2 را برای پر کردن کانتکست باقیمانده ذکر کرده بودند. مرجع پارامترهای Modelfile را برای نسخه خود بررسی کنید و سپس آن را با ollama show --parameters و یک درخواست curl تأیید کنید.
آیا افزایش num_predict باعث میشود مدل پاسخهای طولانیتری بنویسد؟
خیر. این کار فقط سقف محدودیت را برمیدارد. اگر پاسخ با done_reason از stop تمام شود، یعنی مدل تصمیم گرفته که کار تمام شده است یا یکی از رشتههای stop شما مطابقت داشته است؛ در این حالت افزایش سقف تغییری ایجاد نمیکند. طول پاسخ در این شرایط به نحوه پرامپتنویسی بستگی دارد: ساختار خاص، تعداد بخشها یا سطح جزئیات مورد نظر خود را درخواست کنید. num_predict را فقط زمانی افزایش دهید که done_reason به صورت length بازگردانده شود.