آموزش ثابت نگه داشتن نسخه llama.cpp روی سرور

تغییرات در نسخه‌گذاری llama.cpp

ثابت نگه‌داشتن (Pinning) نسخه‌های llama.cpp به معنای ساخت یک تگ نام‌گذاری‌شده و ثبت آن نام در کنار فایل مدل است. این تگ به‌صورت خودکار تغییر نمی‌کند، بنابراین سرور همان خروجی امروز را در آینده نیز تولید خواهد کرد. سال‌ها تنها یک نوع تگ برای انتخاب وجود داشت: یک شماره ساخت (build number) مانند b10502 که به‌طور خودکار از شاخه master گرفته می‌شد. از سال 2026، نوع دومی نیز اضافه شده است، یک تگ نسخه (version tag) مانند v0.1.2، و هر دو مسیر همزمان از یک تاریخچه استخراج می‌شوند.

تگ‌های نسخه هنوز به معنای استانداردی که از شماره نسخه انتظار می‌رود نیستند. یادداشت‌های انتشار در v0.1.2 این موضوع را در یک خط بیان کرده‌اند:

نسخه‌گذاری معنایی (Semantic versioning) هنوز در حال توسعه است. اطلاعات بیشتر در https://github.com/ggml-org/ggml/discussions/1579 موجود است.

این موضوع را دقیقاً همان‌طور که گفته شده در نظر بگیرید. بحث ggml در لینک مربوطه جایی است که این طرح همچنان در حال بررسی است، از جمله اینکه هر چند وقت یک‌بار باید نسخه جدید منتشر شود و چه تغییراتی به عنوان وصله (patch) محسوب می‌شوند. یک تگ v0. به شما می‌گوید که پروژه تصمیم گرفته است نقطه‌ای را در تاریخچه علامت‌گذاری کند. این تگ تضمین نمی‌کند که نسخه بعدی یک جایگزین امن و بی‌دردسر باشد، حتی اگر رقم آخر آن یک واحد افزایش یافته باشد.

شماره موجود در تگ ساخت نیز هیچ معنای نسخه‌گذاری ندارد. این شماره از تعداد commitها به دست می‌آید، بنابراین فارغ از اینکه آیا تغییری مرتبط با تنظیمات شما رخ داده است یا خیر، به‌طور خودکار افزایش می‌یابد. تا تاریخ 19 اوت 2026، صفحه اصلی لیست نسخه‌ها شامل نه تگ ساخت، از b10455 تا b10502 بود که v0.1.2 نیز در میان آن‌ها قرار داشت.

هرگز روی سروری که سرویسی را ارائه می‌دهد، از شاخه master بیلد نگیرید

اجرای git pull و سپس بازسازی (rebuild)، هر تغییری که در چند ساعت اخیر اعمال شده باشد را در سیستم شما پیاده می‌کند. این کار برای لپ‌تاپ شخصی مناسب است، اما روی سرور، توانایی شما را برای پاسخ به پرسش‌های حیاتی هنگام تغییر رفتار سیستم از بین می‌برد: چه چیزی در حال حاضر اجرا می‌شود و هفته گذشته چه چیزی در حال اجرا بود؟ متن تولید شده توسط مدل و سرعت تولید آن، هر دو با هر بیلد تغییر می‌کنند. اگر شکایتی مبنی بر افت کیفیت پاسخ‌ها در سه‌شنبه گذشته مطرح شود، در صورتی که commit مربوط به آن سه‌شنبه ثبت نشده باشد، هیچ پاسخی برای آن وجود نخواهد داشت.

به جای این کار، از یک tag خاص استفاده کنید. پروژه این تگ‌ها را برای شما ایجاد می‌کند و هر آرشیو release از پیش ساخته‌شده، با نام یکی از همین تگ‌ها نام‌گذاری شده است.

برای نسخه‌های llama.cpp باید از کدام تگ استفاده کرد؟

زمانی که می‌خواهید یک وضعیت مشخص و ثابت داشته باشید، یک build tag را پین کنید. این همان مسیری است که تاریخچه طولانی دارد، آرشیوهای نسخه بر اساس آن نام‌گذاری می‌شوند و اکثر گزارش‌های باگ به آن ارجاع می‌دهند؛ بنابراین شماره build ساده‌ترین معیار برای مقایسه با دیگران است.

اگر ترجیح می‌دهید لیست کوتاه‌تری از نقاط هدفمند را دنبال کنید، یک version tag را پین کنید. پیش از تغییر نسخه، یادداشت‌های آن را بخوانید و هشدار بالا را در نظر داشته باشید، زیرا شماره‌گذاری هنوز به عنوان یک قرارداد سازگاری تلقی نمی‌شود.

