Prihlásiť saRezervovať brífing

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

16 min čítania

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.

Vľavo: tri poľa nad sebou, „Asistent“, „Krok pracovného postupu“, „Zručnosť“, každé so šípkou do poľa „Odoslanie UNO (nexus-orchestrator)“. Šípka označená „želania: preferovaný poskytovateľ, preferovaný model, profil schopností“ smeruje doprava do veľkého poľa „AI Provider Router (nexus-gateway)“. Vo vnútri poľa smerovača sú tri malé polia v rade: „Rola“, „Fond organizácie“, „Politika smerovania“. Zo smerovača smerujú tri šípky doprava k „Lokálny model (ai.localProvider.baseUrl)“, „Kľúč hostovaného poskytovateľa A“, „Kľúč hostovaného poskytovateľa B“. Pod smerovačom je samostatné pole „nexus-auth: fond kľúčov organizácie (zašifrovaný)“ s prerušovanou šípkou smerujúcou nahor do smerovača s označením „kľúče, vyhodnotené pre každé volanie“.
Ako sa požiadavka dostane k modelu.

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/24

ai.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.

Pripojenie modelu na vlastnom hardvéri
Pripojenie modelu na vlastnom hardvéri
Pripojenie modelu na vlastnom hardvéri. Stránka uvádza modely, ktoré server hlási, rolu, ktorú každý z nich zohráva, a potvrdzuje, že nič neopúšťa lokalitu.

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í.

Ústredňa AI
Ústredňa AI
AI ústredňa uvádza každého poskytovateľa spolu s tým, kto nastavil jeho kľúč a aké úlohy vykonáva. Jeden kľúč po zlyhaniach odpočíva, ďalší bol vypnutý a stránka uvádza, kam môžu údaje odchádzať.
Modely AI
Modely AI
Základný smerovač vo verzii Community: kľúč organizácie, lokálny model na vlastnom stroji organizácie a určenie, ktorý model vykonáva ktorú úlohu.

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ť.

AI ústredňa, naživo
AI ústredňa, naživo
Smerovač naživo. Prevádzka prúdi od asistenta a úloh cez roly k lokálnemu modelu a hostovaným kľúčom; jeden kľúč odpočíva, jeden je vypnutý a zlaté bodky znázorňujú prepnutie na zálohu, kým je lokálny model zaneprázdnený.

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.

Jeden kľúč pre skripty
Jeden kľúč pre skripty
Jeden kľúč pre skripty. Stránka zobrazuje dosah kľúča, kto ho vytvoril, dátum ukončenia platnosti, volania podľa dňa a služby a výsledok každého volania; tajný kľúč končí na …7QK2 a už sa nikdy nezobrazí.

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.