Passerelle IA Neon

Il s'agit d'une fonctionnalité en aperçu et disponible uniquement dans us-east-2. La passerelle IA Neon est la couche d'inférence LLM intégrée à votre branche Neon : une seule API et une seule credential Neon vous donnent accès à des modèles pionniers et open-source d'Anthropic, OpenAI, Google, Meta, Alibaba, DeepSeek et Databricks — alimentés par Databricks. Votre SDK OpenAI/Anthropic/Gemini existant fonctionne en changeant uniquement l'URL de base.

Utilisez cette skill pour aider l'utilisateur à envoyer des appels de modèles via la passerelle, l'intégrer au SDK AI ou Mastra, et basculer entre les fournisseurs sans réécrire le code. Fournissez une requête d'inférence opérationnelle, un agent configuré, ou une réponse précise tirée de la documentation officielle Neon.

Quand l'utiliser

Recourez à la passerelle IA chaque fois qu'une application ou un agent doit appeler un LLM et que l'utilisateur préfère ne pas gérer lui-même les fournisseurs de modèles :

Une credential au lieu de nombreux comptes de fournisseur. Une seule credential Neon accède à l'intégralité du catalogue de modèles sur sept fournisseurs. Pas de facturation, clés ou inscriptions OpenAI / Anthropic / Google séparées à provisionner et faire tourner.
Basculer entre les modèles sans réécrire. L'endpoint unifié est compatible OpenAI et fonctionne avec tous les modèles du catalogue — changez un seul champ model pour passer entre Claude, GPT et Gemini. Les SDK standard (OpenAI, Anthropic, google-genai) fonctionnent avec juste un changement d'URL de base.
L'IA suit vos branches. Chaque branche a son propre endpoint de passerelle, délimité par la même lignée que votre base de données. Les requêtes IA d'une branche preview/feature sont isolées à cette branche — la même isolation que celle dont bénéficient déjà vos données — ce qui rend les environnements preview, CI et agent autonomes.
Pas d'infrastructure supplémentaire, et c'est déjà à côté de vos données. La passerelle vit à l'intérieur de votre projet Neon (et est injectée dans les Neon Functions automatiquement), s'exécute sur la même infrastructure Databricks qui dessert des milliers de milliards de tokens par mois, et supporte le streaming (SSE) d'office.

Si l'utilisateur possède déjà une intégration monoFournisseur approfondie et n'a aucun intérêt pour la création de branches Neon ou le routage multi-modèles, un SDK de fournisseur direct convient — mais dès qu'il veut une credential unique, la portabilité des modèles ou l'IA délimitée par branche, c'est la raison de l'utiliser.

Ce qu'elle fait

Une API pour tous les modèles — Modèles pionniers et open-source derrière un endpoint unique, adressés par leur ID de catalogue (par ex. claude-sonnet-4-6, gpt-5-mini, gemini-2-5-flash).
SDK standard, un changement d'URL — SDK OpenAI et AI SDK (routes Responses/MLflow compatibles OpenAI), SDK Anthropic (Messages natif), google-genai (Gemini natif).
Délimité par branche — Chaque branche obtient son propre hôte de passerelle ; la credential Neon autorise les requêtes pour cette branche et ses descendants.
Streaming — Les événements envoyés par le serveur fonctionnent sur tous les endpoints sans configuration supplémentaire.

Configuration

La passerelle fait partie de neon.ts (voir la skill neon pour le workflow branch-first et les bases de neon.ts). Activez-la sous preview.aiGateway :

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

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

neonctl deploy   # provisionne la passerelle sur la branche liée

Variables d'environnement

Quand preview.aiGateway est activé, Neon injecte les credentials de la passerelle comme variables d'env standard OpenAI (pour que le SDK OpenAI et le SDK AI fonctionnent depuis l'environnement sans config), plus des alias de marque NEON_. À l'intérieur d'une Neon Function déployée, ces variables sont injectées automatiquement ; localement, neonctl env pull les écrit dans .env/.env.local (ou utilisez neon-env run -- <cmd> pour les injecter à l'exécution sans fichier) :

Variable	Sens
`OPENAI_API_KEY`	Token porteur de la passerelle (une credential Neon, `nt_live_...`)
`OPENAI_BASE_URL`	Route complète du dialecte OpenAI, incluant `/ai-gateway/openai/v1` : `https://<branch-id>-api.ai.<region>.aws.neon.tech/ai-gateway/openai/v1`
`NEON_AI_GATEWAY_TOKEN`	Même porteur que `OPENAI_API_KEY` (persiste si un utilisateur remplace `OPENAI_*` par ses propres clés)
`NEON_AI_GATEWAY_BASE_URL`	Hôte de passerelle de branche nu (`scheme://host`, pas de chemin — pas de `/ai-gateway`) : `https://<branch-id>-api.ai.<region>.aws.neon.tech`

Les deux URL de base sont différentes : OPENAI_BASE_URL inclut déjà la route complète /ai-gateway/openai/v1 (Responses), tandis que NEON_AI_GATEWAY_BASE_URL est juste l'hôte nu, donc vous ajoutez /ai-gateway/<dialect> vous-même (c'est aussi ce que @neondatabase/ai-sdk-provider fait pour vous). Les routes sous l'hôte sont :

/ai-gateway/mlflow/v1 — unifié, compatible Chat Completions OpenAI ; recommandé par défaut, fonctionne avec tous les fournisseurs.
/ai-gateway/openai/v1 — API OpenAI Responses (requis pour les variantes gpt-5-…-codex et gpt-5-5-pro). C'est la route vers laquelle OPENAI_BASE_URL pointe déjà, car le fournisseur @ai-sdk/openai utilise l'API Responses par défaut.
/ai-gateway/anthropic/v1 — Messages Anthropic natif (extended thinking, prompt caching).
/ai-gateway/gemini/v1beta/... — generateContent Gemini natif.

