Le coût d'intégration de l'API GLM est plus faible qu'on ne le pense souvent : elle propose une interface compatible OpenAI, et un SDK OpenAI existant ne demande généralement que trois modifications : la clé API, l'URL de base et le nom du modèle. Les vraies difficultés ne sont pas de « faire passer l'appel », mais de savoir si le nom du modèle est valide, comment traiter le streaming, quel format renvoient les appels d'outils, et quels paramètres ne peuvent pas être repris tels quels lors d'une migration depuis OpenAI.
Cet article valide la chaîne avec une requête minimale, puis complète le streaming, les appels d'outils, le diagnostic des erreurs et la checklist de migration. Tous les exemples peuvent être exécutés après remplacement de la clé.
Remarque : Zhipu, GLM et BigModel sont des marques de leurs détenteurs respectifs. Cet article n'a qu'une vocation d'explication technique et n'implique aucun lien d'affiliation, de représentation ou d'autorisation avec Zhipu. L'URL de base, les noms de modèles, la longueur de contexte et les règles de facturation peuvent évoluer ; référez-vous à la documentation de la plateforme ouverte Zhipu et à la page Tarifs des modèles.
1. Préparation avant l'intégration
Vérifiez trois éléments avant de commencer :
- Une clé API valide, dont le type correspond à l'interface à appeler.
- La bonne URL de base : l'accès direct au fournisseur et l'adresse d'une passerelle ne se mélangent pas.
- Un nom de modèle réellement disponible aujourd'hui ; ne recopiez pas les exemples d'anciens articles.
Pour un nouveau projet, je conseille de vérifier d'abord l'authentification et le réseau avec curl, puis d'intégrer le SDK. En cas d'erreur, il est plus facile de distinguer un problème de clé, d'adresse ou de code.
2. Comment renseigner l'URL de base
L'URL de base de l'interface compatible OpenAI de Zhipu s'écrit généralement :
https://open.bigmodel.cn/api/paas/v4
L'adresse compatible OpenAI de ZSQH AI Gateway est :
https://ai.zhongshangqihang.com/v1
Les deux se combinent avec le chemin OpenAI /chat/completions. Ne concaténez pas deux fois le segment de version ou /chat/completions dans le code, et ne mélangez pas les écritures avec ou sans barre oblique finale.
| Mode d'accès | Exemple d'URL de base | Cas d'usage | Remarque |
|---|---|---|---|
| Zhipu, accès direct | https://open.bigmodel.cn/api/paas/v4 |
GLM uniquement, accès aux dernières fonctionnalités | Compte et solde chez le fournisseur |
| Passerelle ZSQH | https://ai.zhongshangqihang.com/v1 |
Point d'entrée multi-modèles, facture unifiée | Créer une clé sur la passerelle |
3. Comment choisir le modèle
La série GLM se divise en catégories : texte, vision, voix, vecteurs, etc. Les modèles texte ont différents niveaux : certains sont orientés conversation générale et agents, d'autres vers la faible latence et la forte concurrence, d'autres encore vers un contexte plus long. Dans la série GLM-5 actuellement listée par la documentation, on trouve par exemple glm-5.3, glm-5.3-flash et glm-5.2, mais les modèles évoluent en continu : les noms réellement disponibles sont ceux de la console et de la page Tarifs des modèles.
Ne choisissez pas uniquement « le plus puissant ». Pour le support client ou la classification par lots, un niveau à faible latence est souvent plus économique ; réservez les modèles plus puissants à l'analyse de documents longs et aux agents complexes. Faites du nom de modèle un élément de configuration plutôt qu'une valeur codée en dur : les changements ultérieurs seront beaucoup plus simples.
Si la tâche implique la compréhension d'images, choisissez un modèle acceptant les entrées visuelles ; pour la recherche vectorielle, utilisez la série embedding. Les chemins et paramètres des modèles texte, vision et vecteurs ne sont pas identiques : n'utilisez pas le même corps de requête pour tous. Avant la mise en production, faites passer les modèles candidats sur le même jeu d'évaluation et comparez précision, latence et consommation avant de choisir le principal et le secours.
4. Premier appel avec curl
Préparez d'abord la variable d'environnement pour éviter que la clé apparaisse dans l'historique des commandes :
export GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "Tu es un assistant technique concis."},
{"role": "user", "content": "Explique en trois phrases ce qu'est une passerelle API."}
],
"temperature": 0.6
}'
En cas de réponse normale, examinez trois champs : choices[0].message.content contient la réponse, usage la consommation de l'appel et finish_reason la raison de fin. En cas de 401, vérifiez d'abord la clé et l'en-tête ; en cas de 1211, vérifiez d'abord le nom du modèle.
5. Appel avec le SDK Python et streaming
Le SDK OpenAI doit être en version 1.0 ou ultérieure. Après avoir pointé l'URL de base vers GLM, l'appel est presque identique à OpenAI :
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Rédige une présentation produit de moins de cent mots."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Attention au streaming : le premier chunk peut ne contenir que les informations de rôle, avec un content vide ; ne supposez pas que chaque chunk contient du texte. En mode réflexion, le contenu de raisonnement peut apparaître dans le champ reasoning_content, tandis que la réponse finale reste dans content. Traitez les deux séparément pour ne pas afficher le raisonnement directement aux utilisateurs finaux.
6. Appels d'outils et différences de paramètres
Les appels d'outils reprennent le format tools et tool_choice d'OpenAI. Lorsque le modèle renvoie message.tool_calls, il faut analyser le function.arguments de chaque appel en JSON, exécuter la fonction locale, puis renvoyer le résultat dans un message de rôle tool. En production, validez les paramètres et contrôlez les timeouts ; ne faites pas confiance aveuglément aux paramètres générés par le modèle.
Lors d'une migration depuis OpenAI, plusieurs différences méritent attention : la plage de temperature va généralement de 0 à 1, une valeur de 0 pouvant ne pas prendre effet ; la valeur par défaut est d'environ 0,6 ; certaines nouvelles capacités doivent être passées via extra_body. Les paramètres exacts sont ceux de la documentation compatible OpenAI du fournisseur.
En streaming, gérez aussi la déconnexion du client. Lorsqu'un utilisateur ferme la page, le serveur doit annuler rapidement la requête amont pour éviter de continuer à générer et à facturer ; si le métier exige une génération complète, basculez la tâche dans une file d'attente en arrière-plan plutôt que de dépendre de la connexion front-end.
7. Correspondance des erreurs fréquentes
| Symptôme | Cause possible | Traitement |
|---|---|---|
| 401 / 1000 | Clé erronée, type incompatible | Vérifier le type de clé et l'en-tête |
| 1211 | Nom de modèle inexistant ou non activé | Consulter les modèles disponibles dans la console |
| 1261 | Entrée dépassant la limite de contexte | Compresser l'invite ou segmenter |
| 1302 / 1305 | Limitation de débit du compte ou plateforme surchargée | Réduire la concurrence, réessayer avec backoff |
| 1113 | Compte en impayé | Recharger puis réessayer |
| Timeout de connexion | DNS, proxy ou chemin réseau | Utiliser curl pour localiser la couche réseau |
Les nouvelles tentatives ne sont utiles que pour les 429, les 5xx et les timeouts réseau. Réessayer sur une 401, une 1211 ou une 1261 n'améliore rien et gaspille du temps et du quota.
8. Checklist de migration depuis OpenAI
- Sauvegardez les invites, paramètres de modèles et jeux d'évaluation existants.
- Créez une clé dédiée à GLM ; ne réutilisez pas la clé d'un autre fournisseur.
- Transformez l'URL de base et le nom du modèle en éléments de configuration.
- Comparez la qualité de sortie, la latence et la consommation sur le même lot d'échantillons.
- Vérifiez la compatibilité de l'analyse du streaming, des appels d'outils et de la sortie JSON.
- Ajustez les tentatives, les timeouts et la concurrence, observez une semaine avant la bascule complète.
9. Questions fréquentes (FAQ)
1. L'API GLM est-elle totalement compatible avec OpenAI ?
La plupart des interfaces courantes sont compatibles, mais il subsiste des différences de plage de paramètres, de champs de réflexion et de certaines capacités avancées. Vérifiez chaque point dans la documentation compatible OpenAI du fournisseur ; ne supposez pas que tous les paramètres se comportent à l'identique.
2. Faut-il ajouter une barre oblique à la fin de l'URL de base ?
La documentation du fournisseur a déjà présenté les deux formes, avec et sans barre oblique, et le SDK les gère généralement. L'essentiel est de ne pas dupliquer le chemin : choisissez une forme et appliquez-la partout dans le projet.
3. Le streaming permet-il d'obtenir le raisonnement ?
Certains modèles renvoient reasoning_content en mode réflexion. L'affichage dépend de la conception du produit ; pour les utilisateurs finaux, on ne montre généralement que la réponse finale.
4. Les appels d'outils utilisent-ils le même format qu'OpenAI ?
La définition des outils et la structure de retour reprennent largement le format OpenAI, mais les détails des paramètres peuvent varier selon le modèle. Avant la mise en production, faites un test de régression avec de vrais outils.
5. Les noms de modèles sont-ils identiques entre l'accès direct et la passerelle ?
La plupart du temps, la même nomenclature est utilisée, mais la disponibilité d'un modèle ou la prise en charge d'un paramètre sur la passerelle dépend de la console de celle-ci et de la page Tarifs des modèles.
