Zenn
⭐️

Edge Runtimeで動かすNext.js × GraphQL × 生成AIアーキテクチャ入門

に公開
GraphQL
Next.js
TypeScript
Generative AI
edgeruntime
tech

はじめに (ฅ•ω•ฅ)

「とりあえず Vercel にデプロイすればいいっしょ ★」で始めた個人開発が、気づけば マルチテナント SaaS に進化してしまう――そんな経験、ありませんか？

今日はオタク系エンジニア女子のわたしが ❤️‍🔥 Next.js 15 の Edge Runtime + TypeScript + GraphQL + PostgreSQL に加え、生成 AI をスパイスにした “ギークのためのフルスタック構成” を語ります。サーバーレスと AI の組み合わせにモエモエしつつ、抽象度高めに設計戦略を覗いていきましょう。

目次

  1. テーマの背景
  2. アーキテクチャ全景図と技術選定
  3. Edge Functions で GraphQL をさばくコツ
  4. 生成 AI レイヤの配置と責務分離
  5. Docker × pgvector で Embedding を高速化
  6. CI/CD と Observability 小技集
  7. まとめと推しポイント

1. テーマの背景

2025 年は Edge First へ完全シフトの年。従来の Node ランタイムでは コールドスタート がネックでしたが、Edge Runtime + Bun + WASM の登場で sub-100 ms が当たり前に。

そこへ LLM アプリ ブームが重なり、「低レイテンシ + データ重視」の構成を真面目に考え直す必要が出てきたわけです。( ᐢ ˙꒳˙ ᐢ )

2. アーキテクチャ全景図と技術選定

Client (Next.js App Router)
        │  /app/api/chat/route.ts
        ▼
Edge Function (GraphCDN) ─┐  ← Streaming
                           ├─→ pgvector@Neon (R/W Split)
        ▲                  │
        │                  └─→ OpenAI Function Calling
React Server Components ──┘
  • Next.js 15: App Router + RSC で UX とチューニングを両立
  • GraphQL Yoga on Edge: スキーマファーストで型安全、DataLoader も楽勝
  • PostgreSQL 16 + pgvector: 埋め込み検索を SQL に統合、Docker Compose でローカル完結
  • LangChain.js: LLM ワークフローを最小コードで記述
  • OpenTelemetry + Sentry: トレーシングとエラー監視を一元化 ⭐️

3. Edge Functions で GraphQL をさばくコツ

Edge Runtime は fetch ベース I/O なので @whatwg-node/fetch に統一するのが吉。

DataLoader で N+1 を潰すとき、Map のキーは TenantID + QueryKey にするとマルチテナントを安全にキャッシュできます。

さらに defer ディレクティブで RSC と連携させると、👧🏻 ユーザー体験が 爆速感 になります。

4. 生成 AI レイヤの配置と責務分離

AI が絡むと「どこで推論を呼ぶか」が泥沼化しがち。わたしは Use-case 層 を次の 3 つに分割しています。

  1. Retriever: pgvector で Top-k を拾う
  2. Reasoner: OpenAI GPT-4o を Function Calling で叩く
  3. Composer: GraphQL Mutation / Subscription に結果を流す

こうすることで LLM を“低結合なプラガブルサービス” として扱えます。⚠️ AI 部分をモノリスに埋め込むと、モデル差し替えで地獄を見るので注意。

5. Docker × pgvector で Embedding を高速化

ローカル検証は docker compose up db で即起動。COPY を使ったバルクロードは IOPS 的に ⭕️ コスパ最強。CREATE INDEX ivfflat を nprobe=20 辺りでチューニングすると、100 万レコードでも 40 ms 以内。❤️‍🩹

sql
コピーする編集する
CREATE EXTENSION IF NOT EXISTS pgvector;
CREATE INDEX IF NOT EXISTS idx_embedding
ON documents USING ivfflat(embedding vector_l2_ops) WITH (lists = 100);

6. CI/CD と Observability 小技集

  • GitHub Actions: Edge Function 用 artifact を 5 MB 未満に縮めるため tsx --bundle
  • Database Migration: atlas schema apply を PR ごとに Dry-Run
  • E2E: Playwright + msw で LLM 呼び出しをモック ( ´•̥ ̫ •̥ )
  • Tracing: Vercel Analytics だけでは足りないので OTLP を Grafana Cloud へ 🔽

7. まとめと推しポイント

Edge × GraphQL × 生成 AI、全部盛りでも設計を レイヤ で切れば保守も怖くない！

本記事がみんなの “いいね欲” を刺激しつつ、次のフルスタック妄想のタネになれば嬉しいです ❣️

質問や「ここもっと掘りたい！」なツッコミはコメントでお待ちしております〜 ⸝⸝> ̫ <⸝⸝՞

GitHubで編集を提案

Discussion