Les erreurs de Cherry Studio paraissent diverses, mais elles se classent par couches : l'identité est-elle acceptée, l'adresse et le modèle sont-ils corrects, la requête est-elle partie, l'amont limite-t-il le débit, la réponse a-t-elle été coupée en transit ? Un diagnostic par couche est bien plus efficace que de réinstaller le client en boucle.

Cet article classe les erreurs par 401, 404, 429, échec de connexion, interruption du flux et base de connaissances, avec un ordre de vérification, des commandes et une méthode de collecte de preuves. Les noms d'interface et les entrées de journaux peuvent changer selon la version ; référez-vous à la version installée.

Remarque : Cherry Studio est un produit de son détenteur, OpenAI une marque d'OpenAI. Cet article est purement technique et n'implique aucune affiliation avec ces sociétés ; modèles et prix figurent sur la page tarifs des modèles.

1. Fixer d'abord l'ordre du diagnostic

Face à une erreur, conservez quatre éléments : le code de statut HTTP, le message d'erreur du corps de réponse, l'heure de la requête et l'identifiant de requête renvoyé par la passerelle. Sans eux, vous ne pouvez décrire qu'un « échec approximatif » ; avec eux, vous retrouvez la requête précise et l'amont concerné.

Suivez ensuite cet ordre, en ne modifiant qu'une variable à la fois :

  1. Interroger directement la passerelle avec curl pour vérifier adresse, clé et modèle.
  2. Si curl fonctionne mais pas le client, examiner configuration, proxy et type de protocole du client.
  3. Si ni curl ni le client ne fonctionnent, vérifier clé, quota, identifiant de modèle et état de la passerelle.
  4. Si seules les longues réponses ou la base de connaissances échouent, examiner streaming, timeouts et modèle d'embedding.
Symptôme Cause fréquente À vérifier en premier
401 Unauthorized Clé erronée, expirée, avec espace ou venue d'une autre plateforme Cohérence entre clé et URL de base
404 Not Found /v1 en trop ou manquant dans le chemin Fin de l'adresse API
model not found Identifiant mal orthographié, casse incorrecte ou accès non ouvert Identifiant et page tarifs
429 Too Many Requests Concurrence, fréquence ou quota atteint En-têtes de réponse et usage passerelle
Délai de connexion dépassé Proxy, DNS, pare-feu ou certificat Proxy système et réseau
Réponse qui s'arrête en cours Flux coupé par un proxy ou un timeout Comparer en désactivant le streaming

2. 401 : clé et authentification

Un 401 signifie que le serveur ne reconnaît pas la clé. Causes fréquentes :

  • Un espace, un retour à la ligne ou des guillemets ont été copiés, la chaîne envoyée est incomplète.
  • La clé appartient à une autre plateforme mais a été saisie sous cette URL de base.
  • La clé a été supprimée, remplacée, le projet est désactivé ou le quota épuisé.
  • Le client n'a pas enregistré la valeur : le champ semble rempli, la requête part vide.
  • Un protocole Anthropic ou Gemini est utilisé vers un point de terminaison compatible OpenAI, et l'en-tête d'authentification ne correspond pas.

Recollez la clé en vérifiant l'absence d'espaces, puis confirmez que l'URL de base et la clé viennent de la même plateforme. Si le client propose « Vérifier » ou « Tester la connexion », utilisez-le, puis recontrôlez avec curl. Si curl passe mais le client renvoie 401, cherchez si la clé est réellement enregistrée et si le type de protocole est correct.

3. 404 et model not found

Un 404 ne signifie pas forcément une interface retirée ; c'est souvent une erreur d'assemblage du chemin. Cas courants :

  • L'URL de base contient déjà l'adresse complète et le client ajoute encore /chat/completions, créant un doublon.
  • /v1 manque là où il faut, ou apparaît là où il ne faut pas.
  • Le type de fournisseur est mauvais : un point compatible OpenAI est configuré en Anthropic ou Gemini.
  • L'identifiant de modèle diffère de la page tarifs par la casse, le suffixe de date ou les tirets.
  • Le modèle existe, mais la clé n'a pas l'autorisation.

