Endpoints Personalizados

Adicione provedores de IA personalizados como OpenRouter, Ollama e gateways compatíveis com Anthropic ao LibreChat usando o librechat.yaml

O LibreChat oferece suporte a serviços compatíveis com a API da OpenAI como endpoints personalizados. Ele também oferece suporte a endpoints personalizados compatíveis com a Anthropic com provider: "anthropic". Você configura os endpoints no librechat.yaml, armazena as chaves de API no .env e monta a configuração via docker-compose.override.yml para implantações Docker.

Qual arquivo faz o quê?

A configuração de um endpoint personalizado envolve três arquivos, cada um com uma função específica:

librechat.yaml -- Define seus endpoints personalizados (nome, URL da API, modelos, configurações de exibição)
.env -- Armazena valores sensíveis como chaves de API (referenciados a partir do librechat.yaml usando a sintaxe ${VAR_NAME})
docker-compose.override.yml -- Monta o librechat.yaml no container Docker (apenas para usuários Docker)

Para uma visão geral completa de como esses arquivos funcionam em conjunto, consulte a Visão Geral da Configuração.

Antes de começar

Este guia pressupõe que você tenha o LibreChat instalado e em execução. Caso contrário, conclua a configuração do Docker primeiro.

Passo 1. Monte o librechat.yaml (Apenas Docker)

Usuários de Docker precisam montar o librechat.yaml como um volume para que o container possa lê-lo. Pule esta etapa se você estiver executando o LibreChat localmente sem Docker.

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

Edite o docker-compose.override.yml e certifique-se de que a montagem de volume esteja descomentada:

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

Saiba mais: Guia de Substituição do Docker

Passo 2. Configurar o librechat.yaml

Crie um arquivo librechat.yaml na raiz do projeto (caso ele não exista) e adicione a configuração do seu endpoint. Consulte o guia do librechat.yaml para instruções detalhadas de configuração.

Aqui está um exemplo com OpenRouter, Ollama e um gateway compatível com 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'

Navegue por todos os provedores compatíveis na seção AI Endpoints. Para a referência completa dos campos, consulte Custom Endpoint Object Structure.

Endpoints compatíveis com Anthropic

Use provider: "anthropic" apenas para endpoints que utilizam a API nativa de Messages da Anthropic. Para gateways compatíveis com OpenAI que apenas expõem modelos da Anthropic, omita o provider e utilize o formato de endpoint personalizado compatível com OpenAI padrão.

Configuração de Chave de API

Ao configurar chaves de API em endpoints personalizados, você tem três opções:

Variável de ambiente (recomendado): apiKey: "${OPENROUTER_KEY}" -- lê a partir do .env
User provided: apiKey: "user_provided" -- os usuários inserem sua própria chave na UI
Valor direto (não recomendado): apiKey: "sk-your-actual-key" -- armazenado em texto simples

Passo 3. Definir Variáveis de Ambiente

Adicione as chaves de API referenciadas no seu librechat.yaml ao arquivo .env:

OPENROUTER_KEY=your_openrouter_api_key

Cada ${VARIABLE_NAME} no librechat.yaml deve ter uma entrada correspondente no .env.

Passo 4. Reinicie e Verifique

Após editar os arquivos de configuração, você deve reiniciar o LibreChat para que as alterações entrem em vigor.

docker compose down && docker compose up -d

Interrompa o processo em execução (Ctrl+C) e reinicie:

npm run backend

Abra o LibreChat no seu navegador. Seus endpoints personalizados devem aparecer no menu suspenso de seleção de endpoint.

Não está vendo seu endpoint?

Verifique os logs do servidor em busca de erros de configuração:

docker compose logs api

Problemas comuns: erros de sintaxe YAML, variáveis de ambiente ausentes ou librechat.yaml não montado no Docker. Valide seu YAML com o YAML Validator.

OpenRouter Ainda Não Aparece

Para o OpenRouter especificamente, verifique a cadeia de três arquivos:

O .env contém OPENROUTER_KEY=...
librechat.yaml tem apiKey: "${OPENROUTER_KEY}" sob o endpoint personalizado do OpenRouter
Usuários do Docker montaram o librechat.yaml no docker-compose.override.yml

Em seguida, reinicie com:

docker compose down && docker compose up -d

Se o endpoint aparecer, mas retornar 402 Payment Required, a solicitação alcançou o OpenRouter com sucesso e o problema geralmente está relacionado a créditos da conta, faturamento ou disponibilidade de modelo no OpenRouter.