L'API Qwen est fournie par Alibaba Cloud Model Studio (Bailian), dont DashScope est le système d'interface natif. Model Studio propose à la fois une interface compatible OpenAI et l'interface native DashScope. Pour la plupart des équipes, l'interface compatible OpenAI est la plus simple : les SDK, frameworks d'agents et outils existants ne demandent 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 choisir la bonne région d'URL de base, de vérifier que le nom du modèle est valide, de savoir analyser le streaming et d'identifier les paramètres qui ne peuvent pas être repris tels quels depuis OpenAI. Cet article valide la chaîne avec une requête minimale, puis complète les appels d'outils, le diagnostic des erreurs et la checklist de migration.
Remarque : Qwen, Tongyi Qianwen, Alibaba Cloud, Model Studio (Bailian) et DashScope sont des marques ou noms de produits du groupe Alibaba et de ses sociétés affiliées. Cet article n'a qu'une vocation d'explication technique et n'implique aucun lien d'affiliation, de représentation ou d'autorisation avec le groupe Alibaba. 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 d'Alibaba Cloud Model Studio 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, correspondant à la région cible.
- La bonne URL de base : Chine continentale, site international et adresse de passerelle ne se mélangent pas.
- Un nom de modèle réellement disponible aujourd'hui ; ne recopiez pas les exemples d'anciens articles.
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. URL de base : choisir d'abord la région, puis le domaine
Le chemin de l'interface compatible OpenAI est fixé à /compatible-mode/v1, et l'interface de chat ajoute /chat/completions. Les domaines varient selon la région :
| Scénario | URL de base compatible OpenAI | Remarque |
|---|---|---|
| Chine continentale (Pékin, ancien domaine partagé) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
Compatible avec l'ancien code, encore disponible |
| Singapour (site international) | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
Compte et clé du site international |
| États-Unis, Virginie | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
IPv4 uniquement, capacités selon la documentation |
| Hong Kong, Chine | https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 |
Région et clé distinctes |
| Espace métier dédié | https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 |
Recommandé en production, meilleur débit et isolation |
| ZSQH AI Gateway | https://ai.zhongshangqihang.com/v1 |
Point d'entrée multi-modèles unifié |
Trois points essentiels. Premièrement, la clé API est liée à une région : un appel inter-régions renvoie généralement une 401 avec invalid_api_key, ce qui indique une inadéquation entre la clé et l'adresse, pas nécessairement une clé invalide. Deuxièmement, les comptes de Chine continentale et du site international sont deux systèmes distincts : les clés, la facturation et les listes de modèles ne sont pas interchangeables. Troisièmement, le domaine dédié à un espace métier n'accepte que la clé de cet espace, mais offre un meilleur débit et une meilleure isolation du trafic, ce qui convient à la production ; l'ancien domaine partagé reste pratique pour tester rapidement entre espaces.
Si l'équipe utilise plusieurs modèles et ne veut pas gérer elle-même les régions, les quotas et plusieurs jeux de clés, elle peut créer une clé unifiée sur ZSQH AI Gateway, puis remplacer l'URL de base par la dernière ligne du tableau.
3. Comment choisir le modèle
La liste des modèles de Model Studio évolue rapidement. Sur la page actuelle des modèles, la génération de texte liste notamment qwen3.8-max, qwen3.7-plus et qwen3.8-flash. On peut grossièrement comprendre la nomenclature ainsi : max vise le haut de gamme, plus l'équilibre, flash la faible latence et le coût. Le positionnement exact et la longueur de contexte sont ceux de la documentation des modèles ; les prix évoluent et sont ceux de la page Tarifs des modèles.
Ne choisissez pas uniquement « le plus puissant ». Pour le support client, la classification par lots ou la modération de contenu, 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.
Deux pièges fréquents. Les écritures qwen-max, qwen-plus et similaires trouvées dans d'anciens tutoriels ont peut-être changé : vérifiez la liste des modèles dans la console avant l'intégration. Pour les capacités vectorielles, utilisez la série embedding (par exemple qwen3.7-text-embedding), dont le corps de requête diffère de celui du chat. Qwen-Audio ne prend pas en charge le protocole compatible OpenAI et nécessite l'interface native DashScope.
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 DASHSCOPE_API_KEY="your_key_here"
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"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.7
}'
En cas de réponse normale, examinez trois champs : choices[0].message.content contient la réponse, usage la consommation et finish_reason la raison de fin. En cas de 401, vérifiez d'abord la clé et la région ; en cas de 404 avec ModelNotFound, vérifiez le nom du modèle et si celui-ci est activé dans la région.
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 Model Studio, l'appel est presque identique à OpenAI :
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
stream = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Rédige une présentation produit de moins de cent mots."}],
stream=True,
stream_options={"include_usage": 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. Avec stream_options={"include_usage": True}, l'usage apparaît dans le dernier chunk. En HTTP direct, la réponse est au format SSE et se termine par data: [DONE]. Lorsqu'un utilisateur ferme la page, le serveur doit annuler rapidement la requête amont pour éviter de continuer à générer et à facturer.
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 avec role: "tool". Dans un flux multi-tours, chaque tour doit inclure tools. En production, validez les paramètres, les droits et les timeouts ; ne faites pas confiance aveuglément aux paramètres générés par le modèle.
La documentation de compatibilité impose actuellement deux limites aux outils : seuls certains modèles sont listés comme compatibles, et tools ne peut pas encore être utilisé en même temps que stream=True. La liste des modèles et leurs capacités évoluent ; testez le modèle cible avant la mise en production. Si le métier doit absolument appeler des outils pendant le streaming, envisagez l'interface native DashScope ou transformez l'appel d'outil en étape non streamée.
Lors d'une migration depuis OpenAI, tenez compte de ces différences :
messages: seulmessages[0]peut avoir le rôle system ; user et assistant doivent généralement alterner, et le dernier message doit être de rôle user.temperature: plage [0, 2) ; une valeur de 0 est déconseillée par le fournisseur.top_p: plage (0, 1.0).seed: entier 64 bits non signé.stop: les éléments du tableau ne peuvent pas mélanger identifiants de tokens et chaînes.system_fingerprint: renvoie actuellement une chaîne vide.- Paramètres d'extension comme
enable_search: généralement passés viaextra_body, et pas pris en charge par tous les modèles. - Champs comme
response_formatoufrequency_penalty: ne sont pas couverts par la documentation de compatibilité ; ne supposez pas un comportement identique à OpenAI.
7. Correspondance des erreurs fréquentes
| Symptôme | Code d'erreur courant | Cause possible | Traitement |
|---|---|---|---|
| 401 | InvalidApiKey / invalid_api_key |
Clé erronée, région incompatible, mélange de clés d'offres | Vérifier la région et le type de clé par rapport à l'URL de base |
| 404 | ModelNotFound / model_not_found |
Nom de modèle mal orthographié, modèle absent de la région, non activé | Consulter la liste des modèles dans la console |
| 404 | model_not_supported |
Modèle non compatible avec le mode OpenAI | Utiliser l'interface native DashScope |
| 403 | AccessDenied / Workspace.AccessDenied |
Droits insuffisants sur l'espace ou le modèle | Vérifier les autorisations de l'espace métier |
| 403 | AllocationQuota.FreeTierOnly |
Quota gratuit épuisé | Recharger ou ajuster l'offre |
| 429 | Série Throttling |
Fréquence, tokens ou concurrence dépassés | Réduire la concurrence, backoff, demander un quota |
| 400 | Arrearage |
Compte en impayé | Recharger puis réessayer |
| 400 | Range of input length... |
Entrée dépassant la limite de contexte | Compresser l'invite ou segmenter |
| 400 | DataInspectionFailed |
Entrée ou sortie bloquée par la sécurité du contenu | Ajuster le contenu puis réessayer |
Les nouvelles tentatives ne sont utiles que pour les 429, les 5xx et les timeouts réseau. Réessayer sur une 401, une 403, une 404 ou une erreur de paramètre n'améliore rien et gaspille du temps et du quota. Lors du diagnostic, consignez le Request ID de la réponse et recherchez-le dans les journaux de la console : c'est beaucoup plus rapide que de deviner.
8. Checklist de migration depuis OpenAI
- Sauvegardez les invites, paramètres de modèles et jeux d'évaluation existants.
- Créez une clé Qwen correspondant à la région cible ; 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.
- Vérifiez la règle des rôles dans
messages: premier message system, dernier message user. - Vérifiez l'analyse du streaming et la méthode de comptage de
usage. - Faites un test de régression des appels d'outils avec de vrais outils.
- Comparez la qualité de sortie, la latence et la consommation sur le même lot d'échantillons.
- Ajustez les tentatives, les timeouts et la concurrence, observez une semaine avant la bascule complète.
- Consignez le Request ID dans les journaux et conservez un commutateur de retour arrière.
9. Questions fréquentes (FAQ)
1. L'API Qwen est-elle compatible avec OpenAI ?
La plupart des interfaces de chat courantes sont compatibles, mais il subsiste des différences de liaison à la région, d'ordre des rôles, de plage de paramètres et de limites des appels d'outils. Vérifiez chaque point dans la documentation de compatibilité du fournisseur ; ne supposez pas que tous les paramètres se comportent à l'identique.
2. Peut-on utiliser la même clé en Chine continentale et sur le site international ?
Non. Les comptes, clés, domaines d'accès et facturations des deux sites sont indépendants. Un appel inter-régions ou inter-sites renvoie généralement une 401 avec invalid_api_key.
3. Faut-il utiliser l'ancien domaine ou le domaine dédié à un espace métier ?
Pour un test rapide, l'ancien domaine partagé suffit ; en production, je conseille le domaine dédié à l'espace métier, pour de meilleurs débit et isolation du trafic. L'essentiel est que la clé corresponde à la région et à l'espace métier du domaine.
4. Pourquoi un nom de modèle correct renvoie-t-il model_not_found ?
Les causes fréquentes sont : le modèle n'existe pas dans cette région, il n'est pas activé, la casse du nom diffère, ou la version consultée a été retirée. Référez-vous à la liste actuelle des modèles dans la console.
5. Peut-on utiliser tools avec stream ?
La documentation de compatibilité indique actuellement que les deux ne peuvent pas être utilisés ensemble, et que les appels d'outils ne sont pris en charge que par certains modèles. Les capacités et limites évoluent avec les modèles ; testez le modèle cible avant la mise en production ou utilisez l'interface native DashScope.
