FR ▾
Obtenir une clé API

Guide API Migration : changer de fournisseur LLM en toute sécurité

Ce guide de migration de l'API explique comment déplacer une application qui communique déjà avec un endpoint de chat de style OpenAI vers un autre fournisseur. La majeure partie du travail ne réside pas dans les deux lignes que vous modifiez, mais dans la recherche de ce qui dépendait de l'ancien fournisseur par accident.

Dernière mise à jour

Vanne détournant une partie d'un flux de cubes de lumière d'un pipeline à un autre, illustrant une migration progressive

Résumé

  • Pour une cible compatible OpenAI, modifiez l'URL de base, la clé et l'ID du modèle, puis vérifiez le comportement.
  • Commencez par l'inventaire des fonctionnalités : les embeddings, les images et les fine-tunes ne seront pas transférés vers une API textuelle uniquement.
  • Déployez par pourcentage avec un indicateur afin qu'un retour arrière ne nécessite qu'un seul changement de configuration.
  • Estimez la nouvelle facture à partir de vos propres nombres de tokens avant le basculement.

Le plan en six étapes

  1. Inventoriez toutes les fonctionnalités API appelées par votre application.
  2. Déplacez les paramètres du fournisseur dans la configuration.
  3. Cartographiez les paramètres et les noms de modèles.
  4. Ajoutez une gestion des erreurs et des limites de débit correspondant aux nouvelles limites.
  5. Acheminez une petite part de trafic vers le nouveau fournisseur et comparez.
  6. Vérifiez le coût, basculez, et conservez l'ancienne route pendant un certain temps.

L'endpoint cible dans les exemples est https://api.apimigration.com/v1 avec l'ID de modèle uncensored. Les mêmes étapes s'appliquent à tout fournisseur compatible OpenAI, lisez-les donc comme une liste de contrôle plutôt que comme une recette spécifique à un fournisseur. Si quelque chose tombe en panne en cours de route, l'article de dépannage sur les erreurs courantes d'intégration LLM couvre les causes habituelles.

Étape 1 : Inventoriez les fonctionnalités utilisées par votre application

Recherchez dans votre code chaque appel à l'ancien fournisseur et listez les fonctionnalités ainsi que les endpoints. Un seul appel de chat masque souvent plusieurs dépendances : un prompt système qui repose sur un style particulier, un schéma d'outil, un format de réponse JSON, un grand contexte.

Fonctionnalité dans votre applicationSur cette API
Complétions de chat, /v1/responsesPris en charge
Streaming sur SSEPris en charge, l'utilisation est envoyée à la fin
Appel de fonctionsPris en charge, y compris le streaming des tool_calls
Mode JSONPris en charge via response_format
Contexte100 000 tokens, prompt plus complétion
Embeddings, images, audio, ajustement finNon proposé, conservez ces éléments chez un autre fournisseur

Si l'ancien fournisseur gérait également les embeddings ou la génération d'images, séparez la migration : déplacez uniquement les appels textuels et laissez le reste où il est.

Étape 2 : Placez les paramètres du fournisseur dans la configuration

Les URL codées en dur sont ce qui transforme une migration en un changement de code. Lisez l'URL de base, la clé et le modèle depuis l'environnement afin de pouvoir changer sans déploiement.

export LLM_BASE_URL="https://api.apimigration.com/v1"
export LLM_API_KEY="YOUR_KEY"
export LLM_MODEL="uncensored"
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["LLM_BASE_URL"],
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

L'authentification utilise l'en-tête standard Authorization: Bearer, que le SDK définit pour vous. Pour confirmer la clé et voir ce que le serveur propose, appelez GET /v1/models.

curl https://api.apimigration.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

Étape 3 : Mappez les paramètres et les prompts

Paramètres qui transitent sur cette API : temperature, top_p, stop, seed ainsi que les pénalités de fréquence et de présence. max_tokens est optionnel. Si votre ancien code le définit pour se protéger contre une dérive des coûts, conservez-le.

