首先：請先使用上層 neon 技能取得 Neon 概述、入門指南、Neon 開發最佳實務等資訊。

如果尚未安裝 neon 技能，請從 https://neon.com/docs/ai/skills/neon/SKILL.md 取得或使用以下指令安裝：

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

Neon AI Gateway

此為公開 Beta 功能，目前支援 us-east-2 和 eu-central-1 區域。

Neon AI Gateway 是一個內建於您 Neon 分支中的 LLM 推論層：單一 API 與單一 Neon 憑證即可存取來自多個供應商（Anthropic、OpenAI、Google、Meta 等）的頂尖與開源模型，所有模型皆由 Databricks 代管與驅動。模型目錄會隨時間變化，因此請將 /v1/models 和 models.dev Neon 頁面視為唯一真實來源，而非固定的供應商列表。您只需變更 base URL，即可使用現有的 OpenAI / Anthropic / Gemini SDK。

使用此技能協助使用者透過閘道發送模型呼叫、將其整合至 AI SDK 或 Mastra，並在不重寫程式碼的情況下切換供應商。提供一個可正常運作的推論請求、一個已設定的代理，或直接從官方 Neon 文件中取得精確的答案。

使用時機

每當應用程式或代理需要呼叫 LLM，且使用者不想自行管理模型供應商時，即可使用 AI Gateway：

一個憑證，取代多個供應商帳戶。 單一 Neon 憑證即可存取 Databricks 代管的所有供應商之完整模型目錄。無需為每個 OpenAI / Anthropic / Google 分別設定計費、金鑰或註冊流程。
無需重寫即可切換模型。 統一的端點相容於 OpenAI，可與目錄中的任何模型搭配使用 — 只需變更 model 欄位即可在 Claude、GPT 和 Gemini 之間切換。標準 SDK（OpenAI、Anthropic、google-genai）只需變更 base URL 即可運作。
AI 跟隨您的分支。 每個分支都有自己的閘道端點，其作用範圍與您的資料庫相同。來自預覽 / 功能分支的 AI 請求將隔離於該分支中 — 這與您的資料已獲得的隔離機制相同，使預覽、CI 與代理環境可自成一個封閉系統。
無需額外基礎設施，且已與您的資料相鄰。 閘道位於您的 Neon 專案內（並會自動注入至 Neon Functions），執行於每月處理數兆 tokens 的 Databricks 基礎設施上，並原生支援串流（SSE）。

如果使用者已擁有深入的單一供應商整合，且對 Neon 分支或多模型路由不感興趣，那麼直接使用供應商 SDK 即可 — 但當他們需要一個憑證、模型可攜性、或分支範圍的 AI 時，這就是使用它的理由。

功能說明

所有模型的單一 API — 頂尖與開源模型共用單一端點，以其目錄 ID 做為識別（例如 claude-sonnet-4-6、gpt-5-mini、gemini-3-flash）。
標準 SDK，只需變更一個 URL — OpenAI SDK 與 AI SDK（OpenAI 相容的 MLflow / Responses 路由）、Anthropic SDK（原生 Messages）、google-genai（原生 Gemini）。
分支範圍 — 每個分支都有自己的閘道主機；Neon 憑證授權該分支及其子分支的請求。
串流 — 所有端點皆支援伺服器推送事件（SSE），無需額外設定。

可用性

在進行任何設定前，請先檢查以下前提條件：

AI Gateway 為公開 Beta 功能，目前支援 us-east-2 和 eu-central-1 區域。基礎模型存取需要付費 Neon 方案。請確認使用者的專案位於這些區域之一。

啟用閘道：方案與模型目錄控管

AI Gateway 是透過憑證來控管，而非一個需要額外佈建的步驟，但有兩個方案 / Beta 限制會影響它 — 一個會封鎖佈建，另一個只會縮減目錄 — CLI 會分別顯示每個情況：

