neondatabase/neon-ai-gateway

最初に: Neonの概要、Neonの使い方、Neon開発のベストプラクティスなどについては、親スキル neon を使用してください。

neon スキルがインストールされていない場合は、https://neon.com/docs/ai/skills/neon/SKILL.md から取得するか、次のコマンドでインストールしてください:

npx skills add neondatabase/agent-skills --skill neon

Neon AI Gateway

これは公開ベータ機能であり、現在 us-east-2 と eu-central-1 で利用できます。

Neon AI Gatewayは、Neonブランチに組み込まれたLLM推論レイヤーです。1つのAPIと1つのNeon認証情報で、多くのプロバイダ（Anthropic、OpenAI、Google、Metaなど）の最先端およびオープンソースモデルにアクセスでき、すべてDatabricksによってホストおよび提供されています。カタログは時間とともに変化するため、固定のプロバイダリストではなく、/v1/models と models.dev Neonページ を信頼できる情報源として扱ってください。既存のOpenAI/Anthropic/Gemini SDKは、ベースURLを変更するだけで動作します。

このスキルを使用して、ユーザーがゲートウェイ経由でモデル呼び出しを送信し、AI SDKやMastraに組み込み、コードを書き換えずにプロバイダを切り替えるのを支援します。動作する推論リクエスト、設定済みのエージェント、または公式Neonドキュメントからの正確な回答を提供します。

使用するタイミング

アプリやエージェントがLLMを呼び出す必要があり、ユーザーがモデルプロバイダを自分で管理したくない場合に、AI Gatewayを使用します:

• 多数のプロバイダアカウントではなく、1つの認証情報。 単一のNeon認証情報で、Databricksがホストするすべてのプロバイダのモデルカタログ全体にアクセスできます。OpenAI / Anthropic / Googleの個別の請求、キー、サインアップ、ローテーションは不要です。
• コードを書き換えずにモデルを切り替え。 統一エンドポイントはOpenAI互換であり、カタログ内のすべてのモデルで動作します。Claude、GPT、Gemini間で1つの model フィールドを変更するだけです。標準SDK（OpenAI、Anthropic、google-genai）はベースURLの変更だけで動作します。
• AIはブランチに追従。 各ブランチには独自のゲートウェイエンドポイントがあり、データベースと同じ系統にスコープされています。プレビュー/機能ブランチからのAIリクエストはそのブランチに分離されます。これは、データがすでに得ているのと同じ分離であり、プレビュー、CI、エージェント環境を自己完結型にします。
• 追加インフラは不要で、すでにデータの隣にあります。 ゲートウェイはNeonプロジェクト内に存在し（Neon Functionsに自動的に注入されます）、月間数兆トークンを処理するのと同じDatabricksインフラ上で動作し、ストリーミング（SSE）を標準でサポートしています。

ユーザーがすでに特定のプロバイダに深く統合されており、Neonのブランチングやマルチモデルルーティングに関心がない場合は、直接プロバイダSDKで問題ありません。しかし、1つの認証情報、モデルの移植性、またはブランチスコープのAIが必要になった瞬間、これが使用する理由です。

機能

• すべてのモデルに1つのAPI — 単一のエンドポイントの背後にある最先端およびオープンソースモデルに、カタログID（例：claude-sonnet-4-6、gpt-5-mini、gemini-3-flash）でアクセスします。
• 標準SDK、1つのURL変更 — OpenAI SDKおよびAI SDK（OpenAI互換のMLflow/Responsesルート）、Anthropic SDK（ネイティブMessages）、google-genai（ネイティブGemini）。
• ブランチスコープ — 各ブランチは独自のゲートウェイホストを取得します。Neon認証情報は、そのブランチとその子孫に対するリクエストを承認します。
• ストリーミング — サーバー送信イベントは、追加設定なしですべてのエンドポイントで機能します。

利用可能性

何かを設定する前に、これらの前提条件を確認してください:

AI Gatewayは、現在 us-east-2 と eu-central-1 で利用可能な公開ベータ機能です。ファウンデーションモデルへのアクセスには、有料のNeonプランが必要です。ユーザーのプロジェクトがこれらのリージョンのいずれかにあることを確認してください。

ゲートウェイの有効化: プランとモデルカタログのゲーティング

