SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

llama.cppのリリースをサーバーで固定する方法

llama.cppはbNNNNに加えてvX.Y.Zタグも登場しました。GGUFと量子化をタグと記録し、対応するビルドタグを確認して、取り消せる更新手順を整えます。

llama.cpp のバージョン管理で変わったこと

llama.cpp のリリースを固定する場合は、名前付きタグを 1 つ指定してビルドし、その名前をモデルファイルと併記します。タグは自動では移動しないため、サーバーは今日と同じものを明日も生成します。長年、選択できるタグは 1 種類だけでした。master から自動的に作成される、b10502 のようなビルド番号です。2026 年以降は、v0.6.0 のようなバージョンタグが 2 種類目として追加されました。ただし、この 2 つの系列は連動して更新されません。ビルドタグは master へのほぼすべてのコミットで作成されます。バージョンタグはメンテナーが手動で、より遅いペースで作成します。また、各バージョンリリースでは、それに対応するビルドタグが示されます。

バージョンタグは当初、試行的なものでした。v0.1.2 のリリースノートには、2026 年 8 月 18 日の公開時点で、次の 1 文が記載されていました。

セマンティックバージョニングはまだ作業中です。詳しくは https://github.com/ggml-org/ggml/discussions/1579 を参照してください。

3 日後、v0.2.0 で方針が確定しました。リリースノートでは、このリリースが「llama.cpp における一貫したセマンティックバージョニングの始まりを示す」と説明されています。vX.Y.Z タグは、リリース間隔が長い安定版として説明されており、下流での配布と一般ユーザーに推奨されています。b[NUM] タグは、最新機能を含む nightly または dev ビルドとして説明されており、開発者と技術ユーザーに推奨されています。2026 年 11 月 14 日時点で最新のバージョンタグは、11 月 13 日にリリースされた v1.0.0 です。リリースノートでは、対応するビルドタグとして b12359 が示されています。

そのリンク先にある ggml の議論 には、この方式を採用した理由が現在もまとめられています。2026 年 10 月 21 日時点でも、フィードバックを受け付けています。バージョン番号は 1.x に到達しているため、移行のたびにリリースノートを確認してください。変更された桁だけを見てアップグレードの影響を判断しないでください。

ビルドタグの番号には、バージョンとしての意味はありません。コミット数から決まるため、環境に関係する変更がなくても自動的に増加します。

本番サービスを提供するホストでは master から直接ビルドしない

git pull を実行してから再ビルドすると、直近数時間に取り込まれた変更がすべて反映されます。これはノート PC では問題ありません。しかしサーバーでは、動作が変わったときに重要となる「現在何が動作していて、先週は何が動作していたのか」という問いに答えられなくなります。モデルが生成するテキストと生成速度は、どちらもビルドに応じて変化します。先週火曜日から回答品質が低下したという報告も、その日のコミットを記録していなければ原因を特定できません。

代わりにタグを固定してください。タグはプロジェクト側で作成され、ビルド済みリリースアーカイブのファイル名にもビルドタグが含まれます。ただし、Windows CUDA runtime バンドルは除きます(cudart-llama-bin-win-...)。

llama.cpp のリリースでは、どのタグを固定すべきですか?

特定の既知の状態を使いたい場合は、build tag を固定します。これは長い履歴を持つ系統であり、リリースアーカイブの名前に使われ、最も多くのバグレポートで参照されています。そのため、build number は他の人と比較しやすい単位です。

意図的に選ばれたポイントだけを追いたい場合は、version tag を固定します。これは、プロジェクトが現在 downstream distribution 向けに推奨している系統です。各 version release には対応する build tag が記載され、prebuilt binaries もその build tag に置かれます。そのため、version と build number を併記してください。番号が 1.x に達していても、更新前に notes を確認してください。

どちらを選んでも、運用上のルールは同じです。タグ文字列をファイルに保存し、その文字列が変わった場合だけサーバーを再ビルドします。変更は、誰かが意図的に決定したものとして扱います。

