K-FutureBlogBuild locally. Think clearly.
AILLMLinux

llama-server本番運用ガイド：OpenAI互換APIを安全に公開する

Written by KFB

llama.cppのllama-serverを本番運用する際の並列数、コンテキスト、ヘルスチェック、nginx、認証、ログと更新手順を解説します。

llama-server本番運用ガイド：OpenAI互換APIを安全に公開するのイメージイラスト

結論

llama-serverはOpenAI互換APIとして実用的ですが、プロセスを0.0.0.0で直接公開するだけでは本番構成になりません。推奨構成はllama-serverを127.0.0.1へ限定し、nginxでTLS・認証・流量制限を担当する形です。

推奨構成

クライアント
  ↓ HTTPS + 認証
nginx
  ↓ 127.0.0.1
llama-server
  ↓
GGUF / GPU・CPU

この分離により、モデルプロセスをインターネットから隠し、証明書更新やアクセス制御を一般的なWebサーバー側で扱えます。Docker起動から始める場合はllama.cpp Dockerガイドも参照してください。

最小の安全な起動例

llama-server \
  -m /srv/models/model.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  -c 32768 \
  -np 2 \
  --n-gpu-layers 99
指定役割注意
--host 127.0.0.1外部から直接接続させないnginxと同一ホストの場合
-c 32768全体のコンテキスト容量長くするほどKV cacheが増える
-np 2並列スロット数増やすほど各リクエストの利用可能文脈とメモリを要確認
--n-gpu-layers 99可能な層をGPUへオフロードVRAM不足なら下げる

引数は更新されるため、導入したビルドのllama-server --helpと公式サーバー仕様を優先してください。

ヘルスチェック

curl --fail http://127.0.0.1:8080/health

モデルが利用可能ならHTTP 200、ロード中などは503になる場合があります。監視では「プロセスが存在する」だけでなく、/healthの応答、応答時間、GPUメモリ、エラーログを見ます。

nginxのリバースプロキシ例

server {
    listen 443 ssl http2;
    server_name llm.example.com;

    client_max_body_size 10m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 600s;
    }
}

ストリーミング応答ではproxy_buffering offが重要です。TLS証明書、認証、レート制限は環境に合わせて追加します。APIキーをnginx設定へ平文で直書きするより、認証プロキシや秘密情報管理の仕組みを使う方が安全です。

OpenAI互換APIの確認

curl https://llm.example.com/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "local-model",
    "messages": [{"role":"user","content":"短く自己紹介してください"}],
    "stream": false
  }'

「OpenAI互換」は、すべてのパラメータと応答が完全一致する意味ではありません。接続するアプリがtools、structured output、reasoningなどを使う場合は、実リクエストで互換性を確認します。

並列数とコンテキストの決め方

最初から最大コンテキストと多数並列を指定すると、KV cacheが大きくなり、起動失敗や応答速度低下を招きます。次の順番で増やすと原因を切り分けやすくなります。

  1. -np 1、短いコンテキストで単発応答を確認
  2. 実際の最大入力長まで-cを増やす
  3. 同時利用者数に合わせて-npを増やす
  4. 負荷試験でTTFT、生成速度、エラー率、メモリを記録

ピーク性能だけでなく、2件・4件と同時実行したときの1リクエスト当たり遅延を見てください。

ログへ残すべき情報

  • llama.cppのビルド番号とコミット
  • GGUFリポジトリ、ファイル名、ハッシュ
  • 起動引数とGPUドライバー
  • HTTPステータス、処理時間、入力・出力トークン数
  • OOM、タイムアウト、モデルロード失敗

利用者のプロンプトには個人情報や機密情報が含まれ得ます。本文をそのまま保存するかは別問題として判断し、必要ならメタデータだけを記録します。

更新とロールバック

llama.cppは更新が速いため、本番バイナリやDockerタグを固定します。新ビルドは別ポートで起動し、ヘルスチェック、代表プロンプト、llama-bench、同時実行試験を通してから切り替えます。最新版の確認方法はllama.cpp 2026年7月の開発状況で解説しています。

まとめ

本番運用の要点は、ローカルバインド、TLSと認証の分離、現実的な並列数、アプリ単位の互換性確認、ビルド固定の5点です。小さく起動して測定し、必要な容量だけ増やす方が安定したAPIになります。

NEXT READ

関連記事