Migration depuis les SDK officiels
Connectez vos applications OpenAI, Anthropic ou Gemini SDK à AGTCloud et vérifiez systématiquement les limites de compatibilité.
Si votre application utilise déjà un SDK OpenAI, Anthropic ou Gemini, vous pouvez généralement conserver le SDK et le framework métier en connectant le client au protocole compatible correspondant d’AGTCloud. La migration ne se limite pas à une adresse : vérifiez ensemble l’authentification, l’ID du modèle, les chemins ajoutés automatiquement, les champs et l’analyse des réponses.
Conservez le même protocole
OpenAI, Anthropic Messages et Gemini Generate Content sont trois protocoles distincts. Remplacez l’adresse du service au sein du même protocole ; si vous changez aussi de protocole, concevez et testez une refonte complète de l’interface.
Inventaire avant la migration
Recensez d’abord les capacités réellement utilisées par l’application pour ne pas valider uniquement la requête textuelle la plus simple.
| Élément | Informations à consigner |
|---|---|
| SDK | Package, langage, version et Client synchrone ou asynchrone |
| Protocole | Chat Completions, Responses, Messages ou Generate Content |
| Modèle | ID actuel et éventuelle liste de modèles autorisés dans le code |
| Entrée | Texte, images, fichiers, instructions système et historique |
| Sortie | Propriétés textuelles pratiques, objet de réponse complet et analyse personnalisée |
| Streaming | Types d’événements, assemblage des fragments et conditions de fin |
| Outils | Définitions, ID d’appel, analyse des arguments et renvoi des résultats |
| Fiabilité | Délais, nouvelles tentatives, limites de débit, journaux et stratégie de repli |
Modifications minimales
Vérifiez les paramètres suivants pour les trois SDK ; la façon de les renseigner dépend du SDK.
| Paramètre | Action de migration |
|---|---|
| Adresse API | Utilisez l’Origin ou la Base URL du tutoriel correspondant et vérifiez si le SDK ajoute automatiquement un chemin de version |
| API Key | Lisez l’API Key AGTCloud depuis l’environnement, sans l’inscrire dans le code ni le dépôt |
| ID du modèle | Utilisez un modèle accessible à l’API Key et prenant en charge le protocole cible |
| Méthode de requête | Conservez la méthode Client du protocole, telle que chat.completions.create ou messages.create |
| Lecture de la réponse | Vérifiez le texte, les outils, Usage et les erreurs dans la référence AGTCloud |
Migrer selon le SDK
OpenAI SDK appelle Chat Completions et Responses. La Base URL AGTCloud contient /v1.
| Avant | Après |
|---|---|
| API Key du service précédent | Variable d’environnement AGTCLOUD_API_KEY |
| Base URL du service précédent ou adresse par défaut du SDK | https://api.agtcloud.cn/v1 |
| Nom du modèle précédent | MODEL_ID accessible à l’API Key |
| Méthode Chat ou Responses existante | Conserver la même méthode Client |
N’ajoutez pas /v1 deux fois
https://api.agtcloud.cn/v1 contient déjà le chemin de version. Ne configurez pas https://api.agtcloud.cn/v1/v1 et ne saisissez pas l’endpoint complet /chat/completions ou /responses.
Consultez OpenAI SDK pour l’installation, l’initialisation et les exemples Python et TypeScript.
Cas où trois paramètres ne suffisent pas
Les situations suivantes exigent des modifications du code métier, et pas seulement de la Base URL, de la Key et du modèle :
- Passage de Chat Completions à Responses ;
- Migration entre protocoles OpenAI, Anthropic ou Gemini ;
- Dépendance directe aux classes de réponse, aux propriétés pratiques ou aux événements de streaming d’un SDK ;
- Définitions d’outils et renvoi de résultats propres au protocole ;
- Changement des blocs multimodaux, des instructions système ou des noms de rôles ;
- Ajout automatique du chemin par le SDK alors que le projet lui fournit une URL d’endpoint complète ;
- Dépendance aux fonctions propres au service précédent : découverte de modèles, téléversement de fichiers ou outils hébergés.
Valider la migration
Valider une requête textuelle minimale
Envoyez d’abord une requête sans streaming, outils ni multimodal. Vérifiez l’adresse destinataire et la lecture du texte de la réponse.
Rétablir les capacités nécessaires en production
Rétablissez successivement le streaming, les appels d’outils, les sorties structurées, le multimodal et l’état multitour. Ajoutez une seule capacité à la fois pour localiser les différences.
Vérifier les chemins d’échec
Testez au minimum une API Key invalide, un ID de modèle incorrect, un délai dépassé, une limite de débit et une interruption. Vérifiez la lecture des codes d’état et des erreurs ainsi que l’absence de tentatives infinies.
Comparer les résultats métier
Ne vérifiez pas uniquement HTTP 200. Comparez aussi le texte, les arguments d’outils, la raison de fin, Usage, les conditions de fin du streaming et le Request ID des journaux.
Bascule progressive et retour arrière
- Conservez des configurations distinctes pour les deux Provider, sans disperser les adresses et les noms de modèles dans le code métier.
- Commencez par le trafic de développement ou de test sur AGTCloud, puis élargissez progressivement.
- Consignez le taux de réussite, la latence, les types d’erreurs et les différences fonctionnelles à chaque étape.
- Gardez la configuration du Provider précédent et un mécanisme de repli contrôlable ; retirez l’ancienne configuration après stabilisation.
Ne vous fiez pas aux champs ignorés silencieusement
Certaines implémentations compatibles acceptent des champs inconnus sans exécuter la capacité associée. Observez les résultats réels et la structure de réponse : le code d’état seul ne prouve pas que le champ a pris effet.
Étapes suivantes
- Consultez la Présentation des SDK pour choisir un tutoriel ;
- Consultez API Key, Base URL et authentification ;
- Pour passer de Chat à Responses, lisez Chat Completions → Responses ;
- En cas d’erreur ou d’échec de requête, consultez Erreurs et dépannage.