در هر دو حالت، قاعده عملیاتی یکسان است. رشته تگ در یک فایل قرار می‌گیرد، باکس فقط زمانی دوباره ساخته می‌شود که آن رشته تغییر کند و این تغییر، تصمیمی است که فردی به‌صورت آگاهانه اتخاذ کرده است.

ساخت تگ پین‌شده

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 --tags

git 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 8080

systemd هنگام شروع پردازش، symlink را resolve می‌کند، بنابراین تغییر buildها فقط به یک target جدید برای symlink و یک sudo systemctl restart llama-server نیاز دارد. بقیه فایل unit و reverse proxy که در مقابل آن قرار دارد، در راهنمای کامل برای سرور llama.cpp روی VPS پوشش داده شده است.

ثبت تگ در کنار فایل GGUF و سطح کوانتایز

ساختار build نیمی از چیزی است که خروجی را تعیین می‌کند. فایل مدل نیمه دیگر آن است. GGUF (مخفف GGML universal file format) کانتینری است که وزن‌های مدل در آن عرضه می‌شوند. از آنجا که یک مدل واحد در سطوح کوانتایز متعددی منتشر می‌شود، دو سرور با تگ یکسان ممکن است نتایج متفاوتی تولید کنند، زیرا یکی از آن‌ها از فایل Q4_K_M و دیگری از Q8_0 استفاده می‌کند. یک فایل کوچک در کنار مدل نگه دارید که تمام موارد لازم برای بازسازی دقیق تنظیمات را در خود داشته باشد:

tag: b10502
commit: 7c1f2a9
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>

با استفاده از git rev-parse --short HEAD در checkout پین‌شده، commit را دریافت کنید. checksum را با sha256sum model-q4_k_m.gguf بگیرید و آن را در زمان دانلود با مقدار منتشرشده توسط ناشر مقایسه کنید، زیرا بررسی دانلود در برابر checksum منتشرشده باعث می‌شود فایل‌های ناقص پیش از آنکه به یک باگ گیج‌کننده تبدیل شوند، شناسایی شوند. اینکه سطح کوانتایز دقیقاً چقدر پاسخ‌ها را تغییر می‌دهد، موضوعی جداگانه است و هزینه هر سطح کوانتایز به آن می‌پردازد.

چگونه بدون ایجاد اختلال در سرور، ارتقا را انجام دهیم؟

ارتقا را به صورت یک تمرین آزمایشی اجرا کنید. نسخه جدید را در کنار نسخه قدیمی بسازید، هر دو را ارزیابی کنید و تا زمانی که از عملکرد نسخه جدید مطمئن نشده‌اید، نسخه قدیمی را حفظ کنید.

1. نسخه جدید را در دایرکتوری مجزای خود کلون کنید. از checkout قدیمی مجدداً استفاده نکنید.
2. آن را با همان آرگومان‌های cmake که در manifest ثبت شده است، build کنید.
3. دستور llama-bench را روی هر دو build و با استفاده از یک فایل مدل یکسان، با طول prompt مشابه و تعداد تکرار یکسان اجرا کنید.
4. یک prompt که پاسخ آن را به‌خوبی می‌دانید به هر دو سرور ارسال کنید و پاسخ‌های دریافتی را مقایسه کنید.
5. 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 دچار اختلال می‌شوند

بارگذاری فایل مدل متوقف می‌شود. این معمولاً همان دلیلی است که باعث می‌شود کاربران اقدام به ارتقا کنند: یک مدل تازه منتشرشده از معماری استفاده می‌کند که نسخهٔ نصب‌شدهٔ فعلی آن را نمی‌شناسد، بنابراین مدل هرگز بارگذاری نمی‌شود. llama-server در حین راه‌اندازی خارج می‌شود و لاگ شامل یک خط failed to load model from /srv/models/model-q4_k_m.gguf است. خطوطی که درست پیش از آن چاپ شده‌اند را بخوانید؛ آن‌ها نشان می‌دهند که لودر تا کجا پیش رفته است. فرمت GGUF همچنین یک نسخه در هدر خود دارد (مقدار فعلی مشخصات 3 است و نسخه 2 طول فیلدها را از 32 به 64 بیت افزایش داد)، اگرچه در عمل، نام معماری ناشناخته بسیار زودتر از نسخهٔ فرمت، مانع کار شما می‌شود. راه‌حل، استفاده از یک تگ جدیدتر است که انتخاب و یادداشت شده باشد.

