llama-cpp

llama.cpp の運用

各起動手順は、特定のビルド、モデル、ホスト、ワークロードに関する仮説として扱ってください。インストール済みバイナリで機能を確認し、モデルと起動ログを調べてから、要求された境界を測定してください。

運用上の契約

1. llama.cpp の正確なバージョンまたはコミット、インストール方法、OS とアーキテクチャ、CPU と RAM、アクセラレーターとメモリ、ドライバー／ツールキット、利用可能なデバイス、モデルの出所と量子化、想定するコンテキスト、同時実行数、ワークロードを記録してください。
2. ドキュメントに記載されたフラグを使用する前に、インストール済みコマンドの --help を確認してください。llama.cpp のフラグ、デフォルト値、バイナリ名、REST の動作は頻繁に変わります。
3. 実行前に、対象、範囲、ロールバック方法を確認してください。読み取り専用の調査は確認なしで進められます。
4. --list-devices とモデル読み込みログでバックエンドを確認してください。ビルドが成功したことや GPU フラグが受け付けられたことだけでは、アクセラレーションが有効である証明にはなりません。
5. ループバックまたはローカル入力で、範囲を限定した CLI のスモークテストから始めてください。スレッド、バッチ、コンテキスト、キャッシュ形式、オフロード、分割モードを変更する前に、測定済みのベースラインを確立してください。
6. 要求された境界に達した場合に限り、作業完了としてください。対象となる境界は、バイナリ、モデル読み込み、生成された出力、API 応答、ベンチマーク比較、または根拠を伴う障害の診断です。

使用しない場合

モデルのトレーニング、ファインチューニング、幅広い量子化の方法論、評価設計、または llama.cpp、vLLM、TGI などのエンジン選定には ml-engineering を使用してください。Ollama、LM Studio、LlamaIndex には、それぞれ該当する製品スキルを使用してください。llama-cpp-python、node-llama-cpp、その他の言語バインディングには、バインディング固有のドキュメントを使用してください。

読み取り専用の事前確認

インストール済みビルドに存在するコマンドのみを実行してください。

llama-cli --version
llama-cli --help
llama-cli --list-devices
llama-server --version
llama-server --help
llama-bench --help

また、OS およびベンダーのネイティブツールを使って、ホストのメモリとアクセラレーターの状態を確認してください。結果は運用記録に記録してください。バイナリが存在しない場合は、インストールとバックエンドを読んでから、インストール方法を選択してください。

タスクを振り分ける

必要な作業	最初に読む資料
インストール、ビルド、CPU／Metal／CUDA／HIP／Vulkan／SYCL の選択、Docker、またはバックエンドの使用確認	インストールとバックエンド
GGUF モデルの取得、変換、調査、ライセンス確認、量子化、または適合性の確認	モデル、GGUF、メモリ
llama-cli の実行、llama-server の公開、互換 API の呼び出し、テンプレート、構造化出力、埋め込み、再ランキング、またはツールの使用	推論とサービング
スレッド、バッチ、コンテキスト、キャッシュ、オフロード、同時実行、またはマルチ GPU の調整と結果の比較	パフォーマンスとベンチマーク
読み込み、バックエンド、OOM、速度、コンテキスト、テンプレート、出力、または API の障害の診断	トラブルシューティング
主張の根拠、調査日、上流リビジョン、または更新ルールの確認	ソースインデックス

バッチ推論と対話型チャット

llama-completion と対話型の llama-cli が分離されたビルドでは、無人実行の生の補完に llama-completion を使用します。インストール済みの CLI がヘルプで共通フラグを表示していても、実行時に拒否する場合があります。--no-conversation が存在するだけでは、バッチ処理に対応している証拠にはなりません。補完用のターゲットが見つからない場合、対話型フロントエンドには決してフォールバックしないでください。scripts/llama_batch.py を使用する前に、上限付きバッチ推論を読んでください。その plan コマンドは、上限付きの読み取り専用機能チェックを実行します。run は新しいプライベート出力ディレクトリに書き込み、GPU リソースを消費します。現在、このヘルパーがサポートするのは、モデルを完全にオフロードする POSIX CUDA0 です。他のバックエンドでは、別途検証済みのワークフローを使用してください。

プロセスの実行時間と、標準出力／標準エラー出力を合わせたバイト数に上限を設け、EOF を標準入力として渡し、失敗時のログを保持し、自分が起動したプロセスグループだけを停止してください。トークン数の上限だけでは、対話型プロンプトのループに上限を設けられません。capture_output=True によって、実行時の出力を上限のないバッファに蓄積しないでください。GPU へのフォールバックを隠したり、準備済みのプランを実行済みの推論パスと呼んだりしてはいけません。

安全なワークフロー

1. インストール方法を選択して検証する

コンパイル済みのバックエンドが対象に合致する場合は、サポート対象のパッケージまたはリリースバイナリを優先してください。バックエンドのオプション、移植性、再現性が必要な場合は、固定したリビジョンからビルドしてください。ホストの分離が有用で、デバイスのパススルーについて理解している場合は、Docker を使用してください。インストール後、成功を主張する前に、バージョン、ヘルプ、デバイス一覧、モデル読み込みログを記録してください。

2. モデルを選択して調査する

