Chạy Onyx trên một LLM provider tương thích OpenAI tùy chỉnh.

Câu trả lời nhanh: Add Custom LLM Provider trong panel admin.

Tài liệu Onyx nói rõ rằng một provider tùy chỉnh hoạt động miễn là nó phơi ra các endpoint tương thích OpenAI, và hình dạng Base URL ví dụ của nó chính xác là kiểu gateway https://yourprovider.com/v1. Luồng: mở Admin Panel từ icon hồ sơ của bạn, vào Configuration, sau đó Language Models, và chọn Add Custom LLM Provider. Bốn quyết định quan trọng trong form đó. Display Name chỉ mang tính thẩm mỹ. Provider Name phải khớp một khóa provider LiteLLM, vì Onyx định tuyến lệnh gọi model qua LiteLLM bên dưới; với một gateway tương thích OpenAI đó là openai. Base URL là endpoint gateway gồm cả hậu tố /v1. Và mục Model Configurations là nơi bạn đăng ký mỗi model id bạn muốn có sẵn, viết chính xác như catalog phục vụ. Lưu lại, chọn một mặc định, và chat định tuyến qua gateway ngay lập tức.

Admin Panel -> Configuration -> Language Models
  -> Add Custom LLM Provider

Display Name:   APIsRouter
Provider Name:  openai            (LiteLLM provider key)
Base URL:       https://api.apisrouter.com/v1
API Key:        sk-YOUR-APISROUTER-KEY
Model Configurations:
  claude-sonnet-4-6
  claude-haiku-4-5-20251001
  deepseek-v4-pro

LLM nằm ở đâu trong kiến trúc của Onyx.

Onyx (onyx-dot-app trên GitHub, khoảng 31K star, trước đây là Danswer) là một nền tảng AI mã nguồn mở cho tri thức công ty: nó lập chỉ mục các nguồn như Slack, Google Drive, Confluence, và hàng chục connector khác, sau đó trả lời câu hỏi trên chúng qua một giao diện chat, assistant, và workflow agent. Đây là một trong những stack tìm kiếm doanh nghiệp tự host được deploy nhiều nhất, chính vì thế hóa đơn LLM của nó xứng đáng có một quyết định định tuyến thay vì để mặc định. Pipeline tách gọn thành hai. Lập chỉ mục và truy xuất, gồm cả nhúng tài liệu và rerank, chạy trên server model riêng của Onyx với model cục bộ theo mặc định; không phần nào trong đó chạm vào LLM provider của bạn. Sinh câu trả lời là nửa còn lại: một khi truy xuất lắp ráp các đoạn liên quan, một LLM đọc chúng và viết câu trả lời có căn cứ, và lệnh gọi đó đi qua LiteLLM tới bất kỳ provider nào admin đã cấu hình. Luồng provider tùy chỉnh hoán đổi đúng đích đến của nửa này. Vì LiteLLM chuyển tiếp model id như một chuỗi thuần tới một provider kiểu openai, các id bạn đăng ký trong Model Configurations có thể là bất cứ gì endpoint đứng sau Base URL phục vụ: Claude cho câu trả lời có căn cứ cẩn thận, DeepSeek cho khối lượng lớn, Gemini cho context nguồn rất dài. Các assistant khác nhau có thể mặc định vào model khác nhau, nên một assistant hỗ trợ và một assistant kỹ thuật có thể chạy các mức giá khác nhau qua cùng mục provider.

Cài đặt đầy đủ, và những gì giữ nguyên.

Form provider là toàn bộ tích hợp; không có file cấu hình để sửa hay container để build lại cho nó. Sau khi lưu, đặt model mặc định cho workspace, và tùy chọn ghi đè model theo từng assistant nơi bạn muốn các tầng chất lượng khác nhau. Điều cố ý giữ nguyên: connector giữ credential riêng của chúng, index không bị ảnh hưởng, và model embedding cấu hình cho tìm kiếm không di chuyển. Sự tách biệt đó đáng nói rõ vì nó khiến đây là một thay đổi rủi ro thấp. Nếu gateway hành xử sai, tìm kiếm và nguồn vẫn hoạt động; chỉ sinh câu trả lời sẽ lỗi, và chuyển mặc định về provider trước đó chỉ là một dropdown. Với các đội tự động hóa deployment, cùng định nghĩa provider có thể được gieo mầm qua API của Onyx thay vì nhấp qua giao diện, nhưng con đường panel admin là bề mặt có tài liệu và ổn định, và một cài đặt một-lần hiếm khi cần hơn thế.

# confirm the gateway lists the ids you plan to register
curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

# confirm a chat completion works end to end
curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6",
       "messages":[{"role":"user","content":"ping"}]}'

Chọn model cho câu trả lời doanh nghiệp có căn cứ.

Đánh giá model bên trong Onyx cụ thể một cách khác thường: hỏi cùng câu hỏi trên cùng connector với hai mặc định assistant khác nhau và so sánh câu trả lời nào trích dẫn đúng đoạn. Log sử dụng theo từng key định giá cả hai ứng viên trên bộ câu hỏi thực tế của bạn.

• Trả lời có căn cứ nặng đầu vào: model đọc các đoạn truy xuất áp đảo câu trả lời nó viết. Giá theo token đầu vào vì thế quyết định chi phí mỗi câu hỏi hơn giá đầu ra.
• claude-sonnet-4-6 là một mặc định workspace mạnh: kỷ luật về việc ở lại trong nguồn truy xuất và kháng cự việc bịa ra chính sách không có trong tài liệu.
• Assistant lưu lượng cao (helpdesk IT, FAQ HR) chạy tốt trên claude-haiku-4-5-20251001 hoặc deepseek-v4-pro, nơi giá theo khối lượng giữ chi phí mỗi ghế dự đoán được.
• Tài liệu nguồn dài ưu ái id long-context; gemini-3.1-pro-preview đáng thử cho các assistant kéo tài liệu thiết kế hoặc hợp đồng lớn vào context.
• Đăng ký nhiều id trong một mục provider và gán chúng theo từng assistant. Tầng chất lượng theo từng đội thắng một model thỏa hiệp toàn cục.

Trả theo mức sử dụng · thấp hơn giá chính thức

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Các kiểu lỗi đặc thù của Onyx.

Provider Name không phải một nhãn văn bản tự do. Nó phải khớp một khóa provider LiteLLM, và với một gateway khóa đó là openai. Một cái tên tự bịa sẽ thất bại lúc chạy với lỗi provider LiteLLM dù form vẫn lưu ổn. Base URL cần hậu tố /v1. Tài liệu của chính Onyx cho thấy hình dạng endpoint kết thúc bằng /v1; thiếu nó, đường chat-completions phân giải sai và request bị lỗi 404 tại gateway. Model id sống trong Model Configurations. Một model chưa từng đăng ký ở đó không thể chọn làm mặc định, và một lỗi chính tả trong một id đã đăng ký hiện ra là lỗi model-not-found ở lần dùng đầu, không phải lúc lưu. Danh sách /v1/models của gateway là cách viết chuẩn. Nếu giao diện admin của bạn thiếu field Base URL trên form custom-models, bạn đã gặp một hồi quy giao diện được báo cáo trong một số bản phát hành 2026 chứ không phải thiếu tính năng; nâng cấp sẽ khôi phục field đó. Và hãy nhớ bạn đã di chuyển nửa nào: nếu kết quả tìm kiếm trông sai hoặc cũ, đó là lập chỉ mục và connector, thứ không bao giờ chạm vào custom provider. Chỉ câu trả lời đã sinh mới định tuyến qua gateway.

Ai định tuyến Onyx qua một gateway.

• Các đội tự host thay thế tài khoản theo từng vendor bằng một endpoint, một key, và sử dụng theo từng key ánh xạ gọn gàng tới một workspace hoặc phòng ban.
• Doanh nghiệp đã chuẩn hóa trên Onyx cho tìm kiếm nội bộ và muốn câu trả lời có căn cứ chất lượng Claude mà không cần một quan hệ billing Anthropic riêng.
• Các đội nền tảng chạy nhiều assistant ở các tầng chất lượng khác nhau, định giá theo từng assistant qua model id đã đăng ký trên một provider.
• Người đánh giá so sánh chất lượng câu trả lời qua các họ model trên cùng corpus, nơi mỗi ứng viên là một id đã đăng ký thay vì một tích hợp provider mới.
• Lập trình viên không có quyền truy cập billing của một vendor cụ thể. Truy cập dựa trên nạp tiền không yêu cầu thẻ loại bỏ phụ thuộc đăng ký theo từng provider.

Xác minh endpoint và debug chat đầu tiên.

Hai kiểm tra curl ở trên bao phủ nửa gateway trước khi bạn chạm vào form: các id bạn định đăng ký phải xuất hiện trong /v1/models, và một chat completion trực tiếp nên trả lời. Bên trong Onyx, lỗi khoanh vùng nhanh chóng. Một lỗi provider nhắc tới LiteLLM nghĩa là Provider Name không phải một khóa hợp lệ; hãy đặt nó thành openai. Một lỗi xác thực ở lần chat đầu nghĩa là API Key không thuộc về endpoint trong Base URL. Một lỗi model-not-found là sự không khớp id giữa Model Configurations và catalog. Câu trả lời được sinh ra nhưng bỏ qua tài liệu của bạn là vấn đề truy xuất hoặc connector, nằm ở phía trước LLM provider hoàn toàn. Khi chat đã chạy, console APIsRouter hiển thị model theo từng request, số lượng token, và chi tiêu. Với một công cụ workspace nơi mỗi câu hỏi mang theo context truy xuất, con số token mỗi câu hỏi đó là cơ sở trung thực cho việc lập kế hoạch năng lực, và một key theo từng workspace biến log sử dụng thành một báo cáo chi phí cấp phòng ban.

Câu hỏi thường gặp