はじめに

「AIを使ったWebサービスを作りたい」と思ったとき、Pythonフレームワークのデファクトスタンダードは間違いなくFastAPIです。型安全性、高速な非同期処理、そして自動生成されるAPIドキュメント。これらはモダンなAI開発において必要不可欠な機能です。

しかし、実際のプロジェクトでは「APIを叩くだけ」では済みません。エラーハンドリング、設定管理、CORS、デプロイ構成…考えるべきことは山積みです。

この記事では、そのまますぐに本番環境で使えるレベルのFastAPI + Gemini APIのテンプレートプロジェクトを解説します。

---

プロジェクト構成：スケーラビリティを意識する

単一の main.py に全てを書くのは卒業しましょう。機能ごとに適切に分割されたディレクトリ構成は、将来的な機能拡張を容易にします。

ai-web-app/
├── app/
│   ├── __init__.py
│   ├── main.py          # アプリケーションのエントリーポイント
│   ├── config.py        # Pydanticを使った設定管理
│   ├── routers/         # エンドポイント定義
│   │   ├── __init__.py
│   │   └── ai.py
│   ├── services/        # ビジネスロジック（AI呼び出しなど）
│   │   ├── __init__.py
│   │   └── ai_service.py
│   └── models/          # データモデル（Pydanticスキーマ）
│       ├── __init__.py
│       └── schemas.py
├── requirements.txt
├── Dockerfile
└── docker-compose.yml

---

徹底解説：各コンポーネントの実装

1. 堅牢な設定管理 (config.py)

環境変数の読み込みには pydantic-settings を使います。これにより、型チェックと自動バリデーションが行われ、設定ミスによる実行時エラーを防げます。

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    GEMINI_API_KEY: str
    ALLOWED_ORIGINS: list[str] = ["http://localhost:3000"]
    ENV_MODE: str = "dev"

    class Config:
        env_file = ".env"

settings = Settings()

2. データモデルの定義 (models/schemas.py)

APIの入出力は必ずPydanticモデルで定義します。これにより、クライアントからのリクエストが自動的にバリデーションされます。

from pydantic import BaseModel, Field

class AIRequest(BaseModel):
    prompt: str = Field(..., min_length=1, max_length=2000, description="AIへの指示")
    model: str = Field("gemini-2.0-flash", description="使用するモデル")

class AIResponse(BaseModel):
    response: str
    tokens_used: int

3. ビジネスロジックの分離 (services/ai_service.py)

APIのルーティング層（Controller）とビジネスロジック層（Service）を分けることは重要です。AI APIへの依存をこのファイルに閉じ込めることで、将来的にOpenAIやClaudeに切り替える際もここだけ修正すれば済みます。

from google import genai
from app.config import settings

class AIService:
    def __init__(self):
        self.client = genai.Client(api_key=settings.GEMINI_API_KEY)

    async def generate_text(self, prompt: str, model_name: str) -> str:
        try:
            # 非同期メソッドを使ってI/Oブロッキングを防ぐ
            response = await self.client.aio.models.generate_content(
                model=model_name,
                contents=prompt
            )
            return response.text
        except Exception as e:
            # ここではログ出力などを行う
            raise e

ai_service = AIService()

【重要】: client.aio を使って非同期にリクエストを投げている点に注目してください。通常の同期メソッドを使うと、AIが応答を生成している数秒間、サーバー全体が停止してしまいます。FastAPIの性能を活かすには async/await が必須です。

4. ルーティング (routers/ai.py)

エンドポイントの定義を行います。依存性注入（Dependency Injection）を活用してServiceを利用します。

from fastapi import APIRouter, HTTPException
from app.models.schemas import AIRequest, AIResponse
from app.services.ai_service import ai_service

router = APIRouter()

@router.post("/generate", response_model=AIResponse)
async def generate_response(request: AIRequest):
    try:
        result = await ai_service.generate_text(request.prompt, request.model)
        return AIResponse(response=result, tokens_used=0) # トークン数は仮
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

---

本番環境へのデプロイ：Docker化

モダンなWebアプリはコンテナでデプロイするのが一般的です。軽量な python:3.11-slim をベースにしたDockerfileを作成します。

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# 依存関係のインストール（キャッシュ効率化のため先にコピー）
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# FastAPIサーバー起動 (Uvicorn)
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

開発環境や、簡単な本番デプロイにはDocker Composeが便利です。

services:
  api:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - .:/app  # ホットリロード用
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

---

発展：さらに品質を高めるために

プロダクションレベルにするために追加すべき機能を紹介します。

1. レート制限 (Rate Limiting)

AI APIは高価なリソースです。悪意のあるユーザーや無限ループによる大量消費を防ぐため、slowapi を導入してアクセス制限をかけましょう。

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@router.post("/generate")
@limiter.limit("5/minute") # 1分間に5回まで
async def generate_response(...):
    ...

2. Stream Response（ストリーミング）

チャットボットのようなUIの場合、回答が一気に表示されるより、タイピングされているように一文字ずつ表示される方が体験が良いです。FastAPIの StreamingResponse を使いましょう。

3. ログ監視

logging モジュールを適切に設定し、エラー発生時に通知が飛ぶようにしましょう（Sentryなどの導入も推奨）。

---

まとめ

FastAPIとGemini APIを組み合わせることで、高性能かつスケーラブルなAIアプリケーションを短期間で構築できます。

今回紹介したテンプレートは、「とりあえず動く」から「運用できる」への架け橋となる構成です。これをベースに、認証機能を追加したり、データベースを接続したりして、あなただけのサービスに育てていってください。

これで、AI開発の基礎となる3つの記事が出揃いました。

1. Gemini API入門: まずは動かす
2. AIモデル比較: 賢く選ぶ
3. FastAPIテンプレート: しっかり作る (本記事)

さあ、AI開発の旅を始めましょう！