ユーザーが指定したローカルの GGUF パスまたは Hugging Face リポジトリを使用します。ダウンロードする前に、リポジトリ、リビジョン、ファイル、サイズ、モデルカード、ライセンス、ベースモデルの系譜、量子化子（入手可能な場合）を記録してください。GGUF メタデータとモデル読み込み出力を調べ、アーキテクチャ、量子化、コンテキスト、トークナイザー、チャットテンプレート、サイドカーを確認してください。容量は実際のファイルサイズに加え、KV キャッシュ、コンテキスト、バッチ／並行処理、計算バッファ、バックエンドのオーバーヘッドを基に見積もります。パラメーター数だけでは不十分です。

ある量子化方式が常に最適だとは考えないでください。ワークロードの品質と容量の制約を基準に選び、高精度のソースを利用できる場合は、すでに量子化されたモデルの再量子化を避け、同じタスク品質と性能のワークロードで候補となる量子化を比較してください。

3. ローカル推論を実証する

短く固定されたプロンプトと、上限を設けたトークン数を使用してください。正確なコマンド、シードまたはサンプリング設定、起動ログ、出力、処理時間、期待したバックエンドが読み込まれたかどうかを記録してください。モデルにチャットテンプレートがある場合は、単なる補完をチャットの証拠とみなさず、想定するワークロードで必要なテンプレートの経路をテストしてください。

4. サービングを実証する

初回起動時は 127.0.0.1 にバインドしてください。/health が準備完了を報告するまで待ち、/v1/models にクエリを送信した後、報告されたモデル識別子を使って代表的なリクエストを実行してください。プロセスが待ち受けていることや、簡易的なエンドポイントから HTTP 200 が返ることは、推論の証拠にはなりません。外部に公開する場合は、バインドアドレス、API キー、TLS またはリバースプロキシ、ファイアウォール、CORS、レート制限、ログ記録、実験的な組み込みツールを無効にするかどうかを明示的に決定する必要があります。

5. 一度に1つの要素だけを調整する

コンテキストサイズ、生成スレッドとバッチスレッド、論理バッチサイズまたは物理バッチサイズ、GPU レイヤー、KV キャッシュの種類／オフロード、Flash Attention、並列スロット、マルチ GPU 分割を変更する前に、ベースラインを保存してください。プロンプト処理とトークン生成の比較には llama-bench を使用し、TTFT とリクエストレイテンシの測定にはエンドツーエンドのクライアントまたはサーバーベンチマークを使用してください。各比較をベンチマークテンプレートに記録してください。

厳守すべき境界

• コマンドラインだけからアクセラレーターの使用を推測せず、デバイスと負荷ログの証拠を必須としてください。
• 認証されていないサーバーを、誤ってループバック以外に公開しないでください。認証はネットワークや TLS の制御の代わりにはなりません。
• マスキングされていないユニット定義、プロセス環境、環境ファイルの内容、API キー、その他の認証情報を含む設定を出力したり、tee で保存したりしないでください。マスキング済みのメタデータを優先し、証拠として秘密情報を保持しないでください。正確なロールバックのために秘密情報を含むバックアップが必要な場合は、リポジトリの外に一時的に保存し、モードを 0600 に設定して、保持期間を最小限にし、明示的に削除してください。生の秘密情報やエントロピーの低い秘密情報のハッシュを公開しないでください。
• 信頼できない環境では、llama-server に組み込まれたファイルシステムツールやシェルツールを有効にしないでください。
• モデルのメタデータ、元のモデルカード、レンダリング結果を確認するまでは、チャットテンプレートを上書きしないでください。
• finish_reason: "length" で reasoning_content に値があり、content が空の場合は、アクセス制御された生のレスポンスを確認しますが、報告するのはマスキング済みのフィールド状態、長さ、finish_reason、usage のみにしてください。同じベースラインから、変数を一つずつ変更した個別のプローブを実行してください。出力予算を上限付きで増やすプローブと、正確なテンプレートが対応している場合は chat_template_kwargs.enable_thinking: false を設定するプローブです。ストリーミングでは、choices[].delta.reasoning_content、choices[].delta.content、末尾の choices[].finish_reason について、文書化されたスキーマを確認してください。各項目は、存在しない、null、空、値ありのいずれかとして記録し、存在すると決めつけないでください。reasoning_effort: "none" とサーバー側の推論フラグは、バージョンによって異なるため、どこでも使える既定値ではなく、ソースで検証された代替手段として扱ってください。
• モデル、量子化、コミット、バックエンド、コンテキスト、バッチ、熱状態、ワークロードのいずれかが異なるベンチマーク値を、変数が一つだけ変わったかのように比較しないでください。
• llama-bench のトークン毎秒を TTFT として扱わないでください。計測対象にはトークン化とサンプリングが含まれません。
• モデルとスケーリングの挙動が裏付けており、ワークロードで評価されていない限り、設定したコンテキストを大きくしても品質が保たれると主張しないでください。

完了条件

要求された境界が証拠によって確認できれば、タスクは完了です。確認対象は、期待されるバイナリとバックエンドが観測されたこと、選択したモデルの出所と適合性が記録されたこと、上限付きのプロンプトから使用可能な出力が返ること、サーバーが準備完了状態になり、代表的な API リクエストを完了できること、チューニング変更が条件を揃えた状態で宣言済みの指標を上回るか維持すること、または失敗の原因が裏付けのあるものに絞り込まれ、安全な次のアクションが示されることです。テストしていない、より厳しい境界があれば列挙してください。