اجرای سرور llama.cpp روی VPS با تنظیمات systemd
نحوه کامپایل llama.cpp از یک تگ خاص، میزبانی مدلهای GGUF با API سازگار با OpenAI و مدیریت سرویس با systemd برای محدود کردن مصرف رم روی سرورهای ابری را بیاموزید.
آنچه در حال ساخت آن هستید
اجرای سرور llama.cpp روی یک VPS به معنای استفاده از یک فایل باینری به نام llama-server است که یک فایل مدل GGUF را بارگذاری کرده و به درخواستهای HTTP در قالب یک API سازگار با OpenAI پاسخ میدهد. یک کلاینت سازگار را به http://127.0.0.1:8080/v1 متصل کنید و سپس ویژگیهایی که برنامه شما از آنها استفاده میکند را تست کنید: سازگاری در اینجا کامل نیست. نصب، نیمهٔ آسان کار است.
باقی کار مربوط به عملیات نگهداری است: تعیین نسخه (pin)، محدود کردن پورت به localhost، نوشتن یک unit برای systemd و تصمیمگیری دربارهٔ رفتار سیستم هنگام اتمام حافظه (OOM). این راهنما به همین موارد میپردازد. اگر هنوز بین دو گزینهٔ اصلی تصمیم نگرفتهاید، ابتدا تفاوتها و اولویتهای Ollama و llama.cpp را مطالعه کنید، زیرا این راهنما دقیقاً همان بخش فنی است که در آن مقایسه نادیده گرفته شده است.
یک تگ release انتخاب کرده و آن را یادداشت کنید
پروژه llama.cpp از تگهای شمارهبندی ساخت مانند b10488 برای نسخههای شبانه (nightly) و تگهای نسخه معنایی (semantic version) مانند vX.Y.Z برای نسخههای رسمی استفاده میکند. b10488 نسخه پینشدهای است که در اینجا استفاده میشود و در تاریخ 18 August 2026 منتشر شده است. عبارت "Latest" یک هدف متغیر است و نسخهای که شما تست کردهاید، تنها نسخهای است که میتوانید از آن پشتیبانی کنید. یک تگ را انتخاب کنید، آن را ثبت نمایید و از همان رشته در زمان clone کردن، در نام فایل باینری و در یادداشتهای خود استفاده کنید.
تگ b10488 همچنین آرشیوهای از پیش ساختهشده را ارائه میدهد. برای یک VPS با معماری x86 و فقط CPU، این فایل llama-b10488-bin-ubuntu-x64.tar.gz است و اگر از یک VPS با معماری ARM به جای x86 استفاده میکنید، آرشیو arm64 در کنار آن قرار دارد.
curl -LO https://github.com/ggml-org/llama.cpp/releases/download/b10488/llama-b10488-bin-ubuntu-x64.tar.gz
tar tf llama-b10488-bin-ubuntu-x64.tar.gz | headپیش از استخراج آرشیو، محتویات آن را لیست کنید تا بدانید فایلها در چه مسیری قرار میگیرند. این فایلهای باینری با کتابخانه C مربوط به ایمیجی که آنها را ساخته است لینک شدهاند؛ بنابراین در توزیعهای قدیمیتر، هنگام اجرا با خطایی مواجه میشوند که به یک نسخه GLIBC_ اشاره دارد که نصب نشده است. کامپایل از روی سورسکد در یک VPS کوچک تنها چند دقیقه زمان میبرد و این دسته از مشکلات را بهطور کامل برطرف میکند؛ به همین دلیل در ادامه، این مسیر انتخاب شده است.
ساخت llama-server از یک تگ ثابت (pinned tag)
sudo apt update
sudo apt install -y build-essential cmake git libssl-dev
git clone --depth 1 --branch b10488 https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF
cmake --build build --config Release -t llama-server -j 2دستور --branch b10488 روی یک --depth 1، دقیقاً همان تگ را checkout میکند و هیچ چیز دیگری را تغییر نمیدهد؛ بنابراین در حین کار، نسخهٔ build دچار تغییر ناخواسته نمیشود.
وجود libssl-dev اهمیت دارد، زیرا گزینهٔ LLAMA_OPENSSL بهصورت پیشفرض فعال است و همین گزینه است که به فایل اجرایی اجازه میدهد بعداً مدلها را از طریق HTTPS دانلود کند. بدون فایلهای توسعهٔ OpenSSL، این build ثابت هشدار میدهد که پشتیبانی از HTTPS غیرفعال شده است، بهجای آنکه در مرحلهٔ پیکربندی با خطا مواجه شود.
دستور -DBUILD_SHARED_LIBS=OFF کتابخانههای llama.cpp و GGML را به فایل اجرایی لینک میکند؛ وابستگیهای کتابخانهای سیستم همچنان باقی میمانند. build پیشفرض، کتابخانههای اشتراکی را در کنار فایل اجرایی قرار میدهد، بنابراین کپی کردن تنها فایل اجرایی به /usr/local/bin باعث بروز خطای error while loading shared libraries: libllama.so میشود.
دستور -t llama-server فقط هدف server را build میکند. build پیشفرض، سایر ابزارها و تستها را نیز کامپایل میکند که روی یک VPS با دو هسته، چندین دقیقه زمان اضافی صرف فایلهایی میکند که هرگز از آنها استفاده نخواهید کرد.
استفاده از -j 2 آگاهانه است. هر job کامپایل موازی، فضای کاری (working set) مخصوص به خود را اشغال میکند، بنابراین -j $(nproc) روی یک پلن کوچک با c++: fatal error: Killed signal terminated program cc1plus مواجه میشود که همان قاتل OOM (خارج از حافظه) هسته است که کامپایلر را متوقف میکند. تعداد jobها را کاهش دهید یا برای انجام build، فضای swap اضافه کنید.
یک فلگ که ممکن است بخواهید تغییر دهید: GGML_NATIVE بهصورت پیشفرض روشن است، بنابراین کامپایلر دقیقاً همان CPU که build را انجام میدهد هدف قرار میدهد. این همان چیزی است که هنگام build روی ماشینی که قرار است برنامه را اجرا کند، میخواهید. اگر یک بار build میکنید و فایل اجرایی را به میزبان دیگری کپی میکنید، -DGGML_NATIVE=OFF را اضافه کنید، زیرا فایل اجرایی که از دستوراتی استفاده میکند که CPU دیگر ندارد، در اولین inference با خطای Illegal instruction (core dumped) متوقف میشود.
آن را با نامی نصب کنید که شامل تگ باشد.
./build/bin/llama-server --version
sudo install -m 755 build/bin/llama-server /usr/local/bin/llama-server-b10488
sudo ln -sfn /usr/local/bin/llama-server-b10488 /usr/local/bin/llama-serverدستور --version شمارهٔ build و commit را چاپ میکند. این باید با تگی که checkout کردهاید مطابقت داشته باشد. اگر مطابقت ندارد، شما چیز دیگری را build کردهاید. نگه داشتن شماره در نام فایل و اشاره دادن یک symlink به آن به این معنی است که ارتقا فقط با یک ln -sfn و یک راهاندازی مجدد انجام میشود و بازگشت به نسخهٔ قبل (rollback) نیز با همان دستور و شمارهٔ قدیمی امکانپذیر است.
دریافت مدل GGUF و بررسی اولیه دیسک
فرمت GGUF یک فایل واحد است که توسط llama.cpp بارگذاری میشود. یک فایل شامل وزنها، توکنایزر و متادیتا است، بنابراین نیاز به نصب هیچ مورد دیگری نیست. پسوند موجود در نام فایل نشاندهنده کوانتایزیشن (quantisation) است که دقت ذخیرهسازی وزنها را تعیین میکند: Q4_K_M یک ترکیب 4-بیتی، Q8_0 نسخه 8-بیتی و f16 فایل بدون کوانتایزیشن با دقت نیمبیت (half-precision) است.
پیش از دانلود هر فایلی، یک حساب کاربری سرویس و یک دایرکتوری برای مدل ایجاد کنید.
sudo useradd --system --home /srv/llama --create-home --shell /usr/sbin/nologin llama
sudo install -d -o llama -g llama /srv/models
df -h /srvسرور میتواند با استفاده از -hf مدل را مستقیماً دریافت کند که سریعترین روش برای اطمینان از صحت عملکرد build شماست.
sudo -u llama env LLAMA_CACHE=/srv/models /usr/local/bin/llama-server \
-hf ggml-org/gemma-3-1b-it-GGUF:Q4_K_M --host 127.0.0.1 --port 8080LLAMA_CACHE دایرکتوری دانلود را تعیین میکند. بدون این فلگ یا XDG_CACHE_HOME، فایل در مسیر ~/.cache/llama.cpp و تحت حسابی که دستور را اجرا کرده ذخیره میشود؛ unit زیر باعث میشود /srv/llama فقطخواندنی (read-only) باشد. پس از آن ls -lh /srv/models را اجرا کنید، زیرا نام فایل کششده از نام مخزن مشتق میشود و نه از نام ساده فایل.
برای یک سرویس، فایل را در مسیری که انتخاب کردهاید دانلود کنید تا فایل unit یک مقصد ثابت برای ارجاع داشته باشد.
sudo -u llama curl -L --output-dir /srv/models -O \
https://huggingface.co/ggml-org/gemma-3-1b-it-GGUF/resolve/main/gemma-3-1b-it-Q4_K_M.ggufدیسک اولین محدودیتی است که کاربران با آن مواجه میشوند. اینها اندازههای فایل منتشرشده برای دو مدل هستند که در تاریخ 18 آگوست 2026 بررسی شدهاند.
دادههای پشت این نمودار
[
{
"label": "gemma-3-1b-it Q4_K_M",
"size_gb": 0.81
},
{
"label": "gemma-3-1b-it Q8_0",
"size_gb": 1.07
},
{
"label": "gemma-3-1b-it f16",
"size_gb": 2.01
},
{
"label": "gpt-oss-20b MXFP4",
"size_gb": 12.11
}
]فایل 4-بیتی برای مدل 1B برابر با 0.81 گیگابایت است. همان مدل بدون کوانتایزیشن 2.01 گیگابایت است، بنابراین انتخاب فرمت، عدد را بیش از دو برابر تغییر میدهد. یک مدل 20B با فرمت MXFP4 برابر با 12.11 گیگابایت است و پس از آن همچنان باید در حافظه بارگذاری شود. اگر به خانواده خاصی از مدلها توجه دارید، تمرین مشابه برای اندازهگیری GLM نشان میدهد که چگونه مدلهای بزرگ بهسرعت از محدوده قیمت یک VPS خارج میشوند، در حالی که مدلهای کوچکتر بهراحتی در آن جای میگیرند.
پیش از هر دانلود، df -h را بررسی کنید. پر شدن فایلسیستم root در حین یک انتقال 12 گیگابایتی، عملکرد سایر سرویسهایی که نیاز به نوشتن دارند، از جمله journal، را مختل میکند.
یکبار آن را بهصورت دستی اجرا کنید و بررسی نمایید
sudo -u llama /usr/local/bin/llama-server \
--model /srv/models/gemma-3-1b-it-Q4_K_M.gguf \
--host 127.0.0.1 --port 8080 \
--ctx-size 4096 --parallel 1 --threads 2 --no-webuiدر یک نشست (session) دوم، از سرور بپرسید که آیا آماده است یا خیر.
curl -s http://127.0.0.1:8080/healthهنگامی که فایل در حال بارگذاری است، خطای HTTP 503 و بدنه زیر را دریافت میکنید:
{"error":{"code":503,"message":"Loading model","type":"unavailable_error"}}وقتی سرور آماده باشد، بدنه پاسخ {"status": "ok" } خواهد بود. سپس یک درخواست واقعی ارسال کنید.
curl -s http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"local","messages":[{"role":"user","content":"Say hello in five words."}]}'یک شیء JSON با آرایه choices نشاندهنده عملکرد صحیح سرور است. فیلد model به این دلیل وجود دارد که کلاینتهای OpenAI همیشه آن را ارسال میکنند. این سرور تنها یک مدل بارگذاریشده دارد، بنابراین از این مقدار برای انتخاب چیزی استفاده نمیشود.
رابط برنامهنویسی سازگار با OpenAI و سایر موارد موجود روی این پورت
POST /v1/chat/completions، POST /v1/completions، POST /v1/responses و POST /v1/embeddings مسیرهای سازگار با OpenAI هستند و GET /v1/models مدل بارگذاریشده را گزارش میدهد. برای Embeddings به مدلی نیاز دارید که pooling آن چیزی غیر از none باشد. GET /health همان بررسی آمادگی (readiness check) در بالا است، GET /props تنظیمات فعلی سرور را بازمیگرداند و GET /metrics در صورتی که با --metrics شروع کرده باشید، شمارندههای Prometheus را در دسترس قرار میدهد.
برای فراخوانیهای سازگار با SDK شرکت OpenAI، آدرس پایه (base URL) را روی http://127.0.0.1:8080/v1 تنظیم کنید و اگر SDK نیاز به کلید API دارد، یک رشته غیرخالی ارائه دهید. این کار تضمینکننده سازگاری با تمام قابلیتهای SDK نیست. تا زمانی که خودتان --api-key یا --api-key-file را تنظیم نکنید، هیچچیز آن کلید را بررسی نمیکند.
ادعای هیچکس در مورد نرخ توان عملیاتی (throughput) را به عنوان عددی برای برنامهریزی خود در نظر نگیرید. سرعت استنتاج (inference) روی CPU به تعداد هستهها، پهنای باند حافظه و همسایگانی که میزبان را با آنها به اشتراک میگذارید بستگی دارد، بنابراین تعداد توکن در ثانیه را روی سیستم خودتان اندازهگیری کنید و آن نتیجه را به عنوان حقیقت بپذیرید. زمان سرقتشده (Steal time) از یک همسایه پرمصرف در اینجا به صورت سرعت تولیدی ظاهر میشود که ساعت به ساعت تغییر میکند.
سرویس را روی 127.0.0.1 نگه دارید و یک پروکسی در مقابل آن قرار دهید
--host بهصورت پیشفرض روی 127.0.0.1 تنظیم شده است، بنابراین تا زمانی که آن را تغییر ندهید، سرور از خارج قابل دسترسی نخواهد بود. آن را به همان حالت رها کنید. از پروکسی برای مدیریت حسابهای کاربری، محدودسازی نرخ درخواستها (rate limiting) و ثبت لاگهای بازرسی استفاده کنید؛ احراز هویت داخلی API از کلیدهای ایستا استفاده میکند: --api-key یک کلید یا لیستی از کلیدها با جداکننده کاما را میپذیرد و --api-key-file هر کلید را از یک خط مجزا میخواند. باز گذاشتن پورت استنتاج (inference port) به معنای در اختیار قرار دادن توان پردازشی رایگان برای هر کسی است که آن را پیدا کند؛ اشتباه مشابهی که در Ollama رخ میدهد، پیامدهای یکسانی دارد: ایمنسازی API مدلهای self-hosted خط به خط در اینجا نیز صدق میکند.
پایاندهی TLS (امنیت لایه انتقال) را در nginx انجام دهید و درخواستها را به پورت loopback پروکسی کنید.
server {
listen 443 ssl;
server_name llm.example.com;
location /v1/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_read_timeout 600s;
}
}proxy_buffering off پاسخهای استریمینگ را همزمان با دریافت توسط nginx به کلاینت ارسال میکند. با فعال بودن buffering، nginx دادههای دریافتی از upstream را بهجای ارسال فوری هر رویداد، بافر میکند. proxy_read_timeout 600s به پاسخهای کند فرصت میدهد. این مقدار طولانیترین زمانی است که nginx بین دو عملیات خواندن از سرور منتظر میماند و سقف زمانی برای کل پاسخ نیست؛ بنابراین با مقدار پیشفرض 60 ثانیه، یک درخواست غیر استریمینگ که در این بازه زمانی هیچ دادهای ارسال نکند، دچار timeout میشود. در b10488، پاسخهای استریمینگ بهصورت پیشفرض هر 30 ثانیه پینگهای keepalive از نوع SSE ارسال میکنند، که این شامل زمان پردازش طولانی prompt نیز میشود. گواهی را با استفاده از Certbot و Let's Encrypt روی nginx دریافت کنید.
واحد systemd
/etc/systemd/system/llama-server.service را بنویسید.
[Unit]
Description=llama.cpp server
After=network-online.target
Wants=network-online.target
[Service]
User=llama
Group=llama
Environment=LLAMA_ARG_MODEL=/srv/models/gemma-3-1b-it-Q4_K_M.gguf
Environment=LLAMA_ARG_HOST=127.0.0.1
Environment=LLAMA_ARG_PORT=8080
Environment=LLAMA_ARG_CTX_SIZE=4096
Environment=LLAMA_ARG_N_PARALLEL=1
Environment=LLAMA_ARG_THREADS=2
ExecStart=/usr/local/bin/llama-server --no-webui
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
MemoryHigh=3G
MemoryMax=3500M
OOMPolicy=stop
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
[Install]
WantedBy=multi-user.targetتنظیمات در خطوط Environment= قرار دارند، زیرا llama-server برای اکثر پرچمها (flags) متغیرهای LLAMA_ARG_* را میخواند و آرگومانهای خط فرمان، متغیرهای منطبق را بازنویسی میکنند. این کار باعث میشود یک مکان واحد برای تغییر اندازه context داشته باشید و ExecStart را به اندازه کافی کوتاه نگه میدارد تا در یک نگاه قابل خواندن باشد.
ProtectSystem=strict سیستم فایل را برای این واحد فقطخواندنی (read-only) میکند، با استثنائاتی شامل دایرکتوریهای موقت خصوصی که مشکلی ایجاد نمیکند، زیرا سرور فقط مدل را میخواند. اگر میخواهید خود سرویس مدلها را با -hf دانلود کند، ReadWritePaths=/srv/models و Environment=LLAMA_CACHE=/srv/models را اضافه کنید. ProtectHome=yes مسیرهای /home، /root و /run/user را مخفی میکند؛ این گزینه دایرکتوری home این حساب کاربری سرویس در /srv/llama را مخفی نمیکند، اما ProtectSystem=strict آن دایرکتوری را فقطخواندنی میکند.
sudo systemctl daemon-reload
sudo systemctl enable --now llama-server
systemctl status llama-server
curl -s http://127.0.0.1:8080/health
journalctl -u llama-server -n 50 --no-pagerenable --now بخشی است که اکثر افراد از آن صرفنظر میکنند. بدون enable، سرور پس از reboot بعدی از دسترس خارج میشود. اگر به دنبال اجرای کارهای زمانبندیشده پیرامون سرویس هستید، مانند بررسی شبانه برای انتشار نسخه جدید، یک سرویس systemd به همراه تایمر مکانیزم مناسب برای این کار است.
پیش از وقوع OOM، تصمیم بگیرید چه اتفاقی بیفتد
مصرف حافظه شامل دو بخش است که تحت محدودیت، رفتارهای متفاوتی دارند. فایل مدل بهصورت پیشفرض memory-mapped است، بنابراین صفحات آن file-backed هستند: هسته سیستمعامل میتواند آنها را حذف کرده و دوباره از دیسک بخواند. کش KV که وضعیت هر توکن برای هر گفتگوی فعال است، حافظه anonymous محسوب میشود. این بخش قابل حذف نیست، بنابراین همان چیزی است که باعث کشتهشدن پردازش میشود.
به همین دلیل است که دو محدودیت در unit وظایف متفاوتی دارند. MemoryHigh=3G یک محدودیت نرم (soft limit) است: بالاتر از آن، هسته cgroup را تحت فشار بازپسگیری (reclaim pressure) قرار میدهد، بنابراین صفحات مدل که map شدهاند تخلیه شده و در توکن بعدی از دیسک خوانده میشوند. سرویس به کار خود ادامه میدهد اما کندتر میشود. MemoryMax=3500M سقف سخت (hard ceiling) است: هسته ابتدا هر چه بتواند را بازپس میگیرد و اگر مصرف همچنان زیر حد مجاز کنترل نشود، OOM killer داخل unit اجرا شده و journal این موضوع را بهوضوح اعلام میکند.
llama-server.service: A process of this unit has been killed by the OOM killer.مقدار --ctx-size را خودتان تنظیم کنید. مقدار پیشفرض 0 است که به معنای کانتکستی است که مدل با آن آموزش دیده؛ در مدلهای مدرن با کانتکست طولانی، این مقدار در زمان شروع، یک کش KV بسیار بزرگ تخصیص میدهد. در نتیجه، سرویس پیش از پاسخدهی به حتی یک درخواست، از کار میافتد. --parallel بهتنهایی آن هزینه را چندبرابر نمیکند: --ctx-size اندازه کل کش KV را تعیین میکند که بین تمام اسلاتها مشترک است، بنابراین --ctx-size 4096 --parallel 4 به هر گفتگو حدود 1,024 توکن میدهد، نه چهار برابر حافظه. اختصاص کانتکست کامل به هر اسلات به معنای ضرب --ctx-size در تعداد اسلاتهاست و حافظه با آن رشد میکند، بنابراین تا زمانی که از نیاز خود به concurrency مطمئن نشدهاید، --parallel را روی 1 نگه دارید.
با Restart=on-failure، سرویس کشتهشده دوباره برمیگردد. Systemd تنها زمانی با start request repeated too quickly از راهاندازی مجدد دست میکشد که تعداد شروعها از نرخ مجاز پیکربندیشده فراتر رود؛ تأخیر پنجثانیهای در راهاندازی مجدد در اینجا به حد پیشفرض پنج شروع در ده ثانیه نمیرسد. یک حلقه راهاندازی مجدد مداوم را با sudo systemctl stop llama-server متوقف کنید، محدودیت یا اندازه کانتکست را اصلاح کنید، سپس وضعیت failed را با sudo systemctl reset-failed llama-server پاک کرده و دوباره آن را شروع کنید.
در حین اجرای درخواست، عدد واقعی را با systemctl show llama-server -p MemoryCurrent مشاهده کنید. محدود کردن حافظه و CPU پردازش با systemd این دستورالعملها را با جزئیات بیشتری بررسی میکند.
برای این حجم کاری از swap اجتناب کنید. مدل swap-out شده، هر توکن را به خواندن تصادفی از دیسک تبدیل میکند. Memory mapping فایل مدل، همان اثر را با آسیب کمتر ایجاد میکند، زیرا هسته صفحاتی را که نیاز دارد مستقیماً از فایل میخواند.
چه زمانی Ollama گزینه بهتری است
این یک دوراهی است. زمانی که به یک پردازش واحد با فلگهای تعیینشده، بیلد ثابت و فایل انتخابی خود نیاز دارید، llama-server را انتخاب کنید؛ جایی که به دلیل عدم اجرای سایر سرویسها، هیچ تغییری در زیرساخت شما رخ نمیدهد.
زمانی که به مدیریت مدل نیاز دارید، Ollama را انتخاب کنید: دانلود مدلها با نام، نگهداری چندین مدل روی دیسک، تخلیه مدلهای غیرفعال از حافظه و ارتقای مدلها با یک دستور واحد به جای بازسازی (rebuild). اینها کارهای عملیاتی واقعی هستند که در غیر این صورت باید خودتان برای آنها اسکریپت بنویسید. اجرای Ollama روی یک VPS دقیقاً همین کار را با رویکردی متفاوت انجام میدهد. هر دو سرویس یک API سازگار با OpenAI ارائه میدهند، اما پیش از تغییر در هر جهت، حتماً endpointها و قابلیتهایی که کلاینت شما از آنها استفاده میکند را تست کنید.
ارتقای بیلد پینشده
مقدار bNNNNN را با تگ بیلد شبانه (nightly) که قصد انتقال به آن را دارید جایگزین کنید؛ تگهای انتشار رسمی از vX.Y.Z استفاده میکنند.
cd llama.cpp
git fetch --tags
git checkout bNNNNN
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF
cmake --build build --config Release -t llama-server -j 2
sudo install -m 755 build/bin/llama-server /usr/local/bin/llama-server-bNNNNN
sudo ln -sfn /usr/local/bin/llama-server-bNNNNN /usr/local/bin/llama-server
sudo systemctl restart llama-serverفایل باینری قدیمی روی دیسک باقی میماند، بنابراین بازگشت به نسخه قبل (rollback) تنها با یک دستور ln -sfn به llama-server-b10488 و یک راهاندازی مجدد (restart) امکانپذیر است. پیش از انجام انتقال، یادداشتهای انتشار (release notes) را مطالعه کنید. فایلهای GGUF دارای نسخهبندی هستند، اما سازگاری با نسخههای قدیمی (backward compatibility) همگانی نیست: لودر فعلی، GGUFv1 را نمیپذیرد. نام فلگها نیز تغییر میکند: در b10488، استفاده از --mlock و --no-mmap به نفع --load-mode منسوخ شده بود و از تاریخ 11 اکتبر 2026، مستندات فعلی سرور دیگر آنها را فهرست نمیکند؛ بنابراین اگر یک unit file شامل فلگی باشد که حذف شده است، هنگام شروع با خطای unrecognised argument مواجه میشود. مقادیر پیشفرض نیز تغییر میکنند: بیلدهای فعلی بهطور پیشفرض روی پورت 9931 گوش میدهند، در حالی که b10488 از 8080 استفاده میکرد؛ به همین دلیل است که در اینجا هر دستور و unit file، پورت را بهصورت صریح تنظیم میکند.
حالتهای شکست و پیامهایی که مشاهده خواهید کرد
error while loading shared libraries: libllama.so پس از کپی کردن فایل باینری به یک مسیر دیگر. بیلد پیشفرض، کتابخانههای اشتراکی را در کنار فایل باینری تولید میکند. با استفاده از -DBUILD_SHARED_LIBS=OFF مجدداً بیلد کنید یا کل دایرکتوری build/bin را کپی نمایید.
Illegal instruction (core dumped) در زمان شروع به کار یا اولین درخواست. فایل باینری با فعال بودن GGML_NATIVE برای پردازندهای متفاوت از پردازنده فعلی کامپایل شده است. روی همین ماشین مجدداً بیلد کنید یا با -DGGML_NATIVE=OFF پیکربندی نمایید.
c++: fatal error: Killed signal terminated program cc1plus در حین بیلد. کامپایلر به دلیل مصرف بیش از حد حافظه متوقف شده است. مقدار -j را کاهش دهید یا برای مدت بیلد، فضای Swap اضافه کرده و پس از پایان کار آن را حذف کنید.
curl: (7) Failed to connect ... Connection refused از لپتاپ شما. این رفتار صحیح است: سرور روی آدرس loopback در VPS گوش میدهد. روی خود VPS تست کنید یا یک تونل با ssh -L 8080:127.0.0.1:8080 user@your-vps ایجاد کرده و از http://127.0.0.1:8080 به صورت محلی استفاده کنید.
خطای HTTP 503 همراه با "message":"Loading model" در ثانیهها یا دقایق اول پس از راهاندازی مجدد. خواندن یک فایل چند گیگابایتی زمانبر است و systemd به محض شروع پردازش، وضعیت unit را active گزارش میکند، در حالی که مدل هنوز در حافظه بارگذاری نشده است.
درخواستها معلق میمانند و سپس 504 Gateway Time-out برمیگردانند. سرور برای مدتی طولانیتر از proxy_read_timeout هیچ پاسخی ارسال نکرده است که این اتفاق در درخواستهای غیر-استریم (non-streaming) رخ میدهد. درخواستهای استریم در b10488 بهطور پیشفرض در حین پردازش طولانی پرامپت، هر 30 ثانیه یک پینگ keepalive ارسال میکنند. مقدار proxy_read_timeout را افزایش دهید و proxy_buffering را غیرفعال کنید تا توکنها به محض تولید به کلاینت برسند.
واحد (unit) دچار نوسان (flapping) شده و سپس با start request repeated too quickly متوقف میشود. تعداد دفعات شروع مجدد از حد مجاز پیکربندیشده فراتر رفته است. فایل journalctl -u llama-server را برای یافتن خط مربوط به OOM killer بررسی کنید، سپس مقدار --ctx-size را کاهش یا MemoryMax را افزایش دهید.
FAQ
آیا باید سرور llama.cpp را روی VPS اجرا کنم یا Ollama را؟
زمانی که میخواهید یک build دقیق را ثابت نگه دارید، flagهای خاصی را اعمال کنید و یک مدل را در یک فایل واحد داشته باشید که هیچچیز بهطور خودکار آن را تغییر ندهد، از llama-server استفاده کنید. زمانی که به مدیریت مدل و ارتقای تکدستوری نیاز دارید، Ollama را اجرا کنید؛ زیرا فراخوانی مدلها با نام، نگهداری چندین مدل روی دیسک و تخلیه مدلهای غیرفعال از حافظه، کارهایی هستند که در غیر این صورت باید خودتان برای آنها اسکریپت بنویسید. هر دو سرویس یک API سازگار با OpenAI ارائه میدهند، اما جابهجایی بین آنها مستلزم بررسی endpointها و قابلیتهایی است که کلاینت شما استفاده میکند.
به کدام نسخه از llama.cpp باید متصل (pin) شوم؟
به هر تگی که واقعاً آن را build و تست کردهاید. buildهای توسعه شبانه (nightly) از تگهای شمارهدار مانند b10488 استفاده میکنند که در تاریخ 18 August 2026 منتشر شده است؛ نسخههای رسمی از تگهای معنایی (semantic version) مانند vX.Y.Z استفاده میکنند. با استفاده از --branch <tag> مخزن را clone کنید، فایل باینری را با نامی که شامل آن تگ باشد نصب کنید و یک symlink به آن اشاره دهید تا ارتقا و بازگشت به نسخه قبل (rollback) تنها با یک دستور انجام شود.
سرور llama-server به چه مقدار RAM نیاز دارد؟
از حجم فایل GGUF شروع کنید، سپس KV cache را به آن اضافه کنید که با --ctx-size افزایش مییابد. این عدد، مجموع بودجه توکنهای به اشتراک گذاشته شده بین تمام --parallel اسلاتها است، بنابراین اگر قرار است هر اسلات context یکسانی داشته باشد، اسلاتهای بیشتر به --ctx-size بزرگتری نیاز دارند. ارقام منتشر شده جایگزینی برای اندازهگیری تنظیمات شخصی شما نیستند، زیرا مقدار کل به مدل، کوانتیزاسیون (quantisation) و context مجاز شما بستگی دارد. در حین اجرای یک درخواست، systemctl show llama-server -p MemoryCurrent را اجرا کنید و از عددی که مشاهده میکنید استفاده کنید.
چرا مسیر /health کد 503 با پیام "Loading model" برمیگرداند؟
پردازش شروع شده است اما فایل مدل هنوز در حافظه بارگذاری نشده است، بنابراین سرور {"error":{"code":503,"message":"Loading model","type":"unavailable_error"}} پاسخ میدهد. این وضعیت پس از هر بار راهاندازی مجدد طبیعی است و به اندازه زمان خواندن فایل طول میکشد. این موضوع تنها زمانی به مشکل تبدیل میشود که یک کلاینت یا پروکسی، آن 503 اولیه را به عنوان یک خطای جدی (hard failure) در نظر بگیرد. تا زمانی که /health مقدار {"status": "ok" } را برنگرداند، آن را poll کنید.
آیا میتوانم llama-server را مستقیماً در معرض اینترنت قرار دهم؟
آن را به 0.0.0.0 متصل (bind) نکنید و پورت را باز نگذارید. برای مدیریت حسابها، محدودیت نرخ درخواست (rate limit) و ثبت لاگهای حسابرسی (audit logging) از پروکسی استفاده کنید؛ احراز هویت داخلی API از کلیدهای ثابتی استفاده میکند که با --api-key یا --api-key-file تنظیم میشوند. اتصال پیشفرض 127.0.0.1 را حفظ کنید، nginx را با TLS در مقابل آن قرار دهید و --api-key را نیز تنظیم کنید تا یک اشتباه در پیکربندی پروکسی، مدل را برای همه در دسترس قرار ندهد.