Cherry Studio : API personnalisée, modèles et base de connaissances (2026)

Cherry Studio est un client IA de bureau courant, disponible sous Windows, macOS et Linux. Il ne fournit pas de modèles : ceux-ci viennent du fournisseur d'API que vous configurez. Outre les fournisseurs intégrés, il accepte des points d'entrée personnalisés compatibles OpenAI, ce qui est pratique pour les équipes utilisant une passerelle unifiée : une URL de base et une clé suffisent pour basculer entre plusieurs fournisseurs de modèles.

Cet article suit les versions courantes de 2026, de l'installation aux fournisseurs, modèles, assistants, base de connaissances et usage d'équipe. Les noms d'interface évoluent avec les versions ; la version actuelle fait foi.

Remarque : Cherry Studio est un produit et une marque de son détenteur ; OpenAI est une marque d'OpenAI, Inc. Cet article est purement technique, sans affiliation ni coopération avec ces sociétés. Modèles, périmètre d'interface et tarifs sont indiqués sur la page tarifs des modèles du site.

1. Installation : privilégier les canaux de l'éditeur

Cherry Studio propose des installeurs de bureau, généralement téléchargeables depuis le site du projet et ses GitHub Releases. Choisissez le paquet correspondant au système :

Windows : téléchargez l'installeur et suivez les indications.
macOS : téléchargez le dmg et glissez l'application dans le dossier Applications ; si le système bloque la première ouverture, validez son lancement selon les indications.
Linux : installez l'AppImage ou le paquet de distribution fourni par le projet.

Évitez les « versions portables » ou paquets modifiés d'origine inconnue : un client de bureau stocke les clés API et l'historique de chat, et un installeur non maîtrisé présente un risque élevé. Après installation, ouvrez « À propos » dans les paramètres pour vérifier la version avant de décider d'une mise à jour ; les anciennes versions peuvent avoir des libellés et emplacements de champs différents.

2. Préparer trois paramètres

Un fournisseur personnalisé ne demande que trois éléments, mais chacun est facile à mal remplir :

Paramètre	Valeur conseillée	Explication
Type de fournisseur	OpenAI	Utilise le protocole compatible OpenAI
Adresse API	`https://ai.zhongshangqihang.com/v1`	Jusqu'à `/v1`, pas le chemin complet de l'interface
Clé API	`sk-...`	Créée dans la console de la passerelle, nommée par projet
Identifiant de modèle	L'identifiant API de la page de tarifs	Pas le nom affiché sur le site

Créez la clé dans la console après l'inscription à ZSQH AI Gateway. Préférez une clé par projet, pour suivre l'usage, les quotas et la révocation. Copiez l'identifiant de modèle depuis la page tarifs des modèles, en respectant casse, tirets et suffixe de version.

3. Ajouter un fournisseur personnalisé

Pour une version courante, la séquence est la suivante :

Ouvrez Cherry Studio et cliquez sur l'icône d'engrenage en bas à gauche pour accéder aux paramètres.
Sélectionnez « Services de modèles ».
Cliquez sur « + Ajouter un fournisseur » sous la liste des fournisseurs.
Dans « Ajouter un fournisseur personnalisé », saisissez le nom, par exemple « Passerelle ZSQH ».
Renseignez la « Clé API ».
Dans « Paramètres du point d'entrée », choisissez OpenAI ; si la passerelle propose le protocole Responses, vous pouvez aussi choisir OpenAI Responses dans « Plus de paramètres ».
Saisissez l'adresse API, par exemple https://ai.zhongshangqihang.com/v1.
Cliquez sur « Ajouter » pour enregistrer.

Si votre version n'a pas « + Ajouter un fournisseur », mettez d'abord le client à jour. Les libellés des types de point d'entrée varient, mais les champs essentiels restent : nom, clé, adresse. La génération et l'édition d'images ont des options d'URL de base distinctes ; ne les mélangez pas avec l'adresse des modèles de dialogue.

4. Ajouter des modèles et vérifier la connectivité

Après avoir enregistré le fournisseur, revenez à sa liste de modèles ; deux méthodes existent :

