Onyx را روی یک provider سفارشی سازگار با OpenAI اجرا کنید.

پاسخ سریع: Add Custom LLM Provider در پنل ادمین.

مستندات Onyx صریح‌اند که یک provider سفارشی کار می‌کند تا وقتی endpoint های سازگار با OpenAI افشا کند، و شکل Base URL نمونه آن دقیقاً به‌سبک-gateway https://yourprovider.com/v1 است. جریان: پنل ادمین را از آیکون پروفایل خود باز کنید، به Configuration بروید، سپس Language Models، و Add Custom LLM Provider را انتخاب کنید. چهار تصمیم در آن فرم اهمیت دارند. Display Name آرایشی است. Provider Name باید با یک کلید provider LiteLLM مطابقت داشته باشد، چون Onyx فراخوانی‌های مدل را از طریق LiteLLM زیر پوسته مسیردهی می‌کند؛ برای یک gateway سازگار با OpenAI آن openai است. Base URL همان endpoint gateway شامل پسوند /v1 است. و بخش Model Configurations جایی است که هر id مدلی که می‌خواهید در دسترس باشد را ثبت می‌کنید، دقیقاً همان‌طور که کاتالوگ می‌نویسد. ذخیره کنید، یک پیش‌فرض انتخاب کنید، و چت‌ها فوراً از طریق gateway مسیردهی می‌شوند.

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 کجای معماری Onyx می‌نشیند.

Onyx (onyx-dot-app در GitHub، حدود ۳۱ هزار ستاره، سابقاً Danswer) یک پلتفرم AI متن‌باز برای دانش شرکت است: منابعی مثل Slack، Google Drive، Confluence، و ده‌ها connector دیگر را index می‌کند، سپس از طریق یک UI چت، دستیارها، و workflow های agent روی آن‌ها پاسخ می‌دهد. این یکی از پرمصرف‌ترین stack های جستجوی enterprise self-hosted است، دقیقاً به همین دلیل صورت‌حساب LLM آن یک تصمیم مسیردهی می‌طلبد نه یک پیش‌فرض. pipeline تمیز به دو بخش تقسیم می‌شود. index کردن و retrieval، شامل embedding سند و reranking، به‌طور پیش‌فرض روی سرور مدل خود Onyx با مدل‌های محلی اجرا می‌شوند؛ هیچ‌کدام از آن‌ها به provider LLM شما دست نمی‌زند. تولید پاسخ نیمه دیگر است: وقتی retrieval passage های مربوط را جمع‌آوری کرد، یک LLM آن‌ها را می‌خواند و پاسخ مبتنی می‌نویسد، و آن فراخوانی از طریق LiteLLM به هر provider ای می‌رود که ادمین پیکربندی کرده. جریان provider سفارشی مقصد دقیقاً همین نیمه را سوییچ می‌کند. چون LiteLLM id مدل را به‌عنوان رشته ساده به یک provider نوع-openai فوروارد می‌کند، id هایی که در Model Configurations ثبت می‌کنید می‌توانند هر چیزی باشند که توسط endpoint پشت Base URL سرویس داده می‌شود: Claude برای پاسخ‌های مبتنی دقیق، DeepSeek برای حجم، Gemini برای context منبع خیلی بلند. دستیارهای مختلف می‌توانند به‌طور پیش‌فرض به مدل‌های مختلفی بروند، پس یک دستیار پشتیبانی و یک دستیار مهندسی می‌توانند نقاط قیمتی متفاوتی را از طریق همان entry provider سوار شوند.

راه‌اندازی کامل، و آنچه دست‌نخورده می‌ماند.

فرم provider کل یکپارچگی است؛ هیچ فایل config ای برای ویرایش یا کانتینری برای بازسازی برای آن وجود ندارد. بعد از ذخیره، مدل پیش‌فرض workspace را تنظیم کنید، و اختیاری مدل را به ازای هر دستیار override کنید جایی که tier های کیفیت متفاوتی می‌خواهید. آنچه عمداً دست‌نخورده می‌ماند: connector ها credential های خودشان را نگه می‌دارند، index تحت‌تأثیر قرار نمی‌گیرد، و مدل embedding پیکربندی‌شده برای جستجو جابه‌جا نمی‌شود. آن جدایی ارزش گفتن دارد چون این را یک تغییر کم‌ریسک می‌کند. اگر gateway بدرفتاری کند، جستجو و منابع همچنان کار می‌کنند؛ فقط تولید پاسخ خطا می‌دهد، و برگرداندن پیش‌فرض به provider قبلی یک dropdown است. برای تیم‌هایی که deployment ها را خودکار می‌کنند، همان تعریف provider می‌تواند از طریق API خود Onyx seed شود به‌جای کلیک‌شدن در UI، اما مسیر پنل ادمین سطح مستند و پایدار است، و راه‌اندازی یک‌باره به‌ندرت بیشتر را توجیه می‌کند.

# 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"}]}'

انتخاب مدل‌ها برای پاسخ‌های enterprise مبتنی.

ارزیابی مدل داخل Onyx به‌طور غیرمعمول عینی است: همان سؤال را در برابر همان connector ها با دو پیش‌فرض دستیار متفاوت بپرسید و مقایسه کنید کدام پاسخ منابع درست را cite می‌کند. usage log هر-کلید هر دو کاندید را روی ترکیب سؤال واقعی شما قیمت‌گذاری می‌کند.

• پاسخ‌دهی مبتنی ورودی-سنگین است: مدل passage های بازیابی‌شده‌ای را می‌خواند که پاسخی که می‌نویسد را کوچک می‌کنند. پس قیمت هر-token-ورودی بیشتر از قیمت خروجی هزینه هر-سؤال شما را تعیین می‌کند.
• claude-sonnet-4-6 یک پیش‌فرض قوی workspace است: منضبط در ماندن داخل منابع بازیابی‌شده و مقاوم در برابر اختراع policy ای که در اسناد نیست.
• دستیارهای پرترافیک (helpdesk IT، FAQ منابع انسانی) روی claude-haiku-4-5-20251001 یا deepseek-v4-pro خوب اجرا می‌شوند، جایی که قیمت‌گذاری حجمی هزینه هر-صندلی را قابل‌پیش‌بینی نگه می‌دارد.
• اسناد منبع بلند id های long-context را ترجیح می‌دهند؛ gemini-3.1-pro-preview ارزش تست‌کردن دارد برای دستیارهایی که سند های طراحی یا قراردادهای بزرگ را به context می‌کشند.
• چند id را در یک entry provider ثبت کنید و آن‌ها را به ازای هر دستیار اختصاص دهید. tier های کیفیت به ازای هر تیم بهتر از یک مدل سازش جهانی است.

پرداخت بر اساس مصرف · پایین‌تر از قیمت رسمی

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

حالت‌های شکست مختص Onyx.

Provider Name یک برچسب متن-آزاد نیست. باید با یک کلید provider LiteLLM مطابقت داشته باشد، و برای یک gateway آن کلید openai است. یک نام ساختگی در زمان درخواست با یک خطای provider LiteLLM شکست می‌خورد حتی اگر فرم خوب ذخیره شده باشد. Base URL پسوند /v1 را می‌خواهد. مستندات خود Onyx شکل‌های endpoint را که به /v1 ختم می‌شوند نشان می‌دهند؛ بدون آن، مسیر chat-completions اشتباه resolve می‌شود و درخواست‌ها روی gateway با 404 مواجه می‌شوند. id های مدل در Model Configurations زندگی می‌کنند. مدلی که هرگز آنجا ثبت نکرده‌اید نمی‌تواند به‌عنوان پیش‌فرض انتخاب شود، و یک غلط‌تایپی در یک id ثبت‌شده در اولین استفاده، نه هنگام ذخیره، به‌عنوان یک خطای model-not-found ظاهر می‌شود. فهرست /v1/models گیت‌وی نگارش معتبر است. اگر UI ادمین شما فیلد Base URL را از فرم مدل‌های سفارشی گم کرده، شما به یک رگرسیون UI گزارش‌شده در برخی release های ۲۰۲۶ برخورده‌اید نه یک ویژگی گمشده؛ upgrade کردن فیلد را بازمی‌گرداند. و به‌خاطر بسپارید کدام نیمه را جابه‌جا کرده‌اید: اگر نتایج جستجو اشتباه یا کهنه به‌نظر می‌رسند، آن index کردن و connector هاست، که هرگز provider سفارشی را لمس نمی‌کنند. فقط پاسخ‌های تولیدشده از طریق gateway مسیردهی می‌شوند.

چه کسانی Onyx را از طریق یک gateway مسیردهی می‌کنند.

• تیم‌های self-hosted که حساب‌های هر-vendor را با یک endpoint، یک کلید، و usage هر-کلید که تمیز به یک workspace یا دپارتمان نگاشت می‌شود جایگزین می‌کنند.
• شرکت‌هایی که روی Onyx برای جستجوی داخلی استاندارد شده‌اند و پاسخ‌های مبتنی با کیفیت Claude می‌خواهند بدون یک رابطه صورت‌حساب جدا با Anthropic.
• تیم‌های پلتفرم که چندین دستیار را در tier های کیفیت مختلف اجرا می‌کنند، قیمت‌گذاری‌شده به ازای هر دستیار از طریق id های مدل ثبت‌شده روی یک provider.
• ارزیاب‌هایی که کیفیت پاسخ را در خانواده‌های مدل روی corpus های یکسان مقایسه می‌کنند، جایی که هر کاندید یک id ثبت‌شده است نه یک integration provider جدید.
• توسعه‌دهندگان بدون دسترسی به صورت‌حساب یک vendor خاص. دسترسی مبتنی بر شارژ بدون الزام کارت وابستگی ثبت‌نام هر-provider را حذف می‌کند.

endpoint را تأیید کنید و اولین چت را عیب‌یابی کنید.

دو چک curl بالا نیمه gateway را قبل از لمس فرم پوشش می‌دهند: id هایی که قصد ثبت دارید باید در /v1/models ظاهر شوند، و یک chat completion مستقیم باید پاسخ دهد. داخل Onyx، شکست‌ها سریع موقعیت‌یابی می‌شوند. یک خطای provider که LiteLLM را نام می‌برد یعنی Provider Name یک کلید معتبر نیست؛ آن را روی openai تنظیم کنید. یک خطای authentication در اولین چت یعنی API Key متعلق به endpoint در Base URL نیست. یک خطای model-not-found یک عدم‌تطابق id بین Model Configurations و کاتالوگ است. پاسخ‌هایی که تولید می‌شوند اما اسناد شما را نادیده می‌گیرند یک مسئله retrieval یا connector هستند، کاملاً بالادست provider LLM. وقتی چت‌ها جاری شوند، کنسول APIsRouter مدل، شمارش token، و هزینه هر-درخواست را نشان می‌دهد. برای یک ابزار workspace که هر سؤال context بازیابی‌شده حمل می‌کند، آن عدد token هر-سؤال مبنای صادقانه برنامه‌ریزی ظرفیت است، و یک کلید به ازای هر workspace usage log را به یک گزارش هزینه سطح-دپارتمان تبدیل می‌کند.

پرسش‌های پرتکرار