Configuration personnalisée

Créer, monter et configurer le fichier librechat.yaml pour les endpoints IA personnalisés et les paramètres avancés de LibreChat

Qu'est-ce que librechat.yaml ?

Le fichier librechat.yaml est le fichier de configuration principal de LibreChat pour les endpoints d'IA personnalisés, les paramètres de modèle, les options d'interface et les fonctionnalités avancées telles que les serveurs MCP et les agents. Il est facultatif -- LibreChat fonctionne avec des paramètres par défaut judicieux si le fichier n'existe pas.

Suivez les étapes ci-dessous pour créer le fichier, le monter pour votre type de déploiement et vérifier qu'il fonctionne.

Si vous ne devez retenir qu'une seule chose

Pour les installations Docker, modifier librechat.yaml ne suffit pas. Le fichier doit exister à la racine du projet, être monté dans le conteneur API, et LibreChat doit être redémarré avant que les modifications n'apparaissent dans l'interface utilisateur.

Vous préférez une interface utilisateur ? Utilisez le panneau d'administration

Le Panneau d'administration LibreChat gère cette même configuration depuis un navigateur, y compris les remplacements par rôle et par groupe qui prennent effet à la connexion sans redémarrer LibreChat. Il est fourni avec les stacks Docker Compose officielles. Utilisez librechat.yaml pour une configuration basée sur des fichiers ou un bootstrap, et le panneau d'administration pour une gestion continue.

Configuration

Localiser ou créer le fichier

Créez un nouveau librechat.yaml à la racine de votre projet (dans le même répertoire que votre fichier .env) :

touch librechat.yaml

Vous pouvez également copier la configuration exemple comme point de départ :

cp librechat.example.yaml librechat.yaml

Chemin de fichier alternatif

Vous pouvez définir un chemin de fichier personnalisé en utilisant la variable d'environnement CONFIG_PATH :

CONFIG_PATH="/alternative/path/to/librechat.yaml"

Monter le fichier de configuration

Docker a besoin d'un montage de volume pour accéder à votre fichier librechat.yaml à l'intérieur du conteneur.

Copiez l'exemple de fichier de remplacement :

cp docker-compose.override.yml.example docker-compose.override.yml

Modifiez docker-compose.override.yml et assurez-vous que le montage de volume librechat.yaml est décommenté :

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

Ceci utilise le modèle docker-compose.override.yml -- Docker Compose le fusionne automatiquement avec le docker-compose.yml principal, afin que vos personnalisations survivent aux mises à jour.

Placez librechat.yaml dans le répertoire racine du projet (le même répertoire que votre fichier .env). Aucun montage supplémentaire n'est nécessaire pour les installations locales.

Redémarrer LibreChat

docker compose down && docker compose up -d

Arrêtez le processus en cours (Ctrl+C) et redémarrez :

npm run backend

Vérifier que cela fonctionne

Ouvrez LibreChat dans votre navigateur. Si votre configuration inclut des endpoints personnalisés, vous devriez les voir dans le menu déroulant de sélection de modèle.

Si le serveur ne parvient pas à démarrer, vérifiez les journaux pour détecter d'éventuelles erreurs de validation :

docker compose logs api

Exemple : Ajout d'OpenRouter

Cet exemple explique comment ajouter OpenRouter en tant qu'endpoint personnalisé -- l'une des configurations les plus populaires.

1. Obtenez une clé API sur openrouter.ai/keys.

2. Ajoutez la clé à votre .env file :

OPENROUTER_KEY=sk-or-v1-your-key-here

Nom de la variable d'environnement

Utilisez OPENROUTER_KEY, et non OPENROUTER_API_KEY. L'utilisation de OPENROUTER_API_KEY remplacera également l'endpoint OpenAI pour utiliser OpenRouter.

3. Ajoutez l'endpoint à librechat.yaml :

version: 1.3.5
cache: true
endpoints:
  custom:
    - name: "OpenRouter"
      apiKey: "${OPENROUTER_KEY}"
      baseURL: "https://openrouter.ai/api/v1"
      models:
        default: ["meta-llama/llama-3-70b-instruct"]
        fetch: true
      titleConvo: true
      titleModel: "meta-llama/llama-3-70b-instruct"
      dropParams: ["stop"]
      modelDisplayLabel: "OpenRouter"

4. Redémarrez LibreChat (voir les commandes de redémarrage ci-dessus) et sélectionnez OpenRouter dans le sélecteur de modèle.

Pour le fichier de configuration annoté complet avec plus d'exemples d'endpoint, consultez la configuration exemple.

Référence

Pour une documentation détaillée au niveau des champs, consultez les pages de référence ci-dessous.

Endpoints IA

Fournisseurs d'IA compatibles et exemples de configurations d'endpoint

→

Structure de l'objet

Référence complète des champs pour chaque option de librechat.yaml

→

Dépannage

Les modifications ne s'affichent pas dans LibreChat

Si vous avez modifié librechat.yaml et que rien n'a changé dans l'interface utilisateur :

Assurez-vous que le fichier se trouve à la racine du projet LibreChat, sauf si vous avez défini CONFIG_PATH.
Pour Docker, confirmez que le fichier est monté dans docker-compose.override.yml.
Redémarrez LibreChat avec docker compose down && docker compose up -d.
Vérifiez les logs de l'API avec docker compose logs api.
Validez le fichier avec le YAML Validator.

Les endpoints personnalisés tels que OpenRouter n'apparaissent qu'une fois que les trois éléments suivants sont corrects : .env contient la clé, librechat.yaml définit l'endpoint, et Docker peut lire le fichier de configuration monté.

Validation de la configuration

LibreChat s'arrête avec une erreur (code de sortie 1) si librechat.yaml contient des erreurs de validation. Ce comportement de fail-fast permet de détecter les problèmes de configuration rapidement.

Pour valider votre syntaxe YAML avant de redémarrer, utilisez le YAML Validator ou yamlchecker.com.

Le serveur s'arrête immédiatement au démarrage

Si votre serveur s'arrête immédiatement après le démarrage, il s'agit probablement d'une erreur de validation de configuration.

Pour diagnostiquer :

Vérifiez les journaux du serveur : docker compose logs api
Validez votre syntaxe YAML avec le YAML Validator
Erreurs courantes : indentation incorrecte, deux-points manquants, clés inconnues, valeurs invalides

Solution de contournement temporaire (non recommandée pour la production) :

CONFIG_BYPASS_VALIDATION=true

Avertissement

CONFIG_BYPASS_VALIDATION=true force le serveur à ignorer la validation et à utiliser la configuration par défaut. Corrigez toujours les erreurs de validation à la place.

Configuration personnalisée

Endpoints IA

Structure de l'objet

Sur cette page