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.ggufllama-2-13b-chat.Q4_K_M.ggufgemma3n-e2b-fixed.ggufgemma3n-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
}'
📚 参考リンク
- プロジェクトリポジトリ
- Llama.cpp 公式リポジトリ
- Docker Compose 公式ドキュメント
- NVIDIA Container Toolkit
- Hugging Face Model Hub
このガイドを参考に、WindowsでのLlama.cpp環境構築をお楽しみください！