llama.cppコマンド例10選｜llama-cli・llama-server用途別

先に結論

llama.cppを導入済みのmacOS／Linux環境で使える、用途別の実行コマンド10パターンを掲載します。
ローカルGGUFの対話、Hugging Faceからの取得、CPU限定、GPU自動調整、長文脈、JSON Schema、画像入力、2 GPU、APIサーバー、curlによるAPI確認を順に試せます。
本記事で使用するすべてのオプションを2026年7月30日時点の公式ソースと自動生成ヘルプ表へ照合し、Bash構文を検査しました。
モデルのロード、ダウンロード、推論、速度・VRAM・品質測定は実施していない机上調査です。数値は実測推奨値ではなく、構文を理解するための例です。

おすすめ読者: パラメータの意味は読んだものの、実際にどの順序でコマンドを組み立てるかイメージしにくい人。

確認日時: 2026年7月30日 07:45（Asia/Tokyo）
固定した版: llama.cpp master HEAD 3018a11e79e489b657dbb77c95694889ccff92df
検証区分: 公式README、docs、自動生成ヘルプ表、引数定義ソースを使った机上調査です。記事中のコマンドはBashとして構文検査しましたが、llama.cppバイナリやモデルは実行していません。
画像: アイキャッチは10種類のコマンド例を表現した当サイトの要点図解です。実際の端末画面ではありません。

この記事の前提と置き換える値

本記事はllama-cliとllama-serverがPATHにあり、任意のディレクトリから実行できる状態を前提にします。ソースからビルドした直後でPATHを設定していない場合は、コマンド名を./build/bin/llama-cliまたは./build/bin/llama-serverへ読み替えてください。

まだ導入していない場合は、Macでllama.cppを導入する方法から進めます。Dockerを使う場合はllama.cpp Dockerガイドを参照してください。

表記	置き換える内容	例
`/absolute/path/to/chat-model.gguf`	手元のGGUFの絶対パス	`/Users/name/models/model.gguf`
`/absolute/path/to/long-prompt.txt`	読み込ませるテキストファイル	`/Users/name/docs/request.txt`
`/absolute/path/to/input-image.jpg`	解析する画像	`/Users/name/Pictures/sample.jpg`
`/absolute/path/to/api-keys.txt`	新規作成するAPI key file	`/Users/name/.config/llama/api-keys.txt`
`CUDA0,CUDA1`	`--list-devices`に表示された2台のdevice名	環境により名称が異なる
`8192`、`32768`	例示用コンテキスト長	モデル上限と利用可能メモリに合わせる

Windows PowerShellでは変数代入、引用符、行継続の構文が異なります。本記事のコードブロックはBash／Zsh向けです。

パラメータの定義、既定値、廃止された旧名称を調べる場合は、llama.cpp主要パラメータ一覧を併用してください。

実行前に版・ヘルプ・deviceを確認する

最初に、記事と手元のバイナリの差を確認します。masterは頻繁に更新されるため、記事と異なるSHAやbuild番号が表示されること自体は異常ではありません。

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

--list-devicesでGPUやアクセラレーターが表示されない場合、起動オプションを増やす前にビルド時のバックエンド設定を確認します。Metal、CUDA、ROCm、Vulkan、SYCLの違いはllama.cpp GPUバックエンド比較で整理しています。

10パターンの早見表

No.	目的	主に使う指定
1	ローカルGGUFと対話	`-m`、`-cnv`、`-sys`
2	Hugging Faceから取得して1回生成	`-hf`、`-st`、`-p`
3	GPUを使わずCPUだけで確認	`-dev none`、`-t`
4	GPUメモリへ自動調整して起動	`-ngl auto`、`-fit on`、`-fa auto`
5	長い入力と量子化KVキャッシュ	`-c`、`-ctk`、`-ctv`、`-f`
6	JSON Schemaに沿って出力	`--json-schema`
7	画像をVLMへ入力	`--mmproj-auto`、`--image`
8	2台のGPUへlayer分割	`-dev`、`-sm layer`、`-ts`
9	localhostでAPIサーバーを起動	`--host`、`-np`、`--api-key-file`
10	OpenAI互換APIを`curl`で確認	`/v1/chat/completions`

llama-cliの実行コマンド例

1. ローカルGGUFを読み込み対話する

チャットテンプレートを持つGGUFを指定し、対話モードで起動する基本構成です。

MODEL_GGUF="/absolute/path/to/chat-model.gguf"

llama-cli \
  -m "$MODEL_GGUF" \
  -c 8192 \
  -n 256 \
  -cnv \
  -sys "回答は日本語で簡潔にまとめてください。"

