Les tests de migration de l’URL de base d’une API IA doivent avoir lieu avant le changement de variable d’environnement, et non après que le trafic de production commence à échouer. Modifier un seul baseURL ou base_url peut faire basculer en même temps l’authentification, la sélection du modèle, le streaming, les appels d’outils, les enregistrements d’utilisation, le comportement des quotas et le contrôle du retour arrière vers un nouveau chemin.
Flatkey est conçu pour les équipes qui veulent une seule clé, une couche de routage compatible OpenAI, et une revue plus claire de la facturation et de l’utilisation entre les fournisseurs de modèles. La page d’accueil publique de Flatkey consultée le 7 juillet 2026 affichait l’exemple de route https://router.flatkey.ai/v1/chat/completions, tandis que les pages actuelles des modèles et des tarifs exposaient le modèle, le point de terminaison, le fournisseur et le contexte de facturation à examiner. Considérez ces pages comme des preuves du jour de la migration, puis exécutez vos propres tests de vérification rapide sur le compte avant de déplacer le trafic.
Utilisez ce guide comme une séquence pratique de tests de migration de l’URL de base d’une API IA. L’objectif n’est pas de prouver tous les chemins de l’application. L’objectif est de prouver le chemin minimal et sûr via la nouvelle URL de base, puis d’ajouter les fonctionnalités une couche à la fois.
Les 7 tests de migration de l’URL de base d’une API IA
Exécutez les tests dans cet ordre. Chacun doit produire une preuve que vous pouvez joindre à un ticket de déploiement.
| Test | Ce qu’il prouve | Preuve à conserver |
|---|---|---|
| 1. Authentification et composition de l’URL de base | La clé, l’hôte, la racine /v1 et le chemin du point de terminaison sont correctement configurés. |
Capture d’environnement masquée, code de statut, corps de réponse, temps de requête. |
| 2. Catalogue des modèles et famille de points de terminaison | L’alias de modèle sélectionné appartient au point de terminaison que vous appelez. | Capture d’écran ou export du catalogue, alias du modèle, famille de point de terminaison. |
| 3. Complétion de chat simple | Une requête minimale non diffusée fonctionne sans SDK ni complexité applicative. | Commande curl, ID de réponse, texte de sortie, objet d’utilisation s’il est renvoyé. |
| 4. Parité SDK | Le SDK de l’application construit la même route que celle prouvée par curl. | URL de base résolue, version du SDK, réponse, journal de configuration au démarrage sans secrets. |
| 5. Streaming ou SSE | Les événements incrémentaux atteignent le client sans mise en mémoire tampon ni incompatibilité de parseur. | Exemple de flux brut, type de contenu, délai du premier jeton, événement final. |
| 6. Appel d’outil ou de fonction | La route sélectionnée prend en charge votre schéma d’outil et le comportement de choix d’outil. | Requête avec petit schéma, sortie de l’appel d’outil, corps d’échec si non pris en charge. |
| 7. Utilisation, quota et retour arrière | Le nouveau chemin est visible pour les opérations, et l’échec peut être annulé rapidement. | Relecture du tableau de bord, résultat du quota, configuration précédente, responsable du retour arrière. |
Ne sautez pas les premiers tests parce qu’un wrapper de framework a déjà fonctionné en préproduction. La plupart des tests de migration de l’URL de base d’une API IA échouent parce que le SDK lit silencieusement une clé différente, reçoit la mauvaise racine d’URL de base ou envoie un modèle valide à la mauvaise famille de points de terminaison.
Test 1 : authentification et composition de l’URL de base
Commencez en dehors de l’application. Vous devez prouver que la clé et l’URL de base peuvent atteindre la forme de point de terminaison la plus simple.
L’erreur courante sur l’URL de base consiste à transmettre le point de terminaison complet au SDK. Pour un SDK compatible OpenAI, l’URL de base est généralement la racine de l’API, comme https://router.flatkey.ai/v1, et le SDK ajoute /chat/completions, /responses ou un autre point de terminaison. Transmettre https://router.flatkey.ai/v1/chat/completions comme URL de base peut créer un chemin dupliqué.
Utilisez d’abord une vérification d’environnement masquée :
test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"
Puis effectuez une requête directe :
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"
curl -sS "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{"role": "user", "content": "Reply with exactly: base url ok"}
]
}'
Si cela renvoie 401, corrigez la clé et l’en-tête d’authentification avant de changer de modèle. Si cela renvoie 404, vérifiez l’hôte, la racine /v1 et si le chemin du point de terminaison a été dupliqué. Si cela renvoie 403, vérifiez la politique de compte, de projet, de modèle, de région ou d’adresse IP. La documentation des codes d’erreur d’OpenAI traite 401 comme une authentification, 429 comme une limite ou un quota, et 500 ou 503 comme des conditions serveur ou de surcharge ; une passerelle peut ajouter plus de détails, alors enregistrez le corps de la réponse.
Test 2 : catalogue des modèles et famille de points de terminaison
Une URL de base compatible OpenAI ne rend pas chaque nom de modèle portable. L’API OpenAI dispose d’un point de terminaison List models, et ses points de terminaison Chat Completions et Responses utilisent des formes de requête différentes. Une passerelle ou une route compatible fournisseur peut exposer un modèle pour une famille de points de terminaison mais pas pour une autre.
Avant de modifier la configuration de production, créez une petite carte des modèles :
| Champ | Exemple |
|---|---|
| Alias de l’application | support_chat |
| Alias du gateway | support-chat-primary |
| Modèle du fournisseur ou alias de modèle Flatkey | Valeur actuelle de la console |
| Famille d’endpoint | chat, responses, images, embeddings ou video |
| Propriétaire | Plateforme, produit IA, automatisation ou équipe support |
| Valeur de rollback | Modèle précédent et URL de base précédente |
La condition de réussite n’est pas « le nom du modèle semble correct ». La condition de réussite est que la console Flatkey actuelle, le répertoire des modèles ou le catalogue du fournisseur affiche l’alias exact pour la famille d’endpoint exacte que vous prévoyez d’appeler. Reliez ce travail à votre gouvernance plus large des modèles avec le guide des noms de modèles compatibles OpenAI.
Test 3 : complétion de chat simple
Le troisième test de migration de l’URL de base d’une API IA est la plus petite requête de génération réelle. Gardez-la sans streaming. N’incluez ni outils, ni schéma JSON, ni fichiers, ni images, ni retries, ni middleware applicatif.
Enregistrez :
| Champ | Pourquoi c’est important |
|---|---|
| Statut HTTP | Confirme que la route a accepté la requête. |
| ID de réponse ou ID de requête | Permet au support de tracer la requête. |
| Modèle renvoyé | Indique quel modèle ou alias a traité la requête. |
| Texte de sortie | Confirme que la réponse a bien été générée. |
| Objet usage | Démarre la facturation et la réconciliation des jetons. |
Si la requête simple échoue, ne déboguez pas encore le streaming. Utilisez le guide de dépannage d’API compatibles OpenAI pour isoler d’abord les problèmes de clé, de route, de famille d’endpoint et d’alias de modèle.
Test 4 : parité du SDK
Une fois que curl fonctionne, prouvez que le SDK construit la même route. La documentation officielle actuelle d’OpenAI oriente les développeurs vers les SDK officiels pour JavaScript et Python. L’OpenAI cookbook montre aussi l’utilisation d’un endpoint personnalisé où un client est créé avec un jeton et une URL de base personnalisée. Pour une migration, rendez cela explicite dans le code plutôt que de compter sur des valeurs résiduelles de OPENAI_API_KEY ou OPENAI_BASE_URL.
Modèle Python :
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[{"role": "user", "content": "Répondez exactement : sdk ok"}],
)
print(response.choices[0].message.content)
print(response.usage)
Modèle Node :
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL!,
messages: [{ role: "user", content: "Répondez exactement : sdk ok" }],
});
console.log(response.choices[0]?.message?.content);
console.log(response.usage);
Consignez l’URL de base résolue au démarrage du processus, mais ne consignez pas la clé. Si curl réussit et que le SDK échoue, examinez la priorité des variables d’environnement, la version du SDK, l’assemblage des chemins, les en-têtes d’organisation/de projet et le comportement du proxy avant de changer le modèle.
Test 5 : streaming ou SSE
Le streaming est l’endroit où de nombreuses migrations semblent saines au niveau HTTP mais échouent dans l’application. La référence Chat Completions d’OpenAI renvoie soit un objet JSON, soit des chunks de complétion de chat streamés lorsque le streaming est activé. L’API Responses peut également renvoyer text/event-stream, avec des noms d’événements différents des chunks de Chat Completions.
Lancez ce test après que la requête sans streaming fonctionne :
curl -N "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"stream": true,
"messages": [
{"role": "user", "content": "Compte lentement de un à cinq."}
]
}'
Conditions de réussite :
| Vérification | Condition de réussite |
|---|---|
| Type de contenu | Flux compatible SSE, pas une réponse JSON mise en mémoire tampon sauf si c’est attendu. |
| Premier événement | Le client reçoit un événement incrémental avant la fin de la réponse complète. |
| Analyseur | Les chunks de Chat Completions ne sont pas interprétés comme des événements Responses, ni l’inverse. |
| Événement final | Le client voit la complétion et ne laisse pas de connexions ouvertes. |
| Gestion de l’usage | Votre application sait si l’usage apparaît dans l’événement final, une réponse complète ou une lecture depuis le tableau de bord. |
Pour une analyse plus approfondie du parsing de flux, comparez avec le test SSE de streaming compatible OpenAI.
Test 6 : appel d’outil ou de fonction
L’appel d’outil ajoute des risques liés au schéma et aux capacités. Le guide OpenAI sur le function calling décrit un flux en plusieurs étapes : envoyer des outils, recevoir un appel d’outil, exécuter le code applicatif, renvoyer la sortie de l’outil, puis recevoir la réponse finale du modèle. Une migration d’URL de base peut échouer à n’importe laquelle de ces frontières, même lorsque le texte simple fonctionne.
Ne commencez pas par l’ensemble complet de vos outils de production. Utilisez une seule petite fonction :
{
"model": "your-current-flatkey-model-alias",
"messages": [
{"role": "user", "content": "Utilisez l’outil pour la commande A123."}
],
"tools": [
{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Retourne le statut d’une commande de test.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}
Si cela échoue alors que le chat simple fonctionne, vous ne déboguez plus l’URL de base. Vous déboguez la capacité du modèle, la famille de points de terminaison, la stricteté du schéma, tool_choice ou la prise en charge du routeur pour la route sélectionnée. Le guide publié sur la compatibilité de l’appel d’outils couvre une liste de contrôle plus large des fournisseurs.
Test 7 : utilisation, quota et retour arrière
Les derniers tests de migration de l’URL de base de l’API IA sont opérationnels. Une réponse générée ne suffit pas si la finance ne peut pas la rapprocher, si les quotas ne se comportent pas comme prévu, ou si le retour arrière nécessite une modification de code d’urgence.
Après un test de fumée réussi, vérifiez :
| Domaine | Ce qu’il faut vérifier |
|---|---|
| Lecture de l’utilisation | La requête apparaît dans l’utilisation Flatkey, les journaux, la facturation ou la vue du tableau de bord. |
| Champs de jetons | Les champs de consommation de prompt, de completion, de total, de cache ou spécifiques à la route sont capturés là où votre application les attend. |
| Comportement du quota | Une clé contrôlée à faible limite ou de préproduction produit une réponse de quota/de limitation de débit reconnaissable. |
| Politique de nouvelle tentative | 429, 500, 502, 503 et 504 suivent vos règles de backoff et de bascule. |
| Retour arrière | L’ancienne URL de base, l’ancienne clé, l’ancien modèle et le responsable sont prêts avant la bascule. |
Utilisez un fichier de retour arrière suffisamment simple pour être exécuté sous pression :
# active
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias
# rollback
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall
Ne vous fiez pas à votre mémoire pour le retour arrière. Conservez la configuration précédente, le drapeau de fonctionnalité, la commande de déploiement et la commande de vérification dans le même ticket de déploiement que les tests de migration de l’URL de base de l’API IA.
Le dossier de preuves à conserver
Pour chaque environnement, conservez un dossier qui répond à ces questions :
| Question | Preuve |
|---|---|
| Qu’est-ce qui a changé ? | Ancienne URL de base, nouvelle URL de base, ancien modèle, nouveau modèle, version du SDK. |
| Qui en est responsable ? | Responsable technique, responsable opérations, approbateur finance/achats si nécessaire. |
| Qu’est-ce qui a réussi ? | Les sept tests, les horodatages, les ID de réponse, l’enregistrement d’utilisation et les captures d’écran de la route. |
| Qu’est-ce qui a échoué ? | Code d’état, corps de réponse, résultat de la nouvelle tentative et décision. |
| Quel est le retour arrière ? | Configuration précédente, responsable, délai attendu pour revenir en arrière et test de fumée après retour arrière. |
C’est l’avantage pratique d’exécuter des tests de migration de l’URL de base de l’API IA avant la bascule. L’artefact est utile pour la revue de déploiement, la réponse aux incidents, le rapprochement de l’utilisation et les preuves pour les achats.
La place de Flatkey
Flatkey peut réduire la dispersion des migrations en centralisant l’accès aux modèles, le routage, la facturation, l’analytique d’utilisation et la revue opérationnelle derrière une seule clé. Cela n’élimine pas le besoin de tester. Cela donne à l’équipe un point de contrôle unique où l’ingénierie, la finance et les opérations peuvent examiner les mêmes preuves de route.
Avant de migrer, consultez les pages Flatkey models et pricing en direct, confirmez l’URL de base actuelle de la console et commencez par un test de route simple. Si vous planifiez encore la bascule plus large, associez ce guide au guide de migration d’API compatible OpenAI. Lorsque vous êtes prêt à exécuter vos propres tests, obtenez une clé et gardez la première requête suffisamment petite pour être inspectée à la main.
Questions fréquentes
Que sont les tests de migration de l’URL de base de l’API IA ?
Les tests de migration de l’URL de base de l’API IA sont des vérifications pré-bascule qui prouvent que la nouvelle racine de l’API fonctionne pour l’authentification, le routage des modèles, le chat simple, l’utilisation du SDK, le streaming, les outils, la lecture de l’utilisation, le comportement des quotas et le retour arrière.
Dois-je tester d’abord curl ou le SDK ?
Testez d’abord curl. Curl prouve la clé, l’URL, le chemin du point de terminaison et l’alias du modèle sans le comportement du framework. Ensuite, testez le SDK avec les mêmes valeurs.
L’URL de base doit-elle inclure /chat/completions ?
En général non. Donnez au SDK la racine de l’API comme /v1, puis laissez le SDK ajouter le point de terminaison. N’utilisez le point de terminaison complet que pour les requêtes curl directes.
Pourquoi le streaming échoue-t-il alors que le chat simple fonctionne ?
Le streaming peut échouer parce que la route met les réponses en tampon, que l’analyseur du client attend une mauvaise forme d’événement, qu’un middleware consomme le flux ou que la famille de points de terminaison sélectionnée ne prend pas en charge la forme de flux que vous utilisez.
Que faire si je ne peux pas encore exécuter de requêtes Flatkey en direct ?
Conservez les extraits de code comme modèles, validez la documentation publique et la configuration de la console, et ne déplacez pas le trafic de production tant qu’une vraie clé n’a pas prouvé les sept tests de migration de l’URL de base de l’API IA dans votre propre environnement.
En bref
Modifier l'URL de base d'une API IA est une migration en production, pas une simple modification de chaîne. Exécutez les tests de migration de l'URL de base de l'API IA dans l'ordre : authentification, catalogue de modèles, chat simple, parité SDK, streaming, outils, puis utilisation et rollback. Lorsque les sept passent, le changement d'URL de base devient une bascule contrôlée plutôt qu'une session de débogage tardive.
