neon-ai-gateway

首先：使用父级 neon 技能了解 Neon、开始使用 Neon、掌握 Neon 开发最佳实践等。

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

neon skills -s neon -y

Neon AI Gateway

目前在 aws-us-east-2、aws-us-east-1、aws-eu-central-1 和 aws-ap-southeast-1 中可用。

Neon AI Gateway 可在 Neon 分支中提供大模型和嵌入模型推理能力。使用一个 API 和一个 Neon 凭证，即可访问来自众多提供商（Anthropic、OpenAI、Google、Meta 等）的前沿模型和开源模型，以及嵌入模型；所有模型均由 Databricks 托管并提供支持。模型目录会随时间变化，因此请以 /v1/models 和 models.dev 上的 Neon 页面 为准，而不要依赖固定的提供商列表。有关嵌入模型 ID 和维度，请参阅嵌入指南。只需更改基础 URL，现有的 OpenAI/Anthropic/Gemini SDK 即可继续使用。

使用此技能帮助用户通过网关发送模型调用、将其接入 AI SDK 或 Mastra，并在不改接代码的情况下切换提供商。交付可运行的推理请求、已配置的 Agent，或根据 Neon 官方文档给出准确答案。

适用场景

只要应用或 Agent 需要调用大模型或生成文本嵌入，而用户不想自行管理模型提供商，就应使用 AI Gateway：

• 使用一个凭证，无需管理多个提供商账户。 单个 Neon 凭证即可访问 Databricks 托管的所有提供商的完整模型目录。无需配置或轮换独立的 OpenAI / Anthropic / Google 账单、密钥或注册账户。
• 切换模型，无需改接代码。 统一端点兼容 OpenAI，可用于目录中的所有模型——只需更改一个 model 字段，即可在 Claude、GPT 和 Gemini 之间切换。标准 SDK（OpenAI、Anthropic、google-genai）只需更改基础 URL 即可使用。
• AI 随分支而行。 每个分支都有自己的网关端点，其作用范围与数据库遵循相同的谱系。从预览/功能分支发出的 AI 请求与该分支隔离——数据也采用相同的隔离方式——因此预览、CI 和 Agent 环境都能独立运行。
• 无需额外基础设施，而且网关就在数据旁边。 网关位于 Neon 项目内（并会自动注入 Neon Functions），运行在每月处理数万亿 Token 的同一 Databricks 基础设施上，并且开箱即支持流式传输（SSE）。

如果用户已经深度集成了单一提供商，且不需要 Neon 分支或多模型路由，那么直接使用提供商 SDK 也没问题；但只要他们需要一个凭证、模型可移植性或按分支隔离的 AI，这就是使用 AI Gateway 的理由。

功能

• 通过一个 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 凭证授权访问该分支及其后代分支。
• 流式传输 — 聊天生成支持服务器发送事件，无需额外配置。
• 嵌入 — 生成用于语义搜索的向量。

可用性

设置前请先确认以下前提条件：

AI Gateway 目前在 aws-us-east-2、aws-us-east-1、aws-eu-central-1 和 aws-ap-southeast-1 中可用。请确认用户的项目位于这些区域之一。

AI Gateway 仅适用于 Neon 付费计划（Launch 和 Scale），使用时会扣减预付的 AI Gateway 额度。任何拥有预付额度的付费账户都可以调用目录中的所有模型。请参阅 https://neon.com/docs/ai-gateway/prepaid-credits.md。

启用网关：套餐和模型访问权限

AI Gateway 受凭据限制，而非配置步骤。CLI 会显示套餐和模型访问权限限制：