-cnvは対話モードを明示します。対応チャットテンプレートがあれば自動で有効になる場合もあります。
-sysの反映方法はモデルのチャットテンプレートに依存します。
-c 8192と-n 256は例です。コンテキスト上限や出力長の推奨値ではありません。

確認ポイント: 起動直後にunknown argumentやchat templateのエラーが出ないこと、入力待ちになることを確認します。

2. Hugging FaceからGGUFを取得して1回だけ生成する

公式READMEのQuick startで使われている小型リポジトリを指定する例です。初回はモデルのダウンロードが発生します。

HF_REPO="ggml-org/gemma-3-1b-it-GGUF"

llama-cli \
  -hf "$HF_REPO" \
  -ngl auto \
  -fa auto \
  -c 8192 \
  -n 256 \
  -cnv \
  -st \
  -p "llama.cppを初めて使う人向けに、特徴を3項目で説明してください。"

-hfはHugging FaceリポジトリからGGUFを取得します。量子化を省略したときの選択規則は手元の--helpで確認してください。
-stはプロンプトへ1回応答した後に終了するsingle-turn指定です。
gated repositoryではtokenをコマンドへ直書きせず、HF_TOKEN環境変数を使用します。

確認ポイント: ダウンロード先の空き容量と通信量を確認します。モデルがロードされ、1回応答した後にprocessが終了することまで確認してください。

3. GPUオフロードを無効にしてCPUだけで確認する

GPUバックエンドの影響を切り分けたいときは、使用deviceをnoneへ固定します。

MODEL_GGUF="/absolute/path/to/chat-model.gguf"

llama-cli \
  -m "$MODEL_GGUF" \
  -dev none \
  -t 8 \
  -c 4096 \
  -n 256 \
  --temp 0 \
  -cnv \
  -st \
  -p "このモデルが応答できるか、短い1文で確認してください。"

-dev noneはオフロードdeviceを使用しません。
-t 8は例示値です。CPUや同時に使うアプリに合わせて変更してください。
--temp 0はgreedy samplingになりますが、異なるbuildやバックエンド間でのbit単位の完全再現を保証する指定ではありません。

確認ポイント: GPU利用率ではなく、まずモデルがロードされて1回の応答を返せるかを確認します。速度は本記事では評価しません。

4. GPUメモリへ自動調整して起動する

GPU対応buildで、オフロード層数とFlash Attentionを自動判定させる出発点です。

MODEL_GGUF="/absolute/path/to/chat-model.gguf"

llama-cli \
  -m "$MODEL_GGUF" \
  -ngl auto \
  -fit on \
  -fa auto \
  -c 8192 \
  -n 256 \
  -cnv \
  -st \
  -p "GPUオフロードを確認するための短い応答を返してください。"

-ngl autoはGPUへ置く最大layer数を自動で決めます。
-fit onは未指定の引数をdevice memoryへ収まるよう調整します。この例で明示した-c 8192は自動調整の対象外です。
-fa autoはモデルとバックエンドに応じてFlash Attentionを判定します。

確認ポイント: 起動ログで選択されたdeviceとオフロード状況を確認します。GPUが表示されなければ、--list-devicesとbuild設定へ戻ります。

5. 長いテキストを量子化KVキャッシュで処理する

長い依頼文をファイルから読み込み、32KのコンテキストとQ8_0のK／V cacheを明示する例です。

MODEL_GGUF="/absolute/path/to/chat-model.gguf"
PROMPT_FILE="/absolute/path/to/long-prompt.txt"

llama-cli \
  -m "$MODEL_GGUF" \
  -f "$PROMPT_FILE" \
  -c 32768 \
  -n 512 \
  -ngl auto \
  -fa on \
  -ctk q8_0 \
  -ctv q8_0 \
  --no-display-prompt

-fはファイル内容をプロンプトとして読み込みます。
-c 32768はモデルが32K以上のコンテキストを扱える場合だけ使用します。これは入力専用の枠ではなく、prompt tokenと生成tokenが共有する上限です。この例では-n 512の出力分も残す必要があり、「32K入力に512 tokenを追加できる」という意味ではありません。
量子化V cacheにはFlash Attentionが必要なため、-fa onを組み合わせています。非対応環境ではこの組み合わせを使えません。
KV cacheの量子化には品質や互換性上のトレードオフがあります。メモリ削減量や品質差は本記事では測定していません。

確認ポイント: OOMになった場合は、最初に-cを小さくし、それでも失敗する場合にモデル量子化やGPUオフロードを見直します。

6. JSON Schemaに沿ったJSONを生成する

シェル上でJSON Schemaを直接渡し、summaryとkeywordsを持つobjectへ出力を制約します。

MODEL_GGUF="/absolute/path/to/chat-model.gguf"
JSON_SCHEMA='{"type":"object","properties":{"summary":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}},"required":["summary","keywords"],"additionalProperties":false}'

