URL de base du fournisseur personnalisé du Vercel AI SDK : Notes de configuration Flatkey

La configuration de l'URL de base du fournisseur personnalisé du Vercel AI SDK est plus qu'un simple remplacement de chaîne de caractères. La partie utile consiste à pointer le fournisseur AI SDK vers Flatkey, mais le travail de production sécurisé consiste à vérifier les alias de modèles, la famille de points de terminaison, le comportement du streaming, les appels d'outils, les preuves d'utilisation, les contrôles de quota et la restauration avant que le trafic utilisateur ne soit déplacé.

Ce guide s'adresse aux développeurs, aux équipes produit IA, aux ingénieurs de plateforme, aux créateurs d'automatisation, aux opérateurs financiers et aux examinateurs des achats qui utilisent l'AI SDK dans une route Next.js, une action de serveur, un worker, une file d'attente ou une boucle d'agent. Il a été mis à jour le 29 juin 2026 à partir de la documentation actuelle de l'AI SDK, d'une vérification de type par rapport aux paquets AI SDK actuels et des pages publiques de Flatkey. Les extraits de code sont des modèles. Aucune clé API Flatkey réelle n'était disponible pour cette tâche, alors exécutez les tests de fumée avec votre propre clé, l'URL de base actuelle de la console Flatkey et les alias de modèles activés pour votre compte.

Réponse rapide : URL de base du fournisseur personnalisé du Vercel AI SDK

Pour une configuration de l'URL de base du fournisseur personnalisé du Vercel AI SDK avec Flatkey, commencez par le paquet de fournisseur officiel compatible avec OpenAI. Créez un fournisseur avec createOpenAICompatible, définissez baseURL sur l'URL de base actuelle de Flatkey depuis votre console, définissez apiKey sur votre clé Flatkey, et utilisez les alias de modèles Flatkey dans generateText ou streamText.

npm install ai @ai-sdk/openai-compatible zod

export FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Copy the current value from Flatkey
export FLATKEY_MODEL="your-flatkey-model-alias"

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short Flatkey AI SDK routing check.',
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);

C'est la configuration minimale fonctionnelle pour une migration de l'URL de base du fournisseur personnalisé du Vercel AI SDK. Ne vous arrêtez pas là. Une réponse textuelle réussie prouve seulement qu'une forme de requête a atteint un alias de modèle. Cela ne prouve pas l'utilisation du streaming, des outils, de la sortie structurée, de la visibilité des coûts, du comportement des quotas ou de la restauration.

Ce que la documentation actuelle de l'AI SDK prend en charge

La documentation actuelle de l'AI SDK propose deux approches pertinentes. Le paquet de fournisseur compatible OpenAI est conçu pour les fournisseurs qui implémentent l'API OpenAI. Il expose createOpenAICompatible avec des options incluant name, apiKey, baseURL, headers, queryParams, un fetch personnalisé, includeUsage, supportsStructuredOutputs, des transformations du corps de la requête et l'extraction de métadonnées.

Le paquet de fournisseur OpenAI prend également en charge createOpenAI({ baseURL }) pour les configurations personnalisées, y compris les serveurs proxy. Le fournisseur compatible OpenAI est le choix par défaut le plus propre pour une URL de base du fournisseur personnalisé du Vercel AI SDK car son nom de fournisseur, l'extraction de métadonnées personnalisées, les options spécifiques au fournisseur et les noms de fabrique de modèles sont conçus pour les routes compatibles OpenAI qui ne sont pas d'OpenAI.

Modèle de fournisseur	Quand l'utiliser	Point d'examen Flatkey
createOpenAICompatible	Vous voulez un fournisseur Flatkey nommé pour les modèles de chat, de streaming, d'outils, d'embeddings, d'images ou de complétion compatibles avec OpenAI.	Point de départ privilégié pour une intégration Flatkey car name: 'flatkey' facilite le raisonnement sur les options spécifiques au fournisseur et les métadonnées.
createOpenAI({ baseURL })	Votre base de code est déjà standardisée sur @ai-sdk/openai et vous n'avez besoin que d'une URL de base personnalisée de type proxy.	Soyez explicite sur le comportement de .chat(...) par rapport à celui des Réponses ; ne présumez pas que les valeurs par défaut du fournisseur OpenAI correspondent à chaque route Flatkey.
Wrapper fetch brut	Vous avez besoin d'une transformation de corps non standard ou d'un point de terminaison que le fournisseur AI SDK ne couvre pas.	Conservez ceci comme une exception. Vous perdez la forme de résultat normalisée du SDK, les assistants d'outils et les assistants de flux typés.