• 免费套餐 → 阻止配置。 neon config apply / deploy 和 neon checkout 会拒绝在免费套餐上启用网关（网关无法在该套餐下处理请求），并显示友好的错误信息：“升级到付费套餐，或移除 aiGateway”。试运行 neon config plan 和 neon env pull 不会配置网关，因此只会发出警告。因此，要使用网关，项目账户必须使用 Neon 付费套餐。
• 付费套餐，但模型已锁定。 GET /v1/models 会列出目录中的所有模型，并将账户目前无法调用的模型标记为 enabled: false。当部分模型已启用，但其中没有旗舰模型（例如 Anthropic Opus、OpenAI Codex / *-pro）时，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）。该页面会在 Some models are restricted 下按原因分组列出锁定的模型，并为每种情况提供解决方法：付费套餐对应 Upgrade plan，预付费额度对应 Add credits；如果账户受限或模型不适用于该账户，则需联系 Support。用户升级套餐或购买额度后，Neon 确认访问权限后，模型便会解锁。CLI 未发出警告并不意味着所有模型都已启用；请检查模型的 enabled 值。请参阅 https://neon.com/docs/ai-gateway/troubleshooting.md。

设置

网关是 neon.ts 的一部分（有关以分支为先的工作流和 neon.ts 基础知识，请参阅 neon skill）。使用 aiGateway 启用网关：

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

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

neon deploy   # provisions the gateway on the linked branch

Neon 基础设施即代码（neon.ts）

上面的 aiGateway 开关属于 neon.ts，即 Neon 的基础设施即代码文件——一个 TypeScript 文件即可在版本控制中声明网关及其他所有分支服务（完整参考信息请参阅 neon skill）。按照 Terraform 的方式，将其与分支协调一致：

neon config status   # print the branch's live config (is the gateway on?)
neon config plan     # dry-run diff of what apply would change
neon config apply    # enable the gateway on the branch  (neon deploy is an alias)

网关的作用范围为分支：每个分支都有自己的网关主机。存在 neon.ts 时，neon checkout 会在_创建_分支时应用策略，因此新建的预览／CI 分支会在启动时自动启用网关。检出_现有_分支不会协调配置——请运行 neon deploy 以应用更改。配置（config apply / deploy）、link 和 checkout 也会将分支的网关凭据拉取到本地 .env.local，因此本地运行会使用与已部署函数相同的分支网关（无需手动运行 env pull）。

环境变量

启用 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 的基础 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 是 Chat Completions 端点，${NEON_AI_GATEWAY_BASE_URL}/openai/v1 是 OpenAI Responses 端点（这两个路径都由你自行附加）；对于原生 Anthropic 和 Gemini 协议，将较短的 /anthropic 或 /gemini 基础 URL 交给 SDK，SDK 会附加其余路径。请参阅下文的 与纯 SDK 配合使用。

要以类型安全且经过验证的方式访问注入的凭据，请将同一个 neon.ts 配置对象传递给 @neon/env 中的 parseEnv — 它会根据你的配置返回 env.aiGateway 命名空间（apiKey、baseUrl）。

使用 Vercel AI SDK 构建 Agent（推荐）

Vercel AI SDK 是从 TypeScript 调用网关并构建 Agent 的推荐方式：一套原语（generateText、streamText、工具调用、结构化输出）即可用于目录中的所有模型，并为 Neon Functions 专门构建的长篇 Agent 响应提供一流的流式传输支持。

专用的 @neon/ai-sdk-provider 会从注入的环境变量中读取 NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN，无需任何配置，并将每个模型路由到最佳端点（Anthropic → Messages，OpenAI/Codex → Responses，其他所有模型 → MLflow）。在会流式传输文本并生成图像的 Neon Function 中，请选择 OpenAI 目录模型，因为图像工具使用 Responses 路由：

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

