Endpoint personalizzati

Aggiungi provider AI personalizzati come OpenRouter, Ollama e gateway compatibili con Anthropic a LibreChat utilizzando librechat.yaml

LibreChat supporta servizi compatibili con le API di OpenAI come endpoint personalizzati. Supporta inoltre endpoint personalizzati compatibili con Anthropic con provider: "anthropic". È possibile configurare gli endpoint in librechat.yaml, archiviare le chiavi API in .env e montare la configurazione tramite docker-compose.override.yml per le distribuzioni Docker.

Quale file fa cosa?

La configurazione di un endpoint personalizzato coinvolge tre file, ognuno con un ruolo specifico:

librechat.yaml -- Definisce i tuoi endpoint personalizzati (nome, URL API, modelli, impostazioni di visualizzazione)
.env -- Memorizza valori sensibili come le chiavi API (a cui si fa riferimento da librechat.yaml utilizzando la sintassi ${VAR_NAME})
docker-compose.override.yml -- Monta librechat.yaml nel container Docker (solo per utenti Docker)

Per una panoramica completa di come questi file funzionano insieme, consulta la Panoramica della configurazione.

Prima di iniziare

Questa guida presuppone che LibreChat sia installato e in esecuzione. In caso contrario, completa prima la configurazione Docker.

Passaggio 1. Montare librechat.yaml (Solo Docker)

Gli utenti Docker devono montare librechat.yaml come volume affinché il container possa leggerlo. Salta questo passaggio se stai eseguendo LibreChat localmente senza Docker.

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

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

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

Scopri di più: Docker Override Guide

Passaggio 2. Configurare librechat.yaml

Crea un file librechat.yaml nella root del progetto (se non esiste) e aggiungi la configurazione del tuo endpoint. Consulta la guida a librechat.yaml per istruzioni dettagliate sulla configurazione.

Ecco un esempio con OpenRouter, Ollama e un gateway compatibile con Anthropic:

version: 1.3.13
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'
    - name: 'Ollama'
      apiKey: 'ollama'
      baseURL: 'http://host.docker.internal:11434/v1/'
      models:
        default: ['llama3:latest', 'command-r', 'mixtral', 'phi3']
        fetch: true
      titleConvo: true
      titleModel: 'current_model'
    - name: 'Claude-Compatible'
      provider: 'anthropic'
      apiKey: '${ANTHROPIC_API_KEY}'
      baseURL: 'https://api.anthropic.com'
      headers:
        anthropic-version: '2023-06-01'
      models:
        default: ['claude-sonnet-4-5']
        fetch: false
      titleConvo: true
      titleModel: 'claude-sonnet-4-5'

Sfoglia tutti i provider compatibili nella sezione AI Endpoints. Per il riferimento completo dei campi, consulta Custom Endpoint Object Structure.

Endpoint compatibili con Anthropic

Usa provider: "anthropic" solo per gli endpoint che utilizzano l'API nativa Anthropic Messages. Per i gateway compatibili con OpenAI che espongono semplicemente modelli Anthropic, ometti provider e usa la normale configurazione per endpoint personalizzati compatibili con OpenAI.

Configurazione della chiave API

Quando configuri le chiavi API negli endpoint personalizzati, hai tre opzioni:

Variabile d'ambiente (consigliato): apiKey: "${OPENROUTER_KEY}" -- legge da .env
User provided: apiKey: "user_provided" -- gli utenti inseriscono la propria chiave nell'interfaccia utente
Valore diretto (non raccomandato): apiKey: "sk-your-actual-key" -- memorizzato in testo semplice

Passaggio 3. Impostare le variabili d'ambiente

Aggiungi le chiavi API a cui si fa riferimento nel tuo librechat.yaml al file .env:

OPENROUTER_KEY=your_openrouter_api_key

Ogni ${VARIABLE_NAME} in librechat.yaml deve avere una voce corrispondente in .env.

Passaggio 4. Riavvia e verifica

Dopo aver modificato i file di configurazione, è necessario riavviare LibreChat affinché le modifiche abbiano effetto.

docker compose down && docker compose up -d

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

npm run backend

Apri LibreChat nel tuo browser. I tuoi endpoint personalizzati dovrebbero apparire nel menu a discesa del selettore di endpoint.

Non vedi il tuo endpoint?

Controlla i log del server per errori di configurazione:

docker compose logs api

Problemi comuni: errori di sintassi YAML, variabili d'ambiente mancanti o librechat.yaml non montato in Docker. Convalida il tuo YAML con il YAML Validator.

OpenRouter continua a non apparire

Per OpenRouter nello specifico, verifica la catena di tre file:

.env contiene OPENROUTER_KEY=...
librechat.yaml ha apiKey: "${OPENROUTER_KEY}" sotto l'endpoint personalizzato OpenRouter
Gli utenti Docker hanno montato librechat.yaml in docker-compose.override.yml

Quindi riavvia con:

docker compose down && docker compose up -d

Se l'endpoint appare ma restituisce 402 Payment Required, la richiesta ha raggiunto OpenRouter con successo e il problema è solitamente legato ai crediti dell'account, alla fatturazione o alla disponibilità del modello su OpenRouter.