Migration vers une passerelle API compatible OpenAI : créez un contrat de compatibilité avant d'inverser l'URL de base

Modifier base_url, api_key et model suffit souvent pour qu'une simple démo de chat fonctionne avec un API compatible OpenAI. Il ne suffit pas de prouver qu'une migration de production est sûre.

Les échecs apparaissent généralement plus tard : les appels d'outils diffusés arrivent sous une forme différente, un mode de schéma JSON est ignoré, un modèle d'intégration renvoie une taille de vecteur différente, des champs d'utilisation sont manquants, des tentatives de double soumission d'un effet secondaire ou une option de raisonnement spécifique au fournisseur ne fait rien en silence. L’objectif pratique n’est pas de demander si un point de terminaison est « OpenAI compatible » dans l’abstrait. L'objectif est de définir de quelles parties du contrat de forme OpenAI dépendent vos applications, de tester ces parties et de les acheminer via une passerelle uniquement une fois que le contrat est explicite.

Ce guide montre comment migrer une équipe depuis des SDK spécifiques à un fournisseur ou des points de terminaison compatibles dispersés vers une passerelle compatible OpenAI tout en préservant la fiabilité, l'attribution d'utilisation et les options de restauration.

Qu'est-ce que les faits, les recommandations et les prédictions dans cette migration ?

Faits : Plusieurs fournisseurs documentent les chemins compatibles OpenAI ou l'utilisation SDK de certaines parties de leurs API. Google documents Gemini accèdent via les OpenAI Python bibliothèques TypeScript et REST en modifiant la clé API, l'URL de base et le modèle, tout en recommandant également une utilisation directe Gemini API pour les applications qui n'utilisent pas déjà OpenAI bibliothèques. La documentation de compatibilité de Gemini couvre les achèvements de chat, le streaming, les appels de fonctions, la compréhension des images, les intégrations, les mappages d'effort de raisonnement et les options spécifiques au fournisseur via des corps de requête supplémentaires. Together AI documente la compatibilité OpenAI REST et SDK pour plusieurs modalités, mais sa matrice répertorie également les surfaces en forme de OpenAI non prises en charge telles que les assistants, les threads et les exécutions. Mistral documente un chemin de migration pour les clients compatibles OpenAI en modifiant l'URL de base et le nom du modèle. Groq expose les points de terminaison de complétion de discussion avec le chemin OpenAI. vLLM propose un serveur compatible OpenAI pour les complétions et le chat, tout en documentant les différences de paramètres. La documentation des OpenAI Agents SDK avertit que de nombreux fournisseurs non OpenAI ne prennent pas encore en charge les nouvelles réponses API et que le mode Chat Completion est souvent la cible de compatibilité la plus sûre.

Recommandations : Traitez la compatibilité comme un contrat d'application testé. Inventairez les points de terminaison et les fonctionnalités exacts utilisés par vos applications, créez une matrice de capacités de fournisseur et de modèle, rédigez des tests de conformité avant la migration du trafic, normalisez les différences connues de requêtes et de réponses à la limite de la passerelle et déployez avec des clés et des profils de restauration par application.

Prédiction : OpenAIles surfaces compatibles resteront utiles en tant que couche d'intégration à moindre friction, mais les fonctionnalités natives du fournisseur continueront de diverger. Les équipes qui maintiennent un contrat de compatibilité seront en mesure d'adopter de nouveaux modèles plus rapidement que les équipes qui s'appuient sur des hypothèses informelles de « remplacement immédiat ».

Étape 1 : inventorier chaque appel d'IA en cours

Commencez par un inventaire, pas par des modifications de code. Une migration échoue lorsque les équipes supposent que tous les appels d'IA ressemblent à des discussions terminées et découvrent des dépendances cachées seulement après la publication.

Créez une ligne par site d'appel. Incluez les tâches planifiées, les outils internes, les blocs-notes, les travailleurs en arrière-plan, les harnais d'évaluation et les services destinés aux clients.

app: support-assistant
owner: customer-platform
current_provider: provider_a
current_sdk: provider_a_python_sdk
endpoint_shape: chat.completions
model: provider-a-large-2026
features:
  - streaming
  - tool_calls
  - json_schema_output
  - usage_accounting
latency_budget_ms: 8000
retry_policy: retry_429_5xx_no_tool_side_effects
monthly_volume_estimate: 2.4M requests
rollback_contact: oncall-customer-platform

