第一步：使用父级 neon 技能获取 Neon 概述、入门指南、Neon 开发最佳实践等更多信息。

如果尚未安装 neon 技能，请从 https://neon.com/docs/ai/skills/neon/SKILL.md 获取，或使用以下命令安装：

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

Neon AI 网关

这是一个公开 Beta 功能，目前可在 us-east-2 和 eu-central-1 区域使用。

Neon AI 网关是内置于 Neon 分支中的 LLM 推理层：一个 API 和一个 Neon 凭证即可访问来自多家提供商（Anthropic、OpenAI、Google、Meta 等）的尖端和开源模型，所有模型均由 Databricks 托管和驱动。模型目录会随时间变化，因此请将 /v1/models 和 models.dev Neon 页面视为权威来源，而非固定的提供商列表。您现有的 OpenAI/Anthropic/Gemini SDK 只需更改 base URL 即可工作。

使用此技能帮助用户通过网关发送模型调用，将其集成到 AI SDK 或 Mastra 中，并在不重写代码的情况下切换提供商。提供可用的推理请求、配置好的代理或来自官方 Neon 文档的精确答案。

何时使用

当应用或代理需要调用 LLM，而用户不愿自行管理模型提供商时，请使用 AI 网关：

一个凭证代替多个提供商账户。 单个 Neon 凭证即可访问 Databricks 托管的整个模型目录中的所有提供商。无需单独的 OpenAI/Anthropic/Google 账单、密钥或注册进行配置和轮换。
无需重写代码即可切换模型。 统一的端点兼容 OpenAI，可与目录中的每个模型配合使用 — 更改一个 model 字段即可在 Claude、GPT 和 Gemini 之间切换。标准 SDK（OpenAI、Anthropic、google-genai）只需更改 base URL 即可工作。
AI 跟随您的分支。 每个分支都有自己的网关端点，具有与数据库相同的隔离性。来自预览/功能分支的 AI 请求将隔离到该分支 — 您的数据已经具有这种隔离性 — 这使得预览、CI 和代理环境可以自包含。
无需额外基础设施，且已位于您的数据旁边。 网关位于您的 Neon 项目内部（并自动注入到 Neon Functions 中），在每月处理数万亿个令牌的同一 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 网关是公开 Beta 功能，目前可在 us-east-2 和 eu-central-1 区域使用。基础模型访问需要付费的 Neon 计划。确认用户的项目位于这些区域之一。

启用网关：计划和模型目录限制

AI 网关基于凭证而非配置步骤，但有两个计划/Beta 限制对其进行了限制 — 一个阻止配置，另一个仅限制目录 — CLI 会显示每个限制：

免费计划 → 配置被阻止。 neon config apply / deploy 和 neon checkout 会拒绝在免费计划上启用网关（网关无法在其中服务请求），并显示友好的“升级到付费计划，或移除 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（请参阅下面的模型部分）来验证分支实际可用的模型，而不是假设完整的目录。

当帮助用户调试“网关无法工作”或“模型缺失”时，请使用 /v1/models 以及账户的计划来区分这两种情况 — 免费计划完全阻止配置，而付费计划上的受限目录仅需要模型访问请求。

设置

网关是 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     # dry-run 显示 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 品牌的环境变量注入。在部署的 Neon Function 内部，这些变量会自动注入；在本地，neon env pull 会将它们写入 .env/.env.local（或使用 neon-env run -- <cmd> 在运行时注入而不使用文件）：

变量	含义
`NEON_AI_GATEWAY_TOKEN`	网关 Bearer 令牌（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（扩展思考、提示缓存）。将 Anthropic SDK 的 base URL 设置为此值，它会自行附加 /v1/messages，因此完整请求路径为 /anthropic/v1/messages。
/gemini — 原生 Gemini generateContent。将 google-genai 的 base URL 设置为此值，它会自行附加 /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 方言，您将较短的 /anthropic 或 /gemini base 提供给 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: "为我总结 Postgres。",
});

优先选择 @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: "我有多少打开的任务，最旧的是哪个？",
  tools: {
    listTodos: tool({
      description: "列出用户打开的任务。",
      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: "Hello, world!",
  tools: [{ type: "web_search_preview" }],
});

对于 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 msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});

对于 google-genai 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: "Hello, Gemini",
});

列出模型

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

这将返回目录中的可调用模型列表。使用此端点验证分支上可用的模型，而不是依赖提供商文档。

常见提示

使用 AI 网关时，请记住：

分支的网关设置保留其 Neon 凭证的隔离。不要在不同分支之间共享凭证。
在开发过程中，使用 neon env pull 在本地拉取环境变量，或使用 neon deploy 自动注入。
对于模型目录问题，请检查计划（付费 vs 免费）和 /v1/models 输出。
在项目之间迁移时，您的 neon.ts 文件将网关配置保留在版本控制中，使团队设置变得简单。

neondatabase/neon-ai-gateway

neon-ai-gateway 是什么？

在你喜欢的 AI 中提问

文档