AI Gatewayは、プロビジョニング手順ではなく認証情報によってゲーティングされますが、2つのプラン/ベータ制限がそれをゲーティングします。1つはプロビジョニングをブロックし、もう1つはカタログをトリミングするだけです。CLIはそれぞれを表示します:

• Freeプラン → プロビジョニングがブロックされます。 neon config apply / deploy および neon checkout は、Freeプランでのゲートウェイの有効化を拒否します（ゲートウェイはそこでリクエストを提供できません）。「有料プランにアップグレードするか、preview.aiGateway を削除してください」というフレンドリーなエラーが表示されます。ドライラン neon config plan と neon env pull はプロビジョニングしないため、警告のみを表示します。つまり、ゲートウェイを使用するには、プロジェクトのアカウントが有料のNeonプランである必要があります。
• モデルカタログが縮小された有料プラン。 有料プランではゲートウェイがプロビジョニングされ提供されますが、ベータ期間中はアカウントがトリミングされたカタログで開始される場合があります。一部の主要モデル（例：Anthropic Opus、OpenAI Codex / *-pro）が GET /v1/models にありません。これは予期される動作です。neon env pull（および apply / deploy / checkout にバンドルされている env pull）は警告を表示し、ユーザーをブランチのAI Gatewayページ（Neonコンソール: https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway）にリンクして、より多くのモデルへのアクセスをリクエストできるようにします。完全なカタログを想定するのではなく、/v1/models を読み取って（以下のモデルセクションを参照）、ブランチで実際に利用可能なものを確認してください。

「ゲートウェイが動作しない」または「モデルが見つからない」というユーザーのデバッグを支援する場合は、/v1/models とアカウントのプランを使用して、これら2つのケースを区別してください。Freeプランはプロビジョニングを完全にブロックし、有料プランのカタログ縮小はモデルアクセスリクエストが必要なだけです。

セットアップ

ゲートウェイは neon.ts の一部です（ブランチファーストのワークフローと neon.ts の基本については、neon スキルを参照）。preview.aiGateway の下で有効にします:

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  preview: {
    aiGateway: true,
  },
});

neon deploy   # リンクされたブランチにゲートウェイをプロビジョニングします

Neon Infrastructure as Code (neon.ts)

上記の preview.aiGateway トグルは neon.ts の一部です。NeonのInfrastructure as Codeファイルです。1つのTypeScriptファイルが、すべてのブランチサービスと一緒にゲートウェイを宣言し、バージョン管理下に置きます（完全なリファレンスは neon スキルを参照）。Terraform的な方法でブランチと調整します:

neon config status   # ブランチのライブ設定を表示します（ゲートウェイはオンですか？）
neon config plan     # apply が何を変更するかのドライラン差分を表示します
neon config apply    # ブランチでゲートウェイを有効にします（neon deploy はエイリアスです）

ゲートウェイはブランチスコープです。各ブランチは独自のゲートウェイホストを取得します。neon.ts が存在する場合、neon checkout はブランチを作成するときにポリシーを適用するため、新しいプレビュー/CIブランチはゲートウェイがすでに有効になった状態で起動します。既存のブランチをチェックアウトしても調整されません。変更を適用するには neon deploy を実行してください。プロビジョニング（config apply / deploy）、link、checkout は、ブランチのゲートウェイ認証情報をローカルの .env.local にもプルするため、ローカル実行はデプロイされた関数と同じブランチゲートウェイにヒットします（手動の env pull は不要です）。

環境変数

preview.aiGateway が有効な場合、Neonはゲートウェイ認証情報を Neonブランドの env var として注入します。デプロイされたNeon Function内では自動的に注入され、ローカルでは neon env pull が .env/.env.local に書き込みます（または、ファイルなしで実行時に注入するために neon-env run -- <cmd> を使用します）:

変数	意味
NEON_AI_GATEWAY_TOKEN	ゲートウェイベアラートークン（Neon認証情報 nt_live_...）
NEON_AI_GATEWAY_BASE_URL	ベアのブランチゲートウェイホスト（scheme://host、パスなし — /ai-gateway なし）: https://<branch-id>-api.ai.<region>.aws.neon.tech