Classez chaque appel par point de terminaison et fonctionnalité, et pas seulement par modèle. Un seul nom de modèle peut masquer des exigences de compatibilité très différentes selon la manière dont il est utilisé.

Liste de contrôle d'inventaire

• Chat : messages, instructions système, température, top-p, nombre maximum de jetons, séquences d'arrêt.
• Streaming : analyseur d'événements envoyés par le serveur, morceaux finaux, utilisation dans le flux, comportement d'annulation.
• Outils : schémas de fonctions, appels parallèles, argument JSON, messages de résultat de l'outil, sécurité des effets secondaires.
• Sorties structurées : JSON mode, schéma JSON, validation stricte, logique de réparation de repli.
• Vision ou saisie multimodale : URL de l'image, base64, gestion MIME, paramètres de détail.
• Intégrations : ID du modèle, dimension vectorielle, attentes de normalisation, compatibilité des index.
• Fichiers et lots : API de téléchargement, interrogation des tâches, annulation, formats de sortie.
• Contrôles de raisonnement : effort de raisonnement, budget de réflexion, jetons cachés, paramètres spécifiques au fournisseur.
• Erreurs : forme de limite de débit, forme de délai d'expiration, erreurs de politique de contenu, codes d'état réessayables.
• Utilisation et facturation : jetons d'invite, jetons d'achèvement, jetons mis en cache, jetons de raisonnement, balises de répartition des coûts.

Le résultat de cette étape est une carte de dépendances. Il vous indique quelles applications peuvent migrer avec un simple profil OpenAIcompatible API et quelles applications nécessitent un adaptateur.

Étape 2 : créer une table de contrat de compatibilité

Un contrat de compatibilité est un tableau qui indique, pour chaque fonctionnalité de l'application, ce que la passerelle doit garantir et comment vous allez la tester. Il doit être suffisamment spécifique pour que les équipes d'ingénierie et de produit puissent prendre des décisions de déploiement.

Ce tableau évite également les promesses excessives. Si un fournisseur prend en charge le chat et les intégrations, mais pas un flux de travail de type fichiers ou assistants, le contrat doit le préciser. « Non pris en charge » est un résultat de migration valide lorsqu'il évite une surprise de production.

Étape 3 : créez des profils de modèle au lieu de disperser les ID de modèle

Ne remplacez pas un ID de modèle codé en dur par un autre ID de modèle codé en dur dans chaque application. Utilisez des profils de modèle.

profile: support-chat-fast
openai_model_alias: support-chat-fast
provider: provider_b
provider_model: provider-b/chat-large-fast
endpoint: chat.completions
features:
  streaming: true
  tools: true
  structured_outputs: schema_validated
  vision: false
  embeddings: false
request_policy:
  drop_unsupported_params: false
  reject_unknown_params: true
  pass_through_extra_body: ["reasoning_effort"]
fallback_profile: support-chat-safe
cost_center_required: true

Ce profil donne aux applications un nom stable tandis que la passerelle possède le mappage du fournisseur. Il gère également les fournisseurs qui utilisent des ID de modèle avec espace de noms plutôt qu'un espace de noms de modèle plat. L'application demande support-chat-fast ; la passerelle décide si cela correspond actuellement à un modèle d'espace de noms de style Together, un modèle compatible Gemini, un modèle compatible Mistral, un modèle de chat Groq, un point de terminaison vLLM auto-hébergé ou une autre cible approuvée.

Le compromis concerne les frais généraux de gouvernance. Les profils doivent être documentés, examinés et versionnés. L'avantage est que les migrations, les restaurations et les remplacements de modèles ne nécessitent pas le redéploiement de chaque application.

Étape 4 : rédiger des tests de conformité avant la migration

Les tests de conformité sont de petits contrôles reproductibles qui vérifient votre contrat par rapport à chaque profil cible. Ils doivent être exécutés avant le premier déploiement et chaque fois qu'un fournisseur, un modèle, SDK ou un adaptateur de passerelle change.

Suite de tests minimale

