Si vous travaillez sur un backend d'accès multi-modèles, vous avez très probablement vécu ce genre d'effondrement : le code métier est truffé de if (vendor === 'openai') ... else if (vendor === 'claude') ..., une seule API de conversation en streaming représente huit cents lignes de logique d'adaptation, et l'ajout d'un nouveau fournisseur oblige à retoucher tout le chemin critique. Le problème ne vient pas de vous, mais du fait que les API des grands modèles de chaque éditeur n'ont tout simplement jamais été conçues pour être unifiées.
L'essence d'une passerelle de modèles est une couche de traduction de protocole : elle fait converger les requêtes/réponses hétérogènes de N fournisseurs vers 1 seul protocole interne standard. Cet article procède en trois temps — principes, mise en pratique, comparaison — pour expliquer clairement comment construire cette couche de traduction.
I. Quatre types d'hétérogénéité : pourquoi la connexion directe à plusieurs fournisseurs devient inévitablement incontrôlable
Commençons par les différences réelles, chacune avec des chiffres.
Mode d'authentification : OpenAI utilise Authorization: Bearer sk-xxx, avec un champ d'en-tête d'environ 51 caractères ; Claude utilise x-api-key ; Gemini glisse la clé dans le paramètre de requête ?key= de l'URL ; Qwen et ERNIE utilisent Authorization mais avec des algorithmes de signature différents, l'access_token d'ERNIE ayant une validité par défaut de 30 jours et renvoyant le code d'erreur 110 à expiration. Quatre éditeurs, quatre façons de faire.
Format de segmentation SSE en streaming : le chunk d'OpenAI est data: {"choices":[{"delta":{"content":"x"}}]}, avec le marqueur de fin data: [DONE] ; le type d'événement de Claude est event: content_block_delta accompagné de data: {"delta":{"text":"x"}}, le nom du champ passant de content à text ; Gemini place l'incrément dans candidates[0].content.parts[0].text, imbriqué sur 3 niveaux. Pour analyser une même phrase côté métier, il faut écrire quatre parseurs.
Système de codes d'erreur : c'est le plus pénible. OpenAI utilise le code de statut HTTP + error.type, la limitation de débit étant 429 ; Claude renvoie 429 pour la limitation de débit mais le type dans le body est rate_limit_error ; Qwen peut renvoyer un code de statut 200 pour une limitation de débit mais avec code: "Throttling" dans le body ; ERNIE utilise error_code: 17 pour indiquer un dépassement de quota. Une même chose, quatre expressions.
Référentiel de comptage des tokens : usage.total_tokens = prompt + completion chez OpenAI, le chinois comme l'anglais étant découpés en BPE ; Claude renvoie séparément input_tokens et output_tokens, avec une granularité de découpage des caractères chinois plus fine, si bien qu'un même texte chinois de 500 caractères peut donner un écart de 20 % à 35 % sur le nombre de tokens entre les deux éditeurs. En facturation à l'usage, cet écart se transforme directement en erreur de facture.
En connectant directement quatre fournisseurs, le volume de code de la couche métier gonfle de 3 à 4 fois par rapport à un seul fournisseur, et le coût de maintenance croît linéairement avec le nombre de fournisseurs.
II. Conception de la couche de traduction : format unifié, normalisation du streaming, mappage des codes d'erreur, agrégation de l'usage
La couche de traduction doit faire quatre choses, toutes indispensables.
Format de requête/réponse unifié : définir en interne un schéma standard, avec des champs alignés sur le style d'OpenAI (car son écosystème est le plus large). La requête externe est d'abord convertie au format interne, puis un adaptateur la convertit au format de chaque fournisseur. Patron adaptateur : une classe par fournisseur, implémentant deux méthodes buildRequest() et parseResponse().
Normalisation de la segmentation en streaming : l'essentiel est de convertir les chunks SSE de chaque éditeur en un {delta: string, finish_reason: string|null} unifié. La méthode consiste à écrire une machine à états qui dispatche vers différents parseurs selon le type de fournisseur et produit une structure unifiée. Le point clé est le traitement des frontières : le séparateur \n\n du SSE, le préfixe data:, la concaténation de plusieurs lignes de data — tout cela doit être absorbé dans le parseur. Le piège que j'ai rencontré, ce sont les événements ping et message_stop de Claude : sans les ignorer explicitement, on pousse un delta vide au frontend, ce qui provoque un scintillement de l'UI.
Table de mappage des codes d'erreur : maintenir une table vendorCode -> unifiedCode, unifiée en 6 catégories : AUTH_FAILED, RATE_LIMITED, QUOTA_EXCEEDED, INVALID_REQUEST, UPSTREAM_ERROR, TIMEOUT. Quelle que soit la réponse de l'amont, la couche de traduction consulte la table et la convertit en code unifié ; la couche métier ne connaît que ces 6 codes.
Agrégation de l'usage : après chaque appel, convertir le référentiel de tokens de chaque éditeur en tokens standard internes, et stocker en base avec vendor, model, request_id, pour la réconciliation et l'analyse de coûts ultérieures. Attention ici aux différences de référentiel : les output_tokens de Claude et les completion_tokens d'OpenAI ne peuvent pas être additionnés directement, il faut les normaliser vers une même base via un coefficient de conversion.
Sur le plan de l'architecture en couches, je divise généralement en quatre : couche d'accès (authentification + limitation de débit), couche de routage (choix du modèle), couche de traduction (conversion de protocole), couche d'adaptation (appel du SDK du fournisseur). La couche de traduction est une fonction pure, sans IO, ce qui facilite les tests unitaires.
III. Code pratique : changer une ligne de base_url pour accéder à une passerelle agrégatrice
Si vous ne voulez pas écrire la couche de traduction de zéro, utiliser une plateforme d'agrégation d'API IA existante est un choix plus pragmatique. Dans notre projet, nous avons utilisé token8341, compatible avec le SDK d'OpenAI : changer une ligne de base_url suffit pour basculer, et le travail de la couche de traduction est fait pour vous.
from openai import OpenAI
client = OpenAI(
api_key="your-key",
base_url="https://api.token8341.com/v1" # changer uniquement cette ligne
)
resp = client.chat.completions.create(
model="deepseek-v3", # on peut aussi remplacer par gpt-4o / qwen-max / claude-4-sonnet
messages=[{"role": "user", "content": "explique le SSE"}],
stream=True
)
for chunk in resp:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="")Dans ce code, la normalisation de la segmentation SSE, le mappage des codes d'erreur et l'agrégation de l'usage sont tous réalisés côté passerelle, et la couche métier reçoit directement le format OpenAI standard. Le routage multi-modèles est aussi économisé : la passerelle peut choisir automatiquement le modèle optimal selon la tâche, par exemple Qwen pour le texte long en chinois, DeepSeek pour les tâches de raisonnement, Doubao pour les scénarios sensibles au coût.
Avertissement sur les pièges : après avoir changé le base_url, ne transmettez pas directement les paramètres spécifiques au fournisseur. Par exemple logit_bias d'OpenAI, top_k de Claude : la passerelle ne les supporte pas forcément tous, et les transmettre tels quels peut les faire ignorer silencieusement, vous donnant l'impression qu'ils sont pris en compte alors que ce n'est pas le cas. Avant la mise en production, passez un script de test de charge sur la compatibilité des paramètres.
IV. Comparaison : routage multi-modèles vs liaison mono-modèle
Voici une série de chiffres issus de nos mesures réelles. Liaison mono-modèle (connexion directe à OpenAI) : temps d'intégration d'environ 2 jours-homme, le basculement en cas de panne nécessite de modifier le code et de redéployer, temps de rétablissement moyen de 15 minutes, aucune marge d'optimisation des coûts. Routage multi-modèles (via passerelle) : temps d'intégration d'environ 0,5 jour-homme, basculement automatique en cas de panne, temps de rétablissement inférieur à 3 secondes, coûts réductibles d'environ 30 % à 40 % grâce à la répartition par tâche.
En termes de complexité de maintenance, le code d'adaptation pour quatre fournisseurs en connexion directe représente environ 2000 lignes ; via la passerelle, le code d'adaptation de la couche métier tombe sous les 200 lignes, soit une réduction de 90 %. Côté latence, la passerelle ajoute un saut, avec une augmentation du P99 d'environ 20 à 40 ms ; au regard du coût de maintenance économisé et de la flexibilité de basculement, cette dépense est acceptable.
Bien sûr, la passerelle n'est pas une solution miracle. Si votre activité n'utilise qu'un seul modèle et ne le changera jamais, la connexion directe est plus simple. Mais dès qu'il s'agit de multi-modèles, multi-fournisseurs et d'optimisation des coûts, la couche de traduction devient une infrastructure indispensable. Passerelle de modèles, API de grands modèles, agrégation d'API IA : ces trois choses sont au fond trois façons de nommer le même problème.
Un dernier rappel : la couverture de tests unitaires de la couche de traduction doit être maximale, en particulier les cas limites de la segmentation en streaming, qui constituent une zone à forte incidence d'incidents en production.
Auteur : Liu Zhiyuan
Date de publication : 28 octobre 2026