Trois points méritent une vérification délibérée.

  • Champs spécifiques au fournisseur. Tout ce qui sort du format de requête OpenAI peut être ignoré ou rejeté. Envoyez une requête avec votre charge utile de production exacte et lisez la réponse.
  • Comportement du modèle. Un modèle différent interprète le même prompt différemment. Les prompts système ajustés pour l'ancien modèle nécessitent souvent de petites modifications. Testez-les, ne partez pas du principe.
  • Refus. Si vos anciens prompts contenaient des contournements pour éviter les refus, vous pouvez généralement les supprimer ici, ce qui raccourcit le prompt.

Le modèle diffère également par ce qu'il est prêt à répondre. Celui-ci est optimisé pour une utilisation adulte légale sans refus de contenu, et le contenu sexuel impliquant des mineurs est bloqué.

Étape 4 : Adaptez la gestion des erreurs aux nouvelles limites

Une clé complète permet 8 requêtes simultanées et 300 par minute. Une clé d'essai permet 2 et 60. Au-delà de la limite, vous obtenez un HTTP 429 avec le code d'erreur rate_limited ou concurrency. En cas de surcharge temporaire, vous obtenez également un 429, avec Retry-After: 5.

import time
from openai import RateLimitError

def chat(messages, retries=4):
    for attempt in range(retries):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited after retries")

Les requêtes en streaming conservent leur slot de concurrence jusqu'à la fin du flux, donc un client bloqué peut affamer les autres. Fermez les flux dans un bloc finally. Si votre ancien fournisseur autorisait plus d'appels simultanés, ajoutez un sémaphore dimensionné à la nouvelle limite. Les requêtes échouées ne sont pas facturées, ce qui rend les nouvelles tentatives sûres pour votre budget.

Étape 5 : Déployez par pourcentage

Ne basculez pas tout en même temps. Envoyez une petite part stable d'utilisateurs vers le nouveau fournisseur et conservez l'ancien comme solution de repli. Le hachage de l'ID utilisateur maintient chaque utilisateur d'un côté, afin que les conversations ne changent pas de voix en cours de route.

import hashlib

def use_new(user_id: str, percent: int) -> bool:
    bucket = int(hashlib.sha256(user_id.encode()).hexdigest(), 16) % 100
    return bucket < percent

# 5 percent, then 25, 50, 100 as metrics hold
new_client = OpenAI(base_url="https://api.apimigration.com/v1", api_key=os.environ["NEW_KEY"])
old_client = OpenAI(base_url=os.environ["OLD_BASE_URL"], api_key=os.environ["OLD_KEY"])

def pick(user_id):
    return new_client if use_new(user_id, int(os.environ.get("ROLLOUT_PERCENT", "0"))) else old_client

Augmentez le pourcentage uniquement après l'étape précédente qui a fonctionné correctement pendant environ un jour. Le retour en arrière se fait alors en réinitialisant une variable d'environnement à 0.

Ce qui surprend souvent les équipes après le changement

Le changement de Base URL fonctionne du premier coup. Les surprises arrivent ensuite.

  • Dérive du ton et du format. Le même prompt donne une réponse formulée différemment. Les fonctionnalités qui analysent du texte libre, comme une expression régulière sur les préfixes "Réponse :", sont les premières à tomber en panne. Privilégiez le mode JSON ou les appels d'outils pour tout ce qu'un programme doit lire.
  • Nombres de tokens différents. Chaque modèle tokenise le texte à sa manière. Votre estimation des coûts basée sur les nombres de tokens de l'ancien fournisseur sera faussée d'une certaine marge, alors remesurez avec le champ usage.
  • Longueur de sortie. Sans max_tokens, la complétion peut utiliser le reste de la fenêtre de 100 000 tokens. Si votre ancien setup avait un plafond par défaut, définissez-en un intentionnellement.
  • Délais d'attente. Votre délai d'attente client était ajusté pour l'ancien fournisseur. Les réponses longues sur un nouveau fournisseur peuvent le dépasser. Utilisez le streaming là où c'est possible et augmentez le délai d'attente pour les appels non en streaming.
  • Changement des refus silencieux. Si votre produit interceptait auparavant les messages de refus pour afficher une solution de repli, ce code peut cesser de se déclencher. Décidez si vous le souhaitez toujours.

