Как зафиксировать версию llama.cpp на сервере

Что изменилось в версионировании llama.cpp

Фиксация релизов llama.cpp подразумевает сборку конкретного тега и запись этого имени рядом с файлом модели. Тег не перемещается автоматически, поэтому сервер продолжает выдавать тот же результат, что и сегодня. В течение многих лет существовал только один тип тегов: номер сборки, например b10502, который автоматически создавался из ветки master. С 2026 года появился второй тип — тег версии, например v0.1.2, причем обе ветки создаются из одной и той же истории одновременно.

Теги версий пока не означают то, что обычно подразумевается под номером версии. В примечаниях к релизу на v0.1.2 об этом сказано одной строкой:

Семантическое версионирование все еще находится в разработке. Дополнительную информацию можно найти по ссылке https://github.com/ggml-org/ggml/discussions/1579

Воспринимайте это буквально. В обсуждении ggml по этой ссылке ведется работа над схемой версионирования, включая частоту выпуска релизов и определение того, что считается патчем. Тег v0. означает лишь то, что проект отметил точку в истории разработки. Он не гарантирует, что следующий релиз будет безопасной заменой предыдущему только потому, что последняя цифра увеличилась на единицу.

Номер в теге сборки также не несет смысловой нагрузки версии. Он основан на количестве коммитов, поэтому он растет независимо от того, изменилось ли что-то важное для вашей конфигурации. По состоянию на 19 августа 2026 года на главной странице списка релизов было девять тегов сборок, от b10455 до b10502, среди которых находился и v0.1.2.

Никогда не собирайте ПО из ветки master на сервере, который выполняет рабочие задачи

git pull в сочетании с пересборкой приводит к тому, что на сервере оказывается код, попавший в репозиторий за последние несколько часов. Это допустимо для ноутбука. На сервере это лишает вас возможности ответить на важный вопрос при изменении поведения системы: что запущено сейчас и что работало на прошлой неделе. Текст, генерируемый моделью, и скорость её работы зависят от конкретной сборки. На жалобу о том, что ответы стали хуже в прошлый вторник, невозможно ответить, если коммит от вторника не был зафиксирован.

Используйте конкретный тег. Проект создает их для вас, и каждый готовый архив с релизом имеет соответствующее имя.

На какой тег следует фиксировать релизы llama.cpp?

Фиксируйте тег сборки (build tag), если вам нужно одно конкретное известное состояние. Это ветка с долгой историей, по которой именуются архивы релизов и на которую ссылается большинство отчетов об ошибках, поэтому номер сборки — это самый простой способ сравнения с другими пользователями.

Фиксируйте тег версии (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) на конкретном теге содержит только этот коммит и ничего после него, поэтому никто не сможет изменить его позже неосторожной командой 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 8080

systemd разрешает символическую ссылку при запуске процесса, поэтому для переключения на новую сборку достаточно изменить цель ссылки и выполнить sudo systemctl restart llama-server. Остальная часть файла юнита и работа обратного прокси перед ним описаны в полном руководстве по настройке сервера llama.cpp на VPS.

Запишите тег рядом с файлом GGUF и уровень квантования

Сборка определяет результат наполовину. Вторая половина — это файл модели. 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 внутри зафиксированной копии репозитория. Получите контрольную сумму с помощью sha256sum model-q4_k_m.gguf и сравните её со значением, указанным издателем при загрузке, так как проверка загруженного файла по опубликованной контрольной сумме позволяет выявить повреждённый файл до того, как он превратится в трудноуловимую ошибку. То, насколько сильно сам уровень квантования влияет на ответы, — это отдельный вопрос, который рассматривается в разделе стоимость каждого уровня квантования.

Как выполнить обновление, не нарушив работу сервера?

Проведите обновление в режиме тренировки. Соберите новую версию рядом со старой, выполните замеры для обеих и сохраните старую версию, пока новая не подтвердит свою работоспособность.

1. Клонируйте новую версию в отдельный каталог. Не используйте повторно старую рабочую копию.
2. Выполните сборку с теми же аргументами cmake, которые указаны в манифесте.
3. Запустите llama-bench для обеих сборок с одним и тем же файлом модели, одинаковой длиной промпта и одинаковым количеством повторений.
4. Отправьте промпт, ответ на который вам хорошо известен, через оба сервера и сравните полученные ответы.
5. Переключите символическую ссылку, перезапустите сервис и оставьте старый каталог на диске.

/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 и столбец количества токенов в секунду со стандартным отклонением. Сравнивайте одну и ту же строку между двумя сборками, а не строку промпта одной сборки со строкой генерации другой. Значение, полученное при другой длине промпта, является другим измерением, поэтому измерение количества токенов в секунду одним и тем же способом каждый раз важнее, чем само число.

Откат выполняется двумя командами и работает только потому, что старый каталог всё ещё находится на месте:

sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server

Храните как минимум предыдущую сборку. Это занимает лишь малую часть дискового пространства, которое уже использует файл модели рядом с ней.

Что ломается при обновлении 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 августа 2026 года документация сервера помечает --mlock и --mmap как устаревшие в пользу -lm, --load-mode, который принимает такие значения, как auto, mmap, mlock и dio. Флаг выгрузки на GPU задокументирован как -ngl, --gpu-layers, в то время как в старых руководствах указан --n-gpu-layers. Перед тем как переместить символическую ссылку, запустите /opt/llama.cpp/<new tag>/bin/llama-server --help и сверьте каждый флаг в вашем unit-файле с выводом команды.

