DockerでLocalAIをデプロイ:ローカルLLM・TTS・画像生成のためのOpenAI互換APIサーバーを構築する

AI tutorial - IT technology blog
AI tutorial - IT technology blog

背景:LocalAIがワークフローを変えた理由

約1年前、私はドキュメント要約のためにOpenAI APIを呼び出す社内ツールを運用していました。大したものではありませんでしたが、リクエストのたびに社内データが外部サーバーに送信されていました。セキュリティチームから指摘が入り、法務部門も関わることになりました。単純な自動化がコンプライアンス問題に発展していたのです。

そこで真剣にLocalAIを調べ始めました。単なるセルフホスト型LLMランナーではありません。最大の特徴はAPIにあります。OpenAI APIと完全互換で、エンドポイントもリクエスト/レスポンスの形式も同じです。すでにapi.openai.comと通信しているアプリなら、コードを一切変えずにローカルサーバーに向け直せます。

真の強みはその内部にあります。LocalAIはllama.cpp、Whisper、diffusers、Bark、Piperをバックエンドとして内包しており、LLM推論・音声認識・画像生成・TTSを1つのAPI経由で利用できます。私はこの構成を数ヶ月間本番環境で運用してきましたが、ミドルレンジサーバーで同時負荷に耐え、長期稼働でもクラッシュやメモリリークは発生しませんでした。

GPUがなければ推論は遅くなります。社内ツール、バッチ処理、開発環境であればCPU推論で十分な場合がほとんどです。GPUがあれば、LocalAIはそれを活用します。

インストール:DockerでLocalAIを起動する

前提条件

始める前に、以下を確認してください:

  • Docker Engine 24.0以上とDocker Compose v2
  • 最低8GBのRAM(7Bモデルには16GB以上を推奨)
  • モデルファイル用に20〜50GBの空きディスク容量
  • 任意:CUDAドライバをインストールしたNVIDIA GPU(GPUアクセラレーション用)

プロジェクトのディレクトリ構成

models/サブフォルダを含む作業ディレクトリを作成します。モデルの重みとYAML設定ファイルはどちらもここに配置します:

mkdir localai-server && cd localai-server
mkdir -p models

Docker Composeの設定

ほとんどのデプロイで使用している基本的なdocker-compose.ymlです。変更する前に環境変数を確認しておくことをお勧めします:

services:
  localai:
    image: localai/localai:latest-aio-cpu
    # GPU使用時: localai/localai:latest-aio-gpu-nvidia-cuda-12 を使用
    container_name: localai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/build/models
    environment:
      - THREADS=4              # 推論に使用するCPUスレッド数
      - CONTEXT_SIZE=4096      # 最大コンテキストウィンドウサイズ
      - DEBUG=false
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/readyz"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s

aio(all-in-one)イメージはすべてのバックエンドを1つのコンテナにまとめています。LLM推論のみが必要な場合は、代わりにlocalai/localai:latest-cpuを使用してください。サイズが大幅に小さくなります。

起動します:

docker compose up -d
docker compose logs -f

初回起動時にベースとなる依存関係がダウンロードされます。1〜2分待ってください。ログにLocalAI API is runningと表示されたら準備完了です。

設定:モデルのセットアップ

モデル設定の仕組み

LocalAIはmodels/ディレクトリにモデルの重みと並べてYAML設定ファイルを保存します。各.yamlファイルはAPIが公開するモデルを定義します。使用するバックエンド、読み込む重みファイル、適用するパラメータなどを指定します。

モデルの重み(LLMでは通常.ggufファイル)も同じディレクトリに配置します。YAMLで指定するファイル名は正確に一致している必要があります。一致しない場合、モデルは単純に読み込まれません。

LLMの設定(Llama 3.2)

まずGGUFモデルのダウンロードから始めます。Llama 3.2 3BはCPU推論に実用的な選択肢です。Q4_K_M量子化でディスク容量は約2GBで、GPUなしでほとんどのテキスト処理に対応できます:

# Hugging Faceからダウンロード(huggingface-cli または wget が必要)
wget -O models/llama-3.2-3b-instruct.gguf \
  https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF/resolve/main/Llama-3.2-3B-Instruct-Q4_K_M.gguf

models/llama3.yamlにモデル設定を作成します:

name: llama3
backend: llama-cpp
parameters:
  model: llama-3.2-3b-instruct.gguf
  context_size: 4096
  threads: 4
  f16: true
template:
  chat_message: |
    {{if eq .RoleName "system"}}{{.Content}}{{end}}
    {{if eq .RoleName "user"}}User: {{.Content}}{{end}}
    {{if eq .RoleName "assistant"}}Assistant: {{.Content}}{{end}}

音声合成(TTS)モデルの追加

PiperはLocalAIのTTSバックエンドです。models/tts.yamlを作成します:

name: tts
backend: piper
parameters:
  model: en_US-lessac-medium.onnx

Piperの音声モデルをダウンロードします:

wget -O models/en_US-lessac-medium.onnx \
  https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx
wget -O models/en_US-lessac-medium.onnx.json \
  https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json

Stable Diffusionによる画像生成の追加

画像生成はdiffusersバックエンドを使用します。models/stablediffusion.yamlを作成します:

name: stable-diffusion
backend: diffusers
parameters:
  model: stabilityai/stable-diffusion-2-1
f16: true
diffusers:
  pipeline_type: StableDiffusionPipeline
  cuda: false

モデルYAMLファイルへの変更を反映するには、コンテナの再起動が必要です:

docker compose restart localai

動作確認とモニタリング

APIエンドポイントのテスト

LocalAIが起動している状態でのテストは、OpenAI APIの呼び出しとまったく同じです。ベースURLを変更するだけです。

まず、LocalAIに読み込まれているモデルの一覧を取得します:

curl http://localhost:8080/v1/models | python3 -m json.tool

チャット補完:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [
      {"role": "user", "content": "Dockerボリュームとは何か、一文で説明してください。"}
    ],
    "temperature": 0.7
  }'

TTSも同じAPIパターンで使用できます:

curl http://localhost:8080/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "tts", "input": "LocalAIからこんにちは"}' \
  --output speech.mp3

画像生成:

curl http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion",
    "prompt": "データセンターのサーバーラック、フォトリアリスティック",
    "size": "512x512"
  }'

PythonからLocalAIを使うのも同様に簡単です。OpenAI SDKはそのまま動作し、変更は1か所だけです。ベースURLを更新するだけ。これが本番環境だけでなく開発環境にも導入する価値がある理由です。Dockerのセットアップは10分とかかりません。APIの使い方はすぐに馴染めます。そして、それ以降リクエストが社外に出ることはなくなります。

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # LocalAIはデフォルトでは実際のキーを必要としない
)

response = client.chat.completions.create(
    model="llama3",
    messages=[{"role": "user", "content": "Kubernetesとは何ですか?一段落で説明してください。"}]
)
print(response.choices[0].message.content)

ヘルスチェックとログ監視

readinessエンドポイントはシンプルなヘルスシグナルを返します。ロードバランサーやコンテナオーケストレーションに役立ちます:

curl -s http://localhost:8080/readyz
# 返り値: {"status":"ok"}

ログとリソース使用量の確認:

# ライブログをリアルタイムで表示
docker compose logs -f localai

# エラーのみフィルタリング
docker compose logs localai 2>&1 | grep -i error

# リソース使用量を確認
docker stats localai

モデルが読み込まれない場合は、まずComposeファイルでDEBUG=trueを設定してください。LocalAIはバックエンドの初期化プロセスをすべてログに出力します。何を読み込んでいてどこで失敗しているかが正確にわかります。重みファイルの不足やYAMLキーの設定ミスはすぐに表示され、後で謎のAPIエラーとして現れることがなくなります。

認証が必要ですか?Compose環境にAPI_KEY=your-secretを追加してください。LocalAIはすべてのエンドポイントにベアラートークン認証を適用し、OpenAIと同じAuthorization: Bearer ...形式を使用します。他の変更は不要です。

スタック内のどこかでOpenAI SDKを使用している場合、LocalAIへの切り替えは1行の変更だけです。ベースURLを更新するだけ。これが本番環境だけでなく開発環境にも導入する価値がある理由です。Dockerのセットアップは10分とかかりません。APIの使い方はすぐに馴染めます。そして、それ以降リクエストが社外に出ることはなくなります。

Share: