LobeChat est une application de dialogue IA open source ; le projet et les images utilisent progressivement le nom LobeHub. Elle ne fournit pas de modèle : la qualité des réponses dépend du fournisseur d'API intégré. Pour une équipe qui utilise une passerelle unifiée, l'intérêt d'une API personnalisée est direct : une URL de base et une clé suffisent pour passer d'un modèle à l'autre, avec une consommation visible au même endroit.

Cet article suit les versions courantes de 2026 : déploiement, configuration du fournisseur, vérification de connectivité, puis assistants, plugins, base de connaissances et déploiement d'équipe. Interface et noms de variables évoluent ; comparez avec la documentation de votre version avant d'agir.

Remarque : LobeChat et LobeHub sont des produits et marques de leurs détenteurs respectifs, OpenAI est une marque d'OpenAI, Inc. Cet article est purement technique, sans affiliation ni coopération avec ces sociétés. Le périmètre des modèles et les prix sont indiqués sur la page tarifs des modèles.

1. Choisir d'abord le mode de déploiement

LobeChat peut tourner en local ou être déployé sur un serveur pour l'équipe. Les dépendances diffèrent :

Mode Cas adapté Dépendances principales Points d'attention
Conteneur unique d'essai Essai personnel, validation fonctionnelle Docker, PostgreSQL Mise en route rapide ; ajouter stockage et sauvegardes pour un usage durable
Docker Compose Usage d'équipe durable PostgreSQL, stockage compatible S3, Redis facultatif Méthode recommandée, fonctions complètes
Hébergement type Vercel Essai léger, peu d'exploitation PostgreSQL et S3 externes Le serverless impose des timeouts de fonction et ne prend pas WebSocket en charge

Les versions serveur de 2026 considèrent PostgreSQL comme obligatoire ; la base de connaissances nécessite pgvector et les extensions de recherche plein texte, et l'envoi de fichiers un stockage compatible S3. Les anciennes versions proposaient un mode purement navigateur ; les nouvelles privilégient le déploiement serveur. Vérifiez les dépendances de votre version avant de commencer. Pour une équipe, préparez directement l'option Compose afin d'éviter des reprises.

2. Préparer les trois paramètres

Quel que soit le mode de déploiement, l'intégration d'une API personnalisée ne demande que trois éléments :

  • URL de base : https://ai.zhongshangqihang.com/v1, le point d'entrée compatible OpenAI.
  • Clé API : créée dans la console après l'inscription à ZSQH AI Gateway, nommée par projet ou environnement.
  • Identifiant de modèle : l'identifiant API copié depuis la page tarifs des modèles, pas le nom affiché.

Les deux derniers sont les plus sujets à erreur : espace dans la clé collée, suffixe de version en trop ou casse incorrecte dans l'identifiant. Stockez d'abord la clé dans un gestionnaire de mots de passe, puis configurez.

3. Démarrer le service et écrire les variables d'environnement

Pour un déploiement d'équipe, placez la configuration dans un fichier de variables d'environnement, pas dans l'image ni dans le dépôt. Voici un exemple minimal ; remplacez base de données, stockage et secrets par vos valeurs :

# exemple lobehub.env, générez et conservez vous-même les secrets
APP_URL=https://chat.example.com
DATABASE_URL=postgres://postgres:change-me@postgres:5432/postgres
AUTH_SECRET=généré avec openssl rand -base64 32
KEY_VAULTS_SECRET=généré séparément de la même manière
OPENAI_API_KEY=sk-votre-cle-de-passerelle
OPENAI_PROXY_URL=https://ai.zhongshangqihang.com/v1
OPENAI_MODEL_LIST=-all,+votre-ID-de-modele

Montez ce fichier au démarrage du conteneur :

docker run -d --name lobehub -p 3210:3210 \
  --env-file lobehub.env lobehub/lobehub

Attendez dans les journaux la fin de migration de la base et Ready, puis ouvrez http://adresse-serveur:3210. Si les journaux restent sur un échec de connexion à la base, vérifiez le nom d'hôte, le port et le mot de passe de DATABASE_URL ; localhost dans un conteneur ne désigne pas l'hôte. Figez le tag de version avant de mettre à jour l'image et n'utilisez pas latest durablement.

4. Ajouter un fournisseur compatible OpenAI dans l'interface

Les variables d'environnement conviennent à une configuration unifiée ; l'interface convient aux essais personnels ou aux ajustements temporaires. Pour une version courante :

  1. Ouvrez les paramètres après connexion, puis « Fournisseurs IA ».
  2. Choisissez OpenAI ou ajoutez un fournisseur personnalisé, avec un nom explicite, par exemple « passerelle équipe ».
  3. Saisissez https://ai.zhongshangqihang.com/v1 comme adresse API, sans aller au-delà de /v1.
  4. Renseignez la clé de la passerelle en vérifiant l'absence d'espaces superflus.
  5. Ajoutez l'identifiant de modèle dans la liste et cochez selon ses capacités réelles : vision, appels d'outils, fichiers.
  6. Enregistrez, définissez le fournisseur par défaut ou sélectionnez le modèle manuellement dans la conversation.

Les fournisseurs personnalisés permettent de renseigner des étiquettes de capacités, souvent négligées. Une mauvaise étiquette ne provoque pas d'erreur immédiate, mais fait échouer plugins, compréhension d'images ou envoi de fichiers en cours d'exécution. En cas de doute, cochez moins et validez avec une tâche réelle avant de compléter.

5. Vérifier : curl d'abord, dialogue ensuite

Après la configuration, ne commencez pas à travailler directement : validez la chaîne avec une requête minimale.

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-ID-de-modele","messages":[{"role":"user","content":"Réponds seulement OK"}]}'

Si la réponse contient choices, l'adresse, la clé et le modèle communiquent au moins. Revenez ensuite dans LobeChat, créez une conversation, sélectionnez le même modèle et envoyez « Réponds seulement OK ». Une fois les deux étapes validées, configurez assistants et base de connaissances.

Les codes courants sont explicites : 401 oriente vers la clé et les espaces, 404 vers le chemin /v1, model not found vers l'identifiant de modèle et la page des tarifs, 429 vers l'usage et la concurrence de la passerelle. Ne modifiez qu'une variable à la fois, sinon vous ne saurez pas laquelle a agi.

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

Les assistants (appelés Agents dans les nouvelles versions) conservent prompt système, modèle et paramètres. La pratique utile est de répartir par tâche plutôt que d'empiler tous les modèles dans la liste par défaut :

  • Questions courantes : un modèle général rapide et maîtrisé en coût.
  • Résumés longs et revue de contrats : un assistant dédié avec modèle à contexte long, et une structure de sortie dans le prompt.
  • Tâches de code : un modèle stable en code, avec consigne d'expliquer les changements avant d'exécuter.
  • Traduction et relecture : un assistant chacun, avec glossaire et exigences de ton figés.

Chaque assistant ne traite qu'un type de problème ; plus le prompt est court, plus la maintenance est simple. L'équipe peut distribuer les prompts des assistants courants sous forme de modèles, sans jamais y placer de clé.

7. Plugins et base de connaissances : vérifier les dépendances

Les plugins dépendent de la capacité d'appel de fonctions du modèle. Si le modèle ne prend pas en charge les outils, le bouton du plugin peut rester cliquable mais l'appel échoue. Pour un marché de plugins auto-hébergé, configurez l'index et les clés requises ; n'installez que des plugins de source fiable et vérifiez ce qu'ils lisent.

La base de connaissances a plus de dépendances : PostgreSQL, pgvector, stockage compatible S3 et un modèle d'embedding. La version actuelle utilise par défaut un modèle d'embedding OpenAI, et d'autres modèles compatibles peuvent être désignés par variable d'environnement. Avec une passerelle, vérifiez qu'elle propose l'interface d'embedding et le modèle correspondant ; sinon la recherche sémantique ne fonctionnera pas.

Importez d'abord un ou deux fichiers aux réponses connues, testez la recherche avec des questions précises, puis chargez en masse. Taille des segments, format des fichiers et qualité des scans influencent le résultat : ne changez pas plusieurs réglages à la fois.

8. Déploiement d'équipe : configuration centralisée, clés réparties

Pour un usage d'équipe, respectez quelques limites :

  • Les variables serveur ne contiennent que la configuration partagée et les modèles par défaut ; les clés vont dans un gestionnaire de secrets, jamais dans Git.
  • Chaque membre utilise sa propre clé de passerelle, nommée par personne, révocable individuellement.
  • Base de données et S3 entrent dans le plan de sauvegarde ; les fichiers de sauvegarde sont traités comme des données sensibles.
  • Un déploiement public impose HTTPS et un contrôle d'accès au niveau du reverse proxy.
  • Pour le streaming, désactivez le buffering du proxy, sinon la réponse apparaît d'un bloc ou se bloque.
  • Fixez budget et plafond de concurrence côté passerelle et consultez régulièrement les rapports d'usage.

Pour une petite équipe interne, séparez les clés par projet côté passerelle et utilisez le système de comptes LobeChat pour distinguer les utilisateurs. Deux niveaux de journalisation facilitent diagnostic et facturation.

Questions fréquentes

Quel est le rapport entre LobeChat et LobeHub ?

LobeChat est le nom historique du projet ; en 2026, la documentation et les images des nouvelles versions utilisent la marque LobeHub. Les fonctions se poursuivent, mais variables d'environnement et entrées d'interface ont changé : la documentation actuelle fait foi pour le déploiement.

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

Oui. Saisissez https://ai.zhongshangqihang.com/v1, sans le chemin complet /chat/completions : le client ajoute le chemin. Certains proxies transmettent eux-mêmes /v1 ; le test réel tranche.

Pourquoi la liste de modèles reste-t-elle vide après configuration des variables ?

Vérifiez d'abord le nom et la syntaxe de OPENAI_MODEL_LIST : -all,+ID-modele, séparés par des virgules ASCII sans espaces. Après modification des variables, reconstruisez le conteneur ; un simple redémarrage ne recharge pas toujours les nouvelles valeurs.

Le téléversement dans la base de connaissances réussit mais la recherche ne trouve rien ?

Vérifiez dans l'ordre des dépendances : extension vectorielle installée dans la base, S3 accessible en écriture, modèle d'embedding appelable. Si l'un des trois manque, le fichier peut sembler téléversé mais l'index ne se construit pas.

Peut-on partager une clé dans l'équipe ?

Ce n'est pas recommandé. Une clé partagée ne permet pas de distinguer les usages et une fuite affecte tout le groupe. Émettez des clés par personne, projet ou environnement, avec quotas et journaux côté passerelle.

Pour aller plus loin

L'intégration de LobeChat se résume en trois étapes : choisir le bon déploiement, aligner URL de base, clé et identifiant de modèle, puis valider avec curl et une vraie conversation. Ensuite seulement, ajoutez assistants, plugins et base de connaissances : les problèmes seront moins nombreux. Pour un point d'entrée et une gestion d'usage unifiés, inscrivez-vous à ZSQH AI Gateway ; modèles et prix sont sur la page tarifs des modèles.

Lectures associées :