Zarządzanie kanałami w bramie AI

„Kanał" (Channel) to konfiguracja punktu integracji dostawcy w bramie AI — przechowuje adres dostawcy, rzeczywisty klucz API Key, dostępne modele oraz informacje o wycenie i limitach. To właśnie na podstawie tych kanałów brama kieruje żądania wysyłane przez aplikacje do odpowiedniego dostawcy. W tym artykule opisano, jak dodawać, konfigurować, testować i zarządzać kanałami.

Wymagania wstępne

• ServBay jest zainstalowany i uruchomiony oraz zalogowano się na konto ServBay (logowanie jest wymagane przed dodaniem kanału).
• Przygotowano rzeczywisty klucz API Key docelowego dostawcy (w przypadku dostawców lokalnych, takich jak Ollama / LM Studio, można go pominąć).
• Jeśli nie znasz ogólnej architektury bramy AI, zalecamy najpierw przeczytać Wprowadzenie do bramy AI.

Dodawanie kanału

Przejdź do strony Brama AI → Kanały (Channels) i kliknij Dodaj (Add), aby otworzyć kreatora. Kreator składa się z trzech kroków.

Krok 1: Wybór dostawcy

Dostawcy są wyświetlani pogrupowani według kategorii. Aby dokonać wyboru, kliknij kartę:

• Główni (Mainstream): OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• Chiny (China): DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao (Volcano), ERNIE Bot (Wenxin Yiyan), Hunyuan, MiniMax, 01.AI (Yi), StepFun.
• Lokalni (Local): Ollama, LM Studio.
• Niestandardowi (Custom): OpenAI Compatible, Custom.

Po wybraniu dostawcy brama automatycznie wypełni domyślny Base URL tego dostawcy.

Przełączanie między dwoma regionami

Tacy dostawcy z Chin, jak Qwen, Zhipu GLM, Kimi, Doubao (Volcano), Hunyuan, MiniMax i StepFun, udostępniają jednocześnie dwa zestawy punktów końcowych: krajowy i globalny. Przy wyborze takiego dostawcy w kreatorze pojawi się selektor „Region" (🇨🇳 Krajowy / 🌐 Globalny); po przełączeniu Base URL automatycznie zaktualizuje się do adresu odpowiedniego regionu.

Krok 2: Wypełnienie konfiguracji

• Nazwa kanału (wymagana) — służy do identyfikacji kanału na liście; można ją dostosować.
• Base URL (wymagany) — adres API dostawcy. W przypadku większości dostawców jest już wypełniony automatycznie; Azure OpenAI i Custom wymagają ręcznego wprowadzenia.
• API Key (opcjonalny) — rzeczywisty klucz dostawcy. Jeśli pozostawisz to pole puste, będzie można jedynie sprawdzić osiągalność punktu końcowego, bez weryfikacji ważności klucza; dostawcy lokalni (Ollama / LM Studio) zazwyczaj nie wymagają podawania klucza.
• Modele — do wyboru są dwa sposoby (wybierz jeden):
  • Automatyczne wykrywanie: po kliknięciu wykrywania brama wywołuje interfejs listy modeli dostawcy, pobiera dostępne modele, a Ty wybierasz wiele z nich w formie tagów (chip).
  • Ręczne wprowadzanie: wpisz nazwę modelu bezpośrednio. W przypadku kanału Azure należy podać nazwę wdrożenia (Deployment name), a nie nazwę modelu.
• Priorytet / waga — gdy wiele kanałów może obsłużyć ten sam model, brama na tej podstawie decyduje o routingu i rozdziale obciążenia.

Uwaga dotycząca Azure OpenAI

W polu „Model" kanału Azure należy podać utworzoną w portalu Azure nazwę wdrożenia (Deployment name), a nie nazwę bazowego modelu. W polu Base URL należy również podać punkt końcowy Twojego zasobu Azure.

Krok 3: Potwierdzenie i przesłanie

Sprawdź podsumowanie konfiguracji i prześlij je. Po pomyślnym przesłaniu nowy kanał pojawi się na liście kanałów wraz z bieżącym stanem zdrowia.

Sondowanie możliwości i strategia routingu

Po dodaniu kanału brama przeprowadza na nim sondowanie możliwości (capability probing) — jest to najważniejszy mechanizm inteligentnego routingu w bramie AI. Wynik sondowania decyduje o tym, czy narzędzia takie jak Claude Code mogą być używane bezpośrednio, czy wymagane jest utworzenie mapowania modeli oraz jak wybrać model docelowy.

