Wersja 1.0.0-alpha.1najnowsza
Rozdział 2.14
Dostawcy i modele AI
Jak router dostawców sztucznej inteligencji (AI) (AI Provider Router) wybiera model z własnej puli kluczy organizacji oraz jak skrypty i narzędzia AI łączą się z systemem Nexus z zewnątrz.
Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Harrow Port Authority utrzymuje dwie instalacje. Ta działająca w odizolowanej sieci operacyjnej typu air-gap (rozdział 2.10, Instalacja w sieci odizolowanej) nie korzysta z żadnego dostawcy hostowanego. W podłączonej do sieci instalacji korporacyjnej, której dotyczy ten rozdział, na większość pytań odpowiada model działający na dwóch węzłach z procesorami graficznymi (GPU) we własnej serwerowni portu. Klucz Google Gemini, opłacany przez Harrow, przejmuje nadmiar ruchu, gdy model lokalny jest zajęty, a Aoife Brennan zablokowała ruch związany ze sztuczną inteligencją (AI) organizacji do obszaru UE. Nikt w Harrow nie konfigurował modelu wewnątrz usługi ani wtyczki. Wskazano jednemu komponentowi, czym dysponuje Harrow, i to ten komponent decyduje o każdym wywołaniu.
Niniejszy rozdział omawia ten komponent – AI Provider Router, który w Części 1 oraz w konsoli jest nazywany centralą AI – a także pulę kluczy, z której on korzysta. Na końcu przedstawiono sposoby, w jakie skrypty i narzędzia AI łączą się z systemem Nexus z zewnątrz: klucze dla skryptów, interfejs programowania aplikacji (API) w architekturze REST (representational state transfer) oraz protokół Model Context Protocol (MCP).
Router dostawców AI (AI Provider Router)
Router działa wewnątrz bramy, nexus-gateway. Jest to jedyna usługa przechowująca dane uwierzytelniające modeli organizacji i podejmująca ostateczną decyzję o tym, który dostawca i który model odpowie na poszczególne żądania. Każda inna część systemu Nexus zwraca się właśnie do niej. Krok przepływu pracy określa swoje preferencje, a router podejmuje decyzję.
Zapytania może składać tylko kilka usług, a każda lista jest ściśle określona w pakiecie chart:
| Przedmiot zapytania | Kto może pytać |
|---|---|
Uzupełnienie (/internal/ai/chat i jego strumień) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Wywołania narzędzi i inne wewnętrzne ścieżki AI | nexus-orchestrator, nexus-workflows |
| Osadzenia (embeddings) i zmiana rankingu (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Każda ścieżka wewnętrzna sprawdza po kolei dwa elementy: wewnętrzny klucz usługi wywołującego oraz tożsamość wywołującego względem powyższej listy. Żądanie bez klucza zostaje odrzucone z kodem MISSING_SERVICE_KEY (401), z nieprawidłowym kluczem – INVALID_SERVICE_KEY (403), żądanie bez informacji o tym, kto wywołuje – MISSING_CALLER_IDENTITY (403), a wywołujący spoza listy – UNAUTHORIZED_CALLER (403). Żadne z tych żądań nie jest ponawiane, ponieważ żadne z nich nie wynika z przejściowego błędu.
Aplikacje i wtyczki nigdy nie pojawiają się na tej liście. Wtyczka deklaruje swoje preferencje w umiejętnościach, które rejestruje i przekazuje przez UNO, silnik przepływów pracy. Następnie orkiestrator odpytuje router w imieniu wtyczki. Właśnie dlatego wyciek jednego klucza tajnego wtyczki pozwala na działanie w jej imieniu, ale nie pozwala na wykorzystanie czyjegokolwiek budżetu na modele.
Pula kluczy organizacji
Klucze modeli należą do organizacji. Każda organizacja korzysta z własnego konta u dostawcy i opłaca własne rachunki, a klucz znajduje się w puli organizacji, zaszyfrowany w usłudze nexus-auth. Za organizacją nie kryje się żaden współdzielony klucz platformy, dzięki czemu żadna organizacja nigdy nie wydaje budżetu innej. Koszt tej zasady jest prosty: organizacja nieposiadająca klucza w swojej puli nie otrzymuje odpowiedzi od AI. Asystent wyświetla błąd MODEL_NOT_CONNECTED (503) i informuje, kto może podłączyć klucz.
Do puli można dodać klucz dla czterech dostawców:
| Identyfikator dostawcy | Wyświetlana nazwa |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Własny serwer modeli
Organizacja może również użyć dowolnego utrzymywanego przez siebie serwera, który obsługuje interfejs API zgodny z OpenAI, takiego jak model na węzłach GPU w Harrow. Instalator wskazuje go w pliku wartości (values):
# harrow-values.yaml (Helm values): the AI part
ai:
localProvider:
baseUrl: "https://models.harrow.example/v1"
installationHosts:
- models.harrow.example
- 10.40.20.0/24
networkPolicy:
externalEgressCIDRs:
- 10.40.20.0/24ai.localProvider.baseUrl kieruje zgodny z OpenAI adapter bramy na Państwa serwer. W ramach instalacji gniazdo scaleway w puli łączy się z tym serwerem, więc klucz dodany dla scaleway jest kluczem oczekiwanym przez Państwa własny serwer.
ai.installationHosts zawiera listę nazw hostów znajdujących się wewnątrz instalacji, oprócz własnej domeny usług wydania i trzech hostów publicznych. Każdy wpis to nazwa hosta, .suffix, adres IP lub zakres IPv4 Classless Inter-Domain Routing (CIDR). Router używa tej listy, aby odróżnić wywołanie pozostające w lokalizacji od wywołania wychodzącego na zewnątrz, co jest wykazywane przez weryfikację „Nic nie opuszcza tej lokalizacji” na stronie Podłącz model na własnym sprzęcie.
Polityka sieciowa jest równie istotna co router. Przestrzeń nazw domyślnie blokuje cały ruch wychodzący (egress), więc brama może połączyć się z serwerem modeli poza przestrzenią nazw tylko wtedy, gdy jego zakres znajduje się w networkPolicy.externalEgressCIDRs. To samo dotyczy dostawcy hostowanego: jeśli Harrow chce, aby klucz Gemini odpowiadał na zapytania, zakresy adresów tego dostawcy również muszą zostać tam wymienione, w przeciwnym razie wywołanie nigdy nie opuści klastra. Rozdział 2.16, Bezpieczeństwo i sieci, omawia tę politykę szczegółowo.
Dodawanie i wycofywanie kluczy
Właściciele i administratorzy organizacji zarządzają jej pulą. Nikt inny nie może zobaczyć kluczy ani ich zmienić, a żądanie od innych osób zostaje odrzucone z kodem AUTHORITY_EXCEEDED.
W konsoli
W edycji Enterprise pula jest przechowywana w centrali AI, pod silnikami. W edycji Community te same klucze są przechowywane w sekcji Ustawienia, Modele AI. Ta strona to podstawowy router, w którym dodaje się klucze oraz adres modelu lokalnego i wybiera, który model wykonuje poszczególne zadania. W obu przypadkach przy każdym kluczu wyświetlana jest informacja, kto i kiedy go ustawił („Ustawiony przez: Aoife, 3 wrz”) oraz zamaskowana podpowiedź składająca się z maksymalnie czterech ostatnich znaków, np. ••••7f2q. Sam klucz nigdy nie jest pokazywany ponownie po jego dodaniu.
Przez interfejs BFF API
Warstwa BFF (backend for frontend) konsoli obsługuje trzy ścieżki dla puli. Należy je wywoływać z osobistym tokenem dostępu użytkownika: informacja o organizacji pochodzi z tokena, nigdy z treści żądania.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET zwraca dostawców w puli, informację, czy każdy z nich może odpowiadać, każdy klucz oznaczony jego podpowiedzią oraz dostawców, dla których można dodać klucz. Dodanie klucza wymaga treści JSON z dwoma polami wymaganymi i jednym opcjonalnym:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Klucz jest przesyłany tylko raz. Usługa nexus-auth szyfruje go i powiadamia router, a odpowiedź zawiera jedynie podpowiedź. Odpowiedź to 201 z identyfikatorem nowego klucza i jego wierszem: „Dodano. Klucz Google Gemini ••••7f2q znajduje się w puli AI organizacji i AI Provider Router może już kierować do niego ruch”. Etykieta może mieć maksymalnie 100 znaków, a klucz to pojedynczy ciąg znaków bez spacji o długości do 4096 znaków. Jakiekolwiek inne pole w treści lub pole wskazujące organizację bądź osobę powoduje odrzucenie żądania.
Wycofanie klucza wymaga pustej treści żądania. Router natychmiast przestaje kierować ruch do klucza, a nexus-auth zachowuje go ze statusem wycofanego, dzięki czemu jego historia pozostaje dostępna. Żaden element w puli nie jest nigdy usuwany.
| Odrzucenie | HTTP | Kiedy |
|---|---|---|
VALIDATION_FAILED |
400 | Treść inna niż {provider, api_key, label?}, nieznany dostawca lub osobista subskrypcja użytkownika przekazana jako klucz organizacji |
AUTHORITY_EXCEEDED |
403 | Wywołujący nie jest właścicielem ani administratorem organizacji |
RECORD_NOT_FOUND |
404 | W puli organizacji nie ma klucza o podanym identyfikatorze |
TRANSITION_NOT_PERMITTED |
409 | Klucz został już wycofany |
TENANT_NOT_A_PARAMETER |
403 | W treści lub zapytaniu wskazano organizację |
Stany kluczy
Każdy klucz w puli znajduje się w jednym z sześciu stanów. Tylko klucz będący w użyciu odpowiada na czacie.
| Stan | Co to oznacza |
|---|---|
in_use |
Klucz odpowiada na zapytania aż do daty wygaśnięcia, o ile została określona. |
resting |
Router wstrzymał jego użycie po wystąpieniu błędów, do określonego czasu. W międzyczasie żądania trafiają do kolejnego klucza. |
exhausted |
Klucz wyczerpał swój limit u dostawcy. |
invalid |
Dostawca już go nie akceptuje. |
expired |
Klucz stracił ważność w dniu wygaśnięcia. |
withdrawn |
Administrator wycofał klucz. Pozostaje on na liście jako wpis historyczny. |
Klucz, który zwróci błąd, odpoczywa przez 60 sekund. Po 5 błędach z rzędu router wyłącza go, przenosi jego udział w ruchu na pozostałe klucze i zapisuje powiadomienie PROVIDER_KEY_SWITCHED_OFF. Nikt nie spotyka się z odmową, dopóki inny klucz może udzielić odpowiedzi.
Gdy dostawca nie ma żadnego klucza w użyciu, pula informuje o przyczynie („Brak klucza w użyciu: 1 wycofany, 1 wygasły”). Gdy żaden dostawca w puli nie ma klucza w użyciu, czat zostaje odrzucony z błędem NO_PROVIDER_FOR_ROLE (422) oraz sposobem rozwiązania: właściciel lub administrator musi dodać klucz organizacji. Jest to stan konfiguracji, który pozostaje na ekranie, dopóki ktoś go nie naprawi.
Role, zasady i preferencje
Router operuje pojęciem ról. Każde żądanie dotyczy jednej z pięciu: default, fast, reasoning, code lub long_context. Każdy model należy również do określonej warstwy: frontier, standard lub fast, przy czym wyższa warstwa jest preferowana, gdy rola na to pozwala. Organizacja decyduje, który dostawca obsługuje poszczególne role (przypisania ról) oraz w jakiej kolejności następuje przełączanie awaryjne w przypadku błędu dostawcy (drabina polityki routingu). Administratorzy konfigurują oba te elementy w centrali AI. Usługa nexus-auth udostępnia je również pod adresami /auth/org/<organisation-id>/settings/ai-provider/role-assignments i /auth/org/<organisation-id>/settings/ai-provider/routing-policy dla klucza administratora posiadającego uprawnienie ai_provider:manage.
Wywołujący mogą określić swoje preferencje. Wiersz umiejętności może zawierać preferowanego dostawcę i preferowany model, a także profil możliwości. Router traktuje każdy z tych elementów inaczej:
- Preferowany dostawca jest uwzględniany tylko wtedy, gdy organizacja ma włączonego tego dostawcę i posiada dla niego klucz. W przeciwnym razie router dokonuje zastąpienia.
- Preferowany model jest uwzględniany, gdy znajduje się w katalogu danego dostawcy i pasuje do profilu.
- Profil możliwości to filtr, który nigdy sam nie dokonuje wyboru. Może wymagać minimalnego okna kontekstowego, obsługi narzędzi, analizy obrazu (vision), osadzeń, długiego kontekstu lub określonej rezydencji danych. Wszystko, co nie spełnia tych wymogów, jest odrzucane.
Router dokonuje wyboru w ustalonej kolejności. Uwzględnia preferencje, jeśli to możliwe, następnie próbuje użyć innego modelu tego samego dostawcy, a potem przypisania roli i dowolnego innego dostawcy posiadającego klucz, którego katalog pasuje do wymagań. Jeśli podano profil i żaden katalog do niego nie pasuje, żądanie zostaje odrzucone z kodem MODEL_CAPABILITY_UNAVAILABLE (422). Jeśli nic nie jest przypisane i nic nie pasuje, zwracany jest kod NO_PROVIDER_FOR_ROLE (422). Nie istnieje domyślny model ostatniej szansy. Nieskonfigurowana rola zgłasza wyraźny błąd, a router własnymi słowami informuje, co należy ustawić.
Rezydencja danych to jedyne ograniczenie, którego nie można obejść przez zastąpienie. Profil z parametrem eu_only jest obsługiwany przez dostawcę z UE lub odrzucany. Harrow ustawia tę blokadę dla całej organizacji, dlatego centrala rysuje drugiego dostawcę hostowanego, znajdującego się w regionie USA, jako wyłączonego.
Umiejętność może również przypiąć jeden konkretny model, jeśli wymaga go do działania. Nawet wtedy router używa do tego własnego klucza organizacji, a przy jego braku nic nie udzieli odpowiedzi. Wywołujący nigdy nie może zmusić systemu Nexus do użycia dostawcy, którego organizacja nie skonfigurowała.
Po wybraniu dostawcy przełączanie awaryjne (failover) stanowi osobną kwestię. Błąd 429, 5xx lub awaria sieci przenosi żądanie w dół drabiny do kolejnego dostawcy. Błąd 400, 401, 403 lub 404 natychmiast zatrzymuje proces, ponieważ dane uwierzytelniające i struktura żądania nie są przenoszone między dostawcami, a ponowienie próby zużyłoby tylko limit, prowadząc do tego samego błędu.
Aby sprawdzić, co wybrałby router, zanim ktokolwiek zada pytanie, należy odczytać GET /api/ai/routing-policy/effective na bramie, używając osobistego tokena użytkownika. Zwraca on model dla zalogowanej organizacji lub słowną odmowę routera, gdy brak odpowiedniego modelu, nie wysyłając przy tym żadnego żądania do samego modelu.
Monitorowanie routera
Pasek wskaźników na dole każdej strony pokazuje aktualnie używany model („Model: lokalny”). W edycji Enterprise widok Centrala AI, na żywo rysuje ruch routera w czasie rzeczywistym: żądania od asystenta, zadań i aplikacji przepływające przez role do dostawców i kluczy, klucz podczas 60-sekundowego odpoczynku oznaczony na szaro, klucz wyłączony oznaczony na czerwono oraz przełączenie awaryjne do dostawcy hostowanego, gdy model lokalny jest zajęty. Obok przepływu wyświetlane są wykresy obciążenia poszczególnych dostawców, liczby żądań na sekundę i czasu oczekiwania. Tomás ma ten widok otwarty przez pierwszy tydzień po każdej zmianie polityki routingu, ponieważ błędne przypisanie roli uwidacznia się tam w ciągu kilku minut jako ruch kierowany w niezamierzone miejsce.
W edycji Community na stronie Modele AI znajduje się przycisk Przetestuj każdy model, który sprawdza każdy skonfigurowany model i oznacza, czy odpowiada. To najszybszy sposób na potwierdzenie działania nowego klucza, zanim ktokolwiek zacznie na nim polegać.
Osadzenia (embeddings)
Wyszukiwarka i graf wiedzy przekształcają tekst w wektory. Domyślnie instalacja wykonuje to za pomocą modelu osadzeń (embedding), który działa wewnątrz klastra na procesorze, dzięki czemu żaden tekst nie opuszcza lokalizacji w celu osadzenia, a organizacja nie potrzebuje do tego klucza. Wykorzystanie dostawcy hostowanego do osadzeń jest świadomym wyborem organizacji; proces ten przechodzi wówczas przez tę samą pulę i podlega tym samym zasadom.
Tylko trzy usługi mogą odpytywać router o osadzenia lub zmianę rankingu: nexus-graphrag, nexus-skills-engine oraz nexus-workflows. GraphRAG tworzy osadzenia jako organizacja, do której należy treść, z ustawieniami tej organizacji, i nie przechowuje własnego klucza dostawcy. Gdy organizacja zmienia swój model osadzeń, usługa nexus-workflows uruchamia zadanie ponownego osadzania dla magazynów danych tej organizacji.
Poświadczenia indywidualne pozostają osobiste
Niektóre dane uwierzytelniające należą do jednej osoby. Typowym przypadkiem jest subskrypcja Claude Max, powiązana przez logowanie na osobiste konto użytkownika. Takie dane uwierzytelniające nigdy nie są kluczem organizacji: pula odrzuca je z kodem VALIDATION_FAILED, nigdy nie są wymieniane w tabeli kluczy organizacji i nie pojawiają się na ekranie żadnej innej osoby.
Klucze modeli nigdy też nie trafiają w inne miejsca. Strona Klucze danych zewnętrznych, która przechowuje klucze do zewnętrznych źródeł danych, odrzuca wszystko, co przypomina klucz modelu AI, zwracając błąd AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Jeśli czytnik plików znajdzie klucze modeli wewnątrz dokumentu lub konfiguracji, gdzie nie powinny się znajdować, rejestruje zdarzenie CREDENTIALS_IN_WRONG_PLACE, a administrator je usuwa i zastępuje.
Skrypty, REST i MCP
Nexus posiada trzy hosty publiczne. W Harrow są to console.harrow.example dla konsoli, api.harrow.example dla bramy oraz auth.harrow.example do logowania. Skrypty i narzędzia korzystają z drugiego i trzeciego.
Klucze dla skryptów
Skrypt loguje się za pomocą klucza utworzonego w sekcji Ustawienia, Klucze dla skryptów. Każdy klucz ma nazwę, zakres uprawnień (na przykład „Tylko uruchomienie liczenia na placu przez drony”), osobę, która go utworzyła, oraz datę końcową; organizacja może zablokować maksymalny czas życia klucza. Klucz tajny jest wyświetlany tylko raz podczas tworzenia. Należy skopiować go do magazynu tajemnic skryptu, ponieważ Nexus zachowuje jedynie jego cztery ostatnie znaki. Klucz jest wycofywany, nigdy usuwany: przestaje działać natychmiast i pozostaje na liście wraz z historią wszystkich wykonanych wywołań. Rotacja nadaje kluczowi nową wartość tajną i wyświetla ją jednorazowo.
Każdy klucz ma własną stronę z liczbą wywołań dziennie, wywołaniami według usług oraz dziennikiem aktywności zawierającym czas, adres, usługę i wynik. Wywołanie wykraczające poza zakres uprawnień klucza zostaje odrzucone i zapisane w dzienniku.
Usługa nexus-auth udostępnia te same klucze zalogowanej osobie pod adresem https://auth.harrow.example/api-keys: umożliwia tworzenie i wyświetlanie listy, a następnie odczyt, zmianę, unieważnienie lub rotację pojedynczego klucza według jego identyfikatora.
REST przez bramę
Wywołania REST należy wysyłać na adres https://api.harrow.example z nagłówkiem Authorization: Bearer <token-or-key>. Każdy klucz musi należeć do organizacji. Klucz nieprzypisany do żadnej organizacji zostaje odrzucony z kodem TOKEN_ORG_MISSING (403) przez każdą usługę weryfikującą klucze przez nexus-auth.
Wywołujący, który wysyła zapytania zbyt często, otrzymuje odpowiedź 429 z kodem RATE_LIMITED, nagłówkiem Retry-After oraz informacją o limicie i oknie czasowym w treści odpowiedzi. Należy odczekać wskazaną liczbę sekund. W edycji Enterprise administratorzy ustawiają limity na klucz, na aplikację i na jednostkę w sekcji Ustawienia, Limity zapytań (zob. rozdział 2.16, Bezpieczeństwo i sieci).
MCP dla narzędzi AI
Narzędzia AI obsługujące protokół Model Context Protocol łączą się z adresem https://api.harrow.example/mcp. Logują się przez serwer OAuth 2.1 (OAuth to otwarty standard delegowanej autoryzacji) pod adresem https://auth.harrow.example, który obsługuje samodzielną rejestrację klienta przez narzędzie, dzięki czemu narzędzie takie jak Claude Code czy Cursor rejestruje się samo i otwiera przeglądarkę użytkownika w celu zalogowania. Połączenie działa wówczas w imieniu tej konkretnej osoby, z jej uprawnieniami i niczym więcej. Zalogowana osoba może pobrać gotową konfigurację dla narzędzia wiersza poleceń z adresu https://auth.harrow.example/api/v1/mcp/cli-config.
Wywołania narzędzi wymagające modelu przechodzą przez router jak wszystko inne, w ramach organizacji danej osoby.