llama-cli \
  -m "$MODEL_GGUF" \
  --json-schema "$JSON_SCHEMA" \
  -ngl auto \
  -fa auto \
  -c 8192 \
  -n 256 \
  -cnv \
  -st \
  -p "llama.cppの特徴を要約し、重要語を抽出してください。"

Schema全体をsingle quoteで囲むため、Bash／Zshが内部のdouble quoteをそのまま渡せます。
長いSchemaはJSONファイルへ保存し、-jf /absolute/path/to/schema.jsonで渡すと編集しやすくなります。
外部$refを含むSchemaは、-jfではなく公式のschema-to-grammar変換手順を使います。
Schemaは出力形式を制約します。内容の事実性を保証するものではありません。

確認ポイント: JSON parserで読み込めることに加え、必須keyと値の型がSchemaどおりかを確認します。

7. 画像をマルチモーダルモデルへ入力する

公式のmultimodal資料に掲載されたGemma 3 4BのGGUFを取得し、画像を1枚渡す例です。

IMAGE_FILE="/absolute/path/to/input-image.jpg"

llama-cli \
  -hf ggml-org/gemma-3-4b-it-GGUF \
  --mmproj-auto \
  --image "$IMAGE_FILE" \
  -ngl auto \
  -fa auto \
  -c 8192 \
  -n 256 \
  -cnv \
  -st \
  -p "この画像の内容を説明し、読める文字があれば列挙してください。"

-hf利用時は、利用可能な対応mmprojが自動取得されます。--mmproj-autoはその動作を明示しています。
ローカルファイルを使う場合は、言語モデルと対応するmmprojを-mと--mmprojで別々に指定します。
multimodal機能は公式資料でも開発変化が大きい領域とされているため、手元の版の--helpと公式multimodal資料を必ず確認してください。

確認ポイント: 1B版Gemma 3にはvision機能がないため、この例の4b-itを1b-itへ置き換えないでください。

8. 2台のGPUへlayer単位で分割する

複数GPUで最初に試す、互換性を優先したlayer splitの例です。

MODEL_GGUF="/absolute/path/to/chat-model.gguf"
GPU_DEVICES="CUDA0,CUDA1"

llama-cli --list-devices

llama-cli \
  -m "$MODEL_GGUF" \
  -dev "$GPU_DEVICES" \
  -sm layer \
  -ts 3,1 \
  -ngl all \
  -fit off \
  -fa auto \
  -c 8192 \
  -cnv

CUDA0,CUDA1は例です。必ず--list-devicesに表示された名称へ置き換えます。
-ts 3,1はdeviceの並び順に75％／25％という比率を示します。推奨比率やVRAM容量そのものではありません。
現行のauto-fit実装は、利用者が-tsを指定した構成を調整しないため、この例では-fit offを明示します。自動配分を使う場合は-ts 3,1と-fit offを外し、-ngl auto -fit onへ変更します。
-ngl allでは全layerのGPU offloadを試みます。モデル全体とKV cacheが2台の空きVRAMへ収まることを事前に確認してください。
layerは現行の既定かつ互換性を優先するsplit modeです。rowは非推奨、tensorは実験的で追加制約があります。

確認ポイント: 2台へ割り当てられたことを起動ログで確認します。OOMの場合は-cを下げる、より小さいモデルを使う、または上記の自動配分へ戻します。詳しい制約は公式Multi-GPU資料で確認できます。

llama-serverとAPIの実行コマンド例

9. localhost限定のOpenAI互換APIサーバーを起動する

API keyをファイルへ保存し、localhostだけで待ち受ける例です。2つのserver slotとunified KV、continuous batchingを明示します。

MODEL_GGUF="/absolute/path/to/chat-model.gguf"
API_KEYS_FILE="/absolute/path/to/api-keys.txt"

(umask 077; set -o noclobber; openssl rand -hex 32 > "$API_KEYS_FILE")

llama-server \
  -m "$MODEL_GGUF" \
  -a kfb-local \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl auto \
  -fa auto \
  -c 16384 \
  -np 2 \
  -kvu \
  -cb \
  --api-key-file "$API_KEYS_FILE" \
  --metrics \
  --no-ui