const result = streamText({
  model: neon("gpt-5-mini"),
  messages,
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      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"), // or 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 }) 显式配置。

若要构建 Agent——一种循环调用工具并最终作答的模型——请添加 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`, not `parameters`
      execute: async () => db.select().from(todos),
    }),
  },
  stopWhen: stepCountIs(5), // let the model call tools, then summarize
});

如需查看完整的 AI SDK Agent 部署为 Neon Function 的示例（包括流式传输、工具调用、图像生成和持久化），请参阅 neon-functions 技能中的 references/ai-sdk.md。

生成图像

图像由 OpenAI 模型上的 OpenAI Responses 内置 image_generation 工具生成，并通过 /openai/v1/responses 路由调用。网关没有图像模型端点，因此 AI SDK 的 generateImage() 会抛出 NoSuchModelError。每个图像请求都必须遵循两条规则：

• 使用受支持的图像模型。 网关支持 gpt-image-2、gpt-image-1.5 和 gpt-image-1-mini。请在每个工具定义中显式设置 model，除非用户另有要求，否则使用 gpt-image-2。
• 始终使用流式传输。 图像超过 655,360 字节的非流式响应会失败，并报错 400: The response content length cannot be greater than 655360 bytes long，而大多数图像都超过此大小。附加图像工具时，请使用 streamText，不要使用 generateText。使用纯 OpenAI SDK 时，请向 client.responses.create() 传入 stream: true。

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

const result = streamText({
  model: neon("gpt-5-mini"),
  prompt: "Generate an image of a red apple on a wooden table",
  tools: {
    image_generation: neon.tools.imageGeneration({ model: "gpt-image-2" }),
  },
});

for await (const part of result.fullStream) {
  if (
    part.type === "tool-result" &&
    !part.dynamic &&
    "result" in part.output &&
    typeof part.output.result === "string"
  ) {
    const png = Buffer.from(part.output.result, "base64"); // save or upload it
  }
}

使用 AI SDK 生成嵌入

嵌入调用请使用 @neon/ai-sdk-provider 1.0.0+ 和 AI SDK 6+。neon.embeddingModel() 会读取与语言模型相同的注入网关变量：

import { neon } from "@neon/ai-sdk-provider";
import { embed, embedMany } from "ai";

const model = neon.embeddingModel("qwen3-embedding-0-6b");
const providerOptions = { neon: { dimensions: 1024 } };
const { embeddings } = await embedMany({
  model,
  values: documentBodies, // unprefixed document text
  providerOptions,
  maxParallelCalls: 1,
});
const { embedding } = await embed({
  model,
  value: `Instruct: Given a question about Neon, retrieve documentation passages that answer the question\nQuery: ${queryText}`,
  providerOptions,
});

查询指令专用于 Qwen3 和 Neon 文档搜索；请根据语料进行调整。文档保持不带前缀。文档和查询应使用相同的模型和维度，并为 BM25 保留原始查询文本。如需了解架构、存储、批量限制以及 OpenAI SDK 替代方案，请参阅 neon-postgres 技能中的 向量搜索指南。

使用 Mastra 构建 Agent（推荐）

Mastra 是适合构建开箱即用型 Agent 的推荐框架，内置记忆、工具、工作流和追踪，同时模型仍指向网关。对于 @mastra/core 1.47+，请使用 neon/<model> 魔法字符串；Mastra 会从环境变量中读取 NEON_AI_GATEWAY_BASE_URL 和 NEON_AI_GATEWAY_TOKEN（启用 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:
    "You are a warm, concise personal assistant with long-term memory.",
  model: "neon/claude-haiku-4-5",
  memory, // your Mastra memory store, e.g. @mastra/pg on env.postgres.databaseUrl
});

与普通 SDK 搭配使用（较低层级）

如果你不需要 Agent 框架——例如只需进行一次补全、使用现有的提供商 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 res = await client.responses.create({
  model: "gpt-5-mini", // swap to claude-sonnet-4-6, gemini-3-flash, ...
  input: "What is Neon?",
});

对于统一的 chat-completions 方言，请将 baseURL 指向 /v1：

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

const res = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "What is Neon?" }],
});

Anthropic SDK 和 google-genai 用于提供商原生功能时也采用相同方式——将 Anthropic SDK 指向 ${NEON_AI_GATEWAY_BASE_URL}/anthropic（它会自行追加 /v1/messages），将 google-genai 指向 ${NEON_AI_GATEWAY_BASE_URL}/gemini（它会自行追加 /v1beta/models/...）。

模型标识符

在 model 字段中直接使用模型的目录 ID，例如 claude-sonnet-4-6、gpt-5-mini、gemini-3-flash。无需添加提供商前缀。若要查询网关提供的确切标识符、每个标识符对应的底层模型，以及上下文窗口、定价和功能，请使用以下任一资源：

• models.dev Neon 提供商页面：https://models.dev/providers/neon — Neon 提供商模型 ID 及其底层模型的权威且始终最新的列表。机器可读目录位于 https://models.dev/api.json（`neon` 键）。
• **Models 文档：**参见“延伸阅读”。

在运行时列出可用模型（/v1/models）

网关还会通过你自己的分支端点实时提供模型目录，因此应用或 Agent 可以准确发现此分支提供的模型，无需将列表硬编码。这是一个兼容 OpenAI 的列表端点，仅通过统一方言（/v1）提供：

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

• GET ${NEON_AI_GATEWAY_BASE_URL}/v1/models → 200
• GET ${NEON_AI_GATEWAY_BASE_URL}/openai/v1/models → 404（Responses 方言不提供此端点——请使用 /v1）

**获取请求所需的凭据。**这两个值都来自同一个分支范围的 Neon 凭据，网关在其他所有场景中也使用该凭据——你无需管理提供商密钥：

• 通过 neon.ts 配置（推荐）。在 neon.ts 中启用 aiGateway 并运行 neon deploy（或 neon config apply）。配置、neon link 和 neon checkout 会将 NEON_AI_GATEWAY_TOKEN 和 NEON_AI_GATEWAY_BASE_URL 写入本地 .env.local；在已部署的 Neon Function 中，这些变量会自动注入。参见上文的设置和环境变量。
• 通过 CLI 拉取到环境中。neon env pull 会将这两个变量写入 .env/.env.local，或者 neon-env run -- <cmd> 会在运行时注入它们，而无需写入文件——但前提是 neon.ts 中声明了 aiGateway；这些变量不会仅从分支状态中拉取。
• **通过 Console UI 配置。**在 Neon Console 中为分支启用 AI Gateway，然后从项目的连接/凭据视图中复制该分支的网关基础 URL 和 Neon 凭据（令牌）。

任何对该分支有效的 Neon 凭据（nt_live_...）都可用作 bearer token；NEON_AI_GATEWAY_BASE_URL 是不带路径的分支主机地址。

响应格式——兼容 OpenAI/OpenRouter 的列表：

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-4-6",              // catalog model ID — use directly in the `model` field
      "canonical_slug": "claude-sonnet-4-6",
      "name": "Claude Sonnet 4.6",            // human-readable display name
      "object": "model",
      "owned_by": "anthropic",                // provider slug, e.g. anthropic | openai | google | meta | alibaba | databricks | ... (non-exhaustive; read live)
      "created": 0,
      "enabled": true,
      "context_length": null,
      "architecture": {
        "modality": "text->text",
        "input_modalities": ["text"],
        "output_modalities": ["text"],
        "tokenizer": "Claude",                // Claude | Gemini | GPT | "" (empty for open-source)
        "instruct_type": null
      },
      "top_provider": {
        "is_moderated": false,
        "context_length": null,
        "max_completion_tokens": null
      },
      "pricing": null,
      "per_request_limits": null
    }
    // ... one entry per model in the branch's catalog
  ]
}

注意：目前所有条目的 context_length、pricing 和 per_request_limits 均为 null，created 均为 0。有关上下文窗口、定价和功能，请使用上文的 models.dev 目录。需要实时获取分支范围内可提供的模型 ID 列表时（例如填充模型选择器或在请求前验证 model），请使用 /v1/models，并仅保留 enabled: true 的条目。

Neon 文档

Neon 文档是准确信息的唯一来源，而 AI Gateway 正在快速演进，因此请务必以官方文档为准。向任意文档页面的 URL 追加 .md，或请求 Accept: text/markdown，即可将该页面作为 Markdown 获取。从文档索引（https://neon.com/docs/llms.txt）和更新日志公告中查找所需页面。

Further Reading

• https://neon.com/docs/ai-gateway/overview.md
• https://neon.com/docs/ai-gateway/get-started.md
• https://neon.com/docs/ai-gateway/models.md
• https://neon.com/docs/ai-gateway/chat-completions.md
• https://neon.com/docs/ai-gateway/anthropic-messages.md
• https://neon.com/docs/ai-gateway/openai-responses.md
• https://neon.com/docs/ai-gateway/gemini.md
• https://neon.com/docs/ai-gateway/authentication.md
• https://neon.com/docs/ai-gateway/troubleshooting.md