LobeChat est une application de conversation IA open source qui prend en charge plusieurs modèles, plusieurs assistants, des plugins et une base de connaissances. Elle peut être déployée en un clic dans le cloud ou exécutée sur votre propre serveur. Deux voies permettent de connecter une API personnalisée : renseigner le fournisseur dans l'interface, ou fixer la configuration au déploiement via des variables d'environnement. La première convient à un ordinateur personnel, la seconde aux équipes et aux usages durables.
Cet article prend comme référence les versions courantes d'octobre 2026 : préparation des paramètres, déploiement Docker, variables d'environnement, configuration dans l'interface et dépannage.
Remarque : LobeChat et LobeHub sont des produits de leurs détenteurs, OpenAI est une marque de son détenteur ; cet article est purement technique. Les noms de variables et les entrées d'interface peuvent évoluer selon les versions ; la documentation de votre version fait foi. Modèles et prix sont sur la page Tarifs des modèles.
1. Choisir entre trois modes d'intégration
| Mode | Cas d'usage | Emplacement | Avantages |
|---|---|---|---|
| Configuration dans l'interface | Usage personnel, essai rapide | Fournisseurs IA dans les réglages | Prise d'effet immédiate, sans redémarrage |
| Variables Docker | Serveur interne, usage d'équipe | docker run ou compose |
Versionnable, reproductible |
| Variables de plateforme cloud | Déploiement hébergé type Vercel | Réglages d'environnement du projet | Sans exploitation, adapté aux petites équipes |
Sur un ordinateur personnel, validez d'abord via l'interface, puis migrez vers Docker ; pour une équipe, utilisez directement les variables d'environnement et placez clé et adresse dans un gestionnaire de secrets, jamais dans le dépôt de code.
2. Préparer trois paramètres
- Clé API : créez-la dans ZSQH AI Gateway, avec un nom lié au projet ou à l'environnement.
- URL de base :
https://ai.zhongshangqihang.com/v1, l'entrée compatible OpenAI. - ID de modèle : copiez-le depuis la page Tarifs des modèles ; utilisez l'identifiant API, pas le nom d'affichage.
Validez d'abord avec curl, pour ne pas confondre un problème de passerelle avec un problème de configuration LobeChat :
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, les trois paramètres sont valides et vous pouvez passer au déploiement.
3. Déploiement Docker
Le plus simple est de lancer un conteneur à partir de l'image publiée par le projet, en passant la clé, l'adresse du proxy et la liste de modèles par variables d'environnement :
docker run -d --name lobechat \
-p 3210:3210 \
-e OPENAI_API_KEY="sk-votre-cle" \
-e OPENAI_PROXY_URL="https://ai.zhongshangqihang.com/v1" \
-e CUSTOM_MODELS="-all,+votre-id-modele" \
lobehub/lobe-chat
Accédez ensuite à http://adresse-serveur:3210. Signification des paramètres :
OPENAI_API_KEY: clé de la passerelle, injectée via variables d'environnement ou gestionnaire de secrets, jamais dans un fichier compose public.OPENAI_PROXY_URL: remplace l'adresse OpenAI par défaut et pointe vers votre passerelle compatible.CUSTOM_MODELS: contrôle la liste des modèles ;-allvide la liste par défaut,+id-modeleajoute un modèle.
Avec Docker Compose, placez les mêmes variables dans la section environment. Après modification, recréez le conteneur : un simple redémarrage ne recharge pas forcément les nouvelles variables.
4. Variables d'environnement et liste de modèles
| Variable | Obligatoire | Exemple | Description |
|---|---|---|---|
OPENAI_API_KEY |
Oui | sk-... |
Clé créée sur la passerelle |
OPENAI_PROXY_URL |
Oui | https://ai.zhongshangqihang.com/v1 |
Remplace l'URL de base par défaut |
CUSTOM_MODELS |
Recommandé | -all,+model-a,+model-b |
Contrôle les modèles visibles |
OPENAI_MODEL_LIST |
Selon version | +model-a |
Ancien nom possible selon les versions |
Syntaxe de CUSTOM_MODELS :
+id-modeleajoute un modèle,-id-modelele masque.-allvide d'abord la liste par défaut, pour éviter une série de modèles inutilisables.- Séparez par des virgules, sans espaces.
- Pour renommer, utilisez
id-modele=nom-affiche, sans modifier l'ID lui-même.
Les versions ne prennent pas toutes en charge les mêmes noms et la même syntaxe ; les anciennes peuvent utiliser OPENAI_MODEL_LIST. Si la liste disparaît après une mise à jour, consultez la documentation de la version actuelle plutôt que d'appliquer un ancien tutoriel.
5. Configurer dans l'interface
Si vous ne voulez pas toucher aux variables d'environnement, la configuration se fait dans l'interface. Avec les versions courantes :
- Ouvrez LobeChat et entrez dans les réglages.
- Trouvez « Fournisseurs IA » ou « Modèles de langage ».
- Choisissez OpenAI, saisissez la clé API et l'adresse du proxy.
- Ajoutez l'ID du modèle personnalisé dans la liste.
- Enregistrez, créez une conversation et testez ce modèle.
La configuration dans l'interface convient à un usage local. Sur un serveur, elle est liée à l'utilisateur du navigateur ; après un changement d'appareil ou un nettoyage du cache, il faut parfois la refaire. Pour un usage d'équipe, privilégiez les variables d'environnement.
6. Vérification et reverse proxy
Après le démarrage du conteneur, consultez les journaux pour détecter une erreur de variable :
docker logs -f lobechat
Envoyez ensuite un message de test dans l'interface. En déploiement public, ajoutez Nginx ou Caddy devant l'application, avec au minimum :
- HTTPS, pour ne pas transmettre la clé en clair.
- Un contrôle d'accès, pour ne pas exposer l'application à tous.
- Des délais et tampons adaptés ; le streaming nécessite de désactiver le buffering du proxy.
Pour le streaming avec Nginx, la configuration courante désactive proxy_buffering et allonge le délai de lecture. Sinon, la réponse arrive d'un bloc ou se bloque en cours de route.
7. Liste de contrôle pour la production
- Injecter la clé via gestionnaire de secrets ou variables d'environnement, jamais dans l'image.
- Émettre une clé dédiée à LobeChat, pour faciliter quotas et révocation.
- Configurer une base de données, sinon conversations et réglages peuvent rester en local.
- Activer HTTPS et contrôle d'accès ; ne pas exposer un déploiement public sans protection.
- Fixer budget et limite de concurrence côté passerelle, pour éviter les boucles anormales.
- Sauvegarder régulièrement la base et les fichiers téléversés.
- Lire le changelog avant mise à jour et épingler un tag d'image plutôt que
latest.
8. Erreurs courantes et traitement
| Symptôme | Cause fréquente | Traitement |
|---|---|---|
| Aucun modèle au démarrage | CUSTOM_MODELS non pris en compte |
Vérifier nom, virgules et recréation du conteneur |
401 Unauthorized |
Clé absente ou invalide | Vérifier la variable dans le conteneur, recréer la clé |
404 Not Found |
Chemin du proxy incorrect | Vérifier /v1, ajuster la fin de l'adresse |
model not found |
ID différent de la page tarifs | Copier l'identifiant exact |
| Réponse bloquée en cours | Buffering ou timeout du reverse proxy | Désactiver le buffering, allonger le délai |
| Échec de téléversement | Stockage ou capacité du modèle non configurés | Vérifier stockage et capacités |
| Base de connaissances indisponible | Modèle d'embedding non configuré | Configurer séparément un modèle d'embedding |
Pour diagnostiquer, distinguez d'abord « l'application ne lit pas la configuration » de « la passerelle refuse la requête ». La première se vérifie dans les variables et journaux du conteneur, la seconde dans le code HTTP. Les traitements sont différents.
Questions fréquentes
LobeChat est-il gratuit ?
LobeChat est un projet open source que vous pouvez auto-héberger ; les coûts d'appel des modèles sont facturés par le fournisseur API choisi. Les prix des services hébergés et des fonctions premium sont ceux de l'éditeur.
Faut-il forcément Docker ?
Non. Vous pouvez aussi l'exécuter avec Node.js ou le déployer sur une plateforme cloud compatible Next.js. Docker apporte un environnement homogène et des migrations simples, d'où son usage fréquent en équipe.
Quelle différence entre OPENAI_PROXY_URL et l'adresse de proxy dans l'interface ?
La variable d'environnement s'applique au déploiement et convient à une configuration d'équipe ; la configuration d'interface appartient à l'utilisateur courant et peut être à refaire après un changement d'appareil. Si les deux existent, la priorité dépend de la version.
Pourquoi des modèles inutilisables apparaissent-ils dans la liste ?
Souvent parce que -all n'a pas vidé la liste par défaut, ou parce que la syntaxe de CUSTOM_MODELS est erronée. Ne gardez d'abord qu'un modèle vérifié, puis ajoutez les autres.
Peut-on connecter Claude ou Gemini ?
Oui, à condition que la passerelle expose ces modèles au format compatible OpenAI et que l'ID soit correct. Les capacités au protocole natif différent, comme certains appels d'outils ou paramètres d'image, doivent être testées ; la documentation du site fait foi.
Pour aller plus loin
L'intégration de LobeChat se résume en deux étapes : vérifier la passerelle avec curl, puis aligner URL de base, clé et modèle via les variables d'environnement ou l'interface. Pour une équipe, privilégiez les variables ; pour un essai personnel, l'interface suffit. 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 :