--host 127.0.0.1により同じマシンのloopbackからだけ接続します。
API_KEYS_FILEには、親directoryを先に作成したうえで未使用の新しいパスを指定します。noclobberを有効にしているため、同名ファイルがあれば上書きせず失敗します。既存keyを使う場合は生成行を実行しません。
API key fileは1行1keyです。#で始まる行はcommentとして扱われます。
-np 2は2つのserver slot、-kvuは全sequenceで共有するunified KV buffer、-cbはcontinuous batchingを明示します。
-c 16384は共有コンテキストの例です。各requestへ常に8Kずつ保証する指定ではありません。
unified KVにはモデル固有の制約が加わる場合があります。起動ログと使用モデルの公式資料も確認してください。
API keyは通信を暗号化しません。0.0.0.0へ変更して外部公開する場合は、llama-server本番運用ガイドに沿ってTLS、認証、アクセス制御を設計してください。

確認ポイント: 起動後、別のterminalで次を実行します。

curl --fail-with-body -sS http://127.0.0.1:8080/health

公式/health仕様では、このendpointはAPI key検査の対象外です。ロード中はHTTP 503、準備完了後はHTTP 200と{"status":"ok"}を返します。

10. `curl`でOpenAI互換Chat Completions APIを確認する

例9のserverを起動したまま、別terminalから1件のrequestを送ります。

API_KEYS_FILE="/absolute/path/to/api-keys.txt"
API_KEY="$(awk 'NF && $0 !~ /^[[:space:]]*#/ { print; exit }' "$API_KEYS_FILE")"

curl --fail-with-body -sS http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "model": "kfb-local",
    "messages": [
      {
        "role": "system",
        "content": "回答は日本語で簡潔にまとめてください。"
      },
      {
        "role": "user",
        "content": "llama.cppの特徴を3項目で説明してください。"
      }
    ],
    "max_tokens": 128,
    "temperature": 0.2
  }'

unset API_KEY

"model": "kfb-local"は例9の-a kfb-localと一致させます。
Authorization headerには、API key fileの空行とcommentを除いた最初のkeyを渡します。
max_tokensとtemperatureはAPI request側の例示値です。モデルや用途に合わせて変更します。

確認ポイント: HTTP応答のchoices配列、終了理由、usageを確認します。性能比較を行う場合は、モデル、量子化、prompt、context、出力長、commit SHAを固定して別途測定してください。

並列requestやslotの挙動を確認したい場合は、llama-serverの連続バッチング設定で/slots、/metrics、同時curlの手順を扱っています。

うまく動かないときの確認順

初回導入から確認する場合はllama.cppでGGUFを動かす方法、ロードで止まる場合はGGUFモデルが読み込めない原因と対処法、起動後の速度を調整する場合はllama.cppが遅い原因と高速化設定を先に参照してください。

症状	最初に確認すること
`command not found`	PATHを設定するか、`./build/bin/llama-cli`のように実体を指定
`unknown argument`	記事と手元の版が異なる可能性があるため、同じ実行ファイルの`--version`と`--help`を確認
モデルを開けない	絶対パス、読み取り権限、GGUFの破損、対応architectureを確認
GPUが使われない	`--list-devices`、GPUバックエンド付きbuild、`-ngl`、`-dev`を確認
起動時にOOM	`-c`、serverでは`-np`、モデルサイズ、KV cache型、GPU layer数の順に見直す
system promptが反映されない	モデルのchat templateと`-cnv`の適用を確認
JSON出力で失敗する	Schemaを単純化し、外部`$ref`の有無とshell quotingを確認
APIが401を返す	key fileの内容と`Authorization: Bearer ...`を確認
APIへ接続できない	serverの起動状態、host、port、firewallを確認

複数の設定を一度に変えると原因を切り分けにくくなります。最小コマンドで起動した後、コンテキスト、GPU、KV cache、並列数を1項目ずつ追加してください。

机上調査の範囲と再確認方法

本記事で実施したのは、固定SHAの公式資料とソースコードを使ったオプション名・値・組み合わせの確認、ならびにBash構文検査です。次の内容は実施していません。

llama.cppのビルドとバイナリ実行
GGUF／mmprojのダウンロードとモデルロード
CPU、Metal、CUDA、ROCm、Vulkan、SYCLでの推論
速度、VRAM、RAM、消費電力、出力品質の測定
10例すべてのモデル／ハードウェア互換性の実機検証

そのため、本記事に実測値は掲載せず、「この設定なら何tok/sになる」「必ず何GB削減できる」といった推測も行いません。実行時は次を記録すると、後から条件を比較しやすくなります。

llama-cli --version
llama-cli --list-devices
shasum -a 256 "/absolute/path/to/chat-model.gguf"

Linuxでshasumがない場合はsha256sumを使用してください。モデル名だけでなくファイルhash、量子化、llama.cppの版、実行コマンド全文を一緒に保存します。

使用した公式一次情報

公式ヘルプ表はソースから自動生成されています。それでも手元のbinaryが記事の固定SHAと同一とは限らないため、実行直前には必ずローカルのllama-cli --helpまたはllama-server --helpを優先してください。