SSD Nodes Learn 🎉 VPS $5.50/月〜
ガイド Matt Connor著者 Matt Connor ・更新日 2026-08-21

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

llama.cppはv0.xタグとbNNNNビルドタグを併記します。GGUFと量子化方式の横にタグを記録し、アップグレードは元に戻せる手順として検証してください。

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

llama.cpp のリリースを固定するには、名前付きのタグを1つ指定してビルドし、その名前をモデルファイルの横に記録します。タグは自動的に移動しないため、サーバーは今日と同じものを明日も生成します。長年、選べるタグは1種類だけでした。master から自動的に作成される、b10502 のようなビルド番号です。2026 年以降は、v0.1.2 のようなバージョンタグが2種類目として加わり、両方の系列が同じ履歴から同時に作成されています。

バージョンタグは、一般的なバージョン番号が通常意味するものをまだ表していません。v0.1.2 のリリースノートには、次の1文でそのことが記載されています。

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

これは文字どおりに受け取ってください。そのリンク先の ggml の議論 では、リリースを作成する頻度や、何をパッチとみなすかなど、この方式の詳細が現在も検討されています。v0. タグは、プロジェクトが履歴上のある時点を示すことを選択した、という意味です。末尾の数字が1つ増えたからといって、次のリリースが安全な置き換えになるとは限りません。

ビルドタグの数字にも、バージョンとしての意味はありません。これはコミット数に由来するため、環境に関係する変更があったかどうかにかかわらず、自動的に増加します。2026 年 8 月 19 日時点で、リリース一覧のトップページには b10455 から b10502 までの9個のビルドタグがあり、その中に v0.1.2 も含まれていました。

本番で何かを提供しているサーバーでは、master からビルドしない

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

代わりに tag を固定してください。tag はプロジェクト側で作成され、ビルド済みの各リリースアーカイブもその名前になります。

llama.cpp のリリースはどのタグに固定すべきですか？

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

意図的に選ばれた短い一覧を追跡したい場合は、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 を実行して後からタグを移動させることはできません。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）は重みを格納するコンテナです。同じモデルが複数の量子化レベルで公開されているため、同じ tag を使う2台のサーバーでも、片方が 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 を取得します。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 は起動中に終了し、ログには failed to load model from /srv/models/model-q4_k_m.gguf の行が出力されます。その直前に出力された行を確認してください。ローダーがどこまで処理できたかが分かります。GGUF のヘッダーにはフォーマットバージョンも含まれます（仕様の現在の値は 3 で、バージョン 2 では長さフィールドが 32 ビットから 64 ビットに拡張されました）。ただし実際には、フォーマットバージョンを確認するよりはるか前に、認識できないアーキテクチャ名で停止することがほとんどです。対処方法は、新しい tag を選び、その tag を記録して使用することです。

サーバーのフラグ名が変更または非推奨になる。 認識されないフラグがあると、無視されずに llama-server が起動時に停止します。systemd では、サービスが起動してはループ状に終了する状態に見えます。実際のメッセージは journalctl -u llama-server -n 50 に出力されます。2026 年 8 月 19 日時点で、サーバーのドキュメントでは --mlock と --mmap が非推奨とされ、-lm, --load-mode の使用が推奨されています。-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 になるためです。

アクセラレーター用ビルドを移植できない。 2026 年 8 月 19 日時点で、ビルド tag に付属する Linux 用アセットは、x64、arm64、s390x 向けの CPU、Vulkan、SYCL、OpenVINO バリアントです。この一覧に Linux 用 CUDA アーカイブはありません。そのため、NVIDIA サーバーではソースからビルドするか、コンテナイメージを実行する必要があります。Windows 用 CUDA アーカイブは 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 のようなビルドタグは長期的に続く系列です。ビルド済みリリースアーカイブの名前には必ずそのタグが含まれ、多くのバグ報告でも使われるため、別の運用担当者と比較しやすいのはビルド番号です。v0.1.2 のようなバージョンタグは、意図的に選ばれたポイントを並べた短い一覧です。年に数回しかサーバーへ変更を加えない場合に適しています。どちらを選ぶかより重要なのは、タグ文字列をモデルファイルの横に記録しておくことと、git pull の副作用ではなく、アップグレードを明示的な判断として実施することです。

llama.cpp は現在、セマンティックバージョニングに従っていますか？

まだ従っていません。プロジェクト自身がそう述べています。v0.1.2 のリリースノートでは、セマンティックバージョニングはまだ作業中であり、リリース間隔や何をパッチとみなすかを含む方式を検討している ggml の議論を参照しています。バージョンタグは、メンテナーが記録すべきポイントとして選んだものと考えてください。末尾の数字が変わっただけで、そのまま置き換え可能なアップグレードになるとは限りません。切り替える前に、新しいタグを自分のモデルファイルでテストしてください。

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

llama-server --version でバージョンとビルド情報を表示できます。起動ログの先頭にも build 行が出力され、ビルド番号、コミットハッシュ、使用したコンパイラーが記録されます。そのため、実行中のサービスでは journalctl -u llama-server で確認できます。ソースからインストールした場合は、固定した checkout 内で git describe --tags を実行するとタグが表示されます。また、readlink /opt/llama.cpp/current ではサービスが実際に参照しているディレクトリを確認できます。

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

アップグレード直後の読み込み失敗は、ビルドと GGUF ファイルの不一致が原因です。ログの末尾にはパスを示す failed to load model from 行が出力され、その直前の行からローダーがどこまで読み込んだかを確認できます。新しいモデルファイルを使用する場合は、そのアーキテクチャに対応したビルドが必要です。逆に、モデルファイルが作成されたタグより古いタグへ戻すと、前日まで動作していたファイルでも読み込めなくなることがあります。シンボリックリンクを以前のビルドへ向けて再起動し、どのビルドとファイルの組み合わせが正しく動作したかを確認してから、どちらを変更するか決めてください。

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

構成によってはあります。各ビルドタグには、そのタグを名前に含むリリースアーカイブが用意されています。たとえば llama-b10502-bin-ubuntu-x64.tar.gz です。19 August 2026 時点では、arm64、s390x、Vulkan、SYCL、OpenVINO の各バリアントも用意されています。ファイル名にタグが含まれるため、固定も容易です。その一覧には Linux 用の CUDA アーカイブがなかったため、NVIDIA サーバーでは -DGGML_CUDA=ON を使ってソースからビルドするか、CUDA コンテナーイメージのいずれかを実行する必要があります。

#llama-cpp#versioning#upgrades#pinning#local-llm