یک فلگ سرور تغییر نام یافته یا منسوخ شده است. یک فلگ ناشناخته باعث توقف llama-server در هنگام راه‌اندازی می‌شود و نادیده گرفته نمی‌شود؛ در systemd این وضعیت به شکل سرویسی دیده می‌شود که در یک حلقه شروع و متوقف می‌شود. journalctl -u llama-server -n 50 پیام واقعی را نشان می‌دهد. از تاریخ 19 August 2026، مستندات سرور، --mlock و --mmap را به نفع -lm, --load-mode منسوخ اعلام کرده‌اند که مقادیری مانند auto، mmap، mlock و dio را می‌پذیرد. فلگ offload پردازنده گرافیکی به عنوان -ngl, --gpu-layers مستند شده است، در حالی که راهنماهای قدیمی از --n-gpu-layers استفاده می‌کنند. پیش از جابه‌جایی symlink، دستور /opt/llama.cpp/<new tag>/bin/llama-server --help را اجرا کنید و تمام فلگ‌های موجود در فایل unit خود را با آن مطابقت دهید.

یک گزینه ساخت (build option) تغییر نام یافته است. گزینه‌های CMake از پیشوند LLAMA_ به پیشوند GGML_ منتقل شده‌اند و فایل CMakeLists.txt در ریشه پروژه، همچنان نگاشت آن‌ها را در خود دارد. LLAMA_CUBLAS اکنون یک خطای مهلک است که GGML_CUDA را به عنوان جایگزین معرفی می‌کند، در حالی که LLAMA_CUDA و LLAMA_METAL یک هشدار تولید کرده و به‌طور خودکار برای شما ترجمه می‌شوند. اسکریپت ساختی که در مرحله پیکربندی متوقف می‌شود، نتیجه مطلوبی است. شکست بی‌سروصدا بدتر است: اگر به‌طور تصادفی -DGGML_CUDA=ON را حذف کنید، ساخت با موفقیت انجام می‌شود، سرور بالا می‌آید و همه چیز روی CPU اجرا می‌شود. llama-bench این موضوع را بلافاصله نشان می‌دهد، زیرا ستون backend مقدار CPU را نمایش می‌دهد.

ساخت شتاب‌دهنده (accelerator) قابل حمل نیست. از تاریخ 19 August 2026، دارایی‌های لینوکسی که به یک تگ ساخت متصل هستند، شامل نسخه‌های CPU، Vulkan، SYCL و OpenVINO برای معماری‌های x64، arm64 و s390x می‌باشند. هیچ آرشیو CUDA برای لینوکس در آن لیست وجود ندارد، بنابراین برای سرورهای NVIDIA باید از سورس کد کامپایل کنید یا یک کانتینر اجرا نمایید. آرشیوهای CUDA برای ویندوز بر اساس نسخه toolkit منتشر می‌شوند که راهنمای مفیدی است: نسخه toolkit بخشی از شناسنامه باینری شماست، بنابراین آن را در کنار آرگومان‌های cmake ثبت کنید.

استفاده از Pinning برای image کانتینر

همان قاعده، اما با یک اسم متفاوت. imageهای منتشرشده (ghcr.io/ggml-org/llama.cpp:server و نسخه‌های شتاب‌دهنده آن) نام‌های متغیری دارند؛ بنابراین pull کردن :server در ماه آینده، برنامه متفاوتی را تحت همان برچسب به شما می‌دهد. یک بار pull کنید و digest را بخوانید:

docker pull ghcr.io/ggml-org/llama.cpp:server

docker pull یک خط Digest: sha256:... چاپ می‌کند. آن digest را در فایل compose به جای تگ قرار دهید تا دفعه بعد که شخصی docker compose pull را اجرا می‌کند، image نتواند تغییر کند. digest قبلی را در یک کامنت نگه دارید تا بازگشت به نسخه قبل (rollback) تنها با یک ویرایش انجام شود؛ دقیقاً همان‌طور که روال ارتقا و بازگشت به نسخه قبل برای یک stack در Compose با سایر سرویس‌ها رفتار می‌کند.

اهمیت پین کردن

پین کردن به شما اجازه می‌دهد دقیقاً مشخص کنید چه چیزی در حال اجراست و اگر تغییری باعث بروز مشکل شد، بتوانید در کمتر از یک دقیقه نسخه قبلی را بازگردانید. ابزار llama.cpp از شما می‌خواهد دو مورد را برای این کار دنبال کنید: تگ build و فایل مدل، زیرا این دو را به‌صورت جداگانه در اختیار شما قرار می‌دهد. محیط‌های اجرایی (Runtimes) که این دو را با هم بسته‌بندی می‌کنند، رفتار متفاوتی دارند و مقایسه Ollama و llama.cpp به عنوان سرور این تفاوت را بررسی می‌کند: داشتن یک شماره نسخه واحد برای کل مجموعه، نیاز به ثبت و کنترل کمتری دارد.

