Cherry Studio est un client IA de bureau courant, qui prend en charge plusieurs fournisseurs, le changement de modèle, les assistants et les bases de connaissances. Il ne fournit pas de modèle : celui-ci vient de l'API que vous configurez. Beaucoup d'utilisateurs bloquent au même endroit : quelle URL de base saisir, où mettre la clé, comment ajouter un ID de modèle. Cet article déroule le parcours complet avec les versions courantes.
Remarque : Cherry Studio est un produit de son détenteur ; cet article est purement technique. Les noms d'interface et les entrées peuvent évoluer selon les versions ; la version actuelle fait foi. Modèles et prix sont sur la page Tarifs des modèles.
1. Trois éléments à préparer
Quelle que soit la passerelle, un fournisseur personnalisé ne demande que trois paramètres :
- Clé API : créée dans la console après inscription à ZSQH AI Gateway, nommée selon le projet ou l'environnement.
- URL de base : l'adresse compatible OpenAI de la passerelle, généralement
https://ai.zhongshangqihang.com/v1. - ID de modèle : copié depuis la page Tarifs des modèles, en utilisant l'identifiant API et non le nom d'affichage.
Validez d'abord la clé et le modèle avec une commande, avant d'ouvrir le client :
export ZSQH_API_KEY="sk-votre-cle"
curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
-H "Authorization: Bearer $ZSQH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "votre-id-modele",
"messages": [{"role": "user", "content": "Réponds seulement OK"}]
}'
Si la réponse contient choices, la clé, l'adresse et le modèle fonctionnent ; le problème éventuel vient de la configuration du client.
2. Comment remplir l'URL de base
Le nom du champ varie selon les versions, souvent « Adresse API » ou « API Host ». Remplissez ainsi :
| Élément | Valeur conseillée | Remarque |
|---|---|---|
| Type de fournisseur | OpenAI | Utilise le protocole compatible OpenAI |
| Adresse API | https://ai.zhongshangqihang.com/v1 |
Sans barre oblique finale |
| Clé API | sk-... |
Clé créée dans la console |
| ID de modèle | Selon la page tarifs | À vérifier surtout en ajout manuel |
La gestion de /v1 varie selon les versions : certaines l'ajoutent automatiquement, d'autres exigent l'adresse complète. Méthode simple : 401 indique souvent un problème de clé, 404 un problème de chemin. Si l'adresse complète renvoie 404, essayez sans /v1 ; si le domaine seul renvoie 404, ajoutez /v1. Ne changez qu'une variable à la fois, pas la clé, l'adresse et le modèle en même temps.
3. Ajouter un fournisseur personnalisé
Avec les versions courantes, l'ordre est le suivant (les libellés dépendent de votre version) :
- Ouvrez Cherry Studio et cliquez sur les réglages en bas à gauche (icône d'engrenage).
- Entrez dans « Services de modèles » ou « Fournisseurs de modèles ».
- Cliquez sur « + Ajouter un fournisseur ».
- Choisissez le type OpenAI ou une option compatible OpenAI.
- Renseignez le nom du fournisseur, la clé API et l'adresse API.
- Enregistrez, revenez à la liste des modèles et ajoutez l'ID du modèle.
Si « Ajouter un fournisseur » n'existe pas, mettez d'abord le client à jour. Les anciennes versions ont d'autres entrées et champs ; appliquer un ancien tutoriel conduit facilement à un mauvais emplacement.
4. Ajouter un ID de modèle
Après avoir enregistré le fournisseur, deux méthodes existent :
- Récupérer la liste des modèles : le client interroge la passerelle, puis vous cochez les modèles voulus.
- Ajout manuel : cliquez sur « + » et saisissez l'ID. À utiliser si la passerelle n'expose pas d'interface de liste ou si la récupération échoue.
L'ID doit correspondre exactement à la page tarifs, casse, suffixe de version et traits d'union compris. En ajout manuel, vérifiez aussi que le type est « dialogue » ou « chat » ; un mauvais type empêche le modèle d'apparaître dans le sélecteur de conversation.
| Type de modèle | Usage courant | Attention |
|---|---|---|
| Modèle de dialogue | Questions-réponses, rédaction, code | Le plus courant, à configurer d'abord |
| Modèle de raisonnement | Analyses complexes, mathématiques, planification | Latence et coût souvent plus élevés |
| Modèle visuel | Compréhension d'images, questions sur captures | Vérifier le support des images par la passerelle |
| Modèle d'embedding | Base de connaissances, recherche vectorielle | Interface et modèle à vérifier séparément |
Pour une base de connaissances, le modèle d'embedding doit aussi être disponible côté passerelle ; avec seulement un modèle de dialogue, le téléversement de documents échoue. Dans ce cas, vérifiez si la passerelle propose une interface d'embedding, puis décidez s'il faut configurer un fournisseur distinct.
5. Vérification et ordre de dépannage
Une fois la configuration terminée, créez une conversation, choisissez le modèle ajouté et envoyez « Réponds seulement OK ». En cas d'échec, suivez cet ordre avant de réinstaller le client :
| Symptôme | Cause fréquente | Traitement |
|---|---|---|
401 Unauthorized |
Clé erronée, expirée ou non enregistrée | Recoller la clé, vérifier les espaces |
404 Not Found |
/v1 incorrect dans l'URL de base |
Ajouter ou retirer /v1 selon la méthode ci-dessus |
model not found |
ID erroné ou modèle non ouvert | Copier l'identifiant exact depuis la page tarifs |
| Échec de récupération des modèles | Interface de liste non exposée | Ajouter l'ID manuellement |
| Flux interrompu en cours de réponse | Réseau instable ou timeout | Vérifier proxy, réduire la concurrence, réessayer |
| Erreur de base de connaissances | Modèle d'embedding non configuré | Configurer un modèle d'embedding disponible |
Un point souvent oublié : le réseau d'entreprise ou un logiciel proxy peut bloquer le flux SSE, avec pour symptôme « la requête part mais rien ne revient ». Désactivez temporairement le streaming ; si le mode non-streaming fonctionne, concentrez le diagnostic sur le proxy et le pare-feu.
6. Plusieurs modèles au quotidien
L'intérêt de Cherry Studio est de séparer les tâches. Une pratique utile :
- Un modèle généraliste rapide et économique pour les questions courantes.
- Un modèle à long contexte pour résumer de longs documents, dans un assistant dédié.
- Un modèle plus fort en code pour les tâches de développement.
- Un modèle d'embedding dédié à la base de connaissances.
- Un prompt système clair pour chaque assistant, afin de ne pas répéter le contexte.
Plus les modèles sont nombreux, plus il faut maîtriser la longueur de contexte. Répéter un document entier dans chaque conversation augmente le coût de chaque requête ; mettez d'abord les documents en base de connaissances, et utilisez des résumés quand c'est possible.
7. Sécurité et usage en équipe
- La clé est stockée localement ; sur un ordinateur partagé, pensez à l'isolation des comptes système.
- Ne conservez pas de clé de longue durée sur un appareil partagé.
- Émettez des clés par projet, pour suivre l'usage et révoquer côté passerelle.
- Ne collez pas de données clients confidentielles, de contrats ou de données non pseudonymisées dans le client.
- Surveillez régulièrement l'usage de la passerelle ; en cas de hausse anormale, suspendez la clé avant d'enquêter.
Questions fréquentes
Cherry Studio est-il gratuit ?
Le client peut être utilisé gratuitement, mais les appels de modèles sont facturés par le fournisseur API configuré. La référence reste la version actuelle du client et la page tarifs de la passerelle.
Pourquoi un 401 malgré une clé renseignée ?
Vérifiez d'abord les espaces superflus, puis que la clé appartient bien à la plateforme correspondant à l'URL de base. Les clés de passerelles différentes ne sont pas interchangeables ; vérifiez aussi qu'elle n'a pas été supprimée ou que le quota n'est pas épuisé.
L'URL de base doit-elle contenir /v1 ?
Suivez l'indication de votre version. La plupart des configurations compatibles OpenAI exigent /v1, mais certains clients l'ajoutent. Le critère est que la requête atteigne /v1/chat/completions ; en cas de 404, ajustez la fin de l'adresse.
Peut-on utiliser des modèles Claude ou Gemini ?
Oui, si la passerelle les expose au format compatible OpenAI et si vous saisissez l'ID exact. Pour les modèles au protocole natif différent, certains paramètres peuvent être incompatibles ; la documentation du site fait foi.
Peut-on travailler hors ligne après configuration ?
Non. Le client n'est qu'une interface ; l'inférence a lieu dans l'API distante. Sans réseau ou si la passerelle est injoignable, la conversation ne peut pas aboutir.
Pour aller plus loin
La configuration de Cherry Studio est simple ; la difficulté est d'aligner URL de base, clé et ID de modèle. Validez d'abord avec curl, puis ouvrez le client ; en cas de problème, suivez l'ordre 401, 404, model not found. Pour une entrée de modèles et une gestion d'usage unifiées, vous pouvez créer un compte ZSQH AI Gateway ; modèles et prix sont sur la page Tarifs des modèles.
Lectures associées :