Données récentes de Flatkey à utiliser avec prudence

La page d'accueil de Flatkey, vérifiée le 29 juin 2026, a pour titre One API gateway for production AI teams et une méta-description indiquant que Flatkey unifie l'accès aux modèles, le routage, la facturation, l'analyse de l'utilisation et les contrôles opérationnels. L'API de tarification en direct a retourné 633 lignes de modèles, 23 fournisseurs et des familles de points de terminaison pour /v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:generateContent, /v1/images/generations, et /v1/video/generations.

Utilisez ces faits comme des preuves publiques datées pour le positionnement et la forme du catalogue, et non comme la preuve que chaque compte peut appeler chaque route, que chaque alias de modèle est disponible ou que chaque fonctionnalité est activée. Avant le trafic de production, vos vérifications de l'URL de base du fournisseur personnalisé du Vercel AI SDK doivent utiliser la clé, l'URL de base, l'alias de modèle, la famille de points de terminaison et le chemin de fonctionnalité exacts que votre application enverra.

URL de base et configuration de l'environnement

Conservez l'URL de base, la clé et l'alias du modèle dans des variables d'environnement. Cela rend le déploiement d'une URL de base de fournisseur personnalisé du Vercel AI SDK révisable dans la configuration du déploiement au lieu d'être enfoui dans les gestionnaires de routes, les fichiers de prompts et les workers.

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

Ensuite, maintenez le routage de la charge de travail séparé de la configuration du transport. L'URL de base indique au SDK où envoyer les requêtes. L'alias du modèle décide quelle route Flatkey et quel modèle en amont vous demandez.

const MODEL_ROUTES = {
  supportTriage: 'FLATKEY_SUPPORT_MODEL',
  workflowPlanning: 'FLATKEY_PLANNING_MODEL',
  codeReview: 'FLATKEY_CODE_MODEL',
  fallback: 'FLATKEY_FALLBACK_MODEL',
} as const;

function modelFor(routeName: keyof typeof MODEL_ROUTES) {
  return flatkey.chatModel(requiredEnv(MODEL_ROUTES[routeName]));
}

Ce modèle empêche les équipes de disperser les noms de fournisseurs, les alias de modèles et les URL de base dans l'ensemble de la base de code. Il fournit également aux équipes financières et opérationnelles un ensemble stable de noms de charges de travail à faire correspondre avec les lignes d'utilisation.

Effectuez d'abord un test de fumée sur le texte non-streaming

Commencez avec generateText. Il vous donne un objet de résultat simple avec le texte, le motif de fin, l'utilisation, les avertissements, les étapes et les métadonnées de réponse. Utilisez-le pour valider l'authentification, la forme de l'URL de base, l'alias du modèle et la visibilité de l'utilisation avant de tester le streaming ou les outils.

import { generateText } from 'ai';

const result = await generateText({
  model: modelFor('supportTriage'),
  prompt: 'Reply with one short migration readiness check.',
});

console.log({
  text: result.text,
  finishReason: result.finishReason,
  usage: result.usage,
  warnings: result.warnings,
});

N'approuvez cette première vérification de l'URL de base du fournisseur personnalisé du Vercel AI SDK que si le texte généré, l'alias du modèle, le motif de fin et les champs d'utilisation sont suffisants pour les besoins de journalisation et de révision de votre application. Si l'appel renvoie du texte mais que l'utilisation ne peut être trouvée dans les enregistrements Flatkey, la migration n'est pas prête pour la production.

Testez le streaming séparément

Le streaming présente une surface de défaillance différente. Il concerne le streaming de réponse, les délais d'attente serverless, l'annulation de l'interface utilisateur, la gestion des erreurs et la comptabilisation de l'utilisation. La documentation du SDK AI montre streamText, result.textStream, un rappel onError et des promesses de résultat telles que result.usage. Le fournisseur compatible OpenAI dispose également de includeUsage pour les métadonnées de réponse en streaming lorsque le fournisseur le prend en charge.

import { streamText } from 'ai';

const stream = streamText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Stream three short setup checks.',
  onError({ error }) {
    console.error(error);
  },
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);
}

