چطور نسخه llama.cpp را روی سرور ثابت نگه داریم
از سال 2026، llama.cpp علاوه بر tagهای build مانند b10502، نسخههایی مثل v0.6.0 دارد. tag، فایل GGUF و quant را ثبت کنید تا ارتقا قابل بازگشت باشد.
تغییرات versioning در llama.cpp
Pin کردن releaseهای llama.cpp یعنی یک tag نامگذاریشده را build کنید و نام آن را در کنار فایل مدل ثبت کنید. این tag خودبهخود جابهجا نمیشود؛ بنابراین سرور فردا نیز همان خروجی امروز را تولید میکند. برای سالها فقط یک نوع tag برای انتخاب وجود داشت: یک build number مانند b10502 که بهصورت خودکار از master ساخته میشد. از سال 2026 نوع دوم نیز وجود دارد: یک version tag مانند v0.6.0. این دو مسیر همزمان با یکدیگر پیش نمیروند. Build tagها تقریباً با هر commit در master ایجاد میشوند. Version tagها را maintainer بهصورت دستی و با سرعت کمتری ایجاد میکند و هر version release، build tag متناظر خود را مشخص میکند.
Version tagها در ابتدا قطعی نبودند. Release noteهای v0.1.2 که در 18 August 2026 منتشر شدند، این موضوع را در یک خط بیان کردند:
Semantic versioning هنوز در حال تکمیل است. اطلاعات بیشتر در https://github.com/ggml-org/ggml/discussions/1579 موجود است.
سه روز بعد، v0.2.0 این موضوع را نهایی کرد. در release note آن آمده است که این release «آغاز semantic versioning منسجم برای llama.cpp» را نشان میدهد. در این توضیحات، tagهای vX.Y.Z بهعنوان نسخههای پایدار با چرخه انتشار کندتر معرفی شدهاند که برای توزیع downstream و کاربران عادی توصیه میشوند؛ همچنین tagهای b[NUM] بهعنوان buildهای nightly یا dev با جدیدترین قابلیتها معرفی شدهاند که برای توسعهدهندگان و کاربران فنی توصیه میشوند. در تاریخ 14 November 2026، جدیدترین version tag برابر با v1.0.0 است که در 13 November منتشر شده و در توضیحات آن b12359 بهعنوان build tag متناظر معرفی شده است.
گفتوگوی ggml درباره این موضوع همچنان منطق این طرح را توضیح میدهد و در تاریخ 21 October 2026 هنوز برای دریافت بازخورد باز است. شمارهگذاری نسخهها به 1.x رسیده است؛ بنابراین پیش از هر جابهجایی release noteها را بخوانید و ارتقا را صرفاً بر اساس رقمی که تغییر کرده است ارزیابی نکنید.
عدد موجود در build tag هیچ معنای نسخهای ندارد. این عدد از شمار commitها بهدست میآید؛ بنابراین مستقل از آنکه تغییری مرتبط با setup شما رخ داده باشد یا نه، افزایش پیدا میکند.
هرگز روی سروری که هر سرویسی ارائه میدهد، مستقیماً از شاخه master build نگیرید
اجرای git pull و سپس rebuild، آخرین تغییراتی را که در چند ساعت گذشته وارد شدهاند در اختیار شما میگذارد. این کار روی یک لپتاپ قابلقبول است. اما روی سرور، توانایی پاسخدادن به پرسش مهم هنگام تغییر رفتار را از بین میبرد: اکنون چه چیزی در حال اجراست و هفتهٔ گذشته چه چیزی اجرا میشد؟ متن تولیدشده توسط مدل و سرعت تولید آن، هر دو با build تغییر میکنند. اگر commit مربوط به سهشنبه هرگز ثبت نشده باشد، برای این شکایت که پاسخها از سهشنبهٔ گذشته بدتر شدهاند، پاسخی نخواهید داشت.
در عوض، یک tag را pin کنید. پروژه tagها را برای شما ایجاد میکند و archiveهای release از پیش buildشده، tag مربوط به build را در نام فایلهای خود دارند؛ بهجز bundleهای runtime مربوط به Windows CUDA (cudart-llama-bin-win-...).
کدام tag را باید برای releaseهای llama.cpp pin کنید؟
وقتی به یک وضعیت مشخص و شناختهشده نیاز دارید، یک build tag را pin کنید. این همان مسیری است که سابقه طولانی دارد، archiveهای release بر اساس آن نامگذاری میشوند و بیشتر گزارشهای bug به آن ارجاع میدهند؛ بنابراین مقایسه یک build number با نمونهای که شخص دیگری دارد، سادهتر است.
اگر ترجیح میدهید فهرست کوتاهتری از نقاط مشخص و آگاهانه انتخابشده را دنبال کنید، یک version tag را pin کنید. این همان مسیری است که پروژه اکنون برای توزیع توسط downstreamها توصیه میکند. هر version release، build tag متناظر خود را مشخص میکند و binaryهای ازپیشساخته روی همان build tag قرار دارند؛ بنابراین build number را در کنار version ثبت کنید. پیش از جابهجایی، noteها را بخوانید، حتی اگر شمارهگذاری به 1.x رسیده باشد.
در هر دو حالت، قاعده عملیاتی یکسان است. رشته tag در یک file قرار دارد، box فقط زمانی rebuild میشود که آن رشته تغییر کند و این تغییر باید تصمیمی آگاهانه باشد که فردی عمداً گرفته است.
ساخت تگ پینشده
sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tagsgit describe --tags باید b10502 را چاپ کند. یک shallow clone روی یک تگ، فقط همان commit را نگه میدارد و هیچ چیزی پس از آن را شامل نمیشود، بنابراین هیچکس نمیتواند بعداً با یک git pull بیدقت آن را تغییر دهد. اگر مرحله configure به دلیل نبود یک dependency متوقف شد، آن را نصب کرده و دوباره اجرا کنید.
ساخت را با گزینههای مورد نیاز سختافزار خود انجام دهید. فقط CPU:
cmake -B build
cmake --build build --config Release -j $(nproc)NVIDIA GPU، که ابتدا نیاز به نصب CUDA toolkit دارد:
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)OpenBLAS روی سیستمی که فقط CPU دارد:
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)فایلهای باینری در build/bin قرار میگیرند، در کنار کتابخانههای اشتراکی که بارگذاری میکنند (libllama.so و فایلهای libggml). پیش از نصب، مطمئن شوید که build اجرا میشود:
./build/bin/llama-server --versionکل دایرکتوری را در مسیری که با نام تگ نامگذاری شده نصب کنید، سپس یک symlink به آن اشاره دهید:
sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/currentدایرکتوری را کپی کنید، نه فقط یک فایل تکی را. یک llama-server تنها، در اولین اجرا با خطای error while loading shared libraries: libllama.so: cannot open shared object file مواجه میشود، زیرا کتابخانههای مورد نیاز آن در همان دایرکتوری در کنارش قرار دارند.
سرویس را به symlink اشاره دهید، نه هرگز به دایرکتوری تگ:
[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080systemd هنگام شروع پردازش، symlink را resolve میکند، بنابراین تغییر buildها فقط به یک target جدید برای symlink و یک sudo systemctl restart llama-server نیاز دارد. بقیه فایل unit و reverse proxy که در مقابل آن قرار دارد، در راهنمای کامل برای سرور llama.cpp روی VPS پوشش داده شده است.
برچسب و quant را کنار فایل GGUF ثبت کنید
build نیمی از عواملی است که خروجی را تعیین میکند. فایل مدل نیمه دیگر است. GGUF (GGML universal file format) ظرفی است که weights در آن عرضه میشوند و یک مدل یکسان در سطوح quantisation متعددی منتشر میشود؛ بنابراین حتی دو سرور با یک tag یکسان نیز ممکن است خروجیهای متفاوتی داشته باشند، چون یکی فایل Q4_K_M و دیگری فایل Q8_0 دارد. یک فایل کوچک را کنار مدل نگه دارید و همه اطلاعات لازم برای بازسازی دقیق setup را در آن ثبت کنید:
tag: b10502
commit: 0adcc3b
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>commit را با git rev-parse --short HEAD داخل pinned checkout بهدست آورید. checksum را با sha256sum model-q4_k_m.gguf بهدست آورید و هنگام download آن را با مقدار publisher نیز مقایسه کنید، زیرا بررسی download در برابر checksum منتشرشده فایل ناقص را پیش از تبدیلشدن به یک bug گیجکننده شناسایی میکند. اینکه خود سطح quantisation تا چه اندازه پاسخها را تغییر میدهد، پرسش جداگانهای است و هزینه هر سطح quantisation برای شما به آن میپردازد.
چگونه بدون ایجاد اختلال در سرور، ارتقا را انجام دهیم؟
ارتقا را به صورت یک تمرین آزمایشی اجرا کنید. نسخه جدید را در کنار نسخه قدیمی بسازید، هر دو را ارزیابی کنید و تا زمانی که از عملکرد نسخه جدید مطمئن نشدهاید، نسخه قدیمی را حفظ کنید.
- نسخه جدید را در دایرکتوری مجزای خود کلون کنید. از checkout قدیمی مجدداً استفاده نکنید.
- آن را با همان آرگومانهای cmake که در manifest ثبت شده است، build کنید.
- دستور
llama-benchرا روی هر دو build و با استفاده از یک فایل مدل یکسان، با طول prompt مشابه و تعداد تکرار یکسان اجرا کنید. - یک prompt که پاسخ آن را بهخوبی میدانید به هر دو سرور ارسال کنید و پاسخهای دریافتی را مقایسه کنید.
- symlink را تغییر دهید، سرویس را restart کنید و دایرکتوری قدیمی را روی دیسک باقی بگذارید.
/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5دستور llama-bench برای هر تست یک ردیف چاپ میکند که شامل ستون backend، ستون ngl و ستون توکن در ثانیه به همراه انحراف معیار آن است. ردیف مشابه را بین دو build مقایسه کنید؛ ردیف prompt یک build را با ردیف generation build دیگر مقایسه نکنید. عددی که در طول prompt متفاوتی به دست آمده باشد، یک اندازهگیری متفاوت محسوب میشود؛ به همین دلیل است که اندازهگیری توکن در ثانیه به روش یکسان در هر بار اهمیت بیشتری نسبت به خود عدد دارد.
بازگشت به نسخه قبلی (rollback) تنها با دو دستور انجام میشود و تنها به این دلیل کار میکند که دایرکتوری قدیمی همچنان موجود است:
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-serverحداقل build قبلی را نگه دارید. هزینه فضای دیسک آن در مقایسه با فایل مدلی که در کنارش قرار دارد، ناچیز است.
چه مواردی در ارتقاهای llama.cpp دچار مشکل میشوند
فایل مدل دیگر بارگذاری نمیشود. این معمولاً همان دلیلی است که افراد را در وهله اول به ارتقا ترغیب میکند: مدل تازهمنتشرشده از معماریای استفاده میکند که build مشخصشده آن را نمیشناسد، بنابراین هرگز بارگذاری نمیشود. llama-server هنگام راهاندازی خارج میشود. تا 21 October 2026، کد منبع سرور برای این مورد failed to load model, '/srv/models/model-q4_k_m.gguf' را ثبت میکند؛ این پیام شامل یک ویرگول و مسیر داخل single quote است و آخرین خطی که چاپ میکند exiting due to model loading error است که هیچ مسیری ندارد. journal را برای failed to load model جستوجو کنید، نه برای کل خط. خطهایی را که درست پیش از آن چاپ شدهاند بخوانید؛ از جمله خط error loading model: خود loader که نشان میدهند loader تا کجا پیش رفته و چرا متوقف شده است. GGUF در header خود نسخهٔ format را نیز نگه میدارد؛ مقدار فعلی در spec برابر با 3 است و version 2 طول فیلدها را از 32 به 64 بیت افزایش داد. بااینحال، در عمل نام معماری ناشناخته بسیار زودتر از version format فرایند را متوقف میکند. راهحل، tag جدیدتری است که انتخاب و ثبت شده باشد.
نام یک flag سرور تغییر میکند یا آن flag deprecated میشود. flag ناشناخته در زمان راهاندازی، بهجای آنکه نادیده گرفته شود، llama-server را متوقف میکند؛ در systemd این وضعیت مانند سرویسی است که راهاندازی میشود و در یک حلقه از کار میافتد. journalctl -u llama-server -n 50 پیام واقعی را نشان میدهد. تا 19 August 2026، مستندات سرور --mlock و --mmap را deprecated و استفاده از -lm, --load-mode را بهجای آنها توصیه کرده بود. تا 21 October 2026 دیگر هیچیک از این دو flag در مستندات سرور یا فهرست argumentهای master دیده نمیشوند؛ بنابراین رفتار را با --load-mode حفظ کنید که auto را میپذیرد؛ این مقدار پیشفرض است؛ همچنین none، mmap، mlock، mmap+mlock و dio را نیز میپذیرد. flag مربوط به offload پردازندهٔ گرافیکی با نام -ngl, --gpu-layers, --n-gpu-layers مستند شده است، بنابراین شکل کامل آن در راهنماهای قدیمی همچنان پذیرفته میشود. مقدارهای پیشفرض نیز تغییر میکنند: از زمان v0.7.0، llama-server بهصورت پیشفرض روی پورت 9931 گوش میدهد، نه 8080؛ imageهای Docker همچنان داخل container از 8080 استفاده میکنند. بنابراین unit fileای که --port را مشخص نکرده باشد، در محلی که reverse proxy شما انتظار دارد دیگر پاسخ نمیدهد. release مربوط به v1.0.0 نیز flag deprecated یعنی --defrag-thold را حذف میکند. پیش از جابهجایی symlink، /opt/llama.cpp/<new tag>/bin/llama-server --help را اجرا کنید و هر flag موجود در unit file را با خروجی آن تطبیق دهید.
نام یک build option تغییر میکند. پیشوند گزینههای CMake از LLAMA_ به GGML_ تغییر کرده است و root CMakeLists.txt همچنان mapping را نگه میدارد. LLAMA_CUBLAS اکنون خطایی fatal است که GGML_CUDA را بهعنوان جایگزین معرفی میکند، درحالیکه LLAMA_CUDA و LLAMA_METAL هشدار تولید میکنند و برای شما ترجمه میشوند. اینکه build در مرحلهٔ configure متوقف شود، نتیجهٔ خوبی است. شکست خاموش بدتر است: اگر بهاشتباه -DGGML_CUDA=ON را حذف کنید، build موفق میشود، سرور شروع به کار میکند و همهچیز روی CPU اجرا میشود. llama-bench این وضعیت را فوراً نشان میدهد، چون ستون backend مقدار CPU را نمایش میدهد.
build مربوط به accelerator قابلانتقال نیست. تا 19 August 2026، assetهای Linux متصل به یک build tag شامل variantهای CPU، Vulkan، SYCL و OpenVINO برای x64، arm64 و s390x بودند و هیچ archive مربوط به CUDA برای Linux وجود نداشت. این وضعیت از آن زمان تغییر کرده است. تا 21 October 2026، b11669، یعنی build tag پشت v0.7.0، archiveهای CUDA مربوط به Ubuntu را برای CUDA 12.8 و 13.4 روی x64 و CUDA 13.4 روی arm64 نیز شامل میشود؛ هرکدام از این archiveها archive runtime متناظر cudart- را دارند و یک build مربوط به ROCm نیز ارائه شده است. archiveهای CUDA در Linux و Windows هر دو، برای هر toolkit version جداگانه منتشر میشوند. این نکته راهنمای مفیدی است: toolkit version بخشی از مشخصات شناسایی binary شماست؛ بنابراین آن را در کنار argumentهای cmake ثبت کنید.
استفاده از Pinning برای image کانتینر
همان قاعده، اما با یک اسم متفاوت. imageهای منتشرشده (ghcr.io/ggml-org/llama.cpp:server و نسخههای شتابدهنده آن) نامهای متغیری دارند؛ بنابراین pull کردن :server در ماه آینده، برنامه متفاوتی را تحت همان برچسب به شما میدهد. یک بار pull کنید و digest را بخوانید:
docker pull ghcr.io/ggml-org/llama.cpp:serverdocker pull یک خط Digest: sha256:... چاپ میکند. آن digest را در فایل compose به جای تگ قرار دهید تا دفعه بعد که شخصی docker compose pull را اجرا میکند، image نتواند تغییر کند. digest قبلی را در یک کامنت نگه دارید تا بازگشت به نسخه قبل (rollback) تنها با یک ویرایش انجام شود؛ دقیقاً همانطور که روال ارتقا و بازگشت به نسخه قبل برای یک stack در Compose با سایر سرویسها رفتار میکند.
اهمیت پین کردن
پین کردن به شما اجازه میدهد دقیقاً مشخص کنید چه چیزی در حال اجراست و اگر تغییری باعث بروز مشکل شد، بتوانید در کمتر از یک دقیقه نسخه قبلی را بازگردانید. ابزار llama.cpp از شما میخواهد دو مورد را برای این کار دنبال کنید: تگ build و فایل مدل، زیرا این دو را بهصورت جداگانه در اختیار شما قرار میدهد. محیطهای اجرایی (Runtimes) که این دو را با هم بستهبندی میکنند، رفتار متفاوتی دارند و مقایسه Ollama و llama.cpp به عنوان سرور این تفاوت را بررسی میکند: داشتن یک شماره نسخه واحد برای کل مجموعه، نیاز به ثبت و کنترل کمتری دارد.
FAQ
آیا باید برچسب build از نوع bNNNN را pin کنم یا برچسب v0.x را؟
هر دو گزینه مناسباند، به شرط آنکه چیزی را pin کنید. برچسبهای build مانند b10502 مسیر انتشار مستمر هستند: آرشیوهای release از پیش ساختهشده یکی از آنها را در نام فایل خود دارند، بهجز bundleهای runtime مربوط به Windows CUDA، و بیشتر گزارشهای bug نیز به یکی از آنها اشاره میکنند؛ بنابراین مقایسه یک شماره build با build مورد استفاده اپراتور دیگر آسانتر است. برچسبهای version مانند v0.6.0 فهرست کوتاهتری از نقاط مشخص و عمدی هستند که پروژه برای توزیع downstream توصیه میکند و برای سروری مناسباند که چند بار در سال به آن دست میزنید. هر برچسب، build tag متناظر خود را مشخص میکند؛ بنابراین هر دو را ثبت کنید. مهمتر از انتخاب بین این دو، ثبت رشته برچسب در کنار فایل model است؛ همچنین upgrade باید یک تصمیم آگاهانه باشد، نه پیامد جانبی git pull.
آیا llama.cpp اکنون از semantic versioning پیروی میکند؟
بله، از v0.2.0 در 21 August 2026. در release notes آمده است که این نسخه آغاز semantic versioning منسجم برای llama.cpp را مشخص میکند و caveat مربوط به work-in-progress را که v0.1.2 داشت، کنار میگذارد. تا 14 November 2026 شمارهگذاری version به 1.x رسیده و جدیدترین نسخه v1.0.0 است که در 13 November منتشر شده است. پیش از جابهجایی، release notes را بخوانید و tag جدید را با فایل model خود آزمایش کنید؛ این کار مستقل از آن است که کدام رقم تغییر کرده باشد.
چگونه بفهمم سرور من از کدام build مربوط به llama.cpp استفاده میکند؟
llama-server --version اطلاعات version و build را چاپ میکند؛ بنابراین آن را روی binary مورد استفاده سرویس اجرا کنید: /opt/llama.cpp/current/bin/llama-server --version. از 21 October 2026، خط آغازین شامل شماره build، hash مربوط به commit و compiler در سطح trace لاگ میشود؛ بنابراین در سطح پیشفرض لاگ، روی یافتن آن در journalctl -u llama-server حساب نکنید. در نصب source، اجرای git describe --tags در checkout مربوط به pin، tag را چاپ میکند و readlink /opt/llama.cpp/current نشان میدهد سرویس واقعاً به کدام directory اشاره میکند.
چرا پس از upgrade کردن llama.cpp، model من دیگر load نشد؟
خطای load بلافاصله پس از upgrade، ناشی از ناسازگاری بین build و فایل GGUF است. لاگ شامل خط failed to load model, '<path>' است که نام فایل را مشخص میکند و با exiting due to model loading error پایان مییابد؛ خطوط پیش از آن نیز نشان میدهند loader تا کجا فایل را خوانده است. در حرکت به سمت buildهای جدیدتر، یک فایل model بسیار جدید به buildی نیاز دارد که architecture آن را بشناسد. در حرکت به سمت buildهای قدیمیتر، rollback به نسخهای پایینتر از tag مورد استفاده برای ساخت فایل میتواند فایلی را که دیروز کار میکرد، خراب کند. symlink را به build قبلی اشاره دهید، سرویس را restart کنید و پیش از تصمیمگیری درباره تغییر یکی از آن دو، تأیید کنید کدام build با کدام فایل بهدرستی جفت شده است.
آیا binaryهای از پیش ساختهشده برای Linux وجود دارد که بتوانم بهجای build کردن آنها را pin کنم؟
بله. هر build tag آرشیوهای releaseای با نام همان tag دارد، مانند llama-b10502-bin-ubuntu-x64.tar.gz؛ بنابراین tag در نام فایل قرار دارد و pin کردن آسان است. در 19 August 2026 مجموعه Linux شامل CPU، arm64، s390x، Vulkan، SYCL و OpenVINO بود و آرشیو CUDA نداشت. از 21 October 2026، b11669 جدیدتر آرشیوهای Ubuntu CUDA 12.8 و 13.4 را نیز با bundleهای runtime متناظر cudart- ارائه میکند؛ بنابراین یک سرور NVIDIA با tag جدید دیگر مجبور نیست با -DGGML_CUDA=ON از source build کند یا image مربوط به CUDA container را اجرا کند. اگر version tag را pin میکنید، آرشیوها را از build tagای دانلود کنید که در release notes نام برده شده است.