🦙 Llama.cpp Docker Compose セットアップガイド

開発環境

WindowsでLlama.cppを簡単に動かすためのDocker Composeセットアップです。APIサーバーによる運用が可能です。

🎯 概要

このプロジェクトは、Windows環境でLlama.cppベースのAIモデルを手軽に実行するためのDocker Composeセットアップを提供します。複数の実行モード（CPU版・GPU版・高性能版）に対応し、用途に応じて最適な設定を選択できます。

✨ 特徴

  • 簡単セットアップ: Docker Composeによるワンコマンド起動
  • マルチ構成対応: CPU版・GPU版・高性能版から選択可能
  • 柔軟な設定: 環境変数による詳細なカスタマイズ
  • 運用機能: ヘルスチェック・ログ保存・自動再起動対応
  • GGUFモデル対応: 最新のGGUF形式モデルファイルをサポート

📁 ディレクトリ構成

llama-cpp-docker-compose/
├── models/                    # モデル(GGUF)ファイル配置用
│   ├── gemma3n-e2b-fixed.gguf # Gemma 3n E2B モデル (3.5GB)
│   └── gemma3n-e4b-fixed.gguf # Gemma 3n E4B モデル (5.0GB)
├── logs/                      # サーバーログ保存用
├── .env                      # 環境変数設定
├── .env.example              # 環境変数サンプル
├── .gitignore
├── docker-compose.yml        # GPU版設定（標準）
├── docker-compose.cpu.yml    # CPU版設定
├── docker-compose.high.yml   # 高性能版設定（RTX4090最適化）
└── README.md

🚀 セットアップ手順

1. 前提条件の確認

必要なソフトウェア:

  • Docker Desktop for Windows
  • Git（リポジトリクローン用）
  • NVIDIA Container Toolkit（GPU版使用時）

システム要件:

  • Windows 10/11
  • メモリ: 8GB以上（CPU版）/ 16GB以上（GPU版）
  • GPU: NVIDIA GPU（GPU版使用時、VRAM 8GB以上推奨）

2. リポジトリのクローン

git clone https://github.com/Sunwood-ai-labs/llama-cpp-docker-compose.git
cd llama-cpp-docker-compose

3. モデルファイルの配置

models/ディレクトリにGGUFファイルを配置してください。

対応モデル例:

  • llama-2-7b-chat.Q4_K_M.gguf
  • llama-2-13b-chat.Q4_K_M.gguf
  • gemma3n-e2b-fixed.gguf
  • gemma3n-e4b-fixed.gguf

Gemma 3n E2Bモデルのダウンロード例

# Gemma 3n E2B モデルをダウンロード
curl -L -o gemma3n-e2b-fixed.gguf \
  https://huggingface.co/unsloth/gemma-3n-E2B-it-GGUF/resolve/main/gemma-3n-E2B-it-UD-Q4_K_XL.gguf

# models/ ディレクトリに移動
mv gemma3n-e2b-fixed.gguf models/

4. 環境変数の設定

.env.exampleをコピーして.envを作成し、モデルファイル名などを設定してください。

cp .env.example .env

主要な設定項目:

# 使用するモデルファイル名
LLAMA_MODEL_FILE=gemma3n-e4b-fixed.gguf

# コンテキストサイズ
LLAMA_CTX_SIZE=2048

# 並列処理数
LLAMA_N_PARALLEL=2

# APIポート番号
LLAMA_PORT=8080

# GPU使用レイヤー数（GPU版のみ）
LLAMA_N_GPU_LAYERS=35

5. 実行

用途に応じて適切なDocker Composeファイルを選択してください。

GPU版（推奨）

docker-compose up -d

CPU版

docker-compose -f docker-compose.cpu.yml up -d

高性能版（RTX4090最適化）

docker-compose -f docker-compose.high.yml up -d

6. 動作確認

サーバーが正常に起動したことを確認します。

# ヘルスチェック
curl http://localhost:8080/health

# モデル情報取得
curl http://localhost:8080/v1/models

🔧 設定詳細

環境変数一覧

変数名 デフォルト値 説明
LLAMA_MODEL_FILE - 使用するGGUFモデルファイル名
LLAMA_CTX_SIZE 2048 コンテキストサイズ
LLAMA_N_PARALLEL 1 並列処理数
LLAMA_PORT 8080 APIサーバーポート
LLAMA_N_GPU_LAYERS 35 GPU使用レイヤー数
LLAMA_TEMP 1.0 生成時の温度パラメータ
LLAMA_TOP_K 64 Top-K サンプリング
LLAMA_TOP_P 0.95 Top-P サンプリング

実行モード比較

モード ファイル 対象 メモリ要件 特徴
CPU版 docker-compose.cpu.yml CPU実行 4-8GB 軽量、GPU不要
GPU版 docker-compose.yml NVIDIA GPU 8GB+ 標準的なGPU最適化
高性能版 docker-compose.high.yml RTX4090等 16GB+ 最大パフォーマンス

🌐 API使用例

チャット API

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3n-e4b-fixed.gguf",
    "messages": [
      {
        "role": "user",
        "content": "こんにちは！"
      }
    ],
    "temperature": 0.8,
    "max_tokens": 100
  }'

生成 API

curl -X POST http://localhost:8080/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "人工知能について説明してください。",
    "n_predict": 100,
    "temperature": 0.8
  }'

📚 参考リンク

このガイドを参考に、WindowsでのLlama.cpp環境構築をお楽しみください！

コメント

タイトルとURLをコピーしました