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

結論

llama-serverを公開するときは、processをloopback addressへ限定し、API keyを有効にしたうえで、nginxにTLS、流量制限、接続元制御を担当させます。OpenAI互換APIは完全互換を意味しないため、production applicationが使うrequestを固定版で回帰testします。

確認日時: 2026年8月12日 23:28（Asia/Tokyo）
対象版: llama.cpp b10375（commit ba360efe1f574ebae727aad64112d18ecedca85a）
検証区分: llama.cppとnginxの公式documentを照合した机上調査です。server起動、TLS、負荷、速度、memory、障害復旧は実環境で検証していません。

推奨する通信経路

client
  ↓ HTTPS + Bearer API key
nginx（TLS・rate limit・access control）
  ↓ 127.0.0.1
llama-server（API key・model inference）
  ↓
GGUF / CPU・GPU

nginxとllama-serverを同じhostで動かす例です。model processをpublic interfaceへ直接bindしないため、TLS certificateやaccess policyをWeb server側で更新できます。Dockerを使う場合はllama.cpp Dockerガイドも参照してください。

固定版をloopbackで起動する

API key fileはserver processだけが読めるpermissionにし、keyを1行ずつ保存します。key本体をshell history、unit file、repository、logへ書かないでください。

llama-server \
  -m /srv/models/model.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  --n-gpu-layers auto \
  --api-key-file /run/secrets/llama_api_keys

option	b10375の仕様	運用上の判断
`--host`	defaultは`127.0.0.1`	明示して意図しない外部bindを防ぐ
`--port`	defaultは`8080`	firewallとproxy先を一致させる
`-c`	default 0でmodelから取得	必要な入力長とKV cache実測後に固定
`-np`	defaultはauto	同時request時のlatencyとmemoryで決定
`--n-gpu-layers`	数値、`auto`、`all`	defaultのautoから始め、起動logとmemoryを確認
`--api-key-file`	改行区切りのAPI key file	secret管理とrotationを別途設計

optionは対象binaryのllama-server --helpとb10375のserver READMEを優先します。固定の大きなcontextや多数のparallel slotを最初から指定しない方が、memory不足の原因を切り分けやすくなります。

health checkの仕様

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

b10375では/healthと/v1/healthを利用できます。model loading中はHTTP 503、readyになると200と{"status":"ok"}が返ります。/healthはAPI key認証の対象外なので、公開側ではmonitoring hostだけに許可するか、外部へrouteしない構成にします。

process監視だけでなく、health status、request latency、queue、HTTP error、GPU・system memory、再起動回数を記録します。health 200は生成品質や十分な空きmemoryを保証しません。

nginx reverse proxyの例

limit_req_zoneはnginx設定のhttpcontextへ置きます。次の値は構文例であり、rate、timeout、certificate path、monitoring addressは実trafficに合わせて決めます。

limit_req_zone $binary_remote_addr zone=llm_api:10m rate=2r/s;

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

    ssl_certificate /etc/letsencrypt/live/llm.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/llm.example.com/privkey.pem;
    client_max_body_size 10m;

    location / {
        limit_req zone=llm_api burst=10 nodelay;
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Authorization $http_authorization;
        proxy_buffering off;
        proxy_read_timeout 600s;
    }

    location ~ ^/(v1/)?health$ {
        allow 192.0.2.10;
        deny all;
        proxy_pass http://127.0.0.1:8080;
    }
}

この例のhttp2 on;directiveはnginx 1.25.1以降が対象です。現在のnginx HTTP/2 documentはlisten 443 ssl;とhttp2 on;を分ける例を示しています。古いnginxを使う場合は、そのversionの公式documentを参照してください。変更後はnginx -tで検証し、reload前後にlocalとexternalの両方から確認します。

streaming responseではproxy_buffering offを使い、長い生成に合わせてproxy_read_timeoutを調整します。認証proxyがAuthorizationheaderを独自利用する場合は、llama-serverへ渡すBearer keyとの衝突を避ける設計が必要です。

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
  }'

LLM_API_KEYはshell environmentやsecret managerから渡し、commandそのものへ値を直書きしません。「OpenAI互換」は、OpenAI APIの全endpoint・parameter・responseが一致する意味ではありません。tools、structured output、reasoning、streaming、error responseを使うclientは実requestで確認します。

contextと並列数を決める

1 requestで実際の最大入力と生成を確認する
-cを必要量へ固定し、KV cacheを含むmemoryを測る
-npを段階的に増やし、per-request latencyとerror率を測る
trafficに近いprompt長の分布で負荷testする

peak時に受け付けられないrequestを無制限にserverへ流さず、proxyまたはqueueで上限を設けます。生成token数にもapplication側の上限を設けます。

logとprivacy

llama.cpp tag、commit、build option
GGUF repository、file名、hash
起動option、backend、driver
HTTP status、latency、input・output token数
OOM、timeout、model load error、restart

promptとresponseには個人情報、credential、社外秘が含まれ得ます。本文をdefaultで保存せず、目的、保持期間、閲覧者、削除方法を決めます。access logのquery stringやheaderにもsecretを残さないよう確認します。

更新とrollback

binaryはrelease tagとcommit、containerは解決したdigestまで記録します。新buildを別portで起動し、health、代表request、tool call、streaming、同時実行、memoryを確認してから切り替えます。

llama-benchはprompt processingとtext generationの比較に使えますが、tokenizationとsampling時間を含みません。productionではend-to-end latencyとerror率も測定します。最新版の確認方法はllama.cpp最新動向で整理しています。

情報源と未検証範囲

2026-05-30: llama-bench b10375 README
2026-08-11: llama-server b10375 README
2026-08-12: llama.cpp b10375 release
2026-08-12確認: nginx HTTP/2 module、nginx proxy module

未検証: 記載したnginx設定の環境適合性、certificate発行、API key rotation、client互換性、負荷上限、必要memory、障害時の自動復旧、長時間運転は確認していません。stagingでtestしてから段階的に公開してください。