llm-gateway

LLM Gateway

LLM リクエストをプロバイダーやセルフホストモデルに振り分ける、レート制限、コスト追跡、キャッシュ、フェイルオーバーに対応した統合 API ゲートウェイです。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください：

• 複数の LLM バックエンド（OpenAI、Anthropic、vLLM、Ollama）を単一のエンドポイントの背後で稼働させる
• チームまたはユーザーごとにレート制限と利用予算を適用する
• プロバイダーが停止した際に自動でフォールバックする仕組みを実装する
• API コストを 20～50% 削減するセマンティックキャッシュを追加する
• すべてのアプリにキーを配布する代わりに、API キー管理を一元化する

前提条件

• Docker と Docker Compose
• PostgreSQL または SQLite データベース（LiteLLM の状態管理用）
• LLM API キー（OpenAI、Anthropic など）またはセルフホスト vLLM エンドポイント
• オプション：キャッシュとレート制限用の Redis

LiteLLM Proxy — クイックスタート

LiteLLM は、OpenAI 互換 API を備えたデファクトスタンダードのオープンソース LLM ゲートウェイです。

# Run with Docker
docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd)/litellm-config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml \
  --detailed_debug

LiteLLM の設定

# litellm-config.yaml
model_list:
  # OpenAI models
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
      rpm: 10000
      tpm: 2000000

  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  # Anthropic
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: os.environ/ANTHROPIC_API_KEY

  # Self-hosted vLLM instances (load balanced)
  - model_name: llama-3.1-8b
    litellm_params:
      model: openai/meta-llama/Llama-3.1-8B-Instruct
      api_base: http://vllm-1:8000/v1
      api_key: fake                    # vLLM key
  - model_name: llama-3.1-8b
    litellm_params:
      model: openai/meta-llama/Llama-3.1-8B-Instruct
      api_base: http://vllm-2:8000/v1  # second replica — auto load balanced
      api_key: fake

  # Fallback: cheap model if primary fails
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o-mini        # fallback to cheaper model
      api_key: os.environ/OPENAI_API_KEY

router_settings:
  routing_strategy: least-busy         # or: latency-based, simple-shuffle
  num_retries: 3
  retry_after: 5
  allowed_fails: 2
  cooldown_time: 60

  # Fallback configuration
  fallbacks:
    - gpt-4o: [claude-sonnet-4-6]
    - claude-sonnet-4-6: [gpt-4o]

litellm_settings:
  # Semantic caching
  cache: true
  cache_params:
    type: redis
    host: redis
    port: 6379
    similarity_threshold: 0.90        # cache if >90% semantic similarity

  # Logging
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]
  langfuse_public_key: os.environ/LANGFUSE_PUBLIC_KEY
  langfuse_secret_key: os.environ/LANGFUSE_SECRET_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: postgresql://litellm:password@postgres:5432/litellm
  store_model_in_db: true

Docker Compose：ゲートウェイのフルスタック

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    volumes:
      - ./litellm-config.yaml:/app/config.yaml
    ports:
      - "4000:4000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - DATABASE_URL=postgresql://litellm:password@postgres:5432/litellm
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    command: redis-server --maxmemory 2gb --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:

仮想キーとレート制限

# Create a virtual API key for a team (via LiteLLM API)
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team-backend",
    "key_alias": "backend-team-key",
    "models": ["gpt-4o-mini", "llama-3.1-8b"],
    "max_budget": 100,              # USD limit
    "budget_duration": "monthly",
    "rpm_limit": 100,               # requests per minute
    "tpm_limit": 500000             # tokens per minute
  }'

# View spend
curl http://localhost:4000/spend/keys \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

Nginx ロードバランサー（代替／補完）

# nginx.conf — round-robin across vLLM replicas
upstream vllm_backends {
    least_conn;
    server vllm-1:8000 max_fails=3 fail_timeout=30s;
    server vllm-2:8000 max_fails=3 fail_timeout=30s;
    server vllm-3:8000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

server {
    listen 80;
    server_name llm-api.internal;

    # Rate limiting
    limit_req_zone $http_authorization zone=per_key:10m rate=100r/m;
    limit_req zone=per_key burst=20 nodelay;

    location /v1/ {
        proxy_pass http://vllm_backends;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_read_timeout 300s;        # long timeout for streaming
        proxy_buffering off;            # required for SSE streaming
        proxy_cache_bypass 1;
    }
}

ゲートウェイの健全性を監視する

# Check LiteLLM health
curl http://localhost:4000/health

# Model-level health
curl http://localhost:4000/health/liveliness

# Spend by model
curl http://localhost:4000/spend/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

# Active virtual keys
curl http://localhost:4000/key/list \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

よくある問題

問題	原因	対処方法
バックエンドへの ConnectionRefusedError	バックエンドに到達できない	api_base URL を確認し、バックエンドが正常に動作していることを確認します
レート制限エラー（429）	利用予算／RPM の超過	制限を引き上げるか、フォールバックモデルに切り替えます
ストリーミング応答が遅い	proxy_buffering が有効	Nginx で proxy_buffering off を設定します
キャッシュミス率が高い	しきい値が厳しすぎる	similarity_threshold を 0.85 に下げます
Postgres 接続エラー	DB の準備ができていない	condition: service_healthy を指定した depends_on を追加します

ベストプラクティス

• チーム／アプリごとに仮想キーを使用し、プロバイダーの API キーをそのまま公開しないでください。
• 繰り返しのクエリや類似したクエリには、Redis とともに cache: true を有効にします。コストを 30～50% 削減できます。
• プロバイダーの停止に適切に対応できるよう、フォールバックとともに num_retries: 3 を設定します。
• コストの割り当てとデバッグのため、すべてのリクエストを Langfuse または OpenTelemetry に記録します。
• GPU の飽和を避けるため、セルフホストモデルには least-busy ルーティング戦略を使用します。

関連スキル

• vllm-server - バックエンド推論サーバー
• llm-inference-scaling - バックエンドの自動スケーリング
• llm-caching - セマンティックキャッシュのパターン
• llm-cost-optimization - コスト管理