llama.cppをDockerで動かす方法：CPU・NVIDIA GPU対応ガイド

この記事でわかること

llama.cpp公式Dockerイメージを使い、ホスト環境を汚さずにローカルLLMのAPIサーバーを起動する手順をまとめます。

• 用途に合う公式イメージの選び方
• CPUとNVIDIA GPUそれぞれの起動方法
• Docker Composeによる常駐化
• APIをインターネットへ露出させない安全な公開方法

対象環境: Ubuntu 24.04 LTSなどの64ビットLinux。コマンドは2026年7月12日時点の公式情報をもとにしています。

Dockerでllama.cppを動かすメリット

llama.cppはソースからビルドできますが、CUDAやROCmなどGPUバックエンドの組み合わせによって依存関係が変わります。Dockerを使うと、実行ファイルと必要なライブラリをイメージ内にまとめられるため、ホストOS側の変更を抑えられます。

特に次の用途に向いています。

• 複数バージョンを切り替えて検証したい
• OpenAI互換APIとして他のアプリから利用したい
• CPU版とCUDA版を同じ操作感で管理したい
• 環境を壊したときにコンテナごと作り直したい

llama.cppそのものの仕組みは、既存のllama.cppの基本解説も参照してください。

公式Dockerイメージの選び方

llama.cpp公式ドキュメントでは、用途別に複数のイメージが公開されています。最初にAPIサーバーを試すなら、必要な機能だけを含むserver系が分かりやすい選択です。

イメージ	主な内容	向いている用途
server	llama-server	APIサーバーとして利用
light	CLIと補完用コマンド	対話実行やバッチ処理
full	CLI、サーバー、変換・量子化ツール	GGUF作成まで行う検証環境
server-cuda	CUDA 12対応サーバー	NVIDIA GPU推論
server-cuda13	CUDA 13対応サーバー	対応ドライバーを使う新しい環境
server-rocm	ROCm対応サーバー	対応AMD GPU
server-vulkan	Vulkan対応サーバー	Vulkan対応GPUでの検証

対応プラットフォームや追加イメージは変更される可能性があります。実行前にllama.cpp公式Dockerドキュメントを確認してください。

事前準備

Docker Engineをインストールする

Ubuntuでは、Docker公式APTリポジトリからdocker-ce、containerd.io、Buildx、Composeプラグインを導入する方法が公式に案内されています。本番用途では、内容を確認しにくい一括インストールスクリプトより、APTリポジトリ方式を使うのが無難です。

導入手順はDocker EngineのUbuntu向け公式手順に従ってください。インストール後は次の2点を確認します。

sudo systemctl status docker
sudo docker run --rm hello-world

GGUFモデル用ディレクトリを作る

mkdir -p "$HOME/llama/models"

ダウンロードしたGGUFファイルをこのディレクトリへ置きます。以下では例としてmodel.ggufを使います。モデルごとの利用条件や再配布条件も必ず確認してください。

CPUでllama-serverを起動する

まず公式サーバーイメージを取得します。

sudo docker pull ghcr.io/ggml-org/llama.cpp:server

続いて、モデルディレクトリを読み取り専用でマウントして起動します。

sudo docker run --rm \
  --name llama-server \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/llama/models:/models:ro" \
  ghcr.io/ggml-org/llama.cpp:server \
  -m /models/model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

-p 127.0.0.1:8080:8080が重要です。ホスト側をループバックアドレスに限定し、APIがVPSの外部インターフェースへ直接公開されるのを防ぎます。

モデルの読み込みが完了したら、別ターミナルからヘルスチェックを実行します。

curl http://127.0.0.1:8080/health

正常時はHTTP 200と{"status":"ok"}が返ります。読み込み中は一時的に503になる場合があります。公式のAPI仕様はllama-server READMEで確認できます。

OpenAI互換APIを確認する

llama-serverはOpenAI互換エンドポイントを提供します。ローカルから次のように確認できます。

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "user", "content": "Dockerで動作していますか？"}
    ],
    "temperature": 0.7
  }'

利用するアプリが接続先URLを指定できる場合は、ベースURLをhttp://127.0.0.1:8080/v1へ向けます。

NVIDIA GPUで実行する

NVIDIA GPUをコンテナから利用するには、対応ドライバーに加えてNVIDIA Container Toolkitが必要です。Toolkit導入後、公式手順では次のコマンドでDockerランタイムを設定します。

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

詳細はNVIDIA Container Toolkit公式インストールガイドを確認してください。

GPUがコンテナから見えることを確認したら、CUDA対応イメージで起動します。

sudo docker run --rm \
  --name llama-server-cuda \
  --gpus all \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/llama/models:/models:ro" \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m /models/model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080 \
  --n-gpu-layers 99

--n-gpu-layers 99は可能なレイヤーをGPUへ載せる指定例です。VRAM不足になる場合は値を下げます。CUDA 12版とCUDA 13版のどちらを使うかは、ホストのドライバーと公式イメージの要件を照合して決めてください。

Docker Composeで常駐させる

手動コマンドで動作を確認してから、Composeへ移すと原因を切り分けやすくなります。CPU版の最小構成例です。

services:
  llama:
    image: ghcr.io/ggml-org/llama.cpp:server
    container_name: llama-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./models:/models:ro
    command:
      - -m
      - /models/model.gguf
      - -c
      - "4096"
      - --host
      - 0.0.0.0
      - --port
      - "8080"

docker compose up -d
docker compose logs -f llama
docker compose ps

LinuxではComposeのスタンドアロン版は後方互換向けです。新規環境では公式Composeプラグインを利用します。

VPSで安全に公開する構成

8080番ポートをそのままインターネットへ開けるのは避けます。おすすめは次の構成です。

利用者 → HTTPS nginx → 127.0.0.1:8080 → llama-serverコンテナ

• Dockerのポートは127.0.0.1へ限定する
• nginx側でTLSを終端する
• 認証、接続元制限、リクエストサイズ制限を追加する
• モデルAPI用と公開Webサイト用でサブドメインを分ける
• 秘密情報をComposeファイルへ直接書かない

nginxは静的ファイル配信とリバースプロキシの両方を扱えます。複数サイトを同居させる設計は、2GB VPSで複数サイトを運営する構成で詳しく解説します。

よくあるトラブル

モデル読み込み中に503が返る

/healthはモデルのロード中に503を返します。ログを確認し、メモリ不足やGGUFパスの間違いがないか確認してください。

コンテナ内からGPUが見えない

ホスト側のnvidia-smi、NVIDIA Container Toolkit、Dockerランタイム設定の順に確認します。設定変更後はDockerデーモンの再起動が必要です。

すぐに終了する

モデルファイル名、ボリュームのマウント先、ファイルの読み取り権限を確認します。まず--rm付きの前景実行でログを読み、動作後にCompose化してください。

推論が極端に遅い

モデルサイズ、量子化、コンテキスト長、CPUスレッド数、GPUオフロード量を見直します。モデルが利用可能なRAMとVRAMに収まるかを最初に確認するのが近道です。

まとめ

API利用が目的ならserver、NVIDIA GPUならserver-cudaから始めると構成がシンプルです。最初はローカルホスト限定で起動し、ヘルスチェックとAPI応答を確認してからnginxや認証を追加してください。

Dockerの基本操作を復習したい場合は、既存のDocker完全ガイドもあわせて参照してください。

参考資料

• llama.cpp公式 Dockerドキュメント
• llama-server公式 README
• Docker Engine公式 Ubuntuインストール手順
• NVIDIA Container Toolkit公式ガイド