Neonはこれら2つの変数のみを注入します。OPENAI_API_KEY / OPENAI_BASE_URL は設定しません。@neon/ai-sdk-provider と Mastra の neon/<model> は NEON_AI_GATEWAY_* を直接読み取ります（ゼロ設定）。プレーンなOpenAI SDK / @ai-sdk/openai の場合は、それらからクライアントの apiKey + baseURL を構築するか（以下に示します）、独自の OPENAI_* を手動で設定します（env pull はユーザー設定の変数をそのままにします）。

NEON_AI_GATEWAY_BASE_URL はベアホストです。ダイアレクトパスを自分で追加します（これはまさに @neon/ai-sdk-provider が自動的に行うことです）。ホストの下のルートは次のとおりです:

• /v1 — 統合されたOpenAI Chat Completions互換。推奨されるデフォルトで、すべてのプロバイダで動作します（/v1/chat/completions）。
• /openai/v1 — OpenAI Responses API（gpt-5-…-codex バリアントと gpt-5-5-pro に必要）。@ai-sdk/openai プロバイダはデフォルトでResponses APIを使用します（/openai/v1/responses）。
• /anthropic — ネイティブAnthropic Messages（拡張思考、プロンプトキャッシュ）。Anthropic SDKにこれをベースURLとして与えると、SDKが /v1/messages を自動的に追加するため、完全なリクエストパスは /anthropic/v1/messages になります。
• /gemini — ネイティブGemini generateContent。google-genaiにこれをベースURLとして与えると、SDKが /v1beta/models/<model>:generateContent を自動的に追加するため、完全なリクエストパスは /gemini/v1beta/models/<model>:generateContent になります。

したがって、${NEON_AI_GATEWAY_BASE_URL}/v1 がチャット補完エンドポイント、${NEON_AI_GATEWAY_BASE_URL}/openai/v1 がOpenAI Responsesエンドポイントです（どちらも自分で追加します）。ネイティブのAnthropicおよびGeminiダイアレクトの場合は、SDKに短いベース /anthropic または /gemini を与え、SDKが残りを追加します。以下の「プレーンSDKでの使用」を参照してください。

型指定され検証されたアクセスについては、同じ neon.ts 設定オブジェクトを @neon/env の parseEnv に渡します。設定から派生した env.aiGateway 名前空間（apiKey、baseUrl）を返します。

Vercel AI SDK でエージェントを構築する（推奨）

Vercel AI SDK は、TypeScriptからゲートウェイを呼び出しエージェントを構築するための推奨方法です。1つのプリミティブセット（generateText、streamText、ツール呼び出し、構造化出力）でカタログのすべてのモデルを操作でき、Neon Functionsがホストするように設計された長時間のエージェント応答向けのファーストクラスのストリーミングを備えています。

専用の @neon/ai-sdk-provider は、注入されたenvから NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN をゼロ設定で読み取り、各モデルを最適なエンドポイントにルーティングします（Anthropic → Messages、OpenAI/Codex → Responses、その他すべて → MLflow）。テキストをストリーミングし画像を生成するNeon Functionでは、カタログモデルを選択するだけです:

import { neon } from "@neon/ai-sdk-provider";
import { streamText } from "ai";

const result = streamText({
  model: neon("gpt-5-mini"), // または claude-sonnet-4-6, gemini-3-flash, ...
  messages,
  tools: {
    image_generation: neon.tools.imageGeneration({
      outputFormat: "jpeg",
      size: "1024x1024",
    }),
  },
});
return result.toUIMessageStreamResponse();

単一の補完も、generateText を使用した同じプロバイダです:

import { neon } from "@neon/ai-sdk-provider";
import { generateText } from "ai";

const { text } = await generateText({
  model: neon("claude-haiku-4-5"), // または gpt-5-3-codex, gemini-3-flash, ...
  prompt: "Postgresを説明してください。",
});