Donc ${NEON_AI_GATEWAY_BASE_URL}/ai-gateway/mlflow/v1 est l'endpoint chat-completions, ${NEON_AI_GATEWAY_BASE_URL}/ai-gateway/openai/v1 égale OPENAI_BASE_URL, et ainsi de suite. Si vous avez uniquement OPENAI_BASE_URL et avez besoin de chat completions, changez le dialecte : baseUrl.replace("/openai/v1", "/mlflow/v1") (c'est ce que l'exemple Mastra fait).

Pour un accès typé, parseEnv (de @neondatabase/env) retourne env.aiGateway (apiKey, baseUrl) dérivé de votre neon.ts.

Utiliser avec le SDK Vercel AI

L'exemple with-ai-sdk déploie un agent comme Neon Function qui stream du texte et génère des images. Le fournisseur @ai-sdk/openai lit OPENAI_API_KEY et OPENAI_BASE_URL depuis l'env injecté automatiquement — aucune config client nécessaire ; choisissez juste un modèle du catalogue :

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

const result = streamText({
  model: openai("gpt-5-mini"),
  messages,
  tools: {
    image_generation: openai.tools.imageGeneration({
      outputFormat: "jpeg",
      size: "1024x1024",
    }),
  },
});
return result.toUIMessageStreamResponse();

Pour le routage multi-fournisseur à partir d'un seul appel, le dédié @neondatabase/ai-sdk-provider lit NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN et route chaque modèle vers le meilleur endpoint (Anthropic → Messages, OpenAI/Codex → Responses, tout le reste → MLflow) :

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

const { text } = await generateText({
  model: neon("claude-haiku-4-5"), // ou gpt-5-3-codex, gemini-2-5-flash, ...
  prompt: "Summarize Postgres for me.",
});

Utiliser avec Mastra

L'exemple with-mastra exécute un agent muni de mémoire (threads/messages dans Postgres via @mastra/pg) comme Neon Function, avec son modèle pointant vers la passerelle. Il lit env.aiGateway depuis parseEnv et utilise le dialecte chat-completions (MLflow) :

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

const env = parseEnv(config);
const gatewayUrl = env.aiGateway.baseUrl.replace("/openai/v1", "/mlflow/v1");

export const personalAssistant = new Agent({
  id: "personal-assistant",
  name: "personal-assistant",
  instructions:
    "You are a warm, concise personal assistant with long-term memory.",
  model: {
    id: `neon/claude-haiku-4-5`,
    url: gatewayUrl,
    apiKey: env.aiGateway.apiKey,
  },
  memory,
});

Utiliser avec les SDK simples

Les OPENAI_API_KEY et OPENAI_BASE_URL injectés sont standard OpenAI, donc new OpenAI() les récupère avec zéro config. Puisque OPENAI_BASE_URL est le dialecte OpenAI Responses (/openai/v1), appelez l'API Responses :

import OpenAI from "openai";

const client = new OpenAI(); // lit OPENAI_API_KEY + OPENAI_BASE_URL depuis l'env

const res = await client.responses.create({
  model: "gpt-5-mini", // changez en claude-sonnet-4-6, gemini-2-5-flash, ...
  input: "What is Neon?",
});

Pour le dialecte unifié chat-completions (/mlflow/v1) à la place, pointez le client dessus. La façon ergonomique est de changer le dialecte sur l'URL de base injectée plutôt que de la reconstruire (même mouvement que celui de l'exemple Mastra) :

const client = new OpenAI({
  baseURL: process.env.OPENAI_BASE_URL!.replace("/openai/v1", "/mlflow/v1"),
});

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

Le SDK Anthropic et google-genai fonctionnent de la même façon pour les fonctionnalités de fournisseur natif — pointez-les vers les routes /anthropic et /gemini sur l'hôte de passerelle nu (${NEON_AI_GATEWAY_BASE_URL}/ai-gateway/anthropic, ${NEON_AI_GATEWAY_BASE_URL}/ai-gateway/gemini).

Identifiants de modèle

Utilisez l'ID de catalogue d'un modèle directement dans le champ model — par ex. claude-sonnet-4-6, gpt-5-mini, gemini-2-5-flash. Aucun préfixe de fournisseur n'est nécessaire. Pour rechercher les identifiants exacts que la passerelle sert, quel modèle sous-jacent chaque ID mappe, et leurs fenêtres de contexte, tarification et capacités, utilisez l'un des suivants :

Page fournisseur Neon sur models.dev : https://models.dev/providers/neon — la liste canonique, toujours actuelle des ID de modèle du fournisseur Neon et leurs modèles sous-jacents. Le catalogue lisible par machine est à https://models.dev/api.json (la clé neon).
Doc Models : voir Lectures complémentaires.

Disponibilité

La passerelle IA est une fonctionnalité en aperçu (accès anticipé) disponible uniquement sur les nouveaux projets dans la région us-east-2 ; elle ne peut pas être activée sur les projets existants. L'accès aux modèles de base requiert un plan Neon payant. Confirmez que le projet de l'utilisateur est un nouveau projet dans us-east-2. Si l'utilisateur n'a pas encore accès, pointez-le vers l'inscription à la bêta privée : https://neon.com/blog/were-building-backends#access

Documentation Neon

La documentation Neon est la source de vérité et la passerelle IA évolue rapidement, donc vérifiez toujours par rapport aux docs officielles. N'importe quelle page de documentation peut être récupérée en markdown en ajoutant .md à l'URL ou en demandant Accept: text/markdown. Trouvez la bonne page à partir de l'index des docs (https://neon.com/docs/llms.txt) et les annonces du changelog.

neon-ai-gateway