Free 方案 → 佈建被阻止。 neon config apply / deploy 和 neon checkout 會拒絕在 Free 方案上啟用閘道（閘道在該方案上無法提供服務），並顯示友善的「請升級至付費方案，或移除 preview.aiGateway」錯誤。乾執行的 neon config plan 和 neon env pull 不會進行佈建，因此只會警告。總之：要使用閘道，專案帳戶必須是付費 Neon 方案。
付費方案但模型目錄縮減。 在付費方案上，閘道會正常佈建與提供服務，但在 Beta 期間，帳戶的起始模型目錄可能會被縮減 — 某些旗艦模型（例如 Anthropic Opus、OpenAI Codex / *-pro）不會出現在 GET /v1/models 中。這是預期行為；neon env pull（以及內建於 apply / deploy / checkout 中的 env pull）會顯示警告，並附上連結導向使用者分支在 Neon Console 中的 AI Gateway 頁面（https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway），以便請求存取更多模型。請透過讀取 /v1/models（請參閱下方的 models 區段）來驗證該分支實際可用的模型，而非假設為完整目錄。

當協助使用者除錯「閘道無法運作」或「模型遺失」時，請使用 /v1/models 加上帳戶的方案來區分這兩種情況 — Free 方案會完全封鎖佈建，而付費方案上縮減的目錄只需提出模型存取請求即可。

設定

閘道是 neon.ts 的一部分（請參閱 neon 技能以瞭解分支優先的工作流程和 neon.ts 基礎知識）。在 preview.aiGateway 下啟用它：

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

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

neon deploy   # 在連結的分支上佈建閘道

Neon 基礎設施即程式碼 (`neon.ts`)

上述的 preview.aiGateway 開關是 neon.ts 的一部分，即 Neon 的基礎設施即程式碼檔案 — 一個 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，因此本機執行會與已部署的 Function 使用相同的分支閘道（無需手動執行 env pull）。

環境變數

當啟用 preview.aiGateway 時，Neon 會注入閘道憑證作為Neon 品牌的環境變數。在已部署的 Neon Function 內部，這些變數會自動注入；在本機上，neon env pull 會將它們寫入 .env / .env.local（或使用 neon-env run -- <cmd> 在執行時注入，無需檔案）：

變數	說明
`NEON_AI_GATEWAY_TOKEN`	閘道 Bearer Token（一個 Neon 憑證，`nt_live_...`）
`NEON_AI_GATEWAY_BASE_URL`	裸分支閘道主機（`scheme://host`，不含路徑 — 不含 `/ai-gateway`）：`https://<branch-id>-api.ai.<region>.aws.neon.tech`

Neon 僅注入這兩個變數 — 它不會設定 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（擴展思考、提示快取）。將此作為 base URL 提供給 Anthropic SDK，它會自行附加 /v1/messages，因此完整的請求路徑為 /anthropic/v1/messages。
/gemini — 原生 Gemini generateContent。將此作為 base URL 提供給 google-genai，它會自行附加 /v1beta/models/<model>:generateContent，因此完整的請求路徑為 /gemini/v1beta/models/<model>:generateContent。

因此 ${NEON_AI_GATEWAY_BASE_URL}/v1 是 chat-completions 端點，${NEON_AI_GATEWAY_BASE_URL}/openai/v1 是 OpenAI Responses 端點（兩者皆由您自行附加）；對於原生的 Anthropic 和 Gemini 方言，您將較短的 /anthropic 或 /gemini base URL 提供給 SDK，它會自行附加其餘部分。請參閱下方的與純 SDK 搭配使用。

若要以型別安全的方式存取被注入的憑證，請將相同的 neon.ts 設定物件傳遞給 @neon/env 的 parseEnv — 它會傳回一個從您的設定衍生而來的 env.aiGateway 命名空間（apiKey、baseUrl）。

使用 Vercel AI SDK 建置代理（建議）

Vercel AI SDK 是呼叫閘道並從 TypeScript 建置代理的建議方式：一組基礎元件（generateText、streamText、工具呼叫、結構化輸出）可涵蓋目錄中的所有模型，並為 Neon Functions 設計用來代管的長時間代理回應提供一流的串流支援。

專用的 @neon/ai-sdk-provider 會從注入的環境變數中讀取 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: "Summarize Postgres for me.",
});