ベアの @ai-sdk/openai openai() よりも @neon/ai-sdk-provider を優先してください。Neonは NEON_AI_GATEWAY_* のみを注入し、OPENAI_* は注入しないため、openai() はそれだけではゲートウェイをenvからピックアップしません。@ai-sdk/openai を使用する場合は、createOpenAI({ apiKey: process.env.NEON_AI_GATEWAY_TOKEN, baseURL: ${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1 }) で明示的に設定してください。

エージェント（ツールをループで呼び出してから回答するモデル）を構築するには、tools と stopWhen バジェットを追加します。ループはインプロセスで実行されるため、Neon Function上ではラムダスタイルのタイムアウトで遮断されません:

import { neon } from "@neon/ai-sdk-provider";
import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";

const { text } = await generateText({
  model: neon("claude-sonnet-4-6"),
  prompt: "未完了のTODOはいくつありますか？また、最も古いものはどれですか？",
  tools: {
    listTodos: tool({
      description: "ユーザーの未完了のTODOをリストします。",
      inputSchema: z.object({}), // AI SDK v5+: `inputSchema`、`parameters` ではありません
      execute: async () => db.select().from(todos),
    }),
  },
  stopWhen: stepCountIs(5), // モデルにツールを呼び出させ、要約させる
});

Neon Functionとしてデプロイされた完全なAI SDKエージェント（ストリーミング、ツール呼び出し、画像生成、永続化）については、neon-functions スキルの references/ai-sdk.md を参照してください。

Mastra でエージェントを構築する（推奨）

Mastra は、バッテリー同梱のエージェント（組み込みのメモリ、ツール、ワークフロー、トレーシング）を、モデルをゲートウェイに向けたままにしたい場合に推奨されるフレームワークです。@mastra/core 1.47+ では、neon/<model> マジック文字列を使用します。Mastraは環境から NEON_AI_GATEWAY_BASE_URL と NEON_AI_GATEWAY_TOKEN を読み取ります（preview.aiGateway が有効な場合、neon deploy によって注入されます）。parseEnv は、宣言された他のサービスにのみ使用します（例：@mastra/pg メモリ用の env.postgres.databaseUrl）:

import { Agent } from "@mastra/core/agent";
import { parseEnv } from "@neon/env";
import config from "../neon";

const env = parseEnv(config);

export const personalAssistant = new Agent({
  id: "personal-assistant",
  name: "personal-assistant",
  instructions:
    "あなたは、温かく簡潔な個人アシスタントで、長期記憶を持っています。",
  model: "neon/claude-haiku-4-5",
  memory, // Mastraメモリストア、例: env.postgres.databaseUrl 上の @mastra/pg
});

プレーンSDKでの使用（低レベル）

エージェントフレームワークが不要な場合（単一の補完、既存のプロバイダSDK統合、ネイティブプロバイダ機能）、プレーンSDKでゲートウェイを呼び出します。Neonは NEON_AI_GATEWAY_* 変数を注入します（OPENAI_* ではありません）。そのため、クライアントの apiKey + baseURL をそれらから設定します。OpenAI Responses ダイアレクト（/openai/v1）の場合:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const response = await client.responses.create({
  model: "gpt-5-mini",
  input: "Neon AI Gatewayを説明してください。",
});

Anthropic SDK の場合:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/anthropic`
});

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Neon AI Gatewayを説明してください。" }],
});

Google Gemini SDK の場合:

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/gemini`
});

const response = await ai.models.generateContent({
  model: "gemini-3-flash",
  contents: [
    {
      role: "user",
      parts: [{ text: "Neon AI Gatewayを説明してください。" }],
    },
  ],
});

モデルの一覧表示と選択

カタログを取得するには、OpenAI互換のチャット補完エンドポイントで GET /v1/models を実行します:

curl -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  "$NEON_AI_GATEWAY_BASE_URL/v1/models"

レスポンスには、id（モデルID。例えば claude-sonnet-4-6）、object（model）、owned_by（プロバイダ。例えば anthropic）を持つオブジェクトの配列が含まれます。/v1/models を信頼できる情報源として使用し、カタログは時間とともに変化することに注意してください。

各モデルIDは、ダイアレクトに依存しない方法で使用できます。@neon/ai-sdk-provider は自動的に正しいルートにルーティングします。プレーンSDKでは、正しいエンドポイントを選択してください。

トラブルシューティング

• 401 認証エラー: NEON_AI_GATEWAY_TOKEN が正しく設定されていることを確認してください。nt_live_... の形式である必要があります。
• モデルが見つからない: ベータ版では、一部のモデルが利用できない場合があります。/v1/models を確認して利用可能なモデルを確認するか、Neonコンソールでモデルアクセスをリクエストしてください。
• ゲートウェイがプロビジョニングされない: プロジェクトが有料プランであり、サポートされているリージョン（us-east-2 または eu-central-1）にあることを確認してください。
• ストリーミングが機能しない: SSEがクライアントとネットワークでブロックされていないことを確認してください。