Опция сборки переименована. Опции CMake были перенесены с префикса LLAMA_ на префикс GGML_, а корневой файл CMakeLists.txt по-прежнему содержит таблицу соответствий. LLAMA_CUBLAS теперь вызывает критическую ошибку с указанием GGML_CUDA в качестве замены, в то время как LLAMA_CUDA и LLAMA_METAL выдают предупреждение и транслируются автоматически. Если скрипт сборки останавливается на этапе конфигурации — это хороший исход. Тихий сбой хуже: если случайно пропустить -DGGML_CUDA=ON, сборка завершится успешно, сервер запустится, но всё будет выполняться на CPU. llama-bench сразу покажет это, так как в столбце backend будет указано CPU.

Сборка для ускорителей не является переносимой. По состоянию на 19 августа 2026 года Linux-активы, прикрепленные к тегу сборки, включают варианты CPU, Vulkan, SYCL и OpenVINO для архитектур x64, arm64 и s390x. В этом списке нет архива CUDA для Linux, поэтому для сервера с NVIDIA необходимо выполнять сборку из исходного кода или использовать контейнерный образ. Архивы CUDA для Windows публикуются для каждой версии toolkit, что является полезной подсказкой: версия toolkit — это часть идентификатора вашего бинарного файла, поэтому записывайте её вместе с аргументами cmake.

Фиксация образа контейнера

Правило то же, объект другой. Опубликованные образы (ghcr.io/ggml-org/llama.cpp:server и его варианты с ускорением) — это динамические теги, поэтому загрузка :server в следующем месяце предоставит вам другую программу под тем же именем. Загрузите образ один раз и получите его дайджест:

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

docker pull выводит строку Digest: sha256:.... Укажите этот дайджест в файле compose вместо тега, и образ не изменится при следующем запуске docker compose pull. Сохраните предыдущий дайджест в комментарии, чтобы откат выполнялся одной правкой, точно так же, как это описано в процедуре обновления и отката стека Compose для любого другого сервиса.

Фиксация версии (pinning)

Фиксация версии позволяет точно определить, что именно запущено, и дает возможность вернуть предыдущую сборку в течение минуты, если изменения привели к ухудшению работы. llama.cpp требует отслеживать два компонента: тег сборки и файл модели, так как они предоставляются раздельно. Среды выполнения, объединяющие их в один пакет, работают иначе, и в сравнении Ollama и llama.cpp в качестве серверов рассматривается этот компромисс: единый номер версии для всего пакета требует меньше усилий для записи и контроля.

FAQ

Что лучше использовать: тег сборки bNNNN или тег версии v0.x?

Подходит любой вариант, главное — зафиксировать конкретный тег. Теги сборок, такие как b10502, представляют собой основной путь развития: каждый архив с готовой сборкой имеет соответствующее имя, и большинство отчетов об ошибках ссылаются именно на них, поэтому номер сборки — самый простой способ для сравнения версий между разными операторами. Теги версий, такие как v0.1.2, представляют собой более короткий список намеренно выбранных контрольных точек, что удобно для серверов, которые вы обновляете редко. Важнее не сам выбор, а то, чтобы строка с тегом была зафиксирована рядом с файлом модели, а обновление было осознанным решением, а не побочным эффектом git pull.

Использует ли llama.cpp семантическое версионирование?

На данный момент — нет, согласно официальному заявлению проекта. В примечаниях к выпуску v0.1.2 указано, что внедрение семантического версионирования все еще находится в процессе разработки. Там же приведена ссылка на обсуждение в ggml, где прорабатывается схема версионирования, включая периодичность выпусков и критерии для патчей. Воспринимайте тег версии как контрольную точку, выбранную разработчиками. Не стоит полагаться на то, что изменение последней цифры гарантирует беспроблемное обновление; всегда тестируйте новую версию с вашим файлом модели перед переключением.

Как узнать, какая сборка llama.cpp запущена на сервере?

Команда llama-server --version выводит информацию о версии и сборке. Журнал запуска также начинается со строки build, содержащей номер сборки, хеш коммита и использованный компилятор, поэтому journalctl -u llama-server позволяет найти эту информацию для работающего сервиса. При установке из исходного кода команда git describe --tags внутри зафиксированного репозитория выводит тег, а readlink /opt/llama.cpp/current показывает, на какой каталог фактически указывает сервис.

Почему модель перестала загружаться после обновления llama.cpp?

Ошибка загрузки сразу после обновления обычно означает несовместимость между сборкой и файлом GGUF. Журнал завершается строкой failed to load model from с указанием пути, а строки выше показывают, на каком этапе остановился загрузчик. При обновлении: очень новый файл модели требует сборки, которая поддерживает его архитектуру. При откате: возврат к версии ниже той, для которой был создан файл, может привести к неработоспособности файла, который функционировал вчера. Перенаправьте символическую ссылку на предыдущую сборку, перезапустите сервис и убедитесь, какая пара сборки и файла работает корректно, прежде чем принимать решение о том, что именно нужно изменить.

Существуют ли готовые бинарные файлы для Linux, которые можно зафиксировать вместо сборки из исходников?

Да, для некоторых конфигураций. Каждый тег сборки сопровождается архивами релизов, например llama-b10502-bin-ubuntu-x64.tar.gz, включающими варианты для arm64, s390x, Vulkan, SYCL и OpenVINO по состоянию на 19 августа 2026 года. Именование упрощает фиксацию версии, так как тег присутствует в имени файла. В этом списке не было архива CUDA для Linux, поэтому для сервера с NVIDIA по-прежнему требуется сборка из исходного кода с помощью -DGGML_CUDA=ON или использование одного из контейнерных образов с поддержкой CUDA.