LobeChat réunit plusieurs fournisseurs de modèles, des plugins et une base de connaissances dans une seule interface. Les options sont nombreuses et les erreurs facilement mal interprétées. La plupart des problèmes ne viennent pas du modèle, mais de l'une de quatre couches : une clé inactive, une adresse ou un nom de modèle incorrect, un quota ou une concurrence atteints, ou un problème réseau ou CORS. Classer puis vérifier couche par couche est plus efficace que réinstaller le client.

Cet article traite des 401, 404, 429 et échecs de connexion, puis du streaming, des plugins et de la base de connaissances. Les noms d'interface et de variables dépendent de la version : référez-vous à la documentation actuelle. Les modèles et les prix figurent sur la page Tarifs des modèles et peuvent évoluer.

Remarque : LobeChat et LobeHub sont des produits et marques de leurs détenteurs. Cet article est une aide technique au diagnostic et n'implique aucune affiliation avec les éditeurs concernés.

1. Consigner les preuves avant de classer

Symptôme Code ou message courant Première hypothèse À vérifier
401 Unauthorized invalid_api_key, réponse vide Clé non reconnue Intégrité de la clé, adresse associée, mode d'injection
404 / model not found not_found_error, model_not_found Chemin ou nom de modèle incorrect Base URL, /v1, ID de modèle
429 Too Many Requests rate_limit_error, insufficient_quota Débit limité ou quota insuffisant Concurrence, usage, facturation
Failed to fetch Aucun code, erreur navigateur Requête sans réponse DNS, proxy, pare-feu, CORS
5xx server_error, page d'erreur de passerelle Panne amont ou passerelle Réessayer et noter l'ID de requête
Plugin ou base de connaissances Erreur d'outil, échec de téléversement Capacité ou dépendance manquante Appels de fonctions, stockage, Embedding

Avant tout diagnostic, notez au minimum : heure, version, mode de déploiement (bureau, web ou Docker), code HTTP, corps de réponse et ID de requête. Sans ces éléments, on ne peut que deviner.

2. 401 : la clé n'est pas reconnue

Une 401 signifie que le serveur refuse la clé. Causes fréquentes :

  • des espaces, retours à la ligne ou caractères pleine chasse collés avec la clé, visuellement identiques mais différents ;
  • un mélange entre la configuration de l'interface et les variables d'environnement du déploiement, la requête réelle n'utilisant pas la clé attendue ;
  • une clé supprimée, renouvelée, ou un projet désactivé ;
  • une clé du fournisseur A envoyée à l'adresse du fournisseur B ;
  • une requête interceptée par le proxy de l'entreprise, qui renvoie une page HTML de connexion au lieu de JSON.

Contournez d'abord le client : même clé, même adresse, 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-modele","messages":[{"role":"user","content":"Reponds seulement OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Un code 200 avec choices confirme la clé et l'adresse ; une 401 persistante indique un problème de copie, de permission ou de proxy. En Docker, vérifiez que la variable est bien dans le conteneur : docker exec lobe-chat env | grep -i openai, le nom du conteneur étant donné par docker ps. La configuration d'interface appartient à l'utilisateur courant et peut disparaître après un changement d'appareil ou un nettoyage du cache ; en équipe, préférez les variables d'environnement.

3. 404 et model not found : vérifier l'adresse et le modèle

Il existe deux 404 : chemin inexistant et modèle inexistant. La première se vérifie dans l'URL, la seconde dans l'ID de modèle.

Le champ d'adresse proxy de LobeChat se remplit parfois avec le domaine seul, parfois avec /v1, selon que la passerelle transfère elle-même /v1. Le critère est que /v1 n'apparaisse qu'une fois dans l'adresse finale. Erreur fréquente : l'hôte se termine déjà par /v1 et le chemin l'ajoute encore, donnant /v1/v1/chat/completions. L'adresse proxy doit pointer vers la racine de l'API, pas vers /chat/completions complet.

model not found est indépendant du chemin. L'ID de modèle distingue la casse, le suffixe de version et le préfixe du fournisseur ; copiez-le depuis la page Tarifs des modèles ou la console. Si vous gérez la liste avec CUSTOM_MODELS, testez d'abord -all,+un-modele-confirme, puis ajoutez les autres modèles ; utilisez des virgules ASCII sans espaces. Un modèle présent dans la liste doit aussi avoir un type et des capacités conformes à la réalité, sinon l'appel échoue.

Une 403 signifie généralement que la clé est reconnue mais n'a pas le droit d'utiliser ce modèle ou cette fonction : ne la confondez pas avec une 401 et ne changez pas de clé au hasard.

4. CORS, proxy et TLS : les pièges du navigateur

La version web de LobeChat émet des requêtes depuis le navigateur : la passerelle doit accepter l'origine correspondante. Un échec CORS se manifeste par Access to fetch ... has been blocked by CORS policy dans la console, alors que curl fonctionne parfaitement. Deux solutions : accepter l'origine côté passerelle, ou passer par un transfert serveur pour éviter le contrôle CORS du navigateur.

Derrière Nginx, Caddy ou Cloudflare, la couche proxy doit pouvoir joindre la passerelle ; ne confondez pas l'hôte de l'API et le proxy HTTP. Le proxy système, le VPN, les variables HTTP_PROXY et HTTPS_PROXY du conteneur peuvent se superposer : n'en gardez qu'une couche et excluez les adresses internes via NO_PROXY.

Les problèmes TLS se traduisent souvent par UNABLE_TO_VERIFY_LEAF_SIGNATURE, fréquent avec un proxy d'inspection d'entreprise. La bonne pratique est d'installer le certificat racine de l'entreprise ; mettre NODE_TLS_REJECT_UNAUTHORIZED à 0 ne sert qu'au diagnostic temporaire et réduit la sécurité.

Le service de plugins doit aussi accepter l'origine de LobeHub. En auto-hébergement, vérifiez que la fonction plugins est activée et que le modèle prend en charge les appels de fonctions, sinon les plugins échouent à l'exécution.

5. 429 : débit, concurrence et quota

Une 429 a deux sens courants : requêtes trop rapides, ou quota insuffisant. Le premier s'accompagne souvent de rate_limit_error, le second de insufficient_quota ; la marche à suivre est opposée.

  • Requêtes trop rapides : réduisez la concurrence et le nombre de sessions ou de clients simultanés ; un contexte long amplifie la consommation de tokens.
  • Quota insuffisant : consultez l'usage et la facturation de la passerelle, rechargez ou changez de clé ; réessayer ne résout rien.
  • Si l'en-tête Retry-After est présent, attendez la durée indiquée ; sinon, utilisez un backoff exponentiel avec jitter et fixez un nombre maximal de tentatives.
  • Avec une clé partagée en équipe, plusieurs appareils et fenêtres consomment le même quota de concurrence.

Si la 429 n'apparaît que dans les longues conversations, compressez d'abord le contexte ou créez une nouvelle session, puis vérifiez la fenêtre de contexte du modèle. Réduire le « nombre maximal de messages de contexte » soulage la pression mais ne remplace pas une gestion de l'usage.

6. Streaming interrompu : la réponse s'arrête à mi-chemin

LobeChat utilise le streaming par défaut. Un arrêt en cours de route ne signifie pas que le modèle est cassé : le flux SSE est souvent tamponné par un proxy, la connexion expire par inactivité, ou l'amont se déconnecte pendant la génération. Symptômes : début normal puis fin brutale, ou blocage sur « en train de saisir ».

Désactivez le streaming si la version le permet et reposez la même question. Si la réponse non streamée est complète, le problème vient du SSE. Le reverse proxy doit désactiver le buffering des réponses et allonger le délai de lecture, par exemple proxy_buffering off et proxy_read_timeout sous Nginx ; les CDN comme Cloudflare peuvent aussi tamponner les flux d'événements. Les modèles de raisonnement « réfléchissent » longtemps avant le texte, ce qui ressemble à un blocage : vérifiez d'abord en non streamé.

7. Erreurs spécifiques aux plugins et à la base de connaissances

Un échec de plugin se répartit en trois couches : le modèle prend-il en charge les appels de fonctions, la passerelle du plugin est-elle joignable, le service accepte-t-il le CORS ? En auto-hébergement, confirmez que la fonction plugins est activée. Un modèle sans appels d'outils peut afficher le plugin dans l'interface mais échouer à l'exécution.

La base de connaissances dépend d'un autre ensemble : PostgreSQL avec PGVector pour les vecteurs, un stockage compatible S3 pour les fichiers, et un modèle Embedding disponible. Le modèle d'embedding par défaut est souvent un modèle OpenAI, que votre passerelle ne propose pas forcément : configurez-le séparément, en suivant la documentation pour les noms de variables et les formats.

En cas d'échec de téléversement, vérifiez l'adresse du bucket, les clés, les permissions et le CORS ; en cas d'échec de recherche, l'existence de l'index et la cohérence des dimensions d'Embedding. Changer de modèle d'embedding impose généralement de reconstruire l'ancien index. Le parsing PDF et Word peut dépendre de services supplémentaires : si le texte brut passe mais pas les formats complexes, cherchez de ce côté.

8. Journaux et collecte de preuves

  1. Ouvrez le panneau Network des outils de développement, trouvez la requête en échec et notez URL, code, corps et en-têtes ; supprimez la clé avant de partager.
  2. Utilisez docker logs -f lobe-chat pour les erreurs de démarrage, les migrations et les délais de connexion.
  3. Utilisez docker exec lobe-chat env pour confirmer la présence des variables, en surveillant orthographe et guillemets.
  4. Lancez curl ou nslookup dans le conteneur pour distinguer réseau du conteneur, DNS et passerelle externe.
  5. Pour des journaux détaillés, démarrez avec DEBUG=lobe:* et LOG_LEVEL=debug.
  6. Lors d'un signalement, joignez version, mode de déploiement, heure, code HTTP et ID de requête : « ça ne se connecte pas » ne permet aucun diagnostic.

9. Une procédure de diagnostic fixe

  1. Appelez directement la passerelle avec curl pour valider clé, hôte et modèle.
  2. Si curl échoue : vérifiez DNS, proxy, TLS, pare-feu et état de la passerelle.
  3. Si curl réussit mais LobeChat échoue : vérifiez le type d'API, un éventuel doublon /v1, l'ID de modèle, le CORS et le proxy client.
  4. Répartissez selon le code : 401 pour la clé, 404 pour le chemin et le modèle, 429 pour l'usage et la concurrence, échec de connexion pour le réseau et les certificats.
  5. Ne changez qu'une variable à la fois, retestez immédiatement et notez le résultat.

Cette procédure sépare les problèmes client des problèmes serveur. La plupart des erreurs dites « de LobeChat » se ramènent à une configuration ou à une couche réseau. Pour gérer clés, usage et point d'entrée des modèles au même endroit, vous pouvez créer un compte sur la passerelle AI de ZSQH ; les modèles disponibles et la facturation figurent sur la page Tarifs des modèles.

FAQ

LobeChat affiche Failed to fetch : est-ce une erreur de clé ?

Pas forcément. Ce message indique seulement que le navigateur n'a pas reçu de réponse valide. Testez la même adresse avec curl ; si curl échoue aussi, vérifiez DNS, proxy, pare-feu et certificats ; s'il réussit, examinez CORS, composition du chemin et proxy client.

Pourquoi curl fonctionne-t-il alors que LobeChat renvoie 401 ou une réponse vide ?

Causes courantes : clé de l'interface différente de la variable d'environnement, espaces lors du copier-coller, /v1 manquant ou en trop dans l'adresse proxy, ou blocage CORS du navigateur. Comparez une à une l'adresse finale et les en-têtes.

Un modèle ajouté à CUSTOM_MODELS n'apparaît toujours pas.

Vérifiez que le nom de variable correspond à la version, que les virgules sont ASCII sans espaces et que le conteneur a été recréé, pas seulement redémarré. Testez d'abord -all,+un-modele-confirme, puis ajoutez les autres.

Une 429 finit-elle par se rétablir si l'on réessaie ?

Une 429 de débit peut se résorber après backoff et réduction de la concurrence ; une 429 de quota ne se rétablit pas en réessayant : consultez la facturation, l'usage ou changez de clé. Lisez le type d'erreur dans le corps avant de décider.

L'échec de téléversement dans la base de connaissances est-il lié à l'API de chat ?

En général non. Le chat passe par l'interface de conversation, tandis que la base de connaissances dépend aussi de la base de données, de l'extension vectorielle, du stockage objet et du modèle Embedding. Vérifiez ces éléments avant le format des fichiers et le service de parsing.

Lectures associées :