Dwa kluczowe wskaźniki sondowania

Brama bada dwa kluczowe fakty dla każdego kanału (każdy w trzech stanach: true / false / nieokreślony):

Element sondowania	Znaczenie	true	false	Nieokreślony
Rozpoznawanie nazw modeli Claude (accepts_claude_names)	Czy kanał natywnie rozpoznaje nazwy modeli claude-opus-* / claude-sonnet-* / claude-haiku-*	Można połączyć bezpośrednio, bez mapowania	Nie rozpoznaje; konieczne jest utworzenie mapowania tłumaczącego nazwy claude-* na rzeczywiste nazwy modeli nadrzędnych	Sondowanie nie zostało uruchomione lub się nie powiodło; nie można wyciągnąć wniosków
Rozróżnianie według poziomu (tier_aware)	Czy podmiot nadrzędny sam zwraca różne modele w zależności od poziomu opus / sonnet / haiku	Podmiot nadrzędny już rozróżnia poziomy; wystarczy pozostawić to jemu	Nie rozróżnia (zwraca ten sam model dla wszystkich poziomów); wymagane jest utworzenie mapowania w bramie	Nie można wykryć lub nigdy nie sondowano

Dlaczego sondować, a nie zgadywać

Zachowanie różnych dostawców znacznie się różni. OpenAI natywnie nie rozpoznaje nazw modeli claude-*; niektórzy pośredni dostawcy rozpoznają je poprzez przekazywanie; natomiast dostawcy oferujący pakiety do kodowania (np. subskrypcje Claude Pro/Max) mogą rozpoznawać wyłącznie konkretne nazwy modeli powiązane z subskrypcją. Brama nie zgaduje na podstawie typu kanału, lecz najpierw przeprowadza rzeczywiste sondowanie, a dopiero potem decyduje o strategii routingu.

Rozstrzygnięcie routingu: pięć stanów

Gdy na stronie Brama AI → Zarządzanie integracjami → Klient wykonasz dla Claude Code „przejęcie jednym kliknięciem", brama agreguje wyniki sondowania wszystkich kandydujących kanałów i ustala rozstrzygnięcie routingu:

Stan kandydujących kanałów	Rozstrzygnięcie	Znaczenie
Brak dostępnych kandydujących kanałów (brak kanałów / wszystkie w złym stanie / brak kanałów w zakresie klucza wirtualnego)	Brak kandydujących kanałów	Musisz najpierw dodać lub naprawić kanały
Wartość sondowania któregokolwiek kandydującego kanału jest nieokreślona	Niezweryfikowany	Należy najpierw przeprowadzić sondowanie; nie można tworzyć mapowania bez wcześniejszej weryfikacji
Wszystkie kandydujące kanały rozpoznają nazwy modeli claude	Połączenie bezpośrednie	Bez mapowania; żądania są przekazywane w niezmienionej formie
Żaden z kandydujących kanałów nie rozpoznaje nazw modeli claude	Wymagane mapowanie	Brama tworzy mapowania dla trzech poziomów, tłumacząc claude-* na rzeczywiste nazwy modeli nadrzędnych
Wśród kandydatów są zarówno rozpoznające, jak i nierozpoznające	Mieszany	Wymagana decyzja ręczna (rozpoznające — bezpośrednio, nierozpoznające — przez mapowanie)

Mapowanie modeli: tłumaczenie claude-* na rzeczywiste modele nadrzędne

Gdy rozstrzygnięcie brzmi „wymagane mapowanie", brama tworzy dla Claude Code trzy reguły mapowania modeli, z których każda obejmuje jeden z trzech poziomów:

Nazwa modelu wysyłana przez Claude Code	Reguła mapowania (symbol wieloznaczny)	Mapowana na
claude-opus-*	Dopasowuje wszystkie żądania z poziomu opus	Model flagowy wśród kandydujących kanałów
claude-sonnet-*	Dopasowuje wszystkie żądania z poziomu sonnet	Model flagowy lub model standardowy wśród kandydujących kanałów
claude-haiku-*	Dopasowuje wszystkie żądania z poziomu haiku	Lekki model wśród kandydujących kanałów

Reguły wyboru modelu docelowego (zgodnie z priorytetem fallbacku):