Récupérer la liste des modèles : le client interroge la passerelle et vous cochez les modèles voulus.
Ajouter manuellement : cliquez sur « + » et saisissez l'identifiant. À utiliser si la passerelle n'expose pas d'interface de liste ou si la récupération échoue.

L'identifiant doit correspondre exactement à la page de tarifs. Après un ajout manuel, vérifiez que le type est « Dialogue » ou « Chat » ; un mauvais type empêche le modèle d'apparaître dans le sélecteur de conversation. Les modèles d'embedding et d'image s'ajoutent séparément selon leur usage.

Le bouton « Vérifier » de l'interface contrôle surtout que la clé API fonctionne ; il ne confirme pas que chaque modèle vous est ouvert. Après sauvegarde, créez une conversation, sélectionnez le modèle ajouté et envoyez « Réponds uniquement OK » : c'est la vérification complète.

5. Valider avec curl avant de revenir au client

En cas de blocage, une requête minimale permet de distinguer un problème de passerelle d'un problème de client :

export ZSQH_API_KEY="sk-votre-cle"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "votre-modele",
    "messages": [{"role": "user", "content": "Réponds uniquement OK"}]
  }'

Si la réponse contient choices, l'adresse, la clé et le modèle fonctionnent au moins de bout en bout ; le problème vient probablement d'un champ du client ou d'un proxy réseau. Un 401 oriente vers la clé et les espaces, un 404 vers /v1 et l'identifiant de modèle, un 429 vers l'usage et la concurrence. Ne modifiez qu'une variable à la fois, pour ne pas changer simultanément clé, adresse et modèle.

6. Assistants : affecter les modèles aux tâches

Les « assistants » de Cherry Studio mémorisent prompt système, modèle et paramètres, ce qui convient pour figer les tâches répétitives. Une répartition utile :

Questions quotidiennes : un modèle généraliste rapide et au coût maîtrisé.
Résumé de documents longs : un assistant dédié avec un modèle à contexte long, et une structure de sortie imposée dans le prompt.
Tâches de code : un modèle plus fort en programmation, avec l'exigence de lire les fichiers avant de modifier.
Traduction et réécriture : un assistant chacune, avec glossaire et exigences de style dans le prompt système.
Un assistant par type de problème, pour éviter un prompt qui grossit sans fin.

Vous pouvez aussi définir un modèle par défaut dans les paramètres, pour réduire le choix à chaque nouvelle conversation. Plus les modèles sont nombreux, plus il faut contrôler le contexte : les documents destinés à la base de connaissances y entrent d'abord, et ce qui peut être résumé ne doit pas être recollé en entier à chaque fois.

7. Base de connaissances : l'embedding n'est pas obligatoire

La base de connaissances s'ouvre via « Base de connaissances » à gauche ; cliquez sur « Nouveau », donnez un nom qui délimite le contenu, puis choisissez un modèle d'embedding. La version actuelle propose trois modes :

Aucun : recherche par mots-clés BM25 uniquement, sans configuration supplémentaire ; adapté à une première validation du flux.
Embedding cloud : nécessite un service d'embedding appelable ; la recherche combine mots-clés et vecteurs.
Embedding local : téléchargez d'abord le modèle dans « Paramètres → Modèles locaux », puis sélectionnez-le dans la base.

Si l'embedding passe par la passerelle, vérifiez qu'elle expose une interface et un modèle adaptés ; sinon, choisissez « Aucun » ou l'embedding local. Après création, cliquez sur « Ajouter des documents », importez d'abord un ou deux fichiers aux réponses explicites, puis testez les questions une fois le traitement terminé.

Changer de modèle d'embedding peut déclencher une « reconstruction de la base ». Avant de reconstruire, vérifiez que le nouveau modèle fonctionne et ne changez pas simultanément le modèle et le découpage, sinon l'origine de la variation de qualité devient indéterminable.

8. Ordre de diagnostic des pannes courantes