FAQ

آیا باید از تگ build با فرمت bNNNN استفاده کنم یا تگ v0.x؟

هر دو گزینه مناسب هستند، به شرطی که حتماً یک نسخه خاص را ثابت (pin) کنید. تگ‌های build مانند b10502 مسیر طولانی‌مدت پروژه هستند: هر آرشیو release پیش‌ساخته با این نام‌ها نام‌گذاری می‌شود و اکثر گزارش‌های باگ به یکی از آن‌ها ارجاع می‌دهند، بنابراین شماره build ساده‌ترین معیار برای مقایسه با سایر اپراتورهاست. تگ‌های نسخه مانند v0.1.2 لیست کوتاه‌تری از نقاط عطف مشخص هستند که برای سروری که سالی چند بار به آن سر می‌زنید، مناسب‌ترند. آنچه از انتخاب خودِ تگ مهم‌تر است، این است که رشتهٔ تگ در کنار فایل مدل ثبت شده باشد و ارتقا دادن یک تصمیم آگاهانه باشد، نه یک اثر جانبی از git pull.

آیا llama.cpp اکنون از نسخه‌سازی معنایی (Semantic Versioning) پیروی می‌کند؟

هنوز خیر، طبق بیانیه خود پروژه. یادداشت‌های انتشار v0.1.2 بیان می‌کنند که نسخه‌سازی معنایی هنوز در دست اقدام است و به بحثی در ggml اشاره می‌کنند که در آن روی این طرح، از جمله تناوب انتشار و تعریف patch، کار می‌شود. تگ نسخه را به عنوان نقطه‌ای در نظر بگیرید که نگهدارندگان پروژه برای علامت‌گذاری انتخاب کرده‌اند. فرض نکنید که تغییر در آخرین رقم، تضمین‌کننده یک ارتقای بدون دردسر (drop-in) است؛ پیش از تغییر تگ، حتماً آن را با فایل مدل خود تست کنید.

چگونه بفهمم سرور من کدام build از llama.cpp را اجرا می‌کند؟

دستور llama-server --version اطلاعات نسخه و build را چاپ می‌کند. لاگ راه‌اندازی نیز با یک خط build شروع می‌شود که شامل شماره build، هش commit و کامپایلر استفاده‌شده است، بنابراین journalctl -u llama-server آن را برای یک سرویس در حال اجرا پیدا می‌کند. در نصب از سورس، دستور git describe --tags در داخل دایرکتوری checkout شده، تگ را چاپ می‌کند و readlink /opt/llama.cpp/current نشان می‌دهد که سرویس در واقع به کدام دایرکتوری اشاره دارد.

چرا پس از ارتقای llama.cpp، مدل من دیگر بارگذاری نمی‌شود؟

شکست در بارگذاری بلافاصله پس از ارتقا، ناشی از عدم تطابق بین build و فایل GGUF است. لاگ با یک خط failed to load model from تمام می‌شود که مسیر فایل را مشخص می‌کند و خطوط بالای آن نشان می‌دهند که لودر تا کجا پیش رفته است. در ارتقا به نسخه‌های جدیدتر، یک فایل مدل بسیار جدید به buildای نیاز دارد که معماری آن را بشناسد. در بازگشت به نسخه‌های قدیمی‌تر (rollback)، پایین آمدن از تگی که فایل برای آن ساخته شده است، می‌تواند فایلی را که تا دیروز کار می‌کرد، از کار بیندازد. symlink را به build قبلی برگردانید، سرویس را restart کنید و تأیید کنید که کدام ترکیب build و فایل به درستی کار می‌کند، سپس تصمیم بگیرید کدام‌یک را تغییر دهید.

آیا باینری‌های پیش‌ساخته لینوکس وجود دارند که بتوانم به جای کامپایل کردن، آن‌ها را pin کنم؟

بله، برای برخی تنظیمات. هر تگ build دارای آرشیوهای release است که با همان نام نام‌گذاری شده‌اند، مانند llama-b10502-bin-ubuntu-x64.tar.gz، که تا تاریخ 19 August 2026 شامل نسخه‌های arm64، s390x، Vulkan، SYCL و OpenVINO در کنار آن است. این نام‌گذاری، ثابت کردن (pinning) را آسان می‌کند، زیرا تگ در نام فایل موجود است. در آن لیست آرشیو CUDA برای لینوکس وجود نداشت، بنابراین برای سرورهای NVIDIA همچنان باید از طریق -DGGML_CUDA=ON از سورس کامپایل کنید یا یکی از imageهای کانتینر CUDA را اجرا نمایید.