レッスン3：アプリケーション層ポリシー付きGemma 4用APIゲートウェイの構築

はじめに

ゲートウェイは、ローカルAIスタックを安定して運用するための最も重要な層です。クライアントがモデルランタイムを直接呼び出す代わりに、チームに品質とセキュリティの制御を与えます。

1. 最小限のAPIテンプレート

from fastapi import FastAPI
from pydantic import BaseModel
import requests

app = FastAPI()

class ChatReq(BaseModel):
    prompt: str
    model: str = "gemma4"

@app.post("/chat")
def chat(req: ChatReq):
    r = requests.post(
        "http://127.0.0.1:11434/api/generate",
        json={"model": req.model, "prompt": req.prompt, "stream": False},
        timeout=90,
    )
    r.raise_for_status()
    data = r.json()
    return {"answer": data.get("response", ""), "model": req.model}

2. 必須のゲートウェイポリシー

• エンドポイントごとのハードタイムアウト
• 一時的なエラーに対する限定的なリトライ
• 許可されたモデルのホワイトリスト
• 悪用防止のためのプロンプトサイズ制限

3. 構造化出力

アプリがJSONを必要とする場合、ゲートウェイでコントラクトを強制します：

• 明確なプロンプトコントラクト
• クライアントに返す前にスキーマを検証
• スキーマが失敗した場合、特定のコードでエラーを返す

4. 内部認証

最低限の実装：

• サービスごとのAPIキー
• キーごとのレート制限
• テナント/チームごとのロギング

エンタープライズ使用の場合、モデル層ではなくゲートウェイでSSOを接続します。

5. ロギングとトレーシング

各リクエストでログに記録すべき項目：

• request_id
• endpoint
• model
• latency_ms
• prompt_tokens_est
• status

PIIが含まれる場合、生の機密データをログに記録しないでください。

6. フォールバックモデル戦略

システムがハードクラッシュしないようフォールバックを設計：

1. プライマリモデルがタイムアウト
2. 自動的に軽量モデルに切り替え
3. degraded_mode=trueフラグ付きでレスポンスを返す

デモコード

ゲートウェイ経由のチャットAPIレスポンス：

モデルポリシーの強制 — 許可されていないモデルのブロック：

ソースコード：02-api-gateway

まとめ