Symptôme	Cause fréquente	Traitement
`401 Unauthorized`	Clé erronée, espace ou non enregistrée	Recoller la clé, vérifier qu'elle appartient à la passerelle courante
`404 Not Found`	`/v1` en trop ou manquant dans l'adresse	Ne garder que jusqu'à `/v1`, sans chemin complet
`model not found`	Identifiant erroné ou modèle non ouvert	Copier l'identifiant exact depuis la page de tarifs
Échec de récupération des modèles	Interface de liste non exposée	Ajouter manuellement l'identifiant
Base de connaissances peu pertinente	Découpage, mode de recherche ou qualité des documents	Tester sur un petit corpus, puis ajuster le découpage
Flux interrompu en conversation	Proxy, pare-feu ou réseau instable	Désactiver le streaming pour tester, vérifier proxy et délais

Le réseau d'entreprise ou un logiciel proxy peut bloquer les réponses SSE, avec pour symptôme « la requête part mais rien ne revient ». Désactivez temporairement le streaming : si le mode non streaming fonctionne, examinez le proxy et le pare-feu plutôt que de changer de modèle en boucle.

9. Usage d'équipe : partager des conventions, pas des clés

Cherry Studio est un client de bureau ; sa documentation publique ne présente pas la gestion multi-utilisateur comme une capacité centrale. L'usage d'équipe ressemble donc à « conventions de configuration unifiées + clients locaux ». Recommandations :

Chaque personne utilise sa propre clé de passerelle, nommée par personne ; révocation individuelle en cas de départ ou de fuite.
Suivre usage et quotas côté passerelle, ventiler les coûts par projet.
Rassembler les prompts système des assistants courants dans un modèle texte distribué à tous.
Placer les documents de la base de connaissances dans un emplacement partagé contrôlé par l'équipe, pour éviter des versions divergentes.
Sauvegarder sur WebDAV ou un stockage compatible S3, en sachant que la sauvegarde contient la configuration des fournisseurs et les clés API.
Ne pas envoyer les fichiers de sauvegarde dans un groupe, ni les déposer sur un cloud non fiable.
Ne pas conserver de clé longue durée sur un ordinateur public, ni coller des données clients ou des contrats non anonymisés dans une conversation.

Si l'équipe a besoin d'audit, de quotas et de permissions unifiés, l'effort doit porter sur la passerelle.

Questions fréquentes

Cherry Studio est-il gratuit ?

Le client lui-même est utilisable gratuitement, mais les appels de modèles sont facturés par le fournisseur d'API que vous configurez. La version actuelle du client et la page de tarifs de la passerelle font foi.

L'URL de base doit-elle inclure `/v1` ?

La plupart des configurations compatibles OpenAI l'exigent ; renseignez https://ai.zhongshangqihang.com/v1. N'indiquez pas /v1/chat/completions, le client ajoute lui-même le chemin de l'interface.

Que faire si la récupération de la liste des modèles échoue ?

Vérifiez d'abord si la passerelle expose une interface de liste. Si elle ne l'expose pas ou si la requête échoue, cliquez sur « + » et saisissez l'identifiant manuellement ; le résultat est identique. L'identifiant API de la page de tarifs fait foi.

Faut-il forcément un modèle d'embedding pour la base de connaissances ?

Non. La version actuelle permet « Aucun » et une recherche par mots-clés BM25 pour les questions de base. Configurez un embedding cloud ou local seulement si la recherche vectorielle est nécessaire, en vérifiant que le service est appelable.

Une équipe peut-elle partager une clé ?

Ce n'est pas conseillé. Une clé commune ne permet pas de distinguer les usages, et une fuite affecte toute l'équipe. Distribuez des clés par personne, projet ou environnement, avec quotas et rapports d'usage côté passerelle.

Pour aller plus loin

L'intégration de Cherry Studio n'est pas complexe ; la difficulté est d'aligner URL de base, clé et identifiant de modèle. Validez d'abord avec curl, puis passez au client ; en cas de problème, suivez l'ordre 401, 404, model not found. Pour un point d'entrée modèle et une gestion d'usage unifiés, vous pouvez créer un compte ZSQH AI Gateway ; modèles et tarifs sont indiqués sur la page tarifs des modèles.

Lectures associées :