const usage = await stream.usage;
console.log({ usage });

Ne maintenez le streaming activé qu'après que l'alias du modèle Flatkey sélectionné se soit avéré stable avec la forme de vos requêtes réelles. Si le texte en streaming fonctionne mais que l'utilisation est incomplète, déterminez si votre équipe peut collecter les données d'utilisation à partir des enregistrements Flatkey plutôt que de la réponse du flux avant que le trafic utilisateur ne soit déplacé.

Vérifiez les appels d'outils avec le même alias

L'API d'outils du SDK AI utilise un objet tools, l'assistant tool, un inputSchema et une fonction execute facultative. Un simple passage de chat n'approuve pas l'appel d'outils. Testez d'abord un petit schéma, puis étendez-le à l'ensemble d'outils que vos agents utilisent réellement.

import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_TOOL_MODEL')),
  tools: {
    routeReadiness: tool({
      description: 'Return the readiness state for a Flatkey route.',
      inputSchema: z.object({
        routeName: z.string().describe('Internal route name to inspect'),
      }),
      execute: async ({ routeName }) => ({
        routeName,
        checked: true,
      }),
    }),
  },
  stopWhen: isStepCount(2),
  prompt: 'Use the tool for route supportTriage.',
});

console.log(result.toolCalls);
console.log(result.toolResults);
console.log(result.usage);

Pour le trafic des agents, enregistrez si le modèle a appelé l'outil attendu, si l'entrée a été validée, si le résultat de l'outil a été retourné sans erreur et si la ligne d'utilisation Flatkey peut être rattachée à la même route. Si les schémas stricts, les flux d'approbation ou les appels d'outils parallèles sont importants, testez ces fonctionnalités avec l'alias de modèle exact.

Quand utiliser createOpenAI à la place

Si votre application utilise déjà @ai-sdk/openai partout, l'option baseURL du fournisseur OpenAI peut être une voie de migration avec moins de modifications. Il s'agit toujours d'une configuration d'URL de base de fournisseur personnalisé du Vercel AI SDK, mais vous devriez être plus explicite quant à la sélection de l'API du modèle.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const flatkeyViaOpenAIProvider = createOpenAI({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
});