• Tests d'invites en or : Envoyez des invites déterministes et vérifiez la forme de la réponse, la raison de la fin, le comportement de sécurité et les exigences sémantiques de base. N'exigez pas de formulation exacte, sauf si l'application en dépend vraiment.
• Tests de l'analyseur de streaming : Vérifiez que votre client peut analyser chaque morceau, reconstruire le texte final, gérer l'annulation et détecter l'achèvement du flux.
• Aller-retours d'appel d'outil : Forcez un appel d'outil, analysez les arguments, exécutez un faux outil, renvoyez le résultat de l'outil et confirmez que le modèle continue correctement.
• Tests de streaming d'appels d'outils : Vérifiez que les deltas d'arguments partiels peuvent être mis en mémoire tampon et reconstruits avant l'exécution de l'outil. Sinon, désactivez l'exécution incrémentielle de l'outil pour ce profil.
• JSON validation du schéma : Testez les sorties valides, les sorties non valides, les champs manquants, les champs supplémentaires et les cas de refus ou d'erreur.
• Intégration des vérifications de dimension : Confirmez la longueur du vecteur, le type numérique et la compatibilité avec l'index vectoriel cible avant de réutiliser un index existant.
• Tests de nouvelle tentative et d'idempotence : Simulez les échecs 429, 500, d'expiration et de flux partiel. Assurez-vous que les effets secondaires de l'outil ne se répètent pas accidentellement.
• Rapprochement de l'utilisation : Comparez les enregistrements d'utilisation de la passerelle avec les champs d'utilisation signalés par le fournisseur et vos attentes en matière de facturation.

Gardez les tests proches des modèles de trafic de production. Une seule invite « écrire un poème » ne prouve presque rien sur un flux de travail qui dépend des outils, JSON, des intégrations et de la comptabilité d'utilisation.

Étape 5 : normaliser les bizarreries à la limite de la passerelle

Une passerelle compatible OpenAI devrait réduire les modifications du code d'application, mais elle ne devrait pas prétendre que chaque fournisseur se comporte de manière identique. Utilisez des adaptateurs pour les différences connues et rendez le comportement visible.

Demander une normalisation

• Alias de modèle : Mappez les noms de profils stables orientés application vers les ID de modèle spécifiques au fournisseur.
• Paramètres non pris en charge : Rejetez les paramètres non pris en charge avec une erreur claire par défaut. Le drop silencieux est pratique lors des démos et dangereux en production.
• Options spécifiques au fournisseur : Autoriser les champs de transmission contrôlés, tels que les contrôles de raisonnement ou de réflexion, uniquement dans les profils de modèle documentés.
• Conversion des messages : Normalisez les messages du système, du développeur, de l'utilisateur, de l'assistant et de l'outil lorsque le fournisseur cible attend une forme différente.
• Budgets de délai d'attente : Appliquez un délai au niveau de l'application plutôt que de laisser SDK valeurs par défaut s'accumuler.

Normalisation des réponses

• Choix de texte et d'outils : Renvoie une forme cohérente pour le texte de l'assistant, les appels d'outils et les motifs de fin.
• Blocs de streaming : Normalisez les deltas courants et documentez les endroits où la mise en mémoire tampon est requise.
• Champs d'utilisation : Stockez l'utilisation native du fournisseur ainsi que le nombre normalisé d'invites, d'achèvement et de jetons, le cas échéant.
• Forme d'erreur : Mappez les codes d'état, la possibilité de réessayer, le code d'erreur du fournisseur et l'ID de demande dans un seul schéma d'erreur.
• Métadonnées de coût : Joignez les étiquettes d'application, d'équipe, de profil, de fournisseur, de modèle et d'environnement pour une analyse ultérieure.

Le principal compromis est la portabilité par rapport à la puissance du fournisseur. La normalisation à la plus petite surface commune améliore l’interchangeabilité. Autoriser les champs spécifiques au fournisseur préserve les fonctionnalités avancées, mais chaque option de transmission devient partie intégrante de la documentation du profil et de la matrice de test.

Étape 6 : déploiement avec des clés par application et des profils de restauration

La migration doit être réversible sans redéploiement de code. Utilisez des clés API distinctes pour chaque application, environnement et équipe. Une seule clé partagée rend l'attribution d'utilisation et la restauration d'urgence plus difficiles.

Une séquence de déploiement sécurisée ressemble à ceci :