タグを固定してビルドする

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 を実行して後からタグを移動させることはできません。configure の手順が依存関係の不足で停止した場合は、表示された依存関係をインストールして、もう一度実行します。

ハードウェアに必要なオプションを指定してビルドします。CPU のみの場合:

cmake -B build
cmake --build build --config Release -j $(nproc)

CUDA toolkit を先にインストールした NVIDIA GPU の場合:

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

CPU のみのマシンで OpenBLAS を使用する場合:

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

ディレクトリ全体をタグ名に基づくパスの下へコピーし、シンボリックリンクを 1 つだけそこへ向けます。

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 を実行します。unit ファイルの残りの設定と、その前段に置くリバースプロキシについては、VPS 上で llama.cpp サーバーを運用する手順全体で説明しています。

GGUF ファイルと量子化形式のタグを記録する

ビルドは出力を決める要素の半分です。もう半分はモデルファイルです。GGUF(GGML universal file format)は重みを格納するコンテナです。同じモデルでも多くの量子化レベルで公開されているため、同じタグを使う 2 台のサーバーでも、一方が Q4_K_M ファイルを保持し、もう一方が Q8_0 ファイルを保持していると、結果が一致しないことがあります。セットアップを正確に再構築するために必要な情報をすべて記録した小さなファイルを、モデルの横に 1 つ置いてください。

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>

固定した checkout 内で git rev-parse --short HEAD を使い、commit を取得します。sha256sum model-q4_k_m.gguf で checksum を取得し、ダウンロード時に公開元の値とも比較してください。ダウンロードしたファイルを公開 checksum と照合することで、ファイルの途中での切り詰めを、分かりにくい障害になる前に検出できます。量子化レベル自体が回答をどの程度変えるかは別の問題です。各量子化レベルで生じるコストで説明します。

サーバーを壊さずにアップグレードするにはどうしますか?

アップグレードを訓練として実行します。新しいタグを古いものの隣に配置して両方を測定し、新しいものが問題ないと判断できるまで古いものを残します。

  1. 新しいタグを専用ディレクトリに clone します。古い checkout は再利用しないでください。
  2. manifest に記録されたものと同じ cmake 引数でビルドします。
  3. 同じモデルファイルに対して、同じ prompt 長と同じ反復回数で、両方のビルドに llama-bench を実行します。
  4. 期待する回答が分かっている prompt を両方のサーバーに送信し、2 つの応答を確認します。
  5. symlink を切り替えてサービスを再起動し、古いディレクトリをディスク上に残します。
/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 はテストごとに 1 行を出力します。各行には backend 列、ngl 列、標準偏差付きの tokens per second 列があります。2 つのビルドで同じ行を比較してください。一方のビルドの prompt 行と、もう一方のビルドの generation 行を比較してはいけません。異なる prompt 長で取得した値は別の測定値です。そのため、毎回同じ方法で tokens per second を測定することが、数値そのものより重要になります。

ロールバックは 2 つのコマンドで実行できます。古いディレクトリが残っている場合に限り機能します。

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

少なくとも直前のビルドは残してください。モデルファイルが使用するディスク容量の一部しか必要としません。

llama.cpp のアップグレードで壊れるもの

モデルファイルを読み込めなくなる。 これは、そもそもアップグレードのきっかけになることが多い問題です。新しく公開されたモデルが、固定しているビルドでは認識できないアーキテクチャを使用しているため、読み込みに失敗します。llama-server は起動中に終了します。2026年10月21日時点では、サーバーのソースコードはこの問題に対して、カンマとシングルクォートで囲んだパスを含む 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 を選び、その内容を記録して使用してください。