const result = await generateText({
  model: flatkeyViaOpenAIProvider.chat(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short OpenAI-provider base URL check.',
});

La documentation actuelle du fournisseur OpenAI indique que Responses est l'API par défaut pour le fournisseur OpenAI depuis la version 5 du SDK AI, sauf si vous spécifiez une route telle que .chat(...). C'est pourquoi l'exemple ci-dessus utilise .chat(...) explicitement. Si vous avez l'intention de tester la famille de points de terminaison /v1/responses de Flatkey, traitez cela comme une vérification de route distincte avec un alias de modèle et un chemin de restauration distincts.

Liste de contrôle de configuration

Vérification	Élément à capturer	Pourquoi c'est important
URL de base	Valeur actuelle de la console Flatkey, y compris le préfixe /v1 si nécessaire.	Les segments de chemin manquants et les hôtes obsolètes créent des erreurs 404 déroutantes.
Choix du fournisseur	createOpenAICompatible ou createOpenAI({ baseURL }).	Le choix du fournisseur affecte les valeurs par défaut, les métadonnées, les options spécifiques au fournisseur et les fabriques de modèles.
Alias de modèle	La chaîne de modèle Flatkey exacte pour chaque route de charge de travail.	Un nom de famille de fournisseur n'est pas suffisant pour une requête de production.
Chemin de fonctionnalité	Texte brut, streaming, outils, sortie structurée, images ou Responses.	La réussite d'un chemin de fonctionnalité n'approuve pas un autre chemin de fonctionnalité.
Enregistrement d'utilisation	Horodatage, clé, route, alias de modèle, raison de la fin, jetons, unité de coût et métadonnées du propriétaire, le cas échéant.	Les examinateurs des opérations et des finances doivent pouvoir trouver la requête sans avoir à deviner.
Restauration	Clé précédente, URL de base, modèle, indicateur de déploiement et seuil d'erreur.	La restauration doit être une modification de configuration, pas une réécriture de code lors d'un incident.

Modes d'échec courants

Symptôme	Cause probable	Correctif
404 de la requête du SDK AI	L'URL de base ne contient pas /v1, pointe vers le mauvais hôte ou utilise la mauvaise famille de points de terminaison.	Copiez la valeur actuelle de la console Flatkey et réexécutez la plus petite vérification generateText.
401 ou 403	Le processus a chargé la mauvaise clé ou a mélangé OPENAI_API_KEY et FLATKEY_API_KEY.	Journalisez uniquement les noms des variables d'environnement chargées, jamais les valeurs secrètes, et confirmez l'accès à la clé Flatkey.
Le chat simple fonctionne mais les appels d'outils échouent	L'alias ou la famille de points de terminaison sélectionné ne prend pas en charge votre schéma d'outil.	Testez d'abord le plus petit schéma Zod, puis ajoutez la rigueur, l'approbation et les boucles à plusieurs étapes.
Le streaming de texte fonctionne mais l'utilisation est vide	La route diffuse du contenu en streaming mais ne renvoie pas de métadonnées d'utilisation en streaming.	Vérifiez les enregistrements d'utilisation de Flatkey et décidez si l'utilisation de la réponse en streaming est requise pour le lancement.
Les options spécifiques au fournisseur disparaissent	La requête utilise le mauvais nom de fournisseur ou une option personnalisée non prise en charge.	Utilisez name: 'flatkey' et testez tout champ providerOptions.flatkey avant de vous y fier.

Comment cela s'intègre avec les autres guides Flatkey

Si vous avez besoin du chemin de migration plus large, commencez par le guide de migration de l'API compatible OpenAI. Pour les modèles de configuration d'outils adjacents, consultez le guide de configuration de l'API Cherry Studio et le guide cc-switch Claude Code Flatkey. Utilisez la tarification Flatkey pour inspecter le catalogue de modèles actuel, puis obtenez une clé lorsque vous êtes prêt à exécuter les tests de fumée dans votre propre compte.

Questions fréquentes

Comment définir une URL de base de fournisseur personnalisé du Vercel AI SDK pour Flatkey ?

Créez un fournisseur compatible OpenAI avec createOpenAICompatible, définissez baseURL sur l'URL de base Flatkey actuelle, définissez apiKey sur votre clé Flatkey, et passez un alias de modèle Flatkey à generateText ou streamText.

Dois-je utiliser @ai-sdk/openai-compatible ou @ai-sdk/openai ?

Utilisez @ai-sdk/openai-compatible pour une nouvelle configuration Flatkey car il est conçu pour les fournisseurs compatibles OpenAI. Utilisez @ai-sdk/openai avec createOpenAI({ baseURL }) lorsque votre application est déjà standardisée sur le fournisseur OpenAI et que vous souhaitez une différence de code plus petite.

L'URL de base doit-elle inclure /v1 ?

Utilisez la valeur affichée dans votre console Flatkey actuelle. Dans la plupart des modèles de SDK compatibles OpenAI, l'URL de base inclut le préfixe de version afin que les appels SDK puissent ajouter correctement des chemins tels que /chat/completions.

Une seule URL de base Flatkey peut-elle router plusieurs modèles ?

Le positionnement public de Flatkey est une passerelle unique pour l'accès aux modèles, le routage, la facturation, l'analyse de l'utilisation et les contrôles opérationnels. Dans votre application, mappez toujours chaque charge de travail à un alias de modèle Flatkey explicite et testez l'alias réel avant que le trafic ne soit déplacé.

Ces extraits du SDK AI ont-ils été testés ?

Les extraits ont été vérifiés au niveau des types le 29 juin 2026 par rapport à ai@7.0.4, @ai-sdk/openai-compatible@3.0.1, @ai-sdk/openai@4.0.2, TypeScript et Zod. Ils n'ont pas été exécutés sur Flatkey car aucune clé API Flatkey en direct n'était disponible dans cet environnement d'exécution.

Conclusion

Une migration de l'URL de base d'un fournisseur personnalisé pour le Vercel AI SDK devrait être une petite modification du fournisseur accompagnée d'une liste de vérification sérieuse. Utilisez createOpenAICompatible pour le fournisseur Flatkey, conservez l'URL de base et les alias de modèle dans la configuration, testez d'abord le texte non-streaming, testez le streaming et les appels d'outils séparément, confirmez les preuves d'utilisation dans Flatkey, et gardez une option de restauration prête jusqu'à ce que le trafic de production soit stable. Lorsque les vérifications sont prêtes, obtenez une clé et exécutez les smoke tests avec vos propres alias de modèle.