1. Profil de développement : Acheminez uniquement le trafic local et intermédiaire via la passerelle. Résoudre les problèmes de forme de requête et d'analyseur.
2. Tests fantômes : Rejouez les requêtes du représentant vers le nouveau profil sans affecter la sortie visible par l'utilisateur. Comparez la validité du schéma, le comportement de l'outil, la classe de latence et les champs d'utilisation.
3. Petite tranche de production : Déplacez un faible pourcentage de trafic ou un locataire interne. Surveillez les erreurs, les tentatives, les signaux de qualité destinés aux utilisateurs et les coûts.
4. Extension par application : Migrez une application à la fois. Ne migrez pas les discussions, les intégrations, les lots et les fichiers ensemble, à moins qu'ils ne partagent le même profil de risque.
5. Profil de restauration : Conservez un profil de fournisseur/modèle connu et disponible derrière le même alias d'application ou un changement de configuration rapide.
6. Verrouillage post-migration : Une fois stable, supprimez les clés directes du fournisseur des environnements d'application afin que le trafic ne puisse pas contourner les contrôles de passerelle.

La restauration doit être testée comme n'importe quel autre chemin. Si un profil de modèle peut être modifié dans la passerelle, testez ce changement pendant une période calme et confirmez que les journaux d'application, les analyses d'utilisation et l'attribution de facturation restent cohérents.

Exemple : remplacement des points de terminaison dispersés par un seul contrat de passerelle

Supposons qu'une équipe dispose de trois applications :

• Un assistant de support client utilisant le chat et les outils en streaming.
• Un classificateur de contenu nécessitant une sortie JSON stricte.
• Un service de recherche utilisant des intégrations stockées dans une base de données vectorielle.

Une migration risquée remplacerait les trois applications par la même URL de base et sélectionnerait trois nouveaux ID de modèle. Une migration plus sûre sépare les contrats :

• profil de chat d'assistance : Nécessite le streaming, les appels d'outils, les deltas d'appels d'outils mis en mémoire tampon, la classification des nouvelles tentatives et la journalisation de l'utilisation.
• profil classifier-json : Nécessite une validation de schéma, une gestion des refus et aucune suppression silencieuse de paramètres.
• profil d'intégration de recherche : Nécessite une dimension vectorielle fixe et un plan de migration d'index si la dimension change.

Chaque profil fait l'objet de ses propres tests de conformité et de son propre déploiement. L'assistant d'assistance peut avoir besoin d'un adaptateur de streaming. Le classificateur peut réussir rapidement si la validation du schéma est externe au modèle. Le service d'intégration peut nécessiter un nouvel index plutôt qu'un échange de modèle sur place. La passerelle donne à l'équipe une URL de base compatible OpenAI, mais le contrat de compatibilité maintient la migration honnête.

Liste de contrôle pour la migration

• Répertoriez tous les sites d'appels IA, y compris les tâches en arrière-plan et les scripts internes.
• Classez les appels par point de terminaison, fonctionnalité, modèle, propriétaire et chemin de restauration.
• Définissez des profils de modèle orientés application au lieu de coder en dur les ID de modèle de fournisseur.
• Créez une matrice de capacités pour chaque fournisseur et profil de modèle.
• Rejetez les paramètres non pris en charge, sauf si un profil autorise explicitement le transfert.
• Testez le streaming, les outils, les sorties structurées, les intégrations, les erreurs, les tentatives et les champs d'utilisation.
• Utilisez des clés par application et par environnement API pour l'attribution et le contrôle.
• Exécutez des tests fantômes avant le trafic de production visible par l'utilisateur.
• Déployez une application ou une classe de fonctionnalités à la fois.
• Gardez un profil de restauration testé disponible sans redéploiement de code.

Conclusion exploitable

Une passerelle OpenAI compatible API est plus précieuse lorsqu'elle devient une couche de migration contrôlée, et pas seulement une URL différente. Le commutateur d'URL de base réduit les modifications mécaniques du code. Le contrat de compatibilité réduit le risque opérationnel.

Avant d'inverser le trafic de production, notez ce dont vos applications ont réellement besoin : comportement de streaming, sémantique des outils, garanties de schéma, dimensions d'intégration, règles de nouvelle tentative, champs d'utilisation et signification des erreurs. Convertissez ces exigences en profils de modèle, règles d'adaptateur et tests de conformité. Déployez ensuite avec des clés par application, des analyses et des profils de restauration.

Si le chemin de discussion simple fonctionne, considérez-le comme un bon début. Traitez le reste de la migration comme un travail d'ingénierie qui mérite la même discipline qu'un changement de base de données, de file d'attente ou de fournisseur de paiement.

Lecture connexe

• validation de sortie structurée entre plusieurs fournisseurs de modèles
• remplacement de modèle et runbook de restauration
• analyse d'utilisation et rapprochement de jetons dans un passerelle