8feea123bb
* feat(docs): mirror every docs/ page in all 65 locales Extends the documentation mirrors from the 22-page core set (#13940) to every Markdown page under docs/: 152 sources x 65 locales = 9,880 mirrors (6,208 new), language bars rewritten for the full locale list, state adopted so the blocking drift gate now covers all 152 pages. run-translation.mjs: an oversized block made only of table rows or list items (PROVIDER_REFERENCE.md 244-row table, FREE_TIERS.md 71-item list) is cut at item boundaries and rejoined without a blank line — the single 16-40 KB request outlived the backend socket for verbose scripts. 48 older mirrors whose tables had lost rows were retranslated with --force. * docs(i18n): refresh mirrors for the sources the base changed since the branch cut Section-level retranslation of the 29 docs (and README.md) whose source or mirrors moved on release/v3.8.51 during the run, then state adoption; the drift gate is green again on the merged tree.
15 KiB
Provider Plugin Manifest (فارسی)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
open-sse/config/providerPluginManifest.ts قرارداد افزونهٔ ارائهدهنده با قابلیت سریالسازی امن به JSON را تعریف میکند.
open-sse/config/providerPluginManifestRegistry.ts این قرارداد را به رجیستری فعلی
ارائهدهندگان برای سایدکارهایی مانند Bifrost،
CLIProxyAPI یا یک مسیریاب Go/Rust در آینده متصل میکند. رجیستری TypeScript همچنان
منبع حقیقت باقی میماند، اما سایدکارها میتوانند مانیفست را بدون وارد کردن
کد اجرایی، مقادیر پیشفرض OAuth، هدرها یا وضعیت محیط پردازش مصرف کنند.
همین مانیفست از طریق HTTP و در نشانی
GET /api/v1/provider-plugin-manifest نیز برای سایدکارهایی که خارج از پردازش اجرا میشوند، در دسترس است.
OmniRoute این URL را از طریق هدر درخواست
X-OmniRoute-Provider-Manifest-Url به Bifrost و CLIProxyAPI اعلام میکند. زمانی که
سایدکار بهجای مبدأ محلی درخواست به یک URL عمومی یا URL شبکهٔ کانتینر نیاز دارد،
OMNIROUTE_PROVIDER_MANIFEST_URL را تنظیم کنید.
تازهسازی مانیفست
نقطهٔ پایانی HTTP، هدر Cache-Control: public, max-age=60 و یک
ETag قوی را برمیگرداند. سایدکار باید آخرین مانیفست اعتبارسنجیشده را نگه دارد و هنگام
تازهسازی، ETag آن را در If-None-Match ارسال کند. پاسخ 304 Not Modified فاقد بدنه است؛
سایدکار مانیفست کششدهٔ خود را نگه میدارد. اگر هیچ مانیفست کششدهٔ اعتبارسنجیشدهای وجود نداشته باشد،
سایدکار باید بهجای پذیرفتن پاسخ 304، یک درخواست بدون شرط ارسال کند.
هدف
حرکت دادن فرادادهٔ ارائهدهندگان بهسمت یک قرارداد افزونه تا مسیر داغ درخواست در نهایت بتواند توسط یک سایدکار با تأخیر کمتر مدیریت شود، درحالیکه OmniRoute مسیر TypeScript را بهعنوان دروازهٔ سیاستگذاری و مسیر جایگزین حفظ میکند. مانیفست افزایشی است: بهخودیخود مسیریابی درخواستها را تغییر نمیدهد.
قرارداد
مانیفست شامل موارد زیر است:
- شناسه و نام مستعار ارائهدهنده
- قالب بالادستی و نام اجراکننده
- نوع احراز هویت، هدر احراز هویت و پیشوند اختیاری احراز هویت
- فرادادهٔ ایستای نقطهٔ پایانی
- واجد شرایط بودن برای سایدکار و دلایل صریح برای مواردی که یک ارائهدهنده باید در TS باقی بماند
- فرادادهٔ مدل با قابلیت سریالسازی امن به JSON، مانند طول زمینه، پرچمهای بینایی/استدلال و پارامترهای پشتیبانینشده
- برچسبهای قابلیت شامل
apikey،oauth،custom-executor،passthrough-models،responses،sidecar-candidate،usage-fetchوusage-supported
مانیفست عمداً موارد زیر را شامل نمیشود:
- اسرار کلاینت OAuth و مقادیر پیشفرض محرمانه
- تفکیک محیط زمان اجرا
- هدرهای درخواست و ابزارهای کمکی اعتبارنامهٔ عمومی
- سازندههای پویای URL
- توابع اجراکننده
- جزئیات داخلی مخزن نشستها
برچسبهای قابلیت
capabilities آرایهای مرتبشده از برچسبهای مشتقشده از ورودی رجیستری است. یکپارچهسازها
باید بهجای بازخوانی کدهای منبع TypeScript، آن را پاسخی ماشینخوان به پرسش «این ارائهدهنده چه قابلیتهایی دارد؟» در نظر بگیرند.
| برچسب | معنا |
|---|---|
apikey |
یک کلید API را میپذیرد (authType برابر با apikey یا optional است). |
oauth |
از جریان OAuth یا نشست استفاده میکند. |
responses |
یک URL پایه برای OpenAI Responses-API ارائه میدهد. |
passthrough-models |
مدلها را بهجای یک کاتالوگ ایستا، مستقیماً از بالادست ارائه میکند. |
custom-executor |
یک اجراکنندهٔ غیراستاندارد را اجرا میکند، بنابراین در مسیر TypeScript باقی میماند. |
sidecar-candidate |
بازتابدهندهٔ sidecar.eligible است — برای بررسی جهت وارد کردن به سایدکار ایمن است. |
usage-fetch |
یک واکشیکنندهٔ مصرف یا سهمیهٔ متصل دارد (getUsageForProvider). |
usage-supported |
API مصرف این ارائهدهنده را میپذیرد (isSupportedUsageConnection). |
usage-fetch فقط برای کشف است. این برچسب گزارش میدهد که OmniRoute میداند چگونه اطلاعات مصرف
ارائهدهنده را بخواند؛ واکشی را فعال نمیکند، معناشناسی سهمیه را تغییر نمیدهد و به این معنا نیست که
ویجت سهمیه در Dashboard برای ارائهدهنده فعال است — آن ویجت بهطور جداگانه توسط
USAGE_SUPPORTED_PROVIDERS کنترل میشود. منبع حقیقت، USAGE_FETCHER_PROVIDERS در
open-sse/services/usage/fetcherProviders.ts است.
کلیدهای آن فهرست، رشتههایی هستند که توزیعکنندهٔ مصرف میپذیرد، بنابراین ترکیبی از شناسههای متعارف
و نامهای مستعار است و کمی طولانیتر از تعداد ارائهدهندگان برچسبخورده است: ورودیهایی که
در رجیستری مانیفست ارائهدهندگان چت نیستند (برای مثال ارائهدهندهٔ جستوجوی firecrawl
و ارائهدهندهٔ ACP با نام amazon-q) هیچ ورودی مانیفستی برای برچسبگذاری ندارند.
usage-supported مشخص میکند که آیا مسیرهای مصرف سرور و Dashboard یک اتصال
برای ارائهدهنده را میپذیرند یا خیر. این برچسب بازتابدهندهٔ isSupportedUsageConnection() (src/lib/usage/providerLimits.ts)
و supportsProviderQuota() (src/shared/utils/providerQuotaVisibility.ts) است که هر دو توسط
USAGE_SUPPORTED_PROVIDERS (open-sse/services/usage/supportedProviders.ts) کنترل میشوند. برخلاف
usage-fetch، این برچسب فقط بر اساس شناسهٔ ارائهدهنده تولید میشود — محافظ زمان اجرا
USAGE_SUPPORTED_PROVIDERS.includes(providerId) را بدون تفکیک نام مستعار اجرا میکند، بنابراین مانیفست
همان قاعده را حفظ میکند. این دو برچسب دامنههای متفاوتی دارند: 3 ارائهدهنده فقط
usage-fetch (opencode، opencode-zen، xai) و 1 ارائهدهنده فقط
usage-supported (xiaomi-mimo-token-plan) را دارند، بنابراین هیچیک مستلزم دیگری نیست.
استفاده از Sidecar
Sidecarها باید sidecar.eligible را یک سیگنال محافظهکارانه برای شناسایی گزینههای کاندید در نظر بگیرند، نه یک تصمیم مسیریابی قطعی. نخستین هدف برای واردسازی باید ارائهدهندگانی باشند که از کلید API و endpointهای ایستا بههمراه executor پیشفرض استفاده میکنند. ارائهدهندگان دارای executorهای سفارشی وب، جریانهای OAuth/session، سازندههای پویای URL یا پیکربندی pool باید تا زمانی که یک Sidecar رفتار معادل را پیادهسازی کند و telemetry برابری عملکرد را اثبات کند، در مسیر fallback مبتنی بر TypeScript باقی بمانند.
مراحل پیشنهادی مهاجرت:
- manifest افزونهٔ ارائهدهنده را از registry مربوط به TS تولید و اعتبارسنجی کنید.
- به Bifrost یا CLIProxyAPI امکان دهید manifest را برای ارائهدهندگان مبتنی بر کلید API و endpointهای ایستا وارد کند.
- ارائهدهندگان واجد شرایط را پشت
OMNIROUTE_RELAY_BACKENDاز طریق Sidecar مسیریابی کنید و در عین حال fallback مبتنی بر TS را فعال نگه دارید. - ارائهدهندگان را تنها زمانی ارتقا دهید که نرخ موفقیت، تأخیر p99، رفتار streaming و مدیریت پارامترهای پشتیبانینشده با مسیر TS مطابقت داشته باشند.
- افزونههای بومی Sidecar را برای executorهای سفارشی، هر بار برای یک خانواده از ارائهدهندگان، اضافه کنید.
چرا ارائهدهندگان مستقیماً در Next تعبیه نشوند
frontend مبتنی بر Next نباید مسئول اجرای ارائهدهندگان باشد. این بخش باید API boundary را فراخوانی کند. سپس backend میتواند تصمیم بگیرد که از executor مبتنی بر TypeScript، Bifrost، CLIProxyAPI یا یک Sidecar بومی در آینده استفاده کند. این رویکرد باعث میشود امضای درخواست، بررسیهای allowlist، سیاست DB و رفتار fallback پیش از هرگونه واگذاری به Sidecar، بهصورت متمرکز باقی بمانند.