llama.cpp 1.0.0への更新:APIの破壊的変更、FP8 KVキャッシュとサーバー保護
llama.cppとggmlを1.0.0へ更新する際に、ローカルのコーディングエージェントを壊さないための手順を説明します。削除されたC APIと--defrag-tholdへの対応、FP8 KVキャッシュのメモリ比較、MoEエキスパートキャッシュの調整、llama-serverのツール認証とプライベートURL制限を確認します。セマンティックバージョニングの対象範囲と、OllamaやLM Studioのユーザーが対応すべきタイミングも解説します。
目次

llama.cpp 1.0.0へ更新する前に、Cバインディング、起動オプション、サーバーのセキュリティ設定を確認してください。2026年11月13日のリリースでは、非推奨APIの削除、FP8 KVキャッシュとMoEエキスパートキャッシュの追加、ツールとプライベートメディアURLに対する新しい許可設定が行われました。llama-serverをローカルのコーディングエージェントから利用している場合は、まず検証環境で更新し、通常の応答とツール呼び出しの両方を確認してください。
今回のリリースでは、libllamaとlibggmlのバージョニング方針も明確になりました。今後、公開C APIの互換性を壊す変更にはメジャーバージョンの更新が必要です。
これにより、将来の依存ライブラリ更新に伴うリスクを判断しやすくなります。ただし、モデルの出力、推論速度、GPUバックエンドの動作、すべてのHTTPエンドポイントが同じままになるという保証ではありません。
llama.cpp 1.0.0で何が変わったのか?
主な対象は、llama.cppを組み込む開発者、llama-serverの運用者、ローカル推論のメモリ使用量を最適化する開発者です。
| 分野 | 1.0.0での変更 | 必要な対応 |
|---|---|---|
| バージョニング | 公開C APIとABIの非互換変更はメジャーバージョンで管理 | 本番環境ではリリースやコミットを固定 |
| C API | 35個の非推奨関数とllama_set_warmupを削除 | バインディングを修正して再ビルド |
| コンテキスト設定 | defrag_tholdと--defrag-tholdを削除 | 古い設定を削除 |
| 投機的デコード | NextN APIをllama.hへ移動し、状態関連の関数名を変更 | includeと関数呼び出しを更新 |
| KVキャッシュ | KとVにf8_e4m3形式を追加 | メモリ、品質、バックエンドの対応を比較 |
| MoE推論 | GPUのエキスパートキャッシュとCPUでのキャッシュミス処理を追加 | GPUの空き容量とキャッシュ設定を確認 |
| サーバーセキュリティ | ツール認証とプライベートメディアURLの制限 | ネットワーク公開範囲と認証を確認 |
| モデル対応 | Kimi-K3.1-Pro、Ripple、xing4_0などに対応 | モデルの変換と読み込み条件を確認 |
| 音声API | OpenAI互換の/v1/audio/speechを追加 | 対応する音声モデルで確認 |
変更点は公式のv1.0.0リリースノートとバージョニング方針の発表に記載されています。
プロジェクトは150を超えるモデルアーキテクチャのバリエーションをサポートすると発表しています。ただし、すべてのチェックポイントや機能が、あらゆるバックエンドで動作するわけではありません。
今後のセマンティックバージョニングはどう変わるのか?
新しい互換性の方針は、llama.cppとggmlの./includeにある公開Cインターフェースに適用されます。
バージョン番号は、次の規則で更新されます。
| 区分 | 変更の内容 | 例 |
|---|---|---|
| MAJOR | 公開C APIに互換性のない変更が発生 | 1.x.xから2.0.0 |
| MINOR | 後方互換のある機能、バックエンド、モデル、APIの追加 | 1.0.0から1.1.0 |
| PATCH | API変更を伴わないバグ修正 | 1.0.0から1.0.1 |
これらは規則を示す例です。今後のリリースを予告するものではありません。
libllamaに依存するアプリケーションでは、同じメジャーバージョンの間に公開関数のシグネチャが予期せず変わるリスクが小さくなります。
一方、内部ヘッダー、文書化されていないシンボル、CLI引数、HTTPレスポンスの詳細、モデルの動作までは、この互換性保証の対象になりません。
llama.cppのバージョンを固定するには?
アプリケーションにllama.cppを組み込む場合は、正確なリリースタグか変更されないコミットを指定してください。
公式ビルドガイドのGitとCMakeの手順に、v1.0.0タグのチェックアウトを組み合わせます。
Bashでの例です。
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git fetch --tags
git checkout v1.0.0
cmake -B build
cmake --build build --config Release
これは公式ガイドに記載された基本的なCPUビルド手順です。プラットフォームによっては、別のバックエンドがデフォルトで有効になる場合もあります。使用デバイスを判断する前に、ビルド設定を確認してください。
標準的なビルドでは、サーバーの実行ファイルは./build/bin/llama-serverに生成されます。CMakeのジェネレーターやプラットフォームによっては、出力先が異なります。
GPUを使用する場合は、対象バックエンドの公式ビルドオプションを追加してください。
本番環境では、リリースタグ、Gitコミットハッシュ、ビルドオプション、実行バックエンドを記録します。既存のバイナリを置き換える前に、新しいビルドを検証してください。
アプリケーションがllama.cppを同梱している場合は、アプリケーションやラッパー側のバージョンも固定します。内部で使用するllama.cppのリビジョンが異なることがあります。
削除されたAPIとコマンドラインオプションは?
更新時にまず対処すべきなのは、非推奨C APIとデフラグのしきい値設定です。
PR #30565のAPI整理では、35個の非推奨関数、llama_set_warmup、従来のデフラグしきい値の設定が削除されました。
移行時には次の点を確認してください。
llama_set_warmupの呼び出しを削除します。- コンテキスト設定から
defrag_tholdを削除します。 - 起動スクリプトから
--defrag-tholdを削除します。 - 該当する場合は
llama_set_embd_state_srcをllama_set_ctx_state_srcへ変更します。 llama.hへ移動されたNextN APIのincludeと宣言を更新します。
削除された35個の関数に、それぞれ一対一の代替関数があるとは限りません。v1.0.0のヘッダー変更と、自分のバインディングで使うシンボルを照合してください。
—defrag-tholdを使うスクリプトの修正
以前は、次のようにサーバーを起動していたかもしれません。
./build/bin/llama-server \
-m /path/to/model.gguf \
-c 32768 \
--defrag-thold 0.1
1.0.0では、削除されたオプションを取り除きます。
./build/bin/llama-server \
-m /path/to/model.gguf \
-c 32768
別のしきい値を設定する必要はありません。オプション自体が削除されています。文書化されていない代替オプションを推測して追加しないでください。
シェルスクリプト、Docker設定、サービス定義、アプリケーションのコードを検索します。
grep -RInE \
'defrag[_-]thold|llama_set_warmup|llama_set_embd_state_src' \
./scripts ./config ./src
検索先は自分のプロジェクトに合わせて変更してください。存在しないディレクトリはコマンドから除きます。
環境変数やラッパーの設定が、古いオプションを自動生成していないかも確認します。
CとPythonのバインディングを更新するには?
llama.hを直接参照している場合は、再ビルド前にコードとv1.0.0のヘッダーを比較してください。
CMakeを使用するアプリケーションは、新しいライブラリに対して再ビルドし、コンパイラーとリンカーの出力を確認します。
Pythonのラッパーでは、まず使用中のバージョンがllama.cpp 1.0.0に対応しているか確認してください。
llama.cppの実行ファイルだけを入れ替えても、Python拡張にコンパイル済みの定義は更新されません。
ラッパーが独自にllama.cppのソースを同梱している場合は、ラッパー側の更新手順に従います。互換性を調べずに共有ライブラリだけを手動で置き換えないでください。
importが成功しても十分ではありません。モデルの読み込み、トークン生成、コンテキスト状態の操作、投機的デコードを実際の用途に合わせて確認してください。
llama.cpp 1.0.0でFP8 KVキャッシュを有効にするには?
AttentionのkeyとvalueをFP8形式で保存するには、-ctk f8_e4m3 -ctv f8_e4m3を指定します。
KVキャッシュは、すでに処理したトークンに関する情報を保持します。そのため、次のトークンを生成する際に、過去のコンテキストを毎回計算し直す必要がありません。
一般に、コンテキストが長くなるほどKVキャッシュのメモリ使用量も増えます。
FP8は1つの値に8 bitsを使います。FP16では16 bitsです。同じ形状のテンソルであれば、K/Vデータ自体の保存領域は理論上ほぼ半分になります。
ただし、この見積もりにはスケール情報、メタデータ、メモリのアラインメント、モデルの重み、計算バッファーなどは含みません。GPUメモリ全体が半分になるという意味ではありません。
まずFP16を基準に測定する
両方の実行で同じモデルとコンテキストサイズを使用してください。
最初はFP16でサーバーを起動します。
./build/bin/llama-server \
-m /path/to/model.gguf \
-c 32768 \
--host 127.0.0.1 \
--port 8080 \
-ctk f16 \
-ctv f16
ログに表示されるKVバッファーの割り当て量を記録します。デバイスの空きメモリ、プロンプト処理速度、生成速度も測定してください。
サーバーを停止し、FP8で再起動します。
./build/bin/llama-server \
-m /path/to/model.gguf \
-c 32768 \
--host 127.0.0.1 \
--port 8080 \
-ctk f8_e4m3 \
-ctv f8_e4m3
今回のリリースでは、FP8 KVキャッシュ用の静的なper-tensor scaleもオプションとして追加されています。
起動ログで、選択されたキャッシュ形式と割り当て量を確認してください。オプションが受け付けられても、GPUバックエンドのすべての最適化処理が対応しているとは限りません。
FP8ならコンテキスト長を2倍にできる?
必ずしもできません。
FP8はKVテンソルの保存領域を削減しますが、コンテキスト長にはモデル自体の対応範囲と利用可能なメモリの制約があります。
例えば、FP16 KVキャッシュが8 GiBを使用する仮想的な構成では、同じ形状のFP8データは約4 GiBになる可能性があります。
これは生データの理論計算であり、llama.cppで測定したベンチマーク結果ではありません。
空いたメモリを使って、より長いコンテキストや同時リクエスト数を増やせる場合があります。ただし、モデルが対応する実効コンテキスト長を超えることはできません。
FP8はFP16より精度が低い表現です。公式リリース資料には、コーディング品質やツール呼び出しの正確さに関する普遍的な評価結果は示されていません。
コーディングエージェントでは、同じリポジトリ作業で両方の形式を比較してください。
- 長いソースファイルから必要なシンボルを探します。
- 複数ファイルにまたがる変更を作成します。
- 構造化されたツール呼び出しを生成します。
- 長いやり取りを数回続けた後で、作業を再開します。
tokens per secondだけでなく、コードの正しさとツール引数の解析結果も確認してください。
新しいMoEエキスパートキャッシュの仕組み
MoEエキスパートキャッシュは、Mixture-of-Expertsモデルのエキスパートの重みをGPUではなくシステムRAMに置く場合に役立ちます。
MoEモデルはトークンごとに一部のエキスパートを選びます。その重みをRAMからGPUへ何度も転送すると、デコードの負荷が高くなることがあります。
新しいキャッシュは、使用頻度の高いエキスパートをGPUメモリに保持します。また、キャッシュミスの一部をCPUで計算する設定もあります。
これはFP8 KVキャッシュとは別の機能です。MoEキャッシュはモデルの重みを扱い、KVキャッシュはAttentionの状態を保存します。
公式MoEキャッシュガイドには、次のオプションが記載されています。
| オプション | 動作 | デフォルト |
|---|---|---|
-cmoe | すべてのMoEエキスパートの重みをCPUメモリに置く | 指定しなければ無効 |
--moe-cache-mib N | CPU上のエキスパート用にN MiBのGPUキャッシュを確保 | 0、無効 |
--moe-cache-cpu-share F | キャッシュが満杯になった後、ミスの割合FをCPUで計算 | 0 |
CPU shareの指定範囲は0から1です。
動作には次の規則があります。
- キャッシュヒットはGPUで処理します。
- キャッシュが満杯になるまでは、ミスしたエキスパートをGPUへ転送します。
- 満杯になった後は、指定した割合のキャッシュミスをCPUで処理します。
- 残りのミスはGPUでの実行に向けて転送します。
- 大きなバッチでは、必要なエキスパートを引き続き転送する場合があります。
CPUによるRAMからの読み取りがGPUへの転送より速い場合、CPU計算が役立つことがあります。
一方、pinned host memoryではGPUへの転送が効率的になることがあります。転送帯域を十分に使えている環境では、CPU shareを増やしても効果は小さい場合があります。
CPUメモリ上のMoEエキスパートをキャッシュする例
この例では、対応するGPUバックエンドと、キャッシュ用の空きGPUメモリが必要です。
CPU専用ビルドでは、ここで説明するGPUエキスパートキャッシュを利用できません。
必要なCUDA開発環境があるNVIDIAシステムでは、公式CUDAビルド手順に従います。
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release
ほかの対応GPUでは、そのバックエンド向けのビルド手順を利用してください。
対応するMoEモデルとGPU対応ビルドでは、例えば次のように起動します。
./build/bin/llama-server \
-m /path/to/moe-model.gguf \
-cmoe \
-c 32768 \
--host 127.0.0.1 \
--port 8080 \
--moe-cache-mib 2048 \
--moe-cache-cpu-share 0.5
-cmoeはMoEエキスパートの重みをCPUメモリに配置します。--moe-cache-mib 2048は、選択されたエキスパート用に2,048 MiBのGPUキャッシュを要求します。
0.5は、キャッシュが満杯になった後のミスのうち50%をCPUで処理する設定です。
キャッシュが満杯になるまでは、ミスしたエキスパートはGPUへ転送されます。キャッシュヒットは引き続きGPUで実行します。
これは設定例であり、すべてのGPUに推奨する値ではありません。
GPUにはキャッシュ以外に、モデルのレイヤー、KVキャッシュ、計算バッファーの領域も必要です。
メモリが足りない場合は、キャッシュサイズを小さくするか、重みの配置を見直してください。大きすぎるモデルが必ず収まるようになる機能ではありません。
チューニングスクリプトで設定を選ぶ
プロジェクトには、実際の環境に合わせてキャッシュ設定を調整するためのスクリプトがあります。
llama.cppのリポジトリで次を実行します。
python3 scripts/moe-cache-tune.py -- \
./build/bin/llama-server \
-m /path/to/moe-model.gguf \
-cmoe \
-t 8 \
-c 32768
公式チューニングスクリプトは、異なるキャッシュサイズとCPU shareを指定してサーバーを実行します。
ガイドには6回の測定が記載されています。2つのキャッシュサイズと、0、0.5、0.95のCPU shareを組み合わせます。
スクリプトは測定結果をもとに別の構成を推定します。実測速度、予測スループット、推奨オプションを出力します。
モデル、CPUスレッド数、コンテキスト長、エキスパートの配置は実際の設定に合わせてください。これらは推論速度と空きGPUメモリに影響します。
このキャッシュは主に小さいバッチでのデコードを対象としています。大きいバッチではエキスパート転送が引き続き必要になる場合があります。
Denseモデルや、すべてのエキスパートがGPUに収まるモデルでは効果が期待しにくいため、まずはデフォルトの無効設定を使用してください。
llama-serverのセキュリティはどう変わったのか?
1.0.0では、認証なしのツール公開とプライベートメディアURLへのアクセスについて、明示的な許可オプションが追加されました。
特に、ローカルマシン以外から接続できるサーバーでは確認が必要です。
—allow-unauthenticated-tools
--allow-unauthenticated-toolsは、非ループバックアドレスで待ち受けるサーバーで、API keyを設定せずにサーバーツール、MCPサーバー、MCPプロキシを公開できるようにする設定です。
公式サーバーオプション一覧では、デフォルトで無効になっています。利用対象も信頼できるネットワークに限定するよう案内されています。
127.0.0.1で待ち受ければ接続元はローカルマシンに限られます。一方、0.0.0.0にバインドすると、別のネットワークインターフェースから接続できる場合があります。
そのため、非ループバックの公開、ツールまたはMCPの有効化、API keyなしの設定が重なる場合は、セキュリティを確認してください。
許可用のフラグは次のとおりです。
--allow-unauthenticated-tools
更新時の一般的な修正として追加しないでください。セキュリティ上重要なサーバー機能への未認証アクセスを許可してしまいます。
この設定が対象とするのはサーバー側のツールとMCPです。モデルが構造化されたtool_callsを返す処理とは区別してください。
同じマシンで開発しているなら、ローカル接続を推奨します。
./build/bin/llama-server \
-m /path/to/model.gguf \
--host 127.0.0.1 \
--port 8080 \
--jinja
リモートクライアントには、文書化された--api-keyによる認証と適切なネットワーク制限を使います。
Bashでは、入力内容を表示せずにキーを読み込みます。
read -rs LLAMA_SERVER_API_KEY && export LLAMA_SERVER_API_KEY
続いて、環境変数を参照してサーバーを起動します。
./build/bin/llama-server \
-m /path/to/model.gguf \
--host 0.0.0.0 \
--port 8080 \
--jinja \
--api-key "$LLAMA_SERVER_API_KEY"
サーバーには適切なネットワークアクセス制限も設定してください。API keyだけで、任意のインターネット公開環境が安全になるわけではありません。
—media-allow-private-urls
もう1つの変更は、画像参照など、サーバーに送信されるHTTP(S)メディアURLに関するものです。
デフォルトでは、ローカルアドレスやプライベートネットワークアドレスを指すURLへのアクセスは許可されません。
明示的に許可するフラグは次のとおりです。
--media-allow-private-urls
有効にすると、ローカルまたはプライベートアドレス上のHTTP(S)メディアを読み込めます。
信頼できるアプリケーションが社内サーバーに画像を置いている場合には役立ちます。ただし、信頼できないユーザーがURLを指定できると、SSRF(サーバー側リクエスト偽造)のリスクが高まります。
可能であれば、対応形式で画像データを直接送るか、管理されたメディア配信先を利用してください。
プライベートURLへのアクセスが必要な場合は、リクエストを送信できるユーザーとサーバーから到達できる宛先を制限します。信頼できないURLを通すためだけに有効にしないでください。
その他のセキュリティ修正
リリースには次の変更も含まれています。
--cors-originsの検証とオリジン照合の修正。- DNS rebindingへの対策。
- CORSプロキシ経由のSSRFへの対策。
- 子サーバーインスタンスへのブラウザーからの直接アクセスの修正。
HF_TOKENの送信先の制限。- クライアント切断またはタイムアウト時のMCPツール呼び出しのキャンセル。
HF_TOKENの送信先はhuggingface.coホストに制限されます。
コーディングエージェントでは、クライアントが切断された後に不要なMCPツール呼び出しが続かないことが重要です。
ただし、キャンセル通知によって、外部ツールがすでに行った操作まで自動的に元に戻るわけではありません。
詳細はPR #32113、PR #32115、v1.0.0のリリースノートを参照してください。
更新後にローカルのコーディングエージェントを検証するには?
Claude Code、OpenCodeなどを再接続する前に、サーバーで通常のモデル生成が動くことを確認してください。
まず、ツール呼び出しに適した指示追従モデルを使い、ループバック専用のサーバーを起動します。
./build/bin/llama-server \
-m /path/to/coding-model.gguf \
--alias local-coder \
-c 32768 \
--host 127.0.0.1 \
--port 8080 \
--jinja
モデル自体が、クライアントに必要なツール呼び出し形式に対応している必要があります。
--jinjaはチャットテンプレート処理を有効にします。ツールを使えないモデルに、その能力を追加するわけではありません。
curlでモデル一覧を確認します。
curl --fail-with-body \
http://127.0.0.1:8080/v1/models
レスポンスに設定したモデルのエイリアスが表示されることを確認してください。
次に、簡単なチャットリクエストを送ります。
curl --fail-with-body \
http://127.0.0.1:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "local-coder",
"messages": [
{
"role": "user",
"content": "Explain what a Git diff shows in one sentence."
}
],
"max_tokens": 100
}'
レスポンスのchoicesに生成結果が含まれることを確認します。
その後、コーディングツールが文書化しているカスタムプロバイダー設定を使用します。ローカルのOpenAI互換APIのBase URLは次のとおりです。
http://127.0.0.1:8080/v1
OpenAI Chat Completionsに対応していても、Anthropic Messages APIやOpenAI Responses APIとの完全な互換性があるとは限りません。
Claude Codeをローカルサーバーへ接続する場合は、プロトコルアダプターなどの対応手段が必要になることがあります。OpenCodeでは、APIとモデル設定が一致するカスタムプロバイダーを利用できます。
実際のリポジトリに接続する前に、ファイルの読み取り、編集案の作成、ツール呼び出しをそれぞれ1回確認してください。
テキスト生成だけが成功しても、構造化引数、ファイル操作、長時間の会話が正しく動くとは限りません。
モデル選択については、Kimi K3.1 ProのClaude Code・Codex設定ガイドも参考になります。Kimi K3.1 Proの公開ウェイトとライセンスのガイドでは、ローカル実行とホスト型APIの要件を比較できます。
OllamaとLM Studioのユーザーも更新が必要?
OllamaやLM Studioを完成されたアプリケーションとして使用している場合は、内部のllama.cppライブラリを手動で置き換えないでください。
これらのアプリケーションは、組み込む推論エンジンのバージョン、配布形式、互換性テストを独自に管理しています。
llama.cpp 1.0.0のリリースだけでは、すべての下流アプリケーションがすでに採用したとは判断できません。
実際の組み込みバージョンは、それぞれのリリースノートと更新手順で確認してください。
特に次の変更があれば注意が必要です。
- 更新履歴にllama.cpp 1.0.0や関連する変更が明記されている。
- 新しいKVキャッシュ形式やMoEキャッシュ設定が追加される。
- サーバーツールやMCPの認証要件が変わる。
- 更新後にモデルの読み込みやツール呼び出しの動作が変わる。
通常のデスクトップチャットでは、特定の修正や機能が必要でなければ、動作しているサポート対象バージョンを使い続けてもかまいません。
一方、アプリケーションをコーディングエージェントのバックエンドとして使用する場合は、更新のたびにクライアントからサーバーまでの動作を検証してください。
ホスト型APIへの切り替えを検討するタイミング
選んだモデルを必要なコンテキスト長と速度で実行できるなら、ローカル推論は有効な選択肢です。
FP8 KVキャッシュはメモリ使用量を減らせる可能性があります。MoEキャッシュも、一部のエキスパートをRAMに置く構成では効果が期待できます。ただし、すべてのメモリ制約を解決したり、コーディングを必ず高速化したりする機能ではありません。
モデルの重み、Attentionキャッシュ、同時リクエストがハードウェアの容量を超える場合は、小型のローカルモデルとホスト型モデルを比較してください。
ホスト型APIなら、モデルのGPUメモリを自分で管理する必要がなくなります。一方で、ネットワーク、従量課金、プロバイダーへの依存が生じます。
BetterTokenは、複数モデルへの従量課金APIアクセスを提供する選択肢の1つです。ローカルのllama.cpp実行環境や、そのサーバーセキュリティ機能を提供するものではありません。
ホスト型モデルを選ぶ前に、利用するモデルと処理量の費用を最新の料金ページで確認してください。
ローカルとホスト型を切り替える場合は、それぞれ個別にテストしたプロバイダー設定を保持します。同じモデルID、ツール形式、認証設定が両方のエンドポイントで使えるとは限りません。
安全に更新するためのチェックリスト
本番環境のローカルコーディングバックエンドを切り替える前に、次を確認してください。
v1.0.0のソースか、正確なビルド成果物を固定します。--defrag-tholdと削除されたC APIの呼び出しを取り除きます。- 新しい公開ヘッダーに合わせてネイティブバインディングを再ビルドします。
- まず従来のFP16 KVキャッシュ設定で動作を確認します。
- FP8 KVを別途試し、メモリ、速度、コーディング品質を比較します。
- MoEキャッシュは、対応GPUとCPUメモリ上のエキスパートがある場合に調整します。
- ツール認証とプライベートメディアURLの制限を確認します。
/v1/models、チャット生成、ツール呼び出し、コーディングクライアントを検証します。- 問題発生時に戻せるよう、以前のバイナリと設定を保存します。
llama.cpp 1.0.0では、公開Cライブラリの互換性に関する境界が明確になりました。それでも実際の更新では、バインディング、ハードウェア、サーバーの公開範囲、エージェントの処理を個別に検証する必要があります。