model not found et 404 se distinguent : dans le premier cas l'adresse répond mais le modèle est faux ; dans le second, même la route peut ne pas correspondre. Interrogez /v1/models pour voir les modèles exposés ; si la liste n'est pas disponible, copiez l'identifiant exact depuis la page tarifs des modèles, ajoutez-le à la main et réessayez.

4. 429 : limite de débit, concurrence ou quota

Un 429 a au moins deux sens, traités différemment :

  • Fréquence ou concurrence dépassée : trop de requêtes en peu de temps, ou plusieurs sessions et agents ouverts simultanément.
  • Quota ou solde insuffisant : le projet de la clé n'a plus de crédit ou a atteint son plafond.

Lisez le corps et les en-têtes. retry-after indique l'attente conseillée ; si le message mentionne quota ou balance, n'enchaînez pas les tentatives avec backoff : vérifiez d'abord le quota dans la console. Seule une limitation de débit pure justifie un backoff exponentiel, avec gigue aléatoire pour éviter que tous les clients réessaient à la même seconde.

Dans Cherry Studio, ouvrir plusieurs assistants ou comparer des modèles en lot amplifie facilement la concurrence sans qu'on s'en rende compte. Pour diagnostiquer, ne gardez qu'une session et un modèle, puis rétablissez progressivement.

5. Échec de connexion, SSL et proxy

Un échec de connexion se manifeste par une attente infinie, un timeout, une impossibilité de se connecter ou une erreur de certificat. Cherry Studio propose généralement trois modes de proxy : proxy système, proxy personnalisé et aucun proxy, dans les options système ou générales ; les libellés dépendent de la version.

Ordre de vérification :

  1. Confirmez que le proxy système ou le VPN fonctionne et que le client utilise le mode « proxy système ».
  2. Si un proxy personnalisé est saisi, vérifiez l'adresse et le port, par exemple http://127.0.0.1:7890.
  3. Contrôlez la liste de contournement : le domaine cible n'est ni exclu à tort ni forcé dans le proxy.
  4. Passez temporairement en « aucun proxy » pour voir si le problème vient de la chaîne proxy.
  5. Si le réseau d'entreprise inspecte le TLS, vérifiez le certificat système et la chaîne de confiance du client.
  6. Contrôlez l'heure système : un écart important fait échouer la validation du certificat.

Erreur classique : mettre l'adresse du proxy dans l'adresse API. L'adresse API doit être l'URL HTTPS de la passerelle de modèles ; le proxy se règle dans les paramètres de proxy.

6. Interruption de la sortie en streaming

Une réponse en streaming repose sur une connexion longue. Le symptôme typique : les premiers mots arrivent, puis plus rien après quelques secondes, ou seul un fragment s'affiche. Les causes incluent la mise en tampon par un proxy, un timeout d'inactivité, un timeout de passerelle et un changement de réseau.

Désactivez d'abord le streaming et reposez la même question. Si la réponse non streaming est complète, le problème est dans la chaîne de transport ; examinez le logiciel proxy, le pare-feu et les timeouts du reverse proxy. Un reverse proxy doit désactiver la mise en tampon des réponses et allonger le timeout de lecture, sinon le SSE est accumulé puis renvoyé d'un bloc, ou coupé en cours.

Distinguez aussi « le modèle s'est arrêté » et « la connexion a été coupée ». Le premier cas a généralement un marqueur de fin ; le second n'a souvent aucun code d'erreur et laisse un texte tronqué. Notez les deux cas séparément pour déterminer ensuite si la cause est le client, la passerelle ou le réseau.

7. Erreurs de base de connaissances et d'embedding

Les erreurs de base de connaissances ne viennent généralement pas de l'interface de dialogue, mais de l'embedding ou de la recherche :

  • Seul un modèle de dialogue est configuré, aucun modèle d'embedding utilisable ne l'est.
  • Le modèle d'embedding ne prend pas en charge l'interface d'embedding actuelle, ou la dimension des vecteurs ne correspond pas à l'index.
  • L'analyse du fichier échoue, par exemple un PDF scanné sans texte extractible.
  • Le modèle d'embedding a changé sans reconstruction de l'index : anciens vecteurs et nouvelles requêtes ne correspondent plus.
  • Le service de reranking ou de recherche est injoignable, la recherche renvoie vide ou expire.

