Niestandardowa konfiguracja

Utwórz, zamontuj i skonfiguruj plik librechat.yaml dla niestandardowych endpoint AI oraz zaawansowanych ustawień LibreChat

Czym jest librechat.yaml?

Plik librechat.yaml to główny plik konfiguracyjny LibreChat, służący do obsługi niestandardowych endpoint, ustawień modeli, opcji interfejsu oraz zaawansowanych funkcji, takich jak serwery MCP i agenci. Jest on opcjonalny — LibreChat działa w oparciu o rozsądne ustawienia domyślne, jeśli plik ten nie istnieje.

Wykonaj poniższe kroki, aby utworzyć plik, zamontować go dla swojego typu wdrożenia i zweryfikować jego działanie.

Jeśli masz zapamiętać tylko jedną rzecz

W przypadku instalacji Docker, edycja librechat.yaml nie wystarczy. Plik musi znajdować się w katalogu głównym projektu, być zamontowany w kontenerze API, a LibreChat musi zostać zrestartowany, aby zmiany pojawiły się w interfejsie użytkownika.

Wolisz interfejs użytkownika? Użyj Panelu Administratora

Panel administratora LibreChat zarządza tą samą konfiguracją z poziomu przeglądarki — w tym nadpisaniami dla poszczególnych ról i grup, które wchodzą w życie przy logowaniu bez konieczności restartowania LibreChat. Jest on dostarczany wraz z oficjalnymi stosami Docker Compose. Używaj librechat.yaml do konfiguracji opartej na plikach lub początkowej konfiguracji (bootstrap), a panelu administratora do bieżącego zarządzania.

Konfiguracja

Znajdź lub utwórz plik

Utwórz nowy plik librechat.yaml w katalogu głównym projektu (w tym samym katalogu, co plik .env):

touch librechat.yaml

Możesz również skopiować przykładową konfigurację jako punkt wyjścia:

cp librechat.example.yaml librechat.yaml

Alternatywna ścieżka pliku

Możesz ustawić niestandardową ścieżkę pliku, używając zmiennej środowiskowej CONFIG_PATH:

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

Zamontuj plik konfiguracyjny

Docker wymaga zamontowania wolumenu, aby uzyskać dostęp do pliku librechat.yaml wewnątrz kontenera.

Skopiuj przykładowy plik nadpisujący:

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

Edytuj docker-compose.override.yml i upewnij się, że montowanie wolumenu librechat.yaml jest odkomentowane:

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

Wykorzystuje to wzorzec docker-compose.override.yml — Docker Compose automatycznie scala go z głównym plikiem docker-compose.yml, dzięki czemu Twoje dostosowania przetrwają aktualizacje.

Umieść librechat.yaml w głównym katalogu projektu (tym samym, w którym znajduje się plik .env). W przypadku instalacji lokalnych nie jest wymagane dodatkowe montowanie.

Restart LibreChat

docker compose down && docker compose up -d

Zatrzymaj uruchomiony proces (Ctrl+C) i uruchom ponownie:

npm run backend

Sprawdź, czy działa

Otwórz LibreChat w swojej przeglądarce. Jeśli Twoja konfiguracja zawiera niestandardowe endpoint, powinieneś zobaczyć je na liście rozwijanej wyboru modelu.

Jeśli serwer nie uruchamia się, sprawdź logi pod kątem błędów walidacji:

docker compose logs api

Przykład: Dodawanie OpenRouter

Ten przykład przeprowadzi Cię przez proces dodawania OpenRouter jako niestandardowego endpoint, co jest jedną z najpopularniejszych konfiguracji.

1. Uzyskaj klucz API z openrouter.ai/keys.

2. Dodaj klucz do swojego pliku .env:

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

Nazwa zmiennej środowiskowej

Użyj OPENROUTER_KEY, a nie OPENROUTER_API_KEY. Użycie OPENROUTER_API_KEY spowoduje nadpisanie endpointu OpenAI, co również wymusi użycie OpenRouter.

3. Dodaj endpoint do 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. Zrestartuj LibreChat (zobacz polecenia restartu powyżej) i wybierz OpenRouter z selektora modeli.

Aby uzyskać pełny, opatrzony komentarzami plik konfiguracyjny z większą liczbą przykładów endpoint, zobacz przykładową konfigurację.

Referencje

Szczegółową dokumentację na poziomie pól można znaleźć na poniższych stronach referencyjnych.

Punkty końcowe AI

Kompatybilni dostawcy AI i przykładowe konfiguracje endpoint

→

Struktura obiektu

Pełna dokumentacja pól dla każdej opcji w librechat.yaml

→

Rozwiązywanie problemów

Zmiana nie jest widoczna w LibreChat

Jeśli edytowałeś librechat.yaml i w interfejsie użytkownika nic się nie zmieniło:

Upewnij się, że plik znajduje się w katalogu głównym projektu LibreChat, chyba że ustawiono CONFIG_PATH.
W przypadku Docker, upewnij się, że plik jest zamontowany w docker-compose.override.yml.
Zrestartuj LibreChat za pomocą docker compose down && docker compose up -d.
Sprawdź logi API za pomocą docker compose logs api.
Zweryfikuj plik za pomocą YAML Validator.

Niestandardowe endpointy, takie jak OpenRouter, pojawiają się dopiero po poprawnym skonfigurowaniu wszystkich trzech elementów: plik .env zawiera klucz, librechat.yaml definiuje endpoint, a Docker może odczytać zamontowany plik konfiguracyjny.

Walidacja konfiguracji

Weryfikacja konfiguracji

LibreChat kończy działanie z błędem (kod wyjścia 1), jeśli librechat.yaml zawiera błędy walidacji. To zachowanie typu „fail-fast” pozwala na wczesne wykrywanie problemów z konfiguracją.

Aby zweryfikować składnię YAML przed ponownym uruchomieniem, użyj YAML Validator lub yamlchecker.com.

Serwer wyłącza się natychmiast po uruchomieniu

Jeśli Twój serwer wyłącza się natychmiast po uruchomieniu, prawdopodobnie jest to błąd walidacji konfiguracji.

Aby zdiagnozować:

Sprawdź logi serwera: docker compose logs api
Zweryfikuj składnię YAML za pomocą YAML Validator
Typowe błędy: nieprawidłowe wcięcia, brakujące dwukropki, nieznane klucze, nieprawidłowe wartości

Tymczasowe obejście (niezalecane w środowisku produkcyjnym):

CONFIG_BYPASS_VALIDATION=true

Ostrzeżenie

CONFIG_BYPASS_VALIDATION=true powoduje, że serwer pomija walidację i używa domyślnej konfiguracji. Zawsze naprawiaj błędy walidacji zamiast tego.

Niestandardowa konfiguracja

Punkty końcowe AI

Struktura obiektu

Na tej stronie