Configurazione personalizzata

Crea, monta e configura il file librechat.yaml per endpoint AI personalizzati e impostazioni avanzate di LibreChat

Cos'è librechat.yaml?

Il file librechat.yaml è il file di configurazione principale di LibreChat per endpoint AI personalizzati, impostazioni dei modelli, opzioni dell'interfaccia e funzionalità avanzate come server MCP e agenti. È facoltativo: LibreChat funziona con impostazioni predefinite sensate se il file non esiste.

Segui i passaggi seguenti per creare il file, montarlo per il tuo tipo di deployment e verificare che funzioni.

Se devi ricordare una sola cosa

Per le installazioni Docker, modificare librechat.yaml non è sufficiente. Il file deve esistere nella root del progetto, essere montato nel container dell'API e LibreChat deve essere riavviato affinché le modifiche appaiano nell'interfaccia utente.

Preferisci un'interfaccia utente? Usa il Pannello di amministrazione

Il Pannello di amministrazione di LibreChat gestisce questa stessa configurazione da un browser, incluse le sovrascritture per ruolo e per gruppo che diventano effettive al momento dell'accesso senza dover riavviare LibreChat. Viene fornito con gli stack ufficiali di Docker Compose. Utilizza librechat.yaml per la configurazione basata su file o di bootstrap, e il pannello di amministrazione per la gestione continua.

Setup

Individuare o creare il file

Crea un nuovo librechat.yaml nella root del tuo progetto (la stessa directory del tuo file .env):

touch librechat.yaml

Puoi anche copiare la configurazione di esempio come punto di partenza:

cp librechat.example.yaml librechat.yaml

Percorso file alternativo

È possibile impostare un percorso file personalizzato utilizzando la variabile d'ambiente CONFIG_PATH:

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

Montare il file di configurazione

Docker necessita di un volume mount per accedere al tuo file librechat.yaml all'interno del container.

Copia il file di override di esempio:

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

Modifica docker-compose.override.yml e assicurati che il mount del volume librechat.yaml sia decommentato:

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

Questo utilizza il pattern docker-compose.override.yml -- Docker Compose lo unisce automaticamente con il docker-compose.yml principale, così le tue personalizzazioni sopravvivono agli aggiornamenti.

Posiziona librechat.yaml nella directory principale del progetto (la stessa directory del tuo file .env). Non è necessario alcun montaggio aggiuntivo per le installazioni locali.

Riavviare LibreChat

docker compose down && docker compose up -d

Interrompi il processo in esecuzione (Ctrl+C) e riavvia:

npm run backend

Verifica il funzionamento

Apri LibreChat nel tuo browser. Se la tua configurazione include endpoint personalizzati, dovresti vederli nel menu a discesa del selettore del modello.

Se il server non si avvia, controlla i log per eventuali errori di validazione:

docker compose logs api

Esempio: Aggiunta di OpenRouter

Questo esempio illustra come aggiungere OpenRouter come endpoint personalizzato, una delle configurazioni più diffuse.

1. Ottieni una API key da openrouter.ai/keys.

2. Aggiungi la chiave al tuo file .env:

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

Nome della variabile d'ambiente

Usa OPENROUTER_KEY, non OPENROUTER_API_KEY. L'utilizzo di OPENROUTER_API_KEY sovrascriverà anche l'endpoint OpenAI per utilizzare OpenRouter.

3. Aggiungi l'endpoint a 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. Riavvia LibreChat (vedi i comandi di riavvio sopra) e seleziona OpenRouter dal selettore del modello.

Per il file di configurazione completo e annotato con ulteriori esempi di endpoint, consulta la configurazione di esempio.

Riferimento

Per una documentazione dettagliata a livello di campo, consulta le pagine di riferimento qui sotto.

Endpoint AI

Provider AI compatibili ed esempi di configurazioni di endpoint

→

Struttura dell'oggetto

Riferimento completo dei campi per ogni opzione di librechat.yaml

→

Risoluzione dei problemi

Le modifiche non vengono visualizzate in LibreChat

Se hai modificato librechat.yaml e non è cambiato nulla nell'interfaccia utente:

Conferma che il file si trovi nella root del progetto LibreChat, a meno che tu non abbia impostato CONFIG_PATH.
Per Docker, conferma che il file sia montato in docker-compose.override.yml.
Riavvia LibreChat con docker compose down && docker compose up -d.
Controlla i log dell'API con docker compose logs api.
Convalida il file con il YAML Validator.

Gli endpoint personalizzati come OpenRouter appaiono solo dopo che tutti e tre i componenti sono corretti: il file .env contiene la chiave, librechat.yaml definisce l'endpoint e Docker è in grado di leggere il file di configurazione montato.

Convalida della configurazione

LibreChat termina con un errore (codice di uscita 1) se librechat.yaml contiene errori di convalida. Questo comportamento "fail-fast" rileva tempestivamente i problemi di configurazione.

Per convalidare la sintassi YAML prima del riavvio, utilizza il YAML Validator o yamlchecker.com.

Il server si chiude immediatamente all'avvio

Se il tuo server si chiude immediatamente dopo l'avvio, è probabile che si tratti di un errore di convalida della configurazione.

Per diagnosticare:

Controlla i log del server: docker compose logs api
Valida la tua sintassi YAML con il YAML Validator
Errori comuni: rientro errato, due punti mancanti, chiavi sconosciute, valori non validi

Soluzione temporanea (non raccomandata per la produzione):

CONFIG_BYPASS_VALIDATION=true

Attenzione

CONFIG_BYPASS_VALIDATION=true fa sì che il server ignori la convalida e utilizzi la configurazione predefinita. Correggi sempre gli errori di convalida.

Configurazione personalizzata

Endpoint AI

Struttura dell'oggetto

In questa pagina