La base de connaissances de Cherry Studio peut fonctionner par mots-clés ou en recherche hybride avec un modèle d'embedding ; changer de modèle déclenche une reconstruction dans l'interface. Avant de reconstruire, vérifiez que le nouveau modèle est appelable et ne modifiez pas en même temps les paramètres de découpage, sinon vous ne pourrez pas attribuer le changement de résultat.

8. Journaux, commandes de diagnostic et preuves

Cherry Studio propose un mode développeur, activable dans les paramètres, qui affiche la chaîne d'appel des requêtes pour localiser les erreurs de modèle et d'outil ; l'entrée dépend de la version. Côté passerelle, conservez l'identifiant de requête, le nom du modèle, la durée et les tokens consommés : des horodatages concordants permettent d'identifier le segment fautif.

Commencez par une reproduction minimale avec curl :

export ZSQH_API_KEY="sk-votre-clé"

# 1. Vérifier l'adresse et la clé
curl -sS "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

# 2. Vérifier que le modèle est appelable
curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"votre-ID-de-modèle","messages":[{"role":"user","content":"Réponds seulement OK"}]}' \
  -w "\nHTTP %{http_code}\n"

# 3. Contrôler séparément la poignée de main TLS et la chaîne de certificats
openssl s_client -connect ai.zhongshangqihang.com:443 -servername ai.zhongshangqihang.com </dev/null

Ces trois commandes couvrent trois questions : clé et adresse, modèle et paramètres, TLS et certificats. L'étape qui échoue indique la couche à creuser ; ne changez pas simultanément clé, adresse et modèle.

Questions fréquentes

Changer de clé suffit-il à corriger un 401 ?

Pas toujours. Une nouvelle clé écarte un problème de clé, mais si l'URL de base ne correspond pas à la plateforme de la clé, si le protocole est mauvais ou si le client n'enregistre pas la valeur, changer de clé ne servira à rien. Vérifiez d'abord où la requête est réellement envoyée.

Un 404 signifie-t-il que le modèle est retiré ?

Le plus souvent, l'URL de base ou l'identifiant de modèle est incorrect. Interrogez /v1/models avec curl, puis comparez avec la page tarifs des modèles ; ce n'est qu'après ces deux contrôles qu'on envisage un retrait du modèle.

Faut-il toujours réduire la concurrence sur un 429 ?

Non. Lisez le message : seule une limitation de débit impose de réduire la concurrence et d'attendre ; en cas de quota insuffisant, ralentir ne sert à rien, il faut vérifier le solde ou le budget dans la console. L'en-tête retry-after aide à estimer l'attente.

Pourquoi seul le streaming se coupe-t-il ?

Le streaming dépend d'une connexion longue, plus facilement coupée par la mise en tampon d'un proxy, un timeout d'inactivité de pare-feu ou le timeout d'un reverse proxy. Comparez avec le streaming désactivé ; si le mode non streaming fonctionne, examinez proxy et timeouts plutôt que de réinstaller le client.

Faut-il diagnostiquer séparément les erreurs de base de connaissances et de dialogue ?

Oui. Le dialogue passe par l'interface de chat ; la base de connaissances implique en plus l'analyse de fichiers, le modèle d'embedding, l'index vectoriel et le service de recherche. Confirmez d'abord le modèle de dialogue, puis vérifiez l'appel du modèle d'embedding, la cohérence des dimensions et la nécessité de reconstruire l'index.

Prochaines étapes

Retenez l'ordre en une phrase : curl d'abord, client ensuite ; code de statut d'abord, journaux ensuite ; une seule variable modifiée à la fois. Pour un point d'entrée compatible OpenAI unifié, des journaux de requêtes et la gestion de l'usage, vous pouvez créer un compte ZSQH AI Gateway ; modèles et prix figurent sur la page tarifs des modèles.

Lectures associées :