첫 번째: 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 추론 계층입니다. 하나의 API와 하나의 Neon 자격 증명으로 다양한 제공자(Anthropic, OpenAI, Google, Meta 등)의 최첨단 및 오픈 소스 모델에 접근할 수 있으며, 모두 Databricks에서 호스팅 및 구동됩니다. 카탈로그는 시간에 따라 변동되므로, /v1/models와 models.dev Neon 페이지를 고정된 제공자 목록 대신 신뢰할 수 있는 출처로 삼으세요. 기존의 OpenAI/Anthropic/Gemini SDK는 기본 URL만 변경하면 작동합니다.
이 스킬을 사용하여 사용자가 게이트웨이를 통해 모델 호출을 보내고, AI SDK 또는 Mastra에 연결하며, 코드 재작성 없이 제공자를 전환할 수 있도록 도와주세요. 작동하는 추론 요청, 구성된 에이전트, 또는 공식 Neon 문서의 정확한 답변을 제공하십시오.
사용 시기
앱이나 에이전트가 LLM을 호출해야 하는데 사용자가 직접 모델 제공자를 관리하고 싶지 않을 때마다 AI Gateway를 사용하세요:
- 여러 제공자 계정 대신 하나의 자격 증명. 단일 Neon 자격 증명으로 Databricks가 호스팅하는 모든 제공자의 전체 모델 카탈로그에 접근할 수 있습니다. 별도의 OpenAI / Anthropic / Google 결제, 키, 또는 가입을 프로비저닝하고 교체할 필요가 없습니다.
- 코드 재작성 없이 모델 전환. 통합 엔드포인트는 OpenAI 호환 가능하며 카탈로그의 모든 모델과 작동합니다.
model필드 하나만 변경하면 Claude, GPT, Gemini 간에 전환할 수 있습니다. 표준 SDK(OpenAI, Anthropic, google-genai)는 기본 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 자격 증명은 해당 브랜치 및 그 하위 항목에 대한 요청을 승인합니다.
- 스트리밍 — 서버 전송 이벤트는 추가 구성 없이 모든 엔드포인트에서 작동합니다.
가용성
설정을 시작하기 전에 다음 전제 조건을 확인하세요:
AI Gateway는 현재 us-east-2 및 eu-central-1에서 사용 가능한 공개 베타 기능입니다. 기반 모델에 접근하려면 유료 Neon 플랜이 필요합니다. 사용자의 프로젝트가 이 리전 중 하나에 있는지 확인하세요.
게이트웨이 활성화: 플랜 및 모델 카탈로그 게이팅
AI Gateway는 프로비저닝 단계가 아닌 자격 증명 게이트 방식이지만, 두 가지 플랜/베타 제한이 이를 제어합니다. 하나는 프로비저닝을 차단하고, 다른 하나는 카탈로그만 축소합니다. CLI는 각각을 표시합니다:
- 무료 플랜 → 프로비저닝이 차단됩니다.
neon config apply/deploy및neon checkout은 무료 플랜에서 게이트웨이 활성화를 거부합니다(게이트웨이가 거기서 요청을 서비스할 수 없음). "유료 플랜으로 업그레이드하거나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 페이지(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 Infrastructure as Code (neon.ts)
위의 preview.aiGateway 토글은 neon.ts의 일부입니다. Neon의 Infrastructure as Code 파일로, 하나의 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 브랜딩된 환경 변수로 주입합니다. 배포된 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은 이 두 변수만 주입합니다.
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을 기본 URL로 제공하면 SDK가 자체적으로/v1/messages를 추가하므로, 전체 요청 경로는/anthropic/v1/messages가 됩니다./gemini— 네이티브 GeminigenerateContent. google-genai에 이 URL을 기본 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로 에이전트를 구축하는 권장 방법입니다. 하나의 프리미티브 세트(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/openaiopenai()보다 선호하세요. 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에서 람다 스타일 시간 제한에 의해 중단되지 않습니다:
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), // 모델이 도구를 호출한 다음 요약하도록 함
});
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:
"You are a warm, concise personal assistant with long-term memory.",
model: "neon/claude-haiku-4-5",
memory, // 예: env.postgres.databaseUrl의 @mastra/pg를 사용한 Mastra 메모리 저장소
});
일반 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-3-codex",
input: "List the tables in my database.",
});
네이티브 Anthropic Messages 방언(/anthropic)은 NEON_AI_GATEWAY_BASE_URL + /anthropic 기본 URL을 Anthropic SDK에 전달합니다. SDK가 /v1/messages 경로를 자체적으로 추가합니다:
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 message = await anthropic.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude." }],
});
네이티브 Gemini 방언(/gemini)의 경우, google-genai SDK에 NEON_AI_GATEWAY_BASE_URL + /gemini 기본 URL을 전달합니다:
import { GoogleGenAI } from "@google/genai";
const genAI = new GoogleGenAI({
apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/gemini`,
});
const response = await genAI.models.generateContent({
model: "gemini-3-flash",
contents: "Explain branching in Neon.",
});
OpenAI Chat Completions 호환 경로 (/v1)
가장 간단한 경우로, /v1/chat/completions 엔드포인트는 OpenAI SDK와 함께 모든 제공자에서 작동합니다. 네이티브 Anthropic 기능(확장 사고, 프롬프트 캐싱)은 /v1을 통해 사용할 수 없습니다. 이러한 기능이 필요하면 @neon/ai-sdk-provider 또는 위의 네이티브 방언을 사용하세요.
모델 카탈로그 조회
GET /v1/models를 호출하여 브랜치가 접근할 수 있는 모델 목록을 확인하세요. 응답에는 각 모델에 대한 id, object, created, owned_by가 포함됩니다:
curl -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
${NEON_AI_GATEWAY_BASE_URL}/v1/models
응답은 다음과 같습니다:
{
"object": "list",
"data": [
{
"id": "claude-sonnet-4-6",
"object": "model",
"created": 1710000000,
"owned_by": "system"
},
{
"id": "gpt-5-mini",
"object": "model",
"created": 1710000001,
"owned_by": "system"
}
]
}
위에서 언급했듯이, 이 목록은 베타 기간 동안 축소될 수 있습니다. 생략된 모델이 필요하면 Neon Console의 브랜치 AI Gateway 페이지에서 접근을 요청하세요.
스트리밍
모든 엔드포인트는 서버 전송 이벤트(SSE)를 통한 스트리밍을 지원합니다. AI SDK streamText를 사용할 때 스트리밍이 자동으로 활성화됩니다. 일반 SDK를 사용하는 경우, 요청에 stream: true를 전달하세요(OpenAI SDK 및 기타 호환 가능).
문제 해결
- "게이트웨이가 작동하지 않습니다" — 프로젝트가 지원되는 리전(
us-east-2또는eu-central-1)에 있고 유료 플랜에 있는지 확인하세요.neon config status를 실행하여 게이트웨이가 활성화되었는지 확인하세요. - "모델 X를 찾을 수 없습니다" —
GET /v1/models를 호출하여 해당 모델이 카탈로그에 있는지 확인하세요. 베타 기간 동안 일부 모델이 누락될 수 있습니다. 없으면 Neon Console에서 접근을 요청하세요. - "인증 실패" —
NEON_AI_GATEWAY_TOKEN이 올바르게 설정되었고 만료되지 않았는지 확인하세요.neon env pull을 실행하여 신선한 자격 증명을 가져오세요. - 스트리밍이 작동하지 않습니다 — SDK가 SSE를 지원하는지 확인하세요. 모든 엔드포인트가 스트리밍을 지원하지만, 일부 SDK는 기본적으로 비활성화할 수 있습니다(요청에서
stream: true설정).
참조
neon스킬 — 브랜치 우선 워크플로,neon.ts참조neon-functions스킬 — AI SDK 에이전트를 Neon Function으로 배포@neon/ai-sdk-providerNPM 패키지 — AI SDK 제공자 문서- Neon Console AI Gateway — 게이트웨이 상태 및 모델 접근 관리
- models.dev — 현재 모델 카탈로그