Une courte liste de contrôle avant le basculement

  1. Chaque fonctionnalité de votre inventaire dispose d’un équivalent testé ou d’un écart documenté.
  2. La Base URL, la clé et le modèle proviennent de la configuration dans chaque service qui appelle l’API.
  3. Les limites de débit et les plafonds de concurrence dans votre code correspondent aux nouvelles limites.
  4. Les flux sont fermés en cas de déconnexion du client.
  5. Les journaux incluent l'en-tête X-Request-Id, afin que vous puissiez citer une requête lorsque vous demandez de l'aide.
  6. Le solde est surveillé via X-Balance-USD ou GET /v1/balance, avec une alerte avant qu’il ne soit faible.
  7. L’ancien fournisseur reste financé et configuré pour un retour en arrière.
  8. Une personne désignée est propriétaire de la décision de revenir en arrière.

Ce dernier point semble absurde jusqu'à ce qu'un incident se produise à 2 heures du matin. Quelqu'un doit pouvoir basculer l'indicateur.

Étape 6 : Vérifiez le coût, puis basculez

Calculez la nouvelle facture à partir de votre propre trafic. Les prix sont de $0,15 par 1 M de tokens d’entrée et de $0,50 par 1 M de tokens de sortie.

Exemple : 10 000 requêtes par jour, chacune avec 1 500 tokens d’entrée et 400 tokens de sortie.

  • Entrée : 15 000 000 tokens x $0,15 / 1 000 000 = $2,25.
  • Sortie : 4 000 000 tokens x $0,50 / 1 000 000 = $2,00.
  • Total : $4,25 par jour.

Comparez cela avec l'ancienne facture, en utilisant la page de tarification actuelle de l'ancien fournisseur. La facturation ici repose sur un crédit prépayé sans abonnement, et le crédit n'expire jamais. Les recharges vont de 20 $ à 500 $ en montants entiers, avec un bonus de 5 % à partir de 50 $, de 10 % à partir de 100 $ et de 15 % à partir de 200 $, payés en crypto (USDT sur TRC20 ou USDC sur Base). Le solde s'affiche dans l'en-tête de réponse X-Balance-USD, afin que vous puissiez configurer une alerte dessus.

Les nouveaux comptes peuvent réclamer $0,50 de crédit d'essai pour les premiers tests. Consultez la tarification, puis obtenez une clé API, et gardez la documentation ouverte pendant que vous cartographiez les paramètres.

Questions fréquentes

Puis-je migrer en modifiant uniquement l'URL de base ?

Pour une API compatible OpenAI, l'URL de base, la clé et l'ID du modèle sont les modifications requises. Vous devez tout de même tester les prompts, car un modèle différent répond différemment.

Mes appels d’outils et le mode JSON continueront-ils de fonctionner ?

L’appel de fonctions et le mode JSON (response_format json_object) sont pris en charge. Validez vos schémas avec des prompts réels avant le basculement.

Que faire si mon application utilise des embeddings ?

Cette API est uniquement textuelle et ne propose ni embeddings, ni génération d’images, ni fine-tuning. Maintenez ces appels chez votre fournisseur actuel.

Comment revenir en arrière rapidement ?

Acheminez le trafic via un indicateur d’environnement tel qu’un pourcentage de déploiement, et conservez l’ancien client configuré jusqu’à ce que le nouveau routage ait fonctionné proprement pendant quelques jours.

Obtenez votre clé API

Inscrivez-vous, copiez la clé, mettez à jour la Base URL. L’installation est terminée.

Obtenir une clé API