優先使用 @neon/ai-sdk-provider 而非單純的 @ai-sdk/openai openai()：Neon 僅注入 NEON_AI_GATEWAY_*，而非 OPENAI_*，因此 openai() 無法自行從環境變數中取得閘道。如果您確實使用 @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 上不會被類似 lambda 的逾時機制中斷：

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: "How many open todos do I have, and what's the oldest one?",
  tools: {
    listTodos: tool({
      description: "List the user's open todos.",
      inputSchema: z.object({}), // AI SDK v5+: `inputSchema`, 而非 `parameters`
      execute: async () => db.select().from(todos),
    }),
  },
  stopWhen: stepCountIs(5), // 讓模型呼叫工具，然後總結
});

如需一個完整 AI SDK 代理部署為 Neon Function（串流、工具呼叫、圖片生成、持久化），請參閱 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（例如 env.postgres.databaseUrl 用於 @mastra/pg 記憶體）：

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:
    "You are a warm, concise personal assistant with long-term memory.",
  model: "neon/claude-haiku-4-5",
  memory, // 您的 Mastra 記憶體儲存，例如使用 env.postgres.databaseUrl 的 @mastra/pg
});

與純 SDK 搭配使用（低階）

當您不需要代理框架時 — 單次補全、現有的供應商 SDK 整合、或原生供應商功能 — 可使用純 SDK 呼叫閘道。Neon 注入 NEON_AI_GATEWAY_* 變數（而非 OPENAI_*），請從這些變數設定用戶端的 apiKey + baseURL。

OpenAI SDK（Chat Completions 與 Responses）

`/v1` — Chat Completions（統一端點）

這是目錄中所有模型的通用端點（包括 Anthropic / Gemini 模型在內），透過 OpenAI 相容的 Chat Completions 路由。對於不需要 Anthropic 專用功能（提示快取、擴展思考）或 Gemini 專用功能的情況，建議使用此端點：

import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "claude-sonnet-4-6", // 任何目錄 ID
  messages: [{ role: "user", content: "Hello" }],
});

`/openai/v1` — OpenAI Responses API

此路由的處理方式與 /v1 相同，但使用 OpenAI Responses 語義（而非 Chat Completions）。對於需要 Responses API 的模型（例如 gpt-5-…-codex 變體），請使用 client.responses：

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-3-codex",
  input: "Write a React component.",
});

Anthropic SDK（原生 Messages 路由）

使用 Anthropic SDK 設定為指向 NEON_AI_GATEWAY_BASE_URL/anthropic。SDK 會自行附加 /v1/messages，因此完整的請求路徑為 /anthropic/v1/messages。這解鎖了 Anthropic 專用功能，例如提示快取：

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

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

const msg = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});

google-genai SDK（原生 Gemini 路由）

使用 google-genai SDK 設定為指向 NEON_AI_GATEWAY_BASE_URL/gemini：

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: "Explain quantum computing",
});

串流

上述所有 SDK 都原生支援其串流 API（例如 client.chat.completions.stream() 或 client.messages.stream()），並透過閘道的 SSE 支援。所有端點皆可串流，無需額外設定。

模型目錄與可用性

模型目錄會動態變化 — 新的模型會加入，偶爾也會有模型退役。從 /v1/models 取得特定模型清單（可使用 curl 測試，或使用 openai 用戶端，或參考 models.dev）：

# 使用 curl 列出模型
curl -s -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  "${NEON_AI_GATEWAY_BASE_URL}/v1/models" | jq '.data[].id'

在 us-east-2 區域，這會傳回一個物件陣列，其中包含 id、owned_by、created 等欄位。將此輸出與 Neon Console 中的「AI Gateway」頁面及 models.dev 視為最新清單。/v1/models 端點會反映您帳戶在該分支中實際可用的模型。

目錄會定期更新；請查閱 Neon 文件以取得最新資訊。

neondatabase/neon-ai-gateway

neon-ai-gateway 是什麼？

在你喜歡的 AI 中提問

說明文件