Các endpoint tùy chỉnh

Thêm các nhà cung cấp AI tùy chỉnh như OpenRouter, Ollama và các cổng tương thích với Anthropic vào LibreChat bằng cách sử dụng librechat.yaml

LibreChat hỗ trợ các dịch vụ tương thích với OpenAI API dưới dạng các endpoint tùy chỉnh. Nó cũng hỗ trợ các endpoint tùy chỉnh tương thích với Anthropic với provider: "anthropic". Bạn cấu hình các endpoint trong librechat.yaml, lưu trữ các khóa API trong .env và mount cấu hình thông qua docker-compose.override.yml cho các triển khai Docker.

Tệp nào thực hiện chức năng gì?

Thiết lập endpoint tùy chỉnh bao gồm ba tệp, mỗi tệp có một vai trò cụ thể:

librechat.yaml -- Định nghĩa các endpoint tùy chỉnh của bạn (tên, URL API, các model, cài đặt hiển thị)
.env -- Lưu trữ các giá trị nhạy cảm như khóa API (được tham chiếu từ librechat.yaml bằng cú pháp ${VAR_NAME})
docker-compose.override.yml -- Gắn librechat.yaml vào trong Docker container (chỉ dành cho người dùng Docker)

Để có cái nhìn tổng quan đầy đủ về cách các tệp này hoạt động cùng nhau, hãy xem Configuration Overview.

Trước khi bắt đầu

Hướng dẫn này giả định rằng bạn đã cài đặt và chạy LibreChat. Nếu chưa, hãy hoàn tất Docker setup trước.

Bước 1. Mount librechat.yaml (Chỉ dành cho Docker)

Người dùng Docker cần mount librechat.yaml dưới dạng một volume để container có thể đọc được tệp này. Hãy bỏ qua bước này nếu bạn đang chạy LibreChat cục bộ mà không sử dụng Docker.

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

Chỉnh sửa docker-compose.override.yml và đảm bảo rằng phần mount volume đã được bỏ chú thích:

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

Tìm hiểu thêm: Docker Override Guide

Bước 2. Cấu hình librechat.yaml

Tạo một tệp librechat.yaml trong thư mục gốc của dự án (nếu tệp chưa tồn tại) và thêm cấu hình endpoint của bạn. Xem hướng dẫn librechat.yaml để biết hướng dẫn thiết lập chi tiết.

Dưới đây là một ví dụ với OpenRouter, Ollama và một gateway tương thích với 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'

Duyệt qua tất cả các nhà cung cấp tương thích trong phần AI Endpoints. Để xem tài liệu tham khảo đầy đủ về các trường, hãy xem Custom Endpoint Object Structure.

Các endpoint tương thích với Anthropic

Chỉ sử dụng provider: "anthropic" cho các endpoint sử dụng native Anthropic Messages API. Đối với các gateway tương thích với OpenAI nhưng chỉ đơn thuần cung cấp các model của Anthropic, hãy bỏ qua provider và sử dụng cấu trúc endpoint tùy chỉnh tương thích với OpenAI thông thường.

Cấu hình API Key

Khi cấu hình các khóa API trong các endpoint tùy chỉnh, bạn có ba tùy chọn:

Biến môi trường (khuyên dùng): apiKey: "${OPENROUTER_KEY}" -- đọc từ .env
User provided: apiKey: "user_provided" -- người dùng nhập khóa của riêng họ trong giao diện người dùng
Giá trị trực tiếp (không khuyến nghị): apiKey: "sk-your-actual-key" -- được lưu trữ dưới dạng văn bản thuần túy

Bước 3. Thiết lập các biến môi trường

Thêm các khóa API được tham chiếu trong librechat.yaml của bạn vào tệp .env:

OPENROUTER_KEY=your_openrouter_api_key

Mỗi ${VARIABLE_NAME} trong librechat.yaml phải có một mục tương ứng trong .env.

Bước 4. Khởi động lại và xác minh

Sau khi chỉnh sửa các tệp cấu hình, bạn phải khởi động lại LibreChat để các thay đổi có hiệu lực.

docker compose down && docker compose up -d

Dừng tiến trình đang chạy (Ctrl+C) và khởi động lại:

npm run backend

Mở LibreChat trong trình duyệt của bạn. Các endpoint tùy chỉnh của bạn sẽ xuất hiện trong menu thả xuống chọn endpoint.

Bạn không thấy endpoint của mình?

Kiểm tra nhật ký máy chủ để tìm lỗi cấu hình:

docker compose logs api

Các vấn đề thường gặp: lỗi cú pháp YAML, thiếu các biến môi trường, hoặc librechat.yaml chưa được mount trong Docker. Hãy kiểm tra tính hợp lệ của tệp YAML của bạn bằng YAML Validator.

OpenRouter Vẫn Không Hiển Thị

Đối với OpenRouter cụ thể, hãy xác minh chuỗi ba tệp:

.env có OPENROUTER_KEY=...
librechat.yaml có apiKey: "${OPENROUTER_KEY}" nằm trong endpoint tùy chỉnh OpenRouter
Người dùng Docker đã mount librechat.yaml trong docker-compose.override.yml

Sau đó khởi động lại với:

docker compose down && docker compose up -d

Nếu endpoint xuất hiện nhưng trả về 402 Payment Required, yêu cầu đã đến được OpenRouter thành công và vấn đề thường nằm ở số dư tài khoản, thanh toán hoặc tính khả dụng của model trên OpenRouter.