Verzia 1.0.0-alpha.1najnovšia
Kapitola 2.14
Poskytovatelia a modely AI
Ako smerovač poskytovateľov umelej inteligencie (AI) vyberá model z vlastného fondu kľúčov organizácie a ako skripty a nástroje AI pristupujú k systému Nexus zvonku.
Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

Harrow Port Authority prevádzkuje dve inštalácie. Tá v oddelenej prevádzkovej sieti (air-gapped) (kapitola 2.10, Oddelená inštalácia) nemá vôbec žiadneho hostovaného poskytovateľa. V pripojenej firemnej inštalácii, ktorej sa venuje táto kapitola, na väčšinu otázok odpovedá model bežiaci na dvoch uzloch s grafickými procesormi (GPU) vo vlastnej serverovni prístavu. Kľúč Google Gemini, za ktorý platí Harrow, preberá prebytočnú záťaž, keď je lokálny model zaneprázdnený, a Aoife Brennan uzamkla prevádzku umelej inteligencie (AI) organizácie pre región EÚ. Nikto v Harrow nenakonfiguroval model priamo v službe alebo zásuvnom module. Jednému komponentu oznámili, čo Harrow vlastní, a tento komponent rozhoduje o každom volaní.
Táto kapitola sa venuje tomuto komponentu, smerovaču AI Provider Router, ktorý 1. časť a konzola nazývajú AI ústredňa, a fondu kľúčov, z ktorého čerpá. Na záver opisuje spôsoby, akými sa skripty a nástroje AI spájajú so systémom Nexus zvonku: kľúče pre skripty, aplikačné programovacie rozhranie (API) typu REST (representational state transfer) a protokol Model Context Protocol (MCP).
Smerovač poskytovateľov AI
Smerovač beží vo vnútri brány nexus-gateway. Je to jediná služba, ktorá uchováva prihlasovacie údaje k modelom organizácie, a robí konečné rozhodnutie o tom, ktorý poskytovateľ a ktorý model odpovie na každú požiadavku. Každá iná časť systému Nexus sa pýta práve jeho. Krok pracovného postupu povie, čo by chcel, a smerovač rozhodne.
Pýtať sa môže len niekoľko služieb a každý zoznam je pevne daný v charte:
| Čo sa požaduje | Kto sa môže pýtať |
|---|---|
Doplnenie (/internal/ai/chat a jeho prúd) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Volania nástrojov a ostatné interné trasy AI | nexus-orchestrator, nexus-workflows |
| Vektorové vkladania (embeddings) a preusporiadanie (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Každá interná trasa postupne kontroluje dve veci: interný kľúč služby volajúceho a identitu volajúceho voči vyššie uvedenému zoznamu. Požiadavka bez kľúča je odmietnutá s kódom MISSING_SERVICE_KEY (401), nesprávny kľúč s INVALID_SERVICE_KEY (403), požiadavka, ktorá neuvádza, kto volá, s MISSING_CALLER_IDENTITY (403), a volajúci mimo zoznamu s UNAUTHORIZED_CALLER (403). Žiadny z týchto prípadov sa neopakuje, pretože nejde o prechodnú chybu.
Aplikácie a zásuvné moduly sa na tomto zozname nikdy neobjavia. Zásuvný modul deklaruje svoje požiadavky v zručnostiach, ktoré registruje a odosiela cez UNO, engine pracovných postupov. Orchestrátor sa potom opýta smerovača v mene zásuvného modulu. Preto jeden uniknutý tajný kľúč zásuvného modulu dokáže vystupovať ako daný modul, ale nemôže minúť nikoho rozpočet na modely.
Fond kľúčov organizácie
Kľúče k modelom patria organizácii. Každá organizácia si prináša vlastný účet poskytovateľa a platí vlastné faktúry, pričom kľúč je uložený vo fonde organizácie a zašifrovaný v službe nexus-auth. Za organizáciou neexistuje žiadny zdieľaný kľúč platformy, takže žiadna organizácia nikdy nečerpá rozpočet inej. Cena za toto pravidlo je zrejmá: organizácia bez kľúča vo svojom fonde nedostane žiadne odpovede od AI. Asistent zobrazí MODEL_NOT_CONNECTED (503) a uvedie, kto môže kľúč pripojiť.
Kľúč je možné pridať do fondu pre štyroch poskytovateľov:
| ID poskytovateľa | Zobrazené ako |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Vlastný modelový server
Organizácia môže použiť aj akýkoľvek server, ktorý prevádzkuje a ktorý komunikuje cez API kompatibilné s OpenAI, ako napríklad model na uzloch GPU v Harrow. Inštalátor ho pomenuje v súbore hodnôt:
# 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 nasmeruje adaptér brány kompatibilný s OpenAI na váš server. V inštalácii sa slot scaleway vo fonde spája s týmto serverom, takže kľúč, ktorý pridáte pre scaleway, je kľúč, ktorý očakáva váš vlastný server.
ai.installationHosts uvádza názvy hostiteľov, ktoré sa nachádzajú vo vnútri inštalácie, okrem vlastnej domény služieb vydania a troch verejných hostiteľov. Každá položka je názov hostiteľa, .suffix, adresa IP alebo rozsah IPv4 CIDR (Classless Inter-Domain Routing). Smerovač používa tento zoznam na rozlíšenie volania, ktoré zostáva v lokalite, od volania, ktoré ju opúšťa, čo hlási kontrola „Nič neopúšťa túto lokalitu“ na stránke Pripojenie modelu na vlastnom hardvéri.
Sieťová politika je rovnako dôležitá ako smerovač. Menný priestor predvolene zakazuje všetku odchádzajúcu komunikáciu (egress), takže brána sa dokáže spojiť s modelovým serverom mimo menného priestoru iba vtedy, keď je jeho rozsah uvedený v networkPolicy.externalEgressCIDRs. To isté platí pre hostovaného poskytovateľa: ak chce Harrow, aby odpovedal jeho kľúč Gemini, rozsahy adries poskytovateľa tam musia byť uvedené tiež, inak volanie nikdy neopustí klaster. Kapitola 2.16, Bezpečnosť a siete, sa tejto politike venuje podrobne.
Pridávanie a odoberanie kľúčov
Vlastníci a správcom organizácie spravujú jej fond. Nikto iný kľúče nevidí ani ich nemôže meniť a požiadavka od iných osôb je odmietnutá s kódom AUTHORITY_EXCEEDED.
V konzole
Vo verzii Enterprise sa fond spravuje v AI ústredni, pod časťou s enginmi. Vo verzii Community sa tie isté kľúče nachádzajú v časti Nastavenia, Modely AI. Táto stránka predstavuje základný smerovač, kde pridávate kľúče a adresu lokálneho modelu a vyberáte, ktorý model vykonáva ktorú úlohu. Obe verzie zobrazujú pri každom kľúči, kto a kedy ho nastavil („Nastavila Aoife, 3. sept.“), a maskovanú nápovedu maximálne posledných štyroch znakov, napríklad ••••7f2q. Samotný kľúč sa po pridaní už nikdy nezobrazí.
Cez BFF API
Služba BFF (backend for frontend) konzoly poskytuje pre fond tri trasy. Volajte ich s osobným prístupovým tokenom používateľa: organizácia sa zisťuje z tokenu, nikdy nie z požiadavky.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET vráti poskytovateľov vo fonde, informáciu, či každý z nich dokáže odpovedať, každý kľúč podľa jeho nápovedy a poskytovateľov, pre ktorých je možné pridať kľúč. Pridanie kľúča vyžaduje telo vo formáte JSON s dvoma povinnými poľami a jedným voliteľným:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Kľúč putuje iba raz. Služba nexus-auth ho zašifruje a informuje smerovač, pričom odpoveď obsahuje iba nápovedu. Odpoveďou je 201 s ID nového kľúča a jeho riadkom: „Pridané. Kľúč Google Gemini ••••7f2q je vo fonde AI organizácie a smerovač AI Provider Router naň teraz môže smerovať požiadavky.“ Menovka môže mať najviac 100 znakov a kľúč je jeden reťazec bez medzier s dĺžkou najviac 4 096 znakov. Akékoľvek iné pole v tele alebo pole uvádzajúce organizáciu či osobu je odmietnuté.
Stiahnutie kľúča vyžaduje prázdne telo. Smerovač okamžite prestane smerovať na daný kľúč a služba nexus-auth si ho ponechá označený ako stiahnutý, takže jeho história zostane zachovaná. Vo fonde sa nikdy nič neodstraňuje.
| Odmietnutie | HTTP | Kedy |
|---|---|---|
VALIDATION_FAILED |
400 | Telo, ktoré nie je {provider, api_key, label?}, neznámy poskytovateľ alebo osobné predplatné ponúknuté ako kľúč organizácie |
AUTHORITY_EXCEEDED |
403 | Volajúci nie je vlastníkom ani správcom organizácie |
RECORD_NOT_FOUND |
404 | Vo fonde organizácie sa nenachádza žiadny kľúč s týmto ID |
TRANSITION_NOT_PERMITTED |
409 | Kľúč už je stiahnutý |
TENANT_NOT_A_PARAMETER |
403 | Telo alebo dopyt uvádzali organizáciu |
Stavy kľúčov
Každý kľúč vo fonde je v jednom zo šiestich stavov. Na chat odpovedá iba používaný kľúč.
| Stav | Čo to znamená |
|---|---|
in_use |
Kľúč odpovedá, a to až do dátumu vypršania platnosti, ak nejaký má. |
resting |
Smerovač ho po zlyhaniach nechal odpočívať do stanoveného času. Požiadavky zatiaľ smerujú na ďalší kľúč. |
exhausted |
Vyčerpal svoj limit u poskytovateľa. |
invalid |
Poskytovateľ ho už neprijíma. |
expired |
Jeho platnosť vypršala v deň exspirácie. |
withdrawn |
Správca ho stiahol. Zostáva uvedený v histórii. |
Kľúč, ktorý zlyhá, odpočíva 60 sekúnd. Po 5 zlyhaniach za sebou ho smerovač vypne, presunie jeho podiel na ostatné kľúče a zaznamená upozornenie PROVIDER_KEY_SWITCHED_OFF. Nikto nie je odmietnutý, kým dokáže odpovedať iný kľúč.
Keď poskytovateľ nemá žiadny používaný kľúč, fond uvedie dôvod („Žiadny používaný kľúč: 1 stiahnutý, 1 s vypršanou platnosťou“). Keď žiadny poskytovateľ vo fonde nemá používaný kľúč, chat je odmietnutý s kódom NO_PROVIDER_FOR_ROLE (422) a riešením: vlastník alebo správca pridá kľúč organizácie. Ide o stav konfigurácie, ktorý zostáva na obrazovke, kým ho niekto neopraví.
Roly, politika a požiadavky (wishes)
Smerovač uvažuje v rolách. Každá požiadavka je určená pre jednu z piatich rolí: default, fast, reasoning, code alebo long_context. Každý model je tiež zaradený do úrovne frontier, standard alebo fast, pričom vyššia úroveň je uprednostnená, ak to rola dovoľuje. Organizácia rozhoduje, ktorý poskytovateľ obsluhuje jednotlivé roly (priradenia rolí) a v akom poradí sa má prepínať pri zlyhaní poskytovateľa (rebríček politiky smerovania). Správcovia nastavujú oboje v AI ústredni. Služba nexus-auth ich tiež sprístupňuje na /auth/org/<organisation-id>/settings/ai-provider/role-assignments a /auth/org/<organisation-id>/settings/ai-provider/routing-policy pre kľúč správcu s oprávnením ai_provider:manage.
Volajúci môžu vyjadriť svoje preferencie. Riadok zručnosti môže obsahovať preferovaného poskytovateľa a preferovaný model spolu s profilom schopností. Smerovač pristupuje ku každej položke inak:
- Preferovaný poskytovateľ sa rešpektuje iba vtedy, keď má organizácia tohto poskytovateľa povoleného a má pre neho kľúč. V opačnom prípade smerovač použije náhradu.
- Preferovaný model sa rešpektuje, ak sa nachádza v katalógu daného poskytovateľa a vyhovuje profilu.
- Profil schopností je filter, ktorý nikdy priamo nevyberá. Môže vyžadovať minimálne kontextové okno, používanie nástrojov, spracovanie obrazu (vision), vektorové vkladania (embeddings), dlhý kontext alebo umiestnenie údajov (data residency). Čokoľvek, čo filtru nevyhovie, nie je spôsobilé.
Smerovač vyberá v pevne stanovenom poradí. Ak môže, vyhovie želaniu, potom skúsi iný model toho istého poskytovateľa, následne priradenie roly a akéhokoľvek iného poskytovateľa s kľúčom, ktorého katalóg vyhovuje. Ak bol zadaný profil a nevyhovuje mu žiadny katalóg, požiadavka je odmietnutá s kódom MODEL_CAPABILITY_UNAVAILABLE (422). Ak nie je nič priradené a nič sa nezhoduje, výsledkom je NO_PROVIDER_FOR_ROLE (422). Neexistuje žiadny predvolený model poslednej záchrany. Rola, ktorú ste nenakonfigurovali, zlyhá s jasným hlásením, v ktorom smerovač vlastnými slovami uvedie, čo treba nastaviť.
Umiestnenie údajov (data residency) je jediné obmedzenie, ktoré sa nedá obísť náhradou. Profil s eu_only je obslúžený poskytovateľom z EÚ alebo odmietnutý. Harrow nastavuje tento zámok pre celú organizáciu a ústredňa vykreslí druhého hostovaného poskytovateľa, ktorý sa nachádza v regióne USA, ako vypnutého.
Zručnosť môže tiež pevne pripnúť jeden konkrétny model, ak ho nevyhnutne potrebuje pre svoje fungovanie. Aj v takom prípade však smerovač použije vlastný kľúč organizácie pre daný model, a ak kľúč neexistuje, nič neodpovie. Volajúci nikdy nemôže prinútiť systém Nexus použiť poskytovateľa, ktorého organizácia nenakonfigurovala.
Po výbere poskytovateľa je prepnutie pri zlyhaní (failover) samostatnou záležitosťou. Chyba 429, 5xx alebo zlyhanie siete posunie požiadavku po rebríčku nižšie k ďalšiemu poskytovateľovi. Chyba 400, 401, 403 alebo 404 proces okamžite zastaví, pretože prihlasovacie údaje a štruktúry požiadaviek nie sú prenosné medzi poskytovateľmi a opakovanie by len zbytočne čerpalo kvótu s rovnakým neúspešným výsledkom.
Ak chcete vidieť, čo by smerovač vybral predtým, než sa niekto opýta, načítajte GET /api/ai/routing-policy/effective na bráne s osobným tokenom používateľa. Vráti model pre prihlásenú organizáciu, alebo slovné odmietnutie smerovača, ak žiadny model nie je k dispozícii, pričom modelu neodošle žiadnu požiadavku.
Sledovanie smerovača
Pruh s údajmi v spodnej časti každej stránky zobrazuje používaný model („Model: local“). Vo verzii Enterprise stránka AI ústredňa, naživo vykresľuje prevádzku smerovača v reálnom čase: požiadavky od asistenta, úloh a aplikácií prúdiace cez roly k poskytovateľom a kľúčom, kľúč počas 60-sekundového odpočinku vykreslený sivou farbou, vypnutý kľúč červenou farbou a prepnutie na hostovaného poskytovateľa, keď je lokálny model zaneprázdnený. Popri toku zobrazuje grafy zaťaženia jednotlivých poskytovateľov, počet požiadaviek za sekundu a čas čakania. Tomás ju necháva otvorenú počas prvého týždňa po akejkoľvek zmene politiky smerovania, pretože nesprávne priradenie roly sa tam v priebehu niekoľkých minút prejaví ako prevádzka smerujúca tam, kam ju nikto nechcel poslať.
Vo verzii Community má stránka Modely AI tlačidlo Otestovať každý model, ktoré skontroluje každý nakonfigurovaný model a označí, či odpovedá. Je to najrýchlejší spôsob, ako overiť fungovanie nového kľúča predtým, než sa naň niekto začne spoliehať.
Vektorové reprezentácie (embeddings)
Vyhľadávanie a znalostný graf premieňajú text na vektory. Inštalácia to predvolene robí pomocou modelu pre vektorové vkladanie (embedding), ktorý beží vo vnútri klastra na procesore, takže žiadny text neopúšťa lokalitu a organizácia na to nepotrebuje žiadny kľúč. Použitie hostovaného poskytovateľa pre vektorové vkladania je voľbou organizácie; proces potom prebieha cez ten istý fond a podľa rovnakých pravidiel.
O vektorové vkladania alebo preusporiadanie (reranking) môžu smerovač požiadať iba tri služby: nexus-graphrag, nexus-skills-engine a nexus-workflows. GraphRAG vytvára vkladania v mene organizácie, ktorej obsah patrí, s nastaveniami tejto organizácie, a nedrží žiadny vlastný kľúč poskytovateľa. Keď organizácia zmení svoj model pre vektorové vkladanie, služba nexus-workflows spustí úlohu opätovného vytvorenia vkladaní pre úložiská danej organizácie.
Osobné prihlasovacie údaje zostávajú osobné
Niektoré prihlasovacie údaje patria jednej osobe. Bežným prípadom je predplatné Claude Max, prihlásené cez osobný účet daného používateľa. Takéto prihlasovacie údaje nikdy nie sú kľúčom organizácie: fond ich odmietne s kódom VALIDATION_FAILED, nikdy sa neuvádzajú v tabuľke kľúčov organizácie a nezobrazia sa na obrazovke žiadnej inej osoby.
Kľúče k modelom sa tiež nikdy nedostanú nikam inam. Stránka Kľúče externých údajov, ktorá uchováva kľúče pre externé zdroje údajov, odmietne čokoľvek, čo vyzerá ako kľúč k modelu AI, s kódom AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Ak čítačka súborov nájde kľúče k modelom vo vnútri dokumentu alebo konfigurácie, kam nepatria, zaznamená CREDENTIALS_IN_WRONG_PLACE a správca ich odstráni a nahradí.
Skripty, REST a MCP
Nexus má troch verejných hostiteľov. V Harrow sú to console.harrow.example pre konzolu, api.harrow.example pre bránu a auth.harrow.example pre prihlasovanie. Skripty a nástroje používajú druhého a tretieho.
Kľúče pre skripty
Skript sa prihlasuje pomocou kľúča vytvoreného v časti Nastavenia, Kľúče pre skripty. Každý kľúč má názov, dosah (napríklad „Iba spustenie sčítania dvora dronom“), osobu, ktorá ho vytvorila, a dátum ukončenia platnosti; organizácia môže uzamknúť maximálnu životnosť kľúča. Tajný kľúč sa zobrazí iba raz pri vytvorení kľúča. Skopírujte ho do úložiska tajných kľúčov skriptu, pretože Nexus uchováva iba jeho posledné štyri znaky. Kľúč sa sťahuje, nikdy sa neodstraňuje: okamžite prestane fungovať a zostane uvedený v zozname spolu s každým volaním, ktoré vykonal. Rotácia pridelí kľúču nový tajný kľúč a raz ho zobrazí.
Každý kľúč má vlastnú stránku s počtom volaní za deň, volaniami podľa služby a denníkom aktivít obsahujúcim čas, adresu, službu a výsledok. Volanie mimo dosahu kľúča je odmietnuté a zobrazí sa v denníku.
Služba nexus-auth sprístupňuje tie isté kľúče prihlásenej osobe na adrese https://auth.harrow.example/api-keys: vytvorenie a zoznam, a následne čítanie, zmena, odvolanie alebo rotácia jedného kľúča podľa jeho ID.
REST cez bránu
Posielajte volania REST na https://api.harrow.example s Authorization: Bearer <token-or-key>. Každý kľúč musí patriť organizácii. Kľúč bez organizácie odmietne s kódom TOKEN_ORG_MISSING (403) každá služba, ktorá kontroluje kľúče cez nexus-auth.
Volajúci, ktorý sa pýta príliš často, dostane odpoveď 429 s RATE_LIMITED, hlavičkou Retry-After a limitom a časovým oknom v tele. Počkajte počet sekúnd, ktorý uvádza. Vo verzii Enterprise nastavujú správcovia limity pre kľúč, aplikáciu a jednotku v časti Nastavenia, Obmedzenia rýchlosti (pozrite kapitolu 2.16, Bezpečnosť a siete).
MCP pre nástroje AI
Nástroje AI, ktoré komunikujú cez protokol Model Context Protocol, sa pripájajú na https://api.harrow.example/mcp. Prihlasujú sa cez server OAuth 2.1 (OAuth je otvorený štandard pre delegovanú autorizáciu) na https://auth.harrow.example, ktorý podporuje registráciu klienta samotným nástrojom, takže nástroj ako Claude Code alebo Cursor sa sám zaregistruje a otvorí prehliadač používateľa na prihlásenie. Pripojenie potom koná v mene tejto jednej osoby, s jej právami a ničím navyše. Prihlásená osoba si môže stiahnuť pripravenú konfiguráciu pre nástroj príkazového riadka z https://auth.harrow.example/api/v1/mcp/cli-config.
Volania nástrojov, ktoré potrebujú model, prechádzajú cez smerovač ako všetko ostatné, pod organizáciou danej osoby.




