Docker Composeでllama‑serverを動かす

こんにちは、色違いモノです。

私はローカルLLMってロマンだと思っています。
LLMをローカルで走らせたいけど、linux環境構築ってよくわがんね
そんなときに便利なのが Docker Compose の llama.cpp のサーバーコンテナです。それは完全で完璧なソリューションを提供します。😋

仕組みなどは置いといて、とにかく動かすために必要なことについてまとめようと思います。
とりあえず、今使っている compose.yaml ファイルをLLMに投げて簡単に解説してもらいました。

• 要約

• images 使用するDockerイメージ（リポジトリ:タグ）を指定
• ports ホストとコンテナ間のポートマッピングを設定
• environment でモデルパスやハイパーパラメータを注入
• command は起動オプション全般（GPU層数・コンテキストサイズ等）
• restart: unless‑stopped … コンテナが落ちても自動再起動

事前知識

Dockerとは

Dockerは、アプリケーションやサービスを「コンテナ」という実行環境にまとめて動かすためのプラットフォームです。コンテナは OS カーネルを共有しつつ(よくある仮想マシンではなく)、ファイルシステム・ネットワーク・依存ライブラリを分離しているため、「このマシンで動く」ことが保証された形でコードを配布・実行できます。

Docker compose とは

Docker Composeは、複数のコンテナサービスを YAML ファイルで定義し、一括で起動・管理できるツールです。ネットワークやボリュームの共有、環境変数の設定も同じファイルに記述できるため、マルチコンテナ構成の構築・テストが非常に楽になります。

compose.yaml全体像

services:
  llama-cpp-vulkan:
    image: ghcr.io/ggml-org/llama.cpp:server-vulkan
    ports:
      - "10000:10000"
    volumes:
      - ./models:/app/models
      - llama-cache:/app/cache
    environment:
      - LLAMA_MODEL=${LLAMA_MODEL}
      - LLAMA_CTX_SIZE=${LLAMA_CTX_SIZE:-128000}
      - LLAMA_N_GPU_LAYERS=${LLAMA_N_GPU_LAYERS:-99}
      - LLAMA_BATCH_SIZE=${LLAMA_BATCH_SIZE:-2048}
      - LLAMA_UBATCH_SIZE=${LLAMA_UBATCH_SIZE:-1024}
      - LLAMA_THREADS=${LLAMA_THREADS:-16}
      - LLAMA_N_PARALLEL=${LLAMA_N_PARALLEL:-8}
      - LLAMA_TEMP=${LLAMA_TEMP:-0.8}
      - LLAMA_TOP_K=${LLAMA_TOP_K:-40}
      - LLAMA_TOP_P=${LLAMA_TOP_P:-0.95}
      - LLAMA_MIN_P=${LLAMA_MIN_P:-0.05}
      - LLAMA_REPEAT_PENALTY=${LLAMA_REPEAT_PENALTY:-1.1}
      - LLAMA_CACHE=/app/cache
    command: >
      --model ${LLAMA_MODEL}
      --alias ${LLAMA_MODEL_ALIAS}
      --host 0.0.0.0
      --port 10000
      --ctx-size ${LLAMA_CTX_SIZE:-128000}
      --n-gpu-layers ${LLAMA_N_GPU_LAYERS:-99}
      --batch-size ${LLAMA_BATCH_SIZE:-1024}
      --ubatch-size ${LLAMA_UBATCH_SIZE:-512}
      --threads ${LLAMA_THREADS:-16}
      --threads-batch ${LLAMA_THREADS:-16}
      --parallel ${LLAMA_N_PARALLEL:-8}
      --temp ${LLAMA_TEMP:-0.8}
      --top-k ${LLAMA_TOP_K:-40}
      --top-p ${LLAMA_TOP_P:-0.95}
      --min-p ${LLAMA_MIN_P:-0.05}
      --repeat-penalty ${LLAMA_REPEAT_PENALTY:-1.1}
      --cont-batching
      --log-verbose
      --mlock
      --jinja
      --reasoning-format auto
    restart: unless-stopped
    devices:
      - /dev/kfd:/dev/kfd
      - /dev/dri:/dev/dri
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
volumes:
  llama-cache:

services: セクション

サービス名

自分的にコンテナ内で実行されるサーバーが分かりやすいように llama-cpp-vulkan としました。

image: コンテナイメージ

ghcr.io/ggml-org/llama.cpp:server-vulkan は、llama.cpp の Vulkan（GPU）バックエンドを利用したサーバーモードのコンテナです。
私のPCは、CPUがRyzen9 AI MAX+ 395 (dGPU無し)なので、ROCmかVulkanなのですが、ROCmはまだ調べきれていないのでとりあえずVulkanを使用しています。

ports: ホストとコンテナのポートマッピング

"10000:10000" は ホスト側 10000 ポート ↔ コンテナ側 10000 ポート を結ぶ設定です。

volumes: モデル置き場

./models:/app/models は ./models ディレクトリをコンテナの /app/models ディレクトリにマウントしています。
そのため、ダウンロードしたモデルは./modelsに置くようにします。

environment: 環境変数でパラメータ注入

environmentに設定すると、コンテナ内限定の環境変数を設定できます。
${ ... }変数は別ファイル(.envファイル)に記述できるので、モデルごとに設定を変えるなんてこともできます。

今回設定した変数それぞれの意味以下の通りです。

• LLAMA_MODEL … 使用するモデルファイルへのパス
• LLAMA_CTX_SIZE … コンテキストウィンドウのトークン上限（デフォルト 128k）。
• LLAMA_N_GPU_LAYERS … GPU で実行する層数。
• LLAMA_BATCH_SIZE, LLAMA_UBATCH_SIZE … バッチ処理サイズ。
• LLAMA_THREADS, LLAMA_N_PARALLEL … CPU スレッド数と並列推論数。
• LLAMA_TEMP, LLAMA_TOP_K, LLAMA_TOP_P, LLAMA_MIN_P … 生成時の温度・サンプリングパラメータ。
• LLAMA_REPEAT_PENALTY … 同一トークン繰り返しペナルティ。

command: サーバー起動オプション

command: では llama.cpp-serverに渡す引数を列挙しています。

• --model ${LLAMA_MODEL} … モデルパス指定
• --alias ${LLAMA_MODEL_ALIAS} … 複数モデル運用時の別名
• --host 0.0.0.0 & --port 10000 … 外部からアクセス可能にする設定
• --n-gpu-layers ${LLAMA_N_GPU_LAYERS:-99} … GPU に割り当てる層数
• --ctx-size, --batch-size, --ubatch-size … 前述の環境変数と同様
• --cont-batching & --log-verbose & --mlock & --jinja & --reasoning-format auto は高度な最適化・デバッグ用ログ、リーズニングなどのフラグ

restart: コンテナの自動再起動ポリシー

unless-stopped は コンテナがクラッシュしたり Docker デーモンが再起動した場合でも、手動で docker stop されない限り自動的に再起動 する設定です。

devices: GPU デバイスのマウント

devices:
  - /dev/kfd:/dev/kfd
  - /dev/dri:/dev/dri

よくわかってないので、いつか勉強します。

logging: ログローテーション設定

Docker の標準ログドライバー json-file を使用し、

• max-size: "10m" … 1 ファイルあたり最大サイズ 10 MiB に制限
• max-file: "3" … 古いファイルを 3 個まで保持
  この設定でディスク容量の肥大化を防げます。

volumes: 永続ストレージ定義

名前付きボリューム llama‑cache を宣言しています。docker volume ls で確認でき、docker volume rm llama-cache で削除可能です。

---

まとめ: Docker Compose を使うことで Ryzen9 AI MAX+ 395 対応の llama.cpp サーバーを手軽に立ち上げることができました。
Docker、Docker composeは初めてだったのですが(というかlinuxあんまり触ったこと……)
ChatGPTに聞けば、意外とすんなり動きました。LLMすげー
と同時に、こんなに使いやすいコンテナを用意してくれている方々に感謝