OmniRoute/docs/i18n/pl/docs/reference/PROVIDER_PLUGIN_MANIFEST.md

Provider Plugin Manifest (Polski)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 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 · 🇵🇹 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 definiuje bezpieczny dla JSON kontrakt wtyczki dostawcy. open-sse/config/providerPluginManifestRegistry.ts wiąże ten kontrakt z bieżącym rejestrem dostawców dla procesów sidecar, takich jak Bifrost, CLIProxyAPI lub przyszły router w Go/Rust. Rejestr TypeScript pozostaje źródłem prawdy, ale procesy sidecar mogą korzystać z manifestu bez importowania kodu wykonawców, domyślnych ustawień OAuth, nagłówków ani stanu środowiska procesu.

Ten sam manifest jest dostępny przez HTTP pod adresem GET /api/v1/provider-plugin-manifest dla procesów sidecar działających poza procesem głównym.

OmniRoute przekazuje ten adres URL do Bifrost i CLIProxyAPI za pośrednictwem nagłówka żądania X-OmniRoute-Provider-Manifest-Url. Ustaw OMNIROUTE_PROVIDER_MANIFEST_URL, gdy proces sidecar wymaga publicznego adresu URL lub adresu w sieci kontenerowej zamiast lokalnego źródła żądania.

Odświeżanie manifestu

Punkt końcowy HTTP zwraca Cache-Control: public, max-age=60 oraz silny ETag. Proces sidecar powinien zachować ostatni zweryfikowany manifest i podczas odświeżania wysyłać jego ETag w If-None-Match. Odpowiedź 304 Not Modified nie zawiera treści; proces sidecar zachowuje swój manifest w pamięci podręcznej. Jeśli nie istnieje zweryfikowany manifest w pamięci podręcznej, proces sidecar musi wysłać żądanie bezwarunkowe zamiast akceptować odpowiedź 304.

Cel

Przenieść metadane dostawców w stronę kontraktu wtyczki, aby w przyszłości gorąca ścieżka żądań mogła być obsługiwana przez proces sidecar o niższych opóźnieniach, podczas gdy OmniRoute zachowa trasę TypeScript jako bramę polityk i mechanizm rezerwowy. Manifest ma charakter rozszerzający: sam w sobie nie zmienia routingu żądań.

Kontrakt

Manifest zawiera:

• identyfikator i alias dostawcy
• format usługi nadrzędnej i nazwę wykonawcy
• typ uwierzytelniania, nagłówek uwierzytelniania i opcjonalny prefiks uwierzytelniania
• statyczne metadane punktu końcowego
• kwalifikowalność do obsługi przez proces sidecar oraz jawne powody, dla których dostawca powinien pozostać na ścieżce TS
• bezpieczne dla JSON metadane modeli, takie jak długość kontekstu, flagi obsługi obrazów/rozumowania oraz nieobsługiwane parametry
• tagi możliwości, w tym apikey, oauth, custom-executor, passthrough-models, responses, sidecar-candidate, usage-fetch i usage-supported

Manifest celowo wyklucza:

• sekrety klientów OAuth i domyślne wartości sekretów
• rozwiązywanie środowiska uruchomieniowego
• nagłówki żądań i publiczne funkcje pomocnicze poświadczeń
• dynamiczne konstruktory adresów URL
• funkcje wykonawców
• wewnętrzne mechanizmy puli sesji

Tagi możliwości

capabilities to posortowana tablica tagów wyprowadzonych z wpisu rejestru. Integratorzy powinni traktować ją jako przeznaczoną do odczytu maszynowego odpowiedź na pytanie „co potrafi ten dostawca”, zamiast ponownie analizować źródła TypeScript.

Tag	Znaczenie
apikey	Akceptuje klucz API (authType ma wartość apikey lub optional).
oauth	Korzysta z przepływu OAuth lub sesji.
responses	Udostępnia bazowy adres URL interfejsu OpenAI Responses API.
passthrough-models	Udostępnia modele bezpośrednio z usługi nadrzędnej zamiast statycznego katalogu.
custom-executor	Uruchamia wykonawcę innego niż domyślny, dlatego pozostaje na ścieżce TypeScript.
sidecar-candidate	Odzwierciedla sidecar.eligible — można bezpiecznie rozważyć import do procesu sidecar.
usage-fetch	Ma skonfigurowany mechanizm pobierania użycia lub limitów (getUsageForProvider).
usage-supported	Interfejs API użycia akceptuje tego dostawcę (isSupportedUsageConnection).

usage-fetch służy wyłącznie do wykrywania. Informuje, że OmniRoute potrafi odczytywać dane o użyciu dla dostawcy; nie aktywuje pobierania, nie zmienia semantyki limitów ani nie oznacza, że widżet limitów w Dashboardzie jest włączony dla dostawcy — ten widżet jest kontrolowany osobno przez USAGE_SUPPORTED_PROVIDERS. Źródłem prawdy jest USAGE_FETCHER_PROVIDERS w open-sse/services/usage/fetcherProviders.ts.

Ta lista jest indeksowana ciągami znaków akceptowanymi przez dyspozytor użycia, dlatego zawiera zarówno kanoniczne identyfikatory, jak i aliasy oraz jest nieco dłuższa niż liczba oznaczonych dostawców: wpisy, które nie są dostawcami czatu w rejestrze manifestu (na przykład dostawca wyszukiwania firecrawl i dostawca ACP amazon-q), nie mają wpisu manifestu, który można byłoby oznaczyć.

usage-supported określa, czy trasy użycia serwera i Dashboardu akceptują połączenie dla danego dostawcy. Odzwierciedla isSupportedUsageConnection() (src/lib/usage/providerLimits.ts) oraz supportsProviderQuota() (src/shared/utils/providerQuotaVisibility.ts), które są kontrolowane przez USAGE_SUPPORTED_PROVIDERS (open-sse/services/usage/supportedProviders.ts). W przeciwieństwie do usage-fetch jest emitowany wyłącznie na podstawie identyfikatora dostawcy — mechanizm sprawdzający w czasie wykonywania wywołuje USAGE_SUPPORTED_PROVIDERS.includes(providerId) bez rozwiązywania aliasów, dlatego manifest zachowuje tę samą regułę. Oba tagi mają różne zakresy: 3 dostawców ma tylko usage-fetch (opencode, opencode-zen, xai), a 1 ma tylko usage-supported (xiaomi-mimo-token-plan), więc jeden nie implikuje drugiego.

Użycie sidecara

Sidecary powinny traktować sidecar.eligible jako zachowawczy sygnał wskazujący kandydata, a nie jako bezwarunkową decyzję o routingu. Pierwszym celem importu powinni być dostawcy korzystający z kluczy API i statycznych endpointów oraz domyślnego executora. Dostawcy z niestandardowymi executorami webowymi, przepływami OAuth/sesji, dynamicznymi generatorami adresów URL lub konfiguracją puli pozostają na ścieżce awaryjnej TypeScript, dopóki sidecar nie zaimplementuje równoważnego zachowania, a telemetria nie potwierdzi zgodności.

Sugerowane etapy migracji:

1. Wygeneruj i zweryfikuj manifest wtyczek dostawców na podstawie rejestru TS.
2. Dodaj w Bifrost lub CLIProxyAPI obsługę importowania manifestu dla dostawców korzystających z kluczy API i statycznych endpointów.
3. Kieruj ruch kwalifikujących się dostawców przez sidecar sterowany przez OMNIROUTE_RELAY_BACKEND, zachowując włączoną ścieżkę awaryjną TS.
4. Promuj dostawców dopiero wtedy, gdy współczynnik powodzenia, opóźnienie p99, zachowanie przesyłania strumieniowego i obsługa nieobsługiwanych parametrów będą zgodne ze ścieżką TS.
5. Dodawaj natywne wtyczki sidecara dla niestandardowych executorów, po jednej rodzinie dostawców naraz.

Dlaczego nie osadzać dostawców bezpośrednio w Next

Frontend Next nie powinien odpowiadać za wykonywanie operacji dostawców. Powinien wywoływać warstwę graniczną API. Backend może następnie zdecydować, czy użyć executora TypeScript, Bifrost, CLIProxyAPI, czy przyszłego natywnego sidecara. Dzięki temu podpisywanie żądań, sprawdzanie listy dozwolonych elementów, zasady bazy danych i zachowanie awaryjne pozostają scentralizowane przed przekazaniem obsługi do sidecara.