Как закрепить релиз llama.cpp на сервере
Разберите различия тегов bNNNN и vX.Y.Z в llama.cpp, запишите тег рядом с GGUF и quant, а обновления проводите так, чтобы откат оставался возможным.
Что изменилось в нумерации версий llama.cpp
Закрепление релизов llama.cpp означает сборку определённого именованного тега и запись этого имени рядом с файлом модели. Тег не изменяется автоматически, поэтому сервер завтра продолжит выдавать тот же результат, что и сегодня. В течение нескольких лет существовал только один тип тегов: номер сборки, например b10502, который автоматически создавался из master. С 2026 года появился второй тип — тег версии, например v0.6.0. Эти два направления развиваются независимо. Теги сборок создаются почти при каждом коммите в master. Теги версий сопровождающий проекта создаёт вручную, реже. В каждом релизе версии указывается соответствующий ему тег сборки.
Сначала теги версий имели предварительный статус. В примечаниях к релизу v0.1.2, опубликованных 18 August 2026, это было указано одной строкой:
Semantic versioning всё ещё находится в разработке. Дополнительную информацию можно найти в https://github.com/ggml-org/ggml/discussions/1579
Через три дня релиз v0.2.0 закрепил этот подход. В его примечаниях сказано, что релиз «обозначает начало последовательного semantic versioning для llama.cpp». В них теги vX.Y.Z описаны как стабильные версии с более редким графиком выпуска, рекомендованные для дистрибуции downstream и обычных пользователей. Теги b[NUM] описаны как nightly- или dev-сборки с последними возможностями, рекомендованные разработчикам и техническим пользователям. По состоянию на 14 November 2026 последним тегом версии является v1.0.0, выпущенный 13 November. В его примечаниях в качестве соответствующего тега сборки указан b12359.
В обсуждении ggml, на которое ведёт эта ссылка, по-прежнему изложено обоснование этой схемы. По состоянию на 21 October 2026 обсуждение всё ещё открыто для отзывов. Нумерация версий достигла 1.x, поэтому перед каждым переходом изучайте примечания к релизу, а не оценивайте обновление только по изменившейся цифре.
Число в теге сборки не имеет смысла версии. Оно соответствует количеству коммитов, поэтому увеличивается само по себе независимо от того, изменилось ли что-либо важное для вашей конфигурации.
Никогда не собирайте ПО из ветки master на сервере, который выполняет рабочие задачи
git pull в сочетании с пересборкой дает вам версию, которая попала в репозиторий за последние несколько часов. Это допустимо на ноутбуке. На сервере это лишает вас возможности ответить на важный вопрос при изменении поведения системы: что запущено сейчас и что работало на прошлой неделе. Текст, генерируемый моделью, и скорость его генерации зависят от сборки. Жалоба на то, что ответы стали хуже в прошлый вторник, останется без ответа, если коммит за вторник не был зафиксирован.
Вместо этого используйте конкретный тег. Проект создает их для вас, а готовые архивы релизов содержат тег сборки в именах файлов, за исключением пакетов Windows CUDA runtime (cudart-llama-bin-win-...).
К какому тегу следует привязывать релизы llama.cpp?
Фиксируйте build tag, если вам нужно конкретное известное состояние. Это ветка с длинной историей, по ней названы архивы релизов, и на неё ссылаются в большинстве отчётов об ошибках. Поэтому номер сборки проще всего сравнить с номером у другого пользователя.
Фиксируйте version tag, если вы предпочитаете следовать более короткому списку определённых контрольных точек. Именно этот вариант проект теперь рекомендует для распространения в downstream-проектах. В каждом релизе версии указан соответствующий build tag, а предварительно собранные бинарные файлы размещаются на этом build tag. Поэтому записывайте номер сборки рядом с версией. Перед обновлением прочитайте примечания, даже несмотря на то, что нумерация достигла 1.x.
В обоих случаях операционное правило одинаково. Строка тега хранится в файле, сервер пересобирается только при изменении этой строки, а само изменение должно быть осознанным решением.
Сборка закрепленного тега
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) на конкретном теге содержит только этот коммит и ничего после него, поэтому никто не сможет изменить его позже неосторожной командой git pull. Если этап конфигурации прерывается из-за отсутствия зависимости, установите указанный пакет и запустите конфигурацию снова.
Выполните сборку с параметрами, необходимыми для вашего оборудования. Только 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/bin/llama-server --versionУстановите весь каталог по пути, названному в честь тега, а затем укажите на него одной символической ссылкой:
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, так как необходимые ему библиотеки находятся рядом с ним в этом каталоге.
Указывайте в сервисе путь к символической ссылке, а не к каталогу с тегом:
[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 разрешает символическую ссылку при запуске процесса, поэтому для переключения на новую сборку достаточно изменить цель ссылки и выполнить sudo systemctl restart llama-server. Остальная часть файла юнита и работа обратного прокси перед ним описаны в полном руководстве по настройке сервера llama.cpp на VPS.
Запишите тег рядом с GGUF-файлом и квантованием
Сборка определяет результат наполовину. Вторая половина — это файл модели. GGUF (GGML universal file format) — это контейнер, в котором поставляются веса. Одна и та же модель выпускается с разными уровнями квантования, поэтому два сервера с одинаковым тегом могут выдавать разные результаты, если на одном используется файл Q4_K_M, а на другом — Q8_0. Храните рядом с моделью небольшой файл, содержащий всё необходимое для точного воспроизведения конфигурации:
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>Получите коммит с помощью git rev-parse --short HEAD внутри зафиксированной копии репозитория. Получите контрольную сумму с помощью sha256sum model-q4_k_m.gguf и сравните её со значением, опубликованным автором на момент загрузки, так как проверка загруженного файла по опубликованной контрольной сумме позволяет выявить поврежденный файл до того, как он станет причиной трудноуловимой ошибки. Насколько сильно сам уровень квантования влияет на ответы — это отдельный вопрос, и стоимость каждого уровня квантования подробно его освещает.
Как выполнить обновление, не нарушив работу сервера?
Проведите обновление в режиме тренировки. Соберите новую версию рядом со старой, выполните замеры для обеих и сохраните старую версию, пока новая не подтвердит свою работоспособность.
- Клонируйте новую версию в отдельный каталог. Не используйте повторно старую рабочую копию.
- Выполните сборку с теми же аргументами cmake, которые указаны в манифесте.
- Запустите
llama-benchдля обеих сборок с одним и тем же файлом модели, одинаковой длиной промпта и одинаковым количеством повторений. - Отправьте промпт, ответ на который вам хорошо известен, через оба сервера и сравните полученные ответы.
- Переключите символическую ссылку, перезапустите сервис и оставьте старый каталог на диске.
/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 5llama-bench выводит по одной строке на каждый тест, включая столбец backend, столбец ngl и столбец количества токенов в секунду со стандартным отклонением. Сравнивайте одну и ту же строку между двумя сборками, а не строку промпта одной сборки со строкой генерации другой. Значение, полученное при другой длине промпта, является другим измерением, поэтому измерение количества токенов в секунду одним и тем же способом каждый раз важнее, чем само число.
Откат выполняется двумя командами и работает только потому, что старый каталог всё ещё находится на месте:
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-serverХраните как минимум предыдущую сборку. Это занимает лишь малую часть дискового пространства, которое уже использует файл модели рядом с ней.
Что ломается при обновлении llama.cpp
Модель перестаёт загружаться. Обычно именно это становится причиной обновления: опубликованная новая модель использует архитектуру, которую закреплённая сборка не знает, поэтому модель не загружается. llama-server завершает работу во время запуска. По состоянию на 21 October 2026 исходный код сервера записывает для этого failed to load model, '/srv/models/model-q4_k_m.gguf' с запятой и путём в одинарных кавычках, а последняя выводимая им строка — exiting due to model loading error, которая не содержит пути. Ищите в журнале failed to load model, а не всю строку целиком. Прочитайте строки непосредственно перед ней, включая собственную строку загрузчика error loading model:. По ним видно, насколько далеко продвинулся загрузчик и почему остановился. GGUF также содержит версию формата в заголовке: текущее значение спецификации — 3, а в версии 2 поля длины были расширены с 32 до 64 бит. Однако на практике неизвестное имя архитектуры останавливает загрузку задолго до проверки версии формата. Исправление — выбрать и зафиксировать более новый tag.
Флаг сервера переименован или объявлен устаревшим. Неизвестный флаг останавливает llama-server во время запуска, а не игнорируется. В systemd это выглядит как сервис, который запускается и зацикленно завершается. journalctl -u llama-server -n 50 показывает настоящее сообщение. По состоянию на 19 August 2026 документация сервера помечала --mlock и --mmap как устаревшие и рекомендовала вместо них -lm, --load-mode. По состоянию на 21 October 2026 ни один из этих флагов больше не указан в документации сервера или в списке аргументов в master. Их поведение нужно перенести с помощью --load-mode, который принимает auto (значение по умолчанию), none, mmap, mlock, mmap+mlock и dio. Флаг выгрузки на GPU документирован как -ngl, --gpu-layers, --n-gpu-layers, поэтому длинная форма из старых руководств по-прежнему поддерживается. Значения по умолчанию также меняются: начиная с v0.7.0, llama-server по умолчанию принимает соединения на порту 9931 вместо 8080 (Docker images сохраняют порт 8080 внутри контейнера). Поэтому unit file без --port перестаёт отвечать там, где его ожидает reverse proxy. В выпуске v1.0.0 также удалён устаревший флаг --defrag-thold. Перед переносом symlink выполните /opt/llama.cpp/<new tag>/bin/llama-server --help и проверьте по его выводу каждый флаг в unit file.
Переименован параметр сборки. Префикс параметров CMake изменился с LLAMA_ на GGML_, а корневой CMakeLists.txt по-прежнему содержит таблицу соответствий. LLAMA_CUBLAS теперь выдаёт критическую ошибку с указанием GGML_CUDA в качестве замены, а LLAMA_CUDA и LLAMA_METAL выводят предупреждение и автоматически преобразуются. Если скрипт сборки останавливается на этапе настройки, это хороший результат. Хуже тихая ошибка: если случайно не указать -DGGML_CUDA=ON, сборка завершится успешно, сервер запустится, а вся работа будет выполняться на CPU. llama-bench сразу показывает это, поскольку в столбце backend указано CPU.
Сборка для ускорителя непереносима. По состоянию на 19 August 2026 Linux assets, прикреплённые к build tag, представляли варианты CPU, Vulkan, SYCL и OpenVINO для x64, arm64 и s390x; архива CUDA для Linux не было. С тех пор это изменилось. По состоянию на 21 October 2026 b11669, build tag, используемый для v0.7.0, также содержит Ubuntu CUDA archives для CUDA 12.8 и 13.4 на x64 и для CUDA 13.4 на arm64. Для каждого варианта опубликован соответствующий cudart- runtime archive, а также сборка ROCm. В Linux и Windows CUDA archives публикуются отдельно для каждой версии toolkit. Это полезная подсказка: версия toolkit является частью идентификации бинарного файла, поэтому записывайте её вместе с аргументами cmake.
Фиксация образа контейнера
Правило то же, объект другой. Опубликованные образы (ghcr.io/ggml-org/llama.cpp:server и его варианты с ускорением) — это динамические теги, поэтому загрузка :server в следующем месяце предоставит вам другую программу под тем же именем. Загрузите образ один раз и получите его дайджест:
docker pull ghcr.io/ggml-org/llama.cpp:serverdocker pull выводит строку Digest: sha256:.... Укажите этот дайджест в файле compose вместо тега, и образ не изменится при следующем запуске docker compose pull. Сохраните предыдущий дайджест в комментарии, чтобы откат выполнялся одной правкой, точно так же, как это описано в процедуре обновления и отката стека Compose для любого другого сервиса.
Фиксация версии (pinning)
Фиксация версии позволяет точно определить, что именно запущено, и дает возможность вернуть предыдущую сборку в течение минуты, если изменения привели к ухудшению работы. llama.cpp требует отслеживать два компонента: тег сборки и файл модели, так как они предоставляются раздельно. Среды выполнения, объединяющие их в один пакет, работают иначе, и в сравнении Ollama и llama.cpp в качестве серверов рассматривается этот компромисс: единый номер версии для всего пакета требует меньше усилий для записи и контроля.
FAQ
Следует фиксировать тег сборки bNNNN или тег v0.x?
Подойдут оба варианта, если вы фиксируете один из них. Теги сборок, например b10502, относятся к долгосрочной ветке: готовые архивы релизов содержат такой тег в имени файла (за исключением наборов Windows CUDA runtime), а в большинстве сообщений об ошибках указывают именно его. Поэтому номер сборки проще всего сравнивать с номером у другого оператора. Теги версий, например v0.6.0, образуют более короткий список явно выбранных точек, которые проект рекомендует для распространения downstream. Это удобно для сервера, к которому вы обращаетесь несколько раз в год. Каждый такой тег указывает соответствующий тег сборки, поэтому сохраняйте оба. Важнее самого выбора то, чтобы строка тега была записана рядом с файлом модели, а обновление было осознанным решением, а не побочным эффектом git pull.
Использует ли llama.cpp теперь семантическое версионирование?
Да, начиная с v0.2.0 от 21 August 2026. В примечаниях к релизу указано, что это начало последовательного семантического версионирования для llama.cpp. Оно заменяет пометку о незавершённой работе, которую содержал v0.1.2. По состоянию на 14 November 2026 нумерация версий достигла 1.x. Последняя версия — v1.0.0, выпущенная 13 November. Перед обновлением прочитайте примечания к релизу и проверьте новый тег на собственном файле модели. Это нужно делать независимо от того, какая цифра изменилась.
Как определить, какую сборку llama.cpp использует сервер?
llama-server --version выводит сведения о версии и сборке. Запустите его для бинарного файла, который использует сервис: /opt/llama.cpp/current/bin/llama-server --version. По состоянию на 21 October 2026 строка запуска с номером сборки, хешем коммита и компилятором записывается на уровне trace. Поэтому не рассчитывайте найти её в journalctl -u llama-server при уровне журнала по умолчанию. При установке из исходного кода команда git describe --tags внутри зафиксированного checkout выводит тег, а readlink /opt/llama.cpp/current показывает, на какой каталог фактически указывает сервис.
Почему модель перестала загружаться после обновления llama.cpp?
Сбой загрузки сразу после обновления означает несовместимость сборки и файла GGUF. В журнале есть строка failed to load model, '<path>' с именем файла, а завершение содержит exiting due to model loading error. Предыдущие строки показывают, насколько далеко продвинулся загрузчик. При обновлении вперёд очень новый файл модели требует сборку, которая знает его архитектуру. При откате сборка ниже тега, для которого был создан файл, может перестать открывать файл, работавший ещё вчера. Укажите symlink на предыдущую сборку, перезапустите сервис и проверьте, какая сборка корректно соответствует файлу. После этого решите, что именно нужно изменить.
Существуют ли готовые бинарные файлы для Linux, которые можно зафиксировать вместо сборки?
Да. Для каждого тега сборки выпускаются архивы с соответствующим именем, например llama-b10502-bin-ubuntu-x64.tar.gz. Поэтому тег находится в имени файла, и его легко зафиксировать. На 19 August 2026 набор для Linux включал CPU, arm64, s390x, Vulkan, SYCL и OpenVINO, но не содержал архива CUDA. По состоянию на 21 October 2026 более новый b11669 также содержит архивы Ubuntu CUDA 12.8 и 13.4 с соответствующими пакетами runtime cudart-. Поэтому серверу NVIDIA с новым тегом больше не требуется собирать llama.cpp из исходного кода с помощью -DGGML_CUDA=ON или запускать образ CUDA container. Если вы фиксируете тег версии, скачивайте архивы из тега сборки, указанного в примечаниях к релизу.