サーバーの flag が変更または非推奨になる。 認識されない flag は無視されず、起動時に llama-server が停止します。systemd では、サービスが起動と終了を繰り返しているように見えます。実際のメッセージは journalctl -u llama-server -n 50 に表示されます。2026年8月19日時点で、サーバーのドキュメントでは --mlock と --mmap が非推奨とされ、代わりに -lm, --load-mode を使用するよう記載されていました。2026年10月21日時点では、いずれの flag もサーバーのドキュメントや master の引数一覧に存在しません。そのため、--load-mode で動作を引き継ぎます。この flag は auto(デフォルト)、none、mmap、mlock、mmap+mlock、dio を受け取ります。GPU オフロードの flag は -ngl, --gpu-layers, --n-gpu-layers と記載されているため、古いガイドにある長い形式も引き続き使用できます。デフォルト値も変わります。v0.7.0 以降、llama-server はデフォルトで 8080 ではなくポート 9931 で待ち受けます(Docker イメージ内では 8080 のままです)。そのため、unit ファイルで --port を省略すると、リバースプロキシが想定する場所で応答しなくなります。v1.0.0 リリースでは、非推奨の --defrag-thold flag も削除されています。シンボリックリンクを切り替える前に /opt/llama.cpp/<new tag>/bin/llama-server --help を実行し、unit ファイル内のすべての flag と照合してください。

ビルドオプションの名前が変更される。 CMake のオプションは LLAMA_ prefix から GGML_ prefix に移行しました。root の CMakeLists.txt には、現在も対応関係が記載されています。LLAMA_CUBLAS は、置き換え先として GGML_CUDA を示す致命的エラーになりました。一方、LLAMA_CUDA と LLAMA_METAL は警告を出し、自動的に変換されます。configure の段階で停止するビルドスクリプトなら、原因を把握しやすいため問題ありません。気付きにくい失敗の方が危険です。誤って -DGGML_CUDA=ON を省略すると、ビルドは成功し、サーバーも起動しますが、すべて CPU 上で実行されます。llama-bench ですぐに確認できます。backend 列が CPU になっているためです。

アクセラレーター向けビルドは移植できない。 2026年8月19日時点では、ビルド tag に付属する Linux 用 asset は CPU、Vulkan、SYCL、OpenVINO の各 variant で、x64、arm64、s390x 向けでした。Linux 用の CUDA archive はありませんでした。その後、状況は変わっています。2026年10月21日時点では、b11669、つまり v0.7.0 の基になっているビルド tag に、x64 向け CUDA 12.8 および 13.4、arm64 向け CUDA 13.4 の Ubuntu CUDA archive と、それぞれに対応する cudart- runtime archive が含まれています。ROCm build も含まれます。Linux と Windows のいずれでも、CUDA archive は toolkit のバージョンごとに公開されています。これは重要な手掛かりです。toolkit のバージョンはバイナリを識別する情報の一部なので、cmake の引数と一緒に記録してください。

コンテナイメージを固定する

ルールは同じで、対象が異なるだけです。公開イメージ(ghcr.io/ggml-org/llama.cpp:server とそのアクセラレーター版)は変動する名前です。そのため、来月 :server を pull すると、同じラベルでも別のプログラムが取得されます。1 回 pull したら、digest を確認します。

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

docker pull は Digest: sha256:... 行を出力します。その digest を tag の代わりに compose ファイルへ記述すると、次回誰かが docker compose pull を実行しても、使用するイメージは変わりません。以前の digest はコメントとして残してください。そうすれば、1 箇所を編集するだけでロールバックできます。これは、Compose スタックのアップグレードとロールバック手順で他のすべてのサービスを扱う方法と同じです。

ピン留めの目的

ピン留めを使うと、実行中の内容を正確に特定できます。変更によって問題が発生した場合も、1 分以内に以前のビルドへ戻せます。そのため、llama.cpp ではビルドタグとモデルファイルの 2 つを記録する必要があります。llama.cpp はこれらを別々に扱うためです。両方をまとめて提供するランタイムは動作が異なります。この違いについては、サーバーとしての Ollama と llama.cpp の比較で説明しています。全体で 1 つのバージョン番号を使う方式は、記録と管理の手間が少なくなります。

FAQ

bNNNN ビルドタグと v0.x タグのどちらを固定すべきですか?

どちらでも構いません。何らかのタグを固定することが重要です。b10502 のようなビルドタグは、長期間使われる系列です。事前ビルド済みリリースアーカイブのファイル名に含まれており(Windows CUDA runtime bundle を除く)、多くのバグレポートでも記載されるため、別の運用担当者と比較する際にはビルド番号が最も扱いやすい情報です。v0.6.0 のようなバージョンタグは、プロジェクトが downstream 配布向けに推奨する、意図的に選ばれたポイントを短い一覧にしたものです。年に数回だけ変更するサーバーに適しています。各バージョンタグには対応するビルドタグが記載されているため、両方を記録してください。どちらを選ぶかよりも、タグ文字列をモデルファイルと並べて記録し、アップグレードを git pull の副作用ではなく、明示的な判断として行うことが重要です。

llama.cpp は現在、semantic versioning に従っていますか?

はい。2026 年 8 月 21 日の v0.2.0 以降、従っています。リリースノートでは、llama.cpp における一貫した semantic versioning の開始点であり、v0.1.2 が示していた開発途中という但し書きを置き換えるものだと説明されています。2026 年 11 月 14 日時点でバージョン番号は 1.x に達しており、最新は 11 月 13 日にリリースされた v1.0.0 です。移行する前にリリースノートを確認し、変更された数字がどれであっても、新しいタグを自分のモデルファイルでテストしてから切り替えてください。

サーバーが実行している llama.cpp のビルドを確認するにはどうすればよいですか?

llama-server --version はバージョンとビルド情報を表示します。サービスが使用しているバイナリに対して実行してください。/opt/llama.cpp/current/bin/llama-server --version。2026 年 10 月 21 日時点では、ビルド番号、commit hash、コンパイラを含む起動行が trace level で記録されます。そのため、デフォルトのログレベルでは journalctl -u llama-server にその情報があるとは限りません。ソースからインストールした場合は、固定した checkout 内で git describe --tags を実行するとタグが表示されます。readlink /opt/llama.cpp/current では、サービスが実際に参照しているディレクトリを確認できます。

llama.cpp をアップグレードした後にモデルを読み込めなくなったのはなぜですか?

アップグレード直後の読み込み失敗は、ビルドと GGUF ファイルの不一致が原因です。ログにはファイル名を示す failed to load model, '<path>' 行が出力され、最後は exiting due to model loading error で終わります。その直前の行から、loader がどこまで読み込んだかを確認できます。新しいモデルファイルへ進む場合は、そのアーキテクチャに対応したビルドが必要です。逆に戻す場合は、そのファイルの作成に使われたタグより古いバージョンへ rollback すると、前日まで動作していたファイルが壊れることがあります。symlink を以前のビルドに向けて再起動し、どのビルドとファイルの組み合わせが正しく動作したかを確認してから、どちらを変更するか判断してください。

ビルドせずに固定できる、事前ビルド済みの Linux バイナリはありますか?

はい。各ビルドタグには、そのタグ名を付けたリリースアーカイブがあります。たとえば llama-b10502-bin-ubuntu-x64.tar.gz のようなファイル名です。ファイル名にタグが含まれるため、固定も容易です。2026 年 8 月 19 日時点の Linux 向けセットは CPU、arm64、s390x、Vulkan、SYCL、OpenVINO で、CUDA アーカイブはありませんでした。2026 年 10 月 21 日時点では、新しい b11669 に Ubuntu CUDA 12.8 および 13.4 向けアーカイブも含まれ、対応する cudart- runtime bundle も提供されています。そのため、最近のタグを使う NVIDIA サーバーでは、-DGGML_CUDA=ON を使ってソースからビルドしたり、CUDA container image を実行したりする必要がなくなりました。バージョンタグを固定する場合は、リリースノートに記載されたビルドタグからアーカイブをダウンロードしてください。

この記事は役に立ちましたか?