1. Presety rodzin: jeśli wśród kandydujących modeli pojawi się znane słowo kluczowe rodziny (np. glm), jako cel dla poziomów opus/sonnet zostanie bezpośrednio wybrany model flagowy tej rodziny (np. glm-5.2), a jako cel dla poziomu haiku — lekki model tej rodziny (np. glm-4.7-flash).
2. Dopasowanie słów kluczowych: gdy brak presetu rodziny, dla opus/sonnet wybierany jest pierwszy model z listy kandydatów; dla haiku — pierwszy model spośród kandydatów dopasowany do lekkiego słowa kluczowego (flash / mini / lite / air / small / turbo / haiku).
3. Fallback: jeśli nadal brak dopasowania, dla wszystkich trzech poziomów wybierany jest pierwszy model z listy kandydatów.

Błędna konfiguracja poziomu haiku jest najkosztowniejsza

Poziom haiku w Claude Code generuje największą liczbę wywołań (używa się go przy każdym lekkim wywołaniu podczas rozmowy). Jeśli przez pomyłkę przypiszesz model flagowy do poziomu haiku, rachunek może wzrosnąć kilkukrotnie. Tabela dopasowania słów kluczowych w bramie obejmuje 7 lekkich przyrostków (flash / mini / lite / air / small / turbo / haiku), dzięki czemu ciężki model nie trafi do poziomu haiku.

Mechanizm zapisu mapowania

Po potwierdzeniu przejęcia brama zapisuje rekordy mapowania przez API /admin/model-mappings. Każdy rekord mapowania zawiera:

• Protokół źródłowy (source_protocol): anthropic (żądania wysyłane przez Claude Code mają format Anthropic)
• Dopasowanie modelu źródłowego (source_model_pattern): symbol wieloznaczny, np. claude-opus-*
• Protokół docelowy (target_protocol): openai (ujednolicony format OpenAI wysyłany do podmiotu nadrzędnego)
• Model docelowy (target_model): konkretna nazwa modelu wybrana w wyniku sondowania

Zapis jest idempotentny — powtórne przejęcie nie tworzy zduplikowanych mapowań; przed zapisem pobierana jest istniejąca lista mapowań w celu porównania.

Reguły routingu w czasie działania: failover i degradacja

Oprócz statycznych mapowań zapisywanych na etapie przejęcia brama obsługuje również reguły routingu w czasie działania (routing rules), które podejmują dynamiczne decyzje, gdy żądanie przechodzi przez bramę:

Pole reguły	Działanie
Warunek wyzwalający (condition_type)	Kiedy następuje degradacja, np. wyczerpanie limitu kanału (quota_exhausted)
Próg kosztu (cost_threshold_usd)	Opcjonalnie: wyzwalane, gdy skumulowany koszt tego kanału przekroczy próg
Akcja (action_type)	Co się dzieje po wyzwoleniu, np. przełączenie na wskazany kanał zapasowy (switch_to)
Kanał docelowy (target_channel_id)	Kanał zapasowy, na który następuje degradacja
Model docelowy (target_model)	Opcjonalnie: jednoczesna zmiana modelu podczas degradacji na kanał zapasowy

Łącząc wiele reguł routingu, możesz uzyskać: automatyczne przełączenie na punkt końcowy rozliczany za zużycie w kanale B, gdy limit subskrypcji kanału A się wyczerpie; degradację do tańszego modelu, gdy 24-godzinny koszt kanału przekroczy limit.

Równoważenie obciążenia i priorytety

Gdy wiele zdrowych kanałów może obsłużyć ten sam model, brama dokonuje wyboru według następującej strategii:

• Tryb priorytetu (domyślny): wybierany jest tylko kanał o najwyższym priorytecie; wśród kanałów o tym samym priorytecie brama rozdziela żądania według wewnętrznych wag.
• Tryb round-robin (round_robin): żądania są przydzielane naprzemiennie pomiędzy wszystkimi zdrowymi kandydującymi kanałami.

Priorytet ustawia się w konfiguracji kanału (im większa liczba, tym wyższy priorytet), a pole allowed_channels klucza wirtualnego ogranicza zakres dostępnych kanałów.

Test łączności

Na liście kanałów można przeprowadzić test łączności dla pojedynczego kanału. Test obejmuje dwa wymiary:

• Osiągalność punktu końcowego (reachable) — sprawdza, czy Base URL jest osiągalny (czy sieć i adres są poprawne).
• Ważność klucza (authenticated) — faktycznie wywołuje interfejs dostawcy, aby zweryfikować ważność klucza API Key. Weryfikacja odbywa się tylko wtedy, gdy podano klucz API Key.

Wyniki testu pokazują: opóźnienie w obie strony (w milisekundach), znacznik stanu oraz komunikat o błędzie.

TIP

W kreatorze dodawania, jeśli punkt końcowy jest nieosiągalny, przejście do następnego kroku zostanie zablokowane; jeśli punkt końcowy jest osiągalny, ale klucz jest nieprawidłowy, pojawi się jedynie ostrzeżenie i możesz kontynuować (np. jeśli zamierzasz dodać klucz później).

Konfiguracja zaawansowana

Podczas dodawania lub edytowania kanału można rozwinąć konfigurację zaawansowaną, służącą do rozliczania kosztów i kontroli limitów:

• Mnożnik wyceny (Rate Multiplier) — mnoży oficjalną cenę dostawcy przez określony współczynnik, co ułatwia rozliczanie według Twojego rzeczywistego kosztu lub ceny odsprzedaży; domyślnie 1.0.
• Struktura rozliczeń — opisuje sposób rozliczania kanału, np. rozliczenie za zużycie (pay as you go), subskrypcja (subscription), pakiet (package).
• Saldo — źródło salda można wybrać jako wartość stałą, rozliczenie OSS lub ręczne prowadzenie; przy wyborze rozliczenia OSS można dodatkowo określić typ rozliczenia. Saldo i czas aktualizacji są wyświetlane w szczegółach kanału tylko do odczytu.
• Data wygaśnięcia subskrypcji — w przypadku kanałów typu subskrypcja / pakiet można zapisać datę wygaśnięcia.
• Limity — można ustawić górny limit według liczby tokenów, liczby żądań lub kwoty, a także wybrać okres (dzienny / tygodniowy / miesięczny / niestandardowy). Po wyczerpaniu limitu kanał jest automatycznie wykluczany z routingu, co stanowi zawór bezpieczeństwa chroniący przed nieoczekiwanym przekroczeniem budżetu.

Edytowanie i usuwanie kanałów

• Edytowanie — otwórz kanał na liście kanałów, aby zmienić nazwę, Base URL, klucz API Key, modele oraz konfigurację zaawansowaną.
• Usuwanie — po usunięciu kanału klucze wirtualne zależne od tego kanału nie będą już mogły być do niego kierowane; zachowaj ostrożność.

Stan zdrowia

Lista kanałów oraz strona przeglądu na bieżąco wyświetlają stan zdrowia każdego kanału (prawidłowy / zdegradowany / niedostępny), co pomaga szybko wykryć niesprawne konfiguracje dostawców.

Często zadawane pytania (FAQ)

• P: Podczas dodawania kanału pojawia się komunikat o konieczności zalogowania?
  • O: Brama AI to funkcja dodatkowa ServBay; przed dodaniem kanału / klucza należy zalogować się na konto ServBay — wystarczy postępować zgodnie z instrukcjami w interfejsie.
• P: Pojawia się komunikat o osiągnięciu maksymalnej liczby kanałów?
  • O: Liczba możliwych do utworzenia kanałów zależy od planu konta; po osiągnięciu limitu możesz usunąć nieużywane kanały lub uaktualnić plan.
• P: Automatyczne wykrywanie modeli nie pobiera listy?
  • O: Najpierw upewnij się, że Base URL jest poprawny, a klucz API Key ważny (możesz to zweryfikować za pomocą „Ważności klucza" w teście łączności); niektórzy dostawcy wymagają ważnego klucza, aby zwrócić listę modeli; możesz też przejść na ręczne wpisywanie nazw modeli.
• P: Czy integracja lokalnych Ollama / LM Studio wymaga podania klucza?
  • O: Zazwyczaj nie. Wystarczy upewnić się, że odpowiednia usługa lokalna jest uruchomiona i nasłuchuje na domyślnym porcie (Ollama 11434, LM Studio 1234).

Podsumowanie

Kanały stanowią podstawę routingu żądań w bramie AI. Dzięki trzystopniowemu kreatorowi możesz szybko podłączyć blisko 20 dostawców, a dzięki przełączaniu między dwoma regionami, automatycznemu wykrywaniu modeli i dwuwymiarowym testom łączności zapewnić poprawność konfiguracji, a następnie precyzyjnie zarządzać kosztami za pomocą zaawansowanych ustawień, takich jak wycena i limity. Po skonfigurowaniu kanałów możesz utworzyć klucze wirtualne